deploy: 9ebfe07

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 73a629f812076d3b0045112237e3f48e
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/description_file.rst.txt

@@ -0,0 +1,215 @@
+Describing an Experiment
+========================
+
+Experiment description file
+---------------------------
+
+All experiments are described by a file with the name
+``_ibl_experiment.description.yaml``. This description file contains
+details about the experiment such as, information about the devices used
+to collect data, or the behavior tasks run during the experiment. The
+content of this file is used to copy data from the acquisition computer
+to the lab server and also determines the task pipeline that will be
+used to extract the data on the lab servers. It’s accuracy in fully
+describing the experiment is, therefore, very important!
+
+Here is an example of a complete experiment description file for a
+mesoscope experiment running two consecutive tasks,
+``biasedChoiceWorld`` followed by ``passiveChoiceWorld``.
+
+.. code:: yaml
+
+   devices:
+     mesoscope:
+       mesoscope:
+         collection: raw_imaging_data*
+         sync_label: chrono
+     cameras:
+       belly:
+         collection: raw_video_data
+         sync_label: audio
+         width: 640
+         height: 512
+         fps: 30
+       left:
+         collection: raw_video_data
+         sync_label: audio
+       right:
+         collection: raw_video_data
+         sync_label: audio
+   procedures:
+   - Imaging
+   projects:
+   - ibl_mesoscope_active
+   sync:
+     nidq:
+       acquisition_software: timeline
+       collection: raw_sync_data
+       extension: npy
+   tasks:
+   - _biasedChoiceWorld:
+       collection: raw_task_data_00
+       sync_label: bpod
+       extractors: [TrialRegisterRaw, ChoiceWorldTrialsTimeline, TrainingStatus]
+   - passiveChoiceWorld:
+       collection: raw_task_data_01
+       sync_label: bpod
+       extractors: [PassiveRegisterRaw, PassiveTaskTimeline]
+   version: 1.0.0
+
+Breaking down the components of an experiment description file
+--------------------------------------------------------------
+
+Devices
+~~~~~~~
+
+The devices section in the experiment description file lists the set of
+devices from which data was collection in the experiment. Supported
+devices are Cameras, Microphone, Mesoscope, Neuropixel, Photometry and
+Widefield.
+
+The convention for this section is to have the device name followed by a
+list of sub-devices, e.g.
+
+.. code:: yaml
+
+   devices:
+     cameras:
+       belly:
+         collection: raw_video_data
+         sync_label: audio
+         width: 640
+         height: 512
+         fps: 30
+       left:
+         collection: raw_video_data
+         sync_label: audio
+       right:
+         collection: raw_video_data
+         sync_label: audio
+
+In the above example, ``cameras`` is the device and the sub-devices are
+``belly``, ``left`` and ``right``.
+
+If there are no sub-devices, the sub-device is given the same name as
+the device, e.g.
+
+.. code:: yaml
+
+   devices:
+     mesoscope:
+       mesoscope:
+         collection: raw_imaging_data*
+         sync_label: chrono
+
+Each sub-device must have at least the following two keys -
+**collection** - the folder containing the data - **sync_label** - the
+name of the common ttl pulses in the channel map used to sync the
+timestamps
+
+Additional keys can also be specified for specific extractors, e.g. for
+the belly camera the camera metadata passed into the camera extractor
+task is defined in this file.
+
+Procedures
+~~~~~~~~~~
+
+The procedures section lists the set of procedures that apply to this
+experiment. The list of possible procedures can be found
+`here <https://alyx.internationalbrainlab.org/admin/actions/proceduretype/>`__.
+
+As many procedure that apply to the experiment can be added e.g.
+
+.. code:: yaml
+
+   procedures:
+   - Fiber photometry
+   - Optical stimulation
+   - Ephys recording with acute probe(s)
+
+Projects
+~~~~~~~~
+
+The projects section lists the set of projects that apply to this
+experiment. The list of possible projects can be found
+`here <https://alyx.internationalbrainlab.org/admin/subjects/project/>`__.
+
+As many projects that apply to the experiment can be added e.g.
+
+::
+
+   projects:
+   - ibl_neuropixel_brainwide_01
+   - carandiniharris_midbrain_ibl
+
+Sync
+~~~~
+
+The sync section contains information about the device used to collect
+the syncing data and the format of the data. Supported sync devices are
+bpod, nidq, tdms, timeline. Only **one** sync device can be specified
+per experiment description file and act as the main clock to which other
+timeseries are synced.
+
+An example of an experiment run with bpod as the main syncing device is,
+
+.. code:: yaml
+
+   sync:
+     bpod:
+       collection: raw_behavior_data
+       extension: bin
+
+Another example for spikeglx electrophysiology recordings with
+Neuropixel 1B probes use the nidq as main synchronisation.
+
+.. code:: yaml
+
+   sync:
+     nidq:
+       collection: raw_ephys_data
+       extension: bin
+       acquisition_software: spikeglx
+
+Each sync device must have at least the following two keys -
+**collection** - the folder containing the data - **extension** - the
+file extension of the sync data
+
+Optional keys include, for example ``acquisition_software``, the
+software used to acquire the sync pulses
+
+Tasks
+~~~~~
+
+The tasks section contains a list of the behavioral protocols run during
+the experiment. The name of the protocol must be given in the list e.g.
+
+.. code:: yaml
+
+   tasks:
+   - _biasedChoiceWorld:
+       collection: raw_task_data_00
+       sync_label: bpod
+       extractors: [TrialRegisterRaw, ChoiceWorldTrialsTimeline, TrainingStatus]
+   - passiveChoiceWorld:
+       collection: raw_task_data_01
+       sync_label: bpod
+       extractors: [PassiveRegisterRaw, PassiveTaskTimeline]
+
+Each task must have at least the following two keys - **collection** -
+the folder containing the data - **sync_label** - the name of the common
+ttl pulses in the channel map used to sync the timestamps
+
+The ``collection`` must be unique for each task. i.e. Data from two
+tasks cannot be stored in the same folder.
+
+If the Tasks used to extract the data are not the default tasks, the
+extractors to use must be passed in as an additional key. The order of
+the extractors defines their parent child relationship in the task
+architecture.
+
+Version
+~~~~~~~
+
+The version section gives version number of the experiment description
+file

_sources/developer_guide.rst.txt

@@ -0,0 +1,143 @@
+===============
+Developer Guide
+===============
+
+Versioning Scheme
+=================
+
+IBLRIG v8 uses `Semantic Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html>`_.
+Its version string (currently "|version|") is a combination of three fields, separated by dots:
+
+.. centered:: ``MAJOR`` . ``MINOR`` . ``PATCH``
+
+* The ``MAJOR`` field is only incremented for breaking changes, i.e., changes that are not backward compatible with previous changes.
+  Releases of IBLRIG v8, for instance, are generally incompatible with IBLRIG v7.
+* The ``MINOR`` field will be incremented upon adding new, backwards compatible features.
+* The ``PATCH`` field will be incremented with each new, backwards compatible bugfix release that does not implement a new feature.
+
+On the developer side, these 3 fields are manually controlled by, both
+
+   1. adjusting the variable ``__version__`` in ``iblrig/__init__.py``, and
+   2. adding the corresponding version string to a commit as a `git tag <https://git-scm.com/book/en/v2/Git-Basics-Tagging>`_,
+      for instance:
+
+      .. code-block:: console
+
+         git tag 8.8.4
+         git push origin --tags
+
+The version string displayed by IBLRIG *may* include additional fields, such as in "|version|-post3.dirty".
+Here,
+
+* ``post3`` indicates the third unversioned commit after the latest versioned release, and
+* ``dirty`` indicates the presence of uncommited changes in your local repository of IBLRIG.
+
+Both of these fields are inferred by means of git describe and do not require manual interaction from the developer.
+
+
+Running Tests Locally
+=====================
+
+.. code-block:: console
+
+   flake8
+   python -m unittest discover ./iblrig/test
+
+
+Building the documentation
+==========================
+
+.. code-block:: console
+
+   # make sure pre-requisites are installed
+   pip install --upgrade -e .[DEV]
+   # create the static directory
+   rm -rf ./docs/build
+   mkdir -p ./docs/build/html/_static
+   # unit tests generate task diagrams
+   python -m unittest discover ./iblrig/test
+   # generate class diagrams
+   pyreverse -o png -m y --ignore iblrig.test -A --output-directory ./docs/build/html/_static ./iblrig_tasks
+   # build and serve the docs locally
+   sphinx-autobuild ./docs/source ./docs/build/html/
+
+
+
+Guide to Creating Your Own Task
+===============================
+
+What Happens When Running an IBL Task?
+--------------------------------------
+
+1. The task constructor is invoked, executing the following steps:
+
+   -  Reading of settings: hardware and IBLRIG configurations.
+   -  Reading of task parameters.
+   -  Instantiation of hardware mixins.
+
+2. The task initiates the ``run()`` method. Prior to execution, this
+   method:
+
+   -  Launches the hardware modules.
+   -  Establishes a session folder.
+   -  Saves the parameters to disk.
+
+3. The experiment unfolds: the ``run()`` method triggers the ``_run()``
+   method within the child class:
+
+   -  Typically, this involves a loop that generates a Bpod state
+      machine for each trial and runs it.
+
+4. Upon SIGINT or when the maximum trial count is reached, the
+   experiment concludes. The end of the ``run()`` method includes:
+
+   -  Saving the final parameter file.
+   -  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()``