v8.12.1

.github/workflows/documentation.yaml

@@ -1,7 +1,14 @@
 name: Docs
 on:
+  workflow_dispatch:
+    branches:
+      - iblrigv8dev
+    paths:
+      - '.github/workflows/documentation.yaml'
+      - 'docs/**'
   push:
-    branches: [iblrigv8, docs]
+    branches:
+      - iblrigv8
     paths:
       - '.github/workflows/documentation.yaml'
       - 'docs/**'

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
 
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
     -   id: end-of-file-fixer
         types_or: [python, yaml, json, toml]

CHANGELOG.md

@@ -1,6 +1,10 @@
 Changelog
 ---------
 
+8.12.1
+------
+* bugfix: remember ability for setting the status LED
+
 8.12.0
 ------
 * add a trainingPhaseChoiceWorld task to fix the training levels

README.md

@@ -4,6 +4,11 @@ Welcome to the International Brain Laboratory decision making task implementatio
 
 The task is implemented in the Bpod system (Sanworks) and uses the Bonsai visual programming language (on Windows) for the visual stimuli and Python for all other purposes.
 
+> **Documentation and installation steps: [int-brain-lab.github.io/iblrig](https://int-brain-lab.github.io/iblrig)**
 
-## Documentation and installation steps here:
-https://int-brain-lab.github.io/iblrig
+---
+
+[![Coverage Status](https://coveralls.io/repos/github/int-brain-lab/iblrig/badge.svg?branch=iblrigv8)](https://coveralls.io/github/int-brain-lab/iblrig?branch=iblrigv8)
+![License](https://img.shields.io/github/license/int-brain-lab/iblrig)
+![GitHub tag](https://img.shields.io/github/v/tag/int-brain-lab/iblrig)
+[![GitHub Discussions](https://img.shields.io/github/discussions/int-brain-lab/iblrig)](https://github.com/int-brain-lab/iblrig/discussions)

docs/source/developer_guide.rst

@@ -105,49 +105,3 @@ What Happens When Running an IBL Task?
    -  Recording administered water and session performance on Alyx.
    -  Halting the mixins.
    -  Initiating local server transfer.
-
-Writing Your Own Task
----------------------
-
-iblrig.base_tasks.BaseTask
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This serves as the fundamental class for all tasks. It supplies abstract
-methods and functions to establish the folder structure and perform Alyx
-database registration.
-
-1. When creating a subclass of BaseTask, you must override the following
-   methods:
-
-   -  ``_run()``: Main method of the task, wrapped by the ``run()``
-      method that incorporates folder creation and Alyx interaction pre-
-      and post-task.
-   -  ``start_hardware()``: Method to activate hardware modules and
-      establish connections.
-
-2. Document your protocol name using the ``protocol_name`` property.
-
-Hardware Modules
-^^^^^^^^^^^^^^^^
-
-Within ``iblrig.base_tasks``, hardware mixins are dedicated to specific
-modules. These mixin classes deliver hardware-specific functionality. To
-use those mixins, compose them with the ``BaseClass`` above.
-
-Mixins for hardware modules decouple hardware-specific code from task
-code: - The ``init_mixin_*()`` methods are called at instantiation, so
-they need to work regardless of whether the hardware is connected or
-not. - The ``start_mixin_*()`` methods are called at the beginning of
-the ``run()`` method, ensuring that the hardware is properly connected.
-- The ``stop_mixin_*()`` methods are called at the end of the ``run()``
-method, ensuring that the hardware is properly disconnected.
-
-To test only the hardware, you can instantiate the task and call the
-``start_hardware()`` and ``stop_hardware()`` methods.
-
-iblrig.base_choice_world.ChoiceWorld
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is a subclass of ``BaseTask`` that implements the IBL
-decision-making task family. When subclassing ``ChoiceWorld``, you must
-override the following methods: - ``next_trial()``

docs/source/index.rst

@@ -13,5 +13,6 @@ IBLRIG documentation
    usage
    installation
    description_file
+   write_your_own_task
    developer_guide
    faq

docs/source/write_your_own_task.rst

@@ -0,0 +1,97 @@
+==============================
+Guide to develop a custom task
+==============================
+
+The basics
+==========
+
+During the lifetime of the IBL project, we realized that multiple task variants combine with multiple hardware configurations and acquisition modalities, leading to a combinatorial explosion of possible tasks and related hardware.
+
+This left us with the only option of developing a flexible task framework through hierarchical inheritance.
+
+All tasks inherit from the ``iblrig.base_tasks.BaseSession`` class, which provides the following functionalities:
+    -   read hardware parameters and rig parameters
+    -   optionally interfaces with the `Alyx experimental database <https://github.com/cortex-lab/alyx>`_
+    -   creates the folder structure for the session
+    -   writes the task and rig parameters, log, and :doc:`acquisition description files <../description_file>`
+
+Additionally the ``iblrig.base_tasks`` module provides "hardware mixins". Those are classes that provide hardware-specific functionalities, such as connecting to a Bpod or a rotary encoder. They are composed with the ``BaseSession`` class to create a task.
+
+.. warning::
+
+    This sounds complicated ? It is !
+    Forecasting all possible tasks and hardware add-ons and modification is fool's errand, however we can go through specific examples of task implementations.
+
+
+
+Examples
+========
+
+.. admonition:: Where to write your task
+    :class: seealso
+
+    After the :doc:`installation of iblrig <../installation>` the `project extraction <https://github.com/int-brain-lab/project_extraction>`_ repository is located at the root of the C: drive.
+    New tasks should be added to the ``C:\project_extraction\iblrig_custom_tasks`` folder to be made visible by the `iblrig` GUI.
+    We use a convention that the task name starts with the author identifier, followed by an underscore, followed by the task name, such as `olivier_awesomeChoiceWorld`.
+
+
+     olivier_awesomeChoiceWorld
+        -   __init__.py
+        -   task.py
+        -   README.md
+        -   task_parameters.yaml
+        -   test_olivier_awesomeChoiceWorld.py
+
+
+Example 1: variation on biased choice world
+-------------------------------------------
+
+We will create a a choice world task that modifies a the quiescence period duration random draw policy.
+In the `task.py` file, the first step is to create a new task class that inherits from the ``BiasedChoiceWorldSession`` class.
+
+Then we want to make sure that the task bears a distinctive protocol name, `_iblrig_tasks_imagingChoiceWorld`.
+We also create the command line entry point for the task that will be used by the `iblrig` GUI.
+
+Also, in this case we can leverage the IBL infrastructure to perform extraction of the trials using existing extractors `extractor_tasks = ['TrialRegisterRaw', 'ChoiceWorldTrials']`
+
+   .. code-block:: python
+
+        import iblrig.misc
+        from iblrig.base_choice_world import BiasedChoiceWorldSession
+
+
+        class Session(BiasedChoiceWorldSession):
+            protocol_name = "_iblrig_tasks_imagingChoiceWorld"
+            extractor_tasks = ['TrialRegisterRaw', 'ChoiceWorldTrials']
+
+        if __name__ == "__main__":  # pragma: no cover
+            kwargs = iblrig.misc.get_task_arguments(parents=[Session.extra_parser()])
+            sess = Session(**kwargs)
+            sess.run()
+
+
+In this case the parent class `BiasedChoiceWorldSession` has a method that draws the quiescence period. We are going to overload this method to add our own policy. This means the parent method will be fully replaced by our implementation.
+The class now looks like this:
+
+   .. code-block:: python
+
+        class Session(BiasedChoiceWorldSession):
+            protocol_name = "_iblrig_tasks_imagingChoiceWorld"
+
+            def draw_quiescent_period(self):
+                """
+                For this task we double the quiescence period texp draw and remove the absolute
+                offset of 200ms. The resulting is a truncated exp distribution between 400ms and 1 sec
+                """
+                return iblrig.misc.texp(factor=0.35 * 2, min_=0.2 * 2, max_=0.5 * 2)
+
+Et voilà, in a few lines, we re-used the whole biased choice world implementation to add a custom parameter. This is the most trivial and easy example.
+The full code is available `here <https://github.com/int-brain-lab/iblrig/tree/iblrigv8/iblrig_tasks/_iblrig_tasks_ImagingChoiceWorld>`_.
+
+
+Example 2: re-writing a state-machine for a biased choice world task
+--------------------------------------------------------------------
+
+In some instances changes in the task logic require to go deeper and re-write the sequence of task events. In bpod parlance, we are talking about rewritng the state-machine code.
+
+Coming, for now here is an example of such a `task <https://github.com/int-brain-lab/iblrig/tree/iblrigv8/iblrig_tasks/_iblrig_tasks_neuroModulatorChoiceWorld>`_.

iblrig/__init__.py

@@ -4,7 +4,7 @@
 # 3) Check CI and eventually wet lab test
 # 4) Pull request to iblrigv8
 # 5) git tag the release in accordance to the version number below (after merge!)
-__version__ = '8.12.0'
+__version__ = '8.12.1'
 
 # The following method call will try to get post-release information (i.e. the number of commits since the last tagged
 # release corresponding to the one above), plus information about the state of the local repository (dirty/broken)