deploy: 0115f0c

.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.md.txt

@@ -0,0 +1,178 @@
+# 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`. 
+
+```
+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.
+```
+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.
+
+```
+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.
+```
+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, 
+
+```
+sync:
+  bpod:
+    collection: raw_behavior_data
+    extension: bin
+
+```
+
+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.
+```
+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.md.txt

@@ -0,0 +1,42 @@
+# Guide to write your own task
+
+## What happens when running an IBL task ? 
+
+1.  the task constructor gets called, this method:
+    - reads-in settings: hardware settings and iblrig settings
+    - reads-in the task parameters
+    - instantiates the hardware mixins
+2. The task starts using the `run()` method. Before running, the method:
+    - starts the hardware modules
+    - creates a session folder
+    - saves the parameters to disk
+3. The experiment runs: the `run()` method calls the child class `_run()` method
+    - this is usually a loop that instantiates a bpod state machine for each trial and runs it
+4. After SIGINT or when the maximum number of trials is reached, the experiment stops. The end of the `run()` method:
+    - saves the final parameter file
+    - registers water administred and session performance to Alyx
+    - stops the mixins.
+    - initiate local server transfer
+
+## How to write a task
+
+### iblrig.base_tasks.BaseTask
+This is the base class for all tasks. It provides abstract methods and methods to create the folder architecture and for the Alyx database registration.
+
+1.  When subclassing BaseTask, you must override the following methods:
+   -   `_run()`: This is the main method of the task. It is wrapped into by the run() method that provides the folder creation and Alyx interface before and after the task run.
+     -  `start_hardware()`: This method starts the hardware modules and connects to each one of them.
+
+2.  Make sure you document your protocol name with the from `protocol_name` property.
+### Hardware modules
+Hardware mixins, in `iblrig.base_tasks` are dedicated to specific modules. These are mixin classes that provide hardware-specific functionality. To use those mixins, compose them with the `BaseClass` above.
+The mixins for hardware modules provide a way to decouple the hardware-specific code from the 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, so they need to ensure that the hardware is properly connected.
+-   The stop_mixin_*() methods are called at the end of the run() method, so they need to ensure 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/index.rst.txt

@@ -0,0 +1,16 @@
+.. 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.
+
+Welcome to iblrig's documentation!
+==================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   usage
+   installation
+   description_file
+   developer_guide

_sources/installation.rst.txt

@@ -0,0 +1,129 @@
+Installation guide
+==================
+
+.. prerequisites::
+
+    *   Windows OS
+    *   git installation.
+    *   Recommended: Notepad++ or a decent text file editor
+
+
+Install Python 3.10
+-------------------
+
+Open an Administrator: Windows Powershell prompt and run the following:
+
+.. code-block:: powershell
+    Set-ExecutionPolicy RemoteSigned
+    New-Item -ItemType Directory -Force -Path C:\Temp
+    Invoke-WebRequest -Uri https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe -OutFile C:\Temp\python-3.10.11-amd64.exe
+    Start-Process -NoNewWindow -Wait -FilePath C:\Temp\python-3.10.11-amd64.exe -ArgumentList "/passive", "InstallAllUsers=0", "Include_launcher=0", "Include_test=0"
+
+
+.. exercise:: You can check that everything worked by running the following command:
+
+    .. code-block:: powershell
+
+        C:\Users\IBLuser\AppData\Local\Programs\Python\Python310\.\python.exe --version
+
+    Should return `Python 3.10.11`
+
+.. warning:: Make sure you exit the Administrator Powershell prompt before going to the next steps.
+
+
+Install iblrigv8
+----------------
+
+From the Powershell command line, clone iblrig to the ‘iblrigv8’ directory, and switch to iblrigv8 branch
+
+.. code-block:: powershell
+
+    cd C:\
+    git clone https://github.com/int-brain-lab/iblrig.git iblrigv8
+    cd iblrigv8
+    git checkout iblrigv8
+
+Install a new virtual environment and update pip (modify the <Username> value if needed)
+
+.. code-block:: powershell
+
+    C:\Users\IBLuser\AppData\Local\Programs\Python\Python310\.\python.exe -m venv C:\iblrigv8\venv
+    C:\iblrigv8\venv\scripts\python.exe -m pip install --upgrade pip wheel
+
+
+Install iblrig in editable mode
+
+.. code-block:: powershell
+
+    C:\iblrigv8\venv\scripts\Activate.ps1
+    cd C:\iblrigv8
+    pip install -e .
+    pip install -r requirements.txt
+
+Install Bonsai in portable mode
+
+.. code-block:: powershell
+
+    cd C:\iblrigv8\Bonsai
+    powershell.exe .\install.ps1
+    cd ..
+
+
+.. exercise:: You can check that everything went fine by running the test suite:
+
+    .. code-block:: powershell
+
+        cd C:\iblrigv8
+        python -m unittest discover
+
+    The tests should pass to completion after around 40 seconds
+
+
+
+Configuration instructions
+--------------------------
+
+
+Rig configuration files
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Copy template settings files.
+
+.. code-block::
+
+    cd C:\iblrigv8\settings
+    cp hardware_settings_template.yaml hardware_settings.yaml
+    cp iblrig_settings_template.yaml iblrig_settings.yaml
+    explorer C:\iblrigv8\settings
+
+
+Update the 2 settings files, these values can likely be found in the `C:\iblrig_params\.iblrig_params.json` file if working with a existing rig
+
+*   iblrig_settings.yaml
+*   hardware_settings.yaml
+
+
+Setup ONE
+~~~~~~~~~
+
+
+Setup ONE to connect to https://alyx.internationalbrainlab.org, you will need your Alyx username and password.
+
+See instructions for that here: https://int-brain-lab.github.io/iblenv/notebooks_external/one_quickstart.html
+
+
+.. exercise:: Make sure you can connect to Alyx !
+
+    Open a Python shell in the environment and connect to Alyx (you may have to setup ONE)
+
+    .. code-block::
+
+        C:\iblrigv8\venv\scripts\Activate.ps1
+        ipython
+
+    Then at the Ipython prompt
+
+    .. code-block:: python
+
+        from one.api import ONE
+        one = ONE()