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 IBL Rig Wizard — A screenshot of IBLRIG Wizard

Starting a Task

Enter your Alyx username, then click on the Connect button. This action will automatically populate the GUI fields with information pertinent to your lab.
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.
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:

Run the ephys task

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

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

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.
Executing the Copy Script: The copy script is executed on each acquisition PC independently and in no particular order.
Navigating Local Session Data: The script systematically navigates through local session folders (or optionally a separate transfers folder) that contain experiment.description stubs.
Skipping Transferred Sessions: The script ignores session folders containing a file named transferred.flag (see 7).
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.
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.
Confirming Transfer Locally: A transferred.flag file is created in the local session folder to confirm the transfer’s success.
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