Using IBLRIG v8

Running a behaviour experiment

IBLRIG v8 provides users with two distinct interfaces: a command line interface (CLI) and a graphical user interface (GUI). The CLI encompasses the complete functionality of IBLRIG, upon which the GUI is constructed to enhance user-friendliness. All tasks achievable through the GUI are equally achievable through the CLI.

The Graphical User Interface

To initiate a task through the graphical user interface, open a Windows PowerShell and enter:

C:\iblrigv8\venv\scripts\Activate.ps1
iblrig

These commands activate the necessary environment and launch the IBLRIG Wizard GUI as shown below:

A screenshot of IBLRIG Wizard

Starting a Task

1. Enter your Alyx username, then click on the Connect button. This action will automatically populate the GUI fields with information pertinent to your lab.

2. Select the desired values from the provided options. Utilize the Filter field to swiftly narrow down the list of displayed subjects. Note that selections for Project and Procedure are mandatory.

3. Click the Start button to initiate the task.

Supplementary Controls

• When starting a subsequent task with the same subject, you’ll be asked if you want to append to the preceding session. Doing so will result in a sequence of connected tasks sharing the same data folder.

• The Flush button serves to toggle the valve for cleaning purposes.

Note

IBLRIG’s Graphical User Interface is still work-in-progress. If you have any suggestions to make the GUI more usable, please add an issue on GitHub or approach the dev-team on Slack! We are happy to discuss possible changes with you!

Interfacing with Alyx

Although this is not mandatory, the IBLRIG GUI is designed to interface with Alyx, the International Brain Laboratory’s database. This feature allows users to access their subjects and projects directly from the GUI, without the need to manually enter this information.

To enable this feature, you must have an Alyx account and have configured your database URL and credentials as mentioned Installation guide.

• The subjects available are the set of alyx subjects that are alive, not stock, and belong to the lab defined in the iblrig_settings.py file.

• The projects available are the set of projects of which the current user is a participant. Login to Alyx > Subjects > Projects to check your projects.

The Command Line Interface

To use the command line interface, open a terminal and activate the environment:

cd C:\iblrigv8\
venv\scripts\Activate.ps1

Running a single task

To run a single task, execute the following command:

python .\iblrig_tasks\_iblrig_tasks_trainingChoiceWorld\task.py --subject algernon --user john.doe

Chaining several tasks together

To chain several tasks together, use the --append flag. For instance, to run a passive task after an ephys task:

1. Run the ephys task

   .\iblrig_tasks\_iblrig_tasks_ephysChoiceWorld\task.py --subject algernon
   

2. Run the passive task with the --appendflag:

   .\iblrig_tasks\_iblrig_tasks_passiveChoiceWorld\task.py --subject algernon --append
   

Flushing the valve

To flush valve 1 of the Bpod, type flush and confirm with ENTER. Press ENTER again to close the valve.

Copy commands

Usage

To initiate the data transfer from the local server to the remote server, open a terminal and type.

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data --tag behavior

The transfer local and remote directories are set in the iblrig/settings/iblrig_settings.py file.

To copy data at another acquisition PC, such as video and ephys, use the relevant tag, e.g.

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data --tag video

NB: By default the local data that was copied over 2 weeks ago will be automatically removed. To avoid this set the cleanup-weeks argument to -1:

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data behavior --cleanup-weeks -1

See the ‘Clean-up local data’ section on how to remove data without calling the copy script.

To view the copy status of your local sessions without actually copying, use the ‘dry’ argument:

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data behavior --dry

For more information on the tranfer_data arguments, use the help flag:

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data --help

Clean-up local data

To remove sessions fully copied to the server and older than 2 weeks, open a terminal and type:

C:\iblrigv8\venv\scripts\Activate.ps1
remove-old-sessions

Note: the server needs to be up and running or the sessions won’t be verified as copied.

Behind the Copy Scripts

Workflow

1. Initial Stub Creation: At the start of acquisition, an incomplete experiment description file - a ‘stub’ - is saved to the session on, both, the local PC and the lab server in a subfolder called _devices. The filename of the stub includes the PC’s identifier, allowing the copy script to identify its source.

2. Executing the Copy Script: The copy script is executed on each acquisition PC independently and in no particular order.

3. Navigating Local Session Data: The script systematically navigates through local session folders (or optionally a separate transfers folder) that contain experiment.description stubs.

4. Skipping Transferred Sessions: The script ignores session folders containing a file named transferred.flag (see 7).

5. Copying Collections: For each session, the script reads the respective stub and uses rsync to copy each collection. Subfolders not specified under a collection key are omitted from copying.

6. Removing Remote Stubs: Upon successful copying, the remote stub file is merged with the remote experiment.description file (or copied over if one doesn’t exist already). The remote stub file is then deleted.

7. Confirming Transfer Locally: A transferred.flag file is created in the local session folder to confirm the transfer’s success.

8. Completion and Cleanup: Once no more remote stub files exist for a given session, the empty _devices subfolder is removed. Additionally, a ‘raw_session.flag’ file is created in the remote session folder, indicating the successful transfer of all files.

Example of workflow

Example of three sessions each in a different copy state:

• The State on the Remote Lab Server

  lab server/
  └── subject/
      └── 2020-01-01/
          ├── 001/
          │   └── _devices/
          │       ├── 2020-01-01_1_subject@taskPC.yaml
          │       └── 2020-01-01_1_subject@ephysPC.yaml
          ├── 002/
          │   ├── _ibl_experiment.description.yaml
          │   ├── raw_task_data_00/
          │   └── _devices/
          │       └── 2020-01-01_1_subject@ephysPC.yaml
          └── 003/
              ├── raw_task_data_00/
              ├── raw_ephys_data/
              ├── _ibl_experiment.description.yaml
              └── raw_session.flag
  

• The State on the Local Task Acquisition PC

  acquisition computer (taskPC)/
  └── subject/
      └── 2020-01-01/
          ├── 001/
          │   ├── raw_task_data_00/
          │   └── _ibl_experiment.description_taskPC.yaml
          ├── 002/
          │   ├── raw_task_data_00/
          │   ├── _ibl_experiment.description_taskPC.yaml
          │   └── transferred.flag
          └── 003/
              ├── raw_task_data_00/
              ├── folder_not_in_desc_file/
              ├── _ibl_experiment.description_taskPC.yaml
              └── transferred.flag
  

• The State on the Local Ephys Acquisition PC

  acquisition computer (ephysPC)/
  └── subject/
      └── 2020-01-01/
          ├── 001/
          │   ├── raw_ephys_data/
          │   └── _ibl_experiment.description_ephysPC.yaml
          ├── 002/
          │   ├── raw_ephys_data/
          │   ├── _ibl_experiment.description_ephysPC.yaml
          └── 003/
              ├── raw_ephys_data/
              ├── folder_not_in_desc_file/
              ├── _ibl_experiment.description_ephysPC.yaml
              └── transferred.flag
  

With the lab server and acquisition pcs in the states above, the sessions are in the following states

• subject/2020-01-01/001 no data have been copied.

• subject/2020-01-01/002 data from taskPC have been copied, data from ephysPC remains to be copied.

• subject/2020-01-01/003 data copied from all acquisition PCs.

Video acquisition computer

Video can be run on a separate computer, which is recommended when recording multiple cameras.

Setup

Installing drivers

Both spinnaker and pyspin must be installed before running an experiment:

cd C:\iblrigv8\
venv\scripts\Activate.ps1
install_spinnaker
install_pyspin

Settings config

The camera acquisition is configured by parameters in the ‘device_cameras’ key of the hardware_settings.yaml file. Below is an overview of the parameters:

device_cameras:
  # The name of the configuration. This is passed to the CLI.
  default:
    # This is required: the Bonsai workflows to be called by the CLI script.
    BONSAI_WORKFLOW:
      # Optional setup (e.g. alignment) workflow
      setup: devices/camera_setup/EphysRig_SetupCameras.bonsai
      # Required workflow to be called when the experiment starts
      recording: devices/camera_recordings/TrainingRig_SaveVideo_TrainingTasks.bonsai
    # Camera #1 name
    left:
      # Required camera device index (assigned in driver software)
      INDEX: 1
      # Optional expected frame height. Actual resolution should be set in the driver software.
      HEIGHT: 1024
      # Optional expected frame width. This is simply used in QC.
      WIDTH: 1280
      # Optional expected frame rate (Hz). This is simply used in QC.
      FPS: 30

Multiple configurations can be added, e.g. ‘default’, ‘training’, ‘ephys’, etc. and within each, multiple cameras can be added, e.g. ‘left’, ‘right’, ‘body’, etc. Each configuration requires a BONSAI_WORKFLOW: recording key; each camera requires an INDEX key.

Starting a task

Below shows how to start the cameras for the subject ‘example’ with configuration ‘default’:

cd C:\iblrigv8\
venv\scripts\Activate.ps1
start_video_session example default

Copy command

Usage

To initiate the data transfer from the local server to the remote server, open a terminal and type.

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data --tag video

The transfer local and remote directories are set in the iblrig/settings/iblrig_settings.py file.

Neuropixel recording with iblrigv8

This document describes how to use the iblrigv8 software to record from the Neuropixel computer.

Setup

Just make sure iblrigv8 is installed according to the instructions and that the iblrig_settings.py file is configured with the local folder and remote folder for the data transfer.

To get access to the viewephys visualizer:

cd C:\iblrigv8\
venv\scripts\Activate.ps1
pip install viewephys

Starting a task

Below shows how to start the electrophysiology for the subject ‘example’ with 2 probes:

cd C:\iblrigv8\
venv\scripts\Activate.ps1
start_ephys_session example 2

Copy command

Usage

To initiate the data transfer from the local server to the remote server, open a terminal and type.

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data --tag ephys

The transfer local and remote directories are set in the iblrig/settings/iblrig_settings.py file.

Look at the raw data

This will launch the viewephys GUI, you can then use file -> open and navigate to open the raw data file you wish to display.

cd C:\iblrigv8\
venv\scripts\Activate.ps1
viewephys

More information on the viewephys package can be found at: https://github.com/int-brain-lab/viewephys

Neurophotometrics recording with iblrigv8

This document describes how to use the iblrigv8 software to record Photometry using Neurophotometrics FP3002 system.

Setup

• iblrigv8 is installed according to the instructions

• settings/iblrig_settings.yaml file is configured with the local folder and remote folder for the data transfer.

• settings/hardware_settings.yaml file is configured with the neurophotometrics device

Starting a photometry recording

• Start the Bonsai workflow by running the following command in powershell:

cd C:\iblrigv8\
venv\scripts\Activate.ps1
start_neurophotometrics

• in Bonsai click on the FP3002 node and load the desired photometry settings file

• start the task

The photometry recording will start and the photometry data will be saved in the data local folder with the following stucture: - {local_data_folder}neurophotometricsyyyy-mm-ddTHHMMSS Where yyyy-mm-dd is the date of the recording and HHMMSS is the time of the recording.

Starting a photometry session

• Start the Bonsai workflow by running the following command in powershell:

cd C:\iblrigv8\
venv\scripts\Activate.ps1
start_photometry_session --subject=Mickey --roi G0 G1 --location NBM SI

Copy command

Usage

To initiate the data transfer from the local server to the remote server, open a terminal and type.

C:\iblrigv8\venv\scripts\Activate.ps1
transfer_data --tag photometry

The transfer local and remote directories are set in the iblrig/settings/iblrig_settings.py file.