deploy: 6da0a84

.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: ace736ba39dc5898b558e025b77347f3
+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,78 @@
+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()``

_sources/faq.rst.txt

@@ -0,0 +1,68 @@
+**************************
+Frequently Asked Questions
+**************************
+
+Here we collect common issues and questions regarding IBLRIG.
+
+First Aid
+=========
+
+If your rig is acting up:
+
+*  Employ the **automated test-script** bundled with IBLRIG. This script helps identify common issues.
+   Execute it using PowerShell:
+
+   .. code:: powershell
+
+      C:\iblrigv8\venv\scripts\Activate.ps1
+      python C:\iblrigv8\scripts\hardware_validation\verify_hardware.py
+
+*  Check `the comprehensive user manual <https://doi.org/10.6084/m9.figshare.11634732.v6>`__ ("Appendix 3" on GoogleDrive).
+   Verify if all connections are secure, and configurations align with the manual's guidelines.
+
+*  Don't hesitate to **contact our developer team** for assistance. We're committed to getting your system back on track.
+
+
+Bug Alert!
+==========
+
+Indeed, bugs are persistently present. Our team is in a perpetual quest to eliminate these pesky issues. Your
+contribution is invaluable in this endeavor; kindly consider `creating an issue on GitHub <https://github.com/int-brain-lab/iblrig/issues>`_.
+
+
+Feature Request?
+================
+
+IBLRIG remains in dynamic development, tailored to meet your needs. Your input shapes our direction. `Send us your
+feature-requests via GitHub <https://github.com/int-brain-lab/iblrig/issues>`_ - we will do our best to help you.
+
+
+Sound Issues
+============
+
+* Double-check all wiring for loose connections.
+
+* Is ``hardware_settings.yaml`` set up correctly? Valid options for sound ``OUTPUT`` are:
+
+  - ``harp``,
+  - ``xonar``, or
+  - ``sysdefault``.
+
+  Make sure that this value matches the actual soundcard used on your rig.
+
+
+Screen Issues
+=============
+
+*  The ribbon cable attaching the screen to the driver board is notoriously finicky. If you are having brightness issues or do not have a signal, try gently repositioning this cable and ensure it is tightly seated in its connection.
+*  Screen and ribbon cable can be easily damaged. It is useful to have backup at on hand.
+*  If the Bonsai display is appearing on the PC screen when a task starts, try unplugging the rig screen, rebooting and plugging the screen back in. Other variations of screen unplugging and rebooting may also work.
+   Also make sure, that the ``DISPLAY_IDX`` value in ``hardware_settings.yaml`` is set correctly.
+*  Screen flashing can occur if the power supply does not match the screen specifications. Use a 12V adapter with at least 1A.
+
+
+Frame2TTL
+=========
+
+*  Version 1 of Frame2TTL won't be detected after restarting the computer.
+   Unplugging and replugging the USB cable should make it responsive again.

_sources/index.rst.txt

@@ -0,0 +1,17 @@
+.. iblrig documentation master file, created by
+   sphinx-quickstart on Tue Jun 20 15:51:34 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+IBLRIG documentation
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   usage
+   installation
+   description_file
+   developer_guide
+   faq