Rigbox is a high-performance, open-source software toolbox for managing behavioral neuroscience experiments. Initially developed to probe mouse behavior for the Steering Wheel Setup, Rigbox is under active, test-driven development to encompass a variety of experimental paradigms across behavioral neuroscience. Rigbox simplifies hardware/software interfacing, synchronizes data streams from multiple sources, manages experimental data via communication with a remote database, implements a viewing model for visual stimuli, and creates a runtime environment in which an experiment's parameters can be easily monitored and manipulated. Rigbox’s object-oriented paradigm facilitates a modular approach to designing experiments. Rigbox requires two machines, one for stimulus presentation ('the stimulus computer' or 'sc') and another for controlling and monitoring the experiment ('the master computer' or 'mc').
The following is a brief description of how to install Rigbox on your experimental rig. Detailed, step-by-step information can be found in Rigbox's documentation. Information specific to the steering wheel task can be found on the CortexLab website.
Rigbox has the following software dependencies:
- Windows Operating System (7 or later, 64-bit)
- MATLAB (2017b or later)
- The following MathWorks MATLAB toolboxes (note, these can all be downloaded and installed directly within MATLAB via the "Add-Ons" button in the "Home" top toolstrip):
- Data Acquisition Toolbox
- Signal Processing Toolbox
- Instrument Control Toolbox
- Statistics and Machine Learning Toolbox
- The following community MATLAB toolboxes:
- GUI Layout Toolbox (v2 or later)
- Psychophsics Toolbox (v3 or later)
- NI-DAQmx support package
Additionally, Rigbox works with a number of extra submodules (included):
- signals (for designing bespoke experiments)
- alyx-matlab (for registering data to, and retrieving from, an Alyx database)
- npy-matlab (for saving data in binary NPY format)
- wheelAnalysis (for analyzing data from the steering wheel task)
- It is highly recommended to install Rigbox via git. If not already downloaded and installed, install git (and the included minGW software environment and Git Bash MinTTY terminal emulator). After installing, launch the Git Bash terminal.
- To install Rigbox, run the following commands in the Git Bash terminal to clone the repository from GitHub to your local machine. (* Note: It is not recommended to clone directly into the MATLAB folder)
git clone --recurse-submodules https://github.com/cortex-lab/Rigbox
- Open MATLAB and run
addRigboxPaths.mthen restart the program. Note: Do not add all Rigbox folders and subfolders to the paths! - Set the correct paths on both computers by following the instructions in the '/docs/setup/paths_config' file.
- On the stimulus computer, set the hardware configuration by following the instructions in the '/docs/setup/hardware_config' file.
- To keep the submodules up to date, run the following in the Git Bash terminal (within the Rigbox directory):
git pull --recurse-submodules
On the stimulus computer, run:
srv.expServer
On the master computer, run:
mc
This opens the MC GUI for selecting a subject, experiment, and the SC on which to run the experiment. The MC GUI also allows for editing some experimental parameters and logging into the Alyx database. To launch the experiment on the selected SC, press 'Start'.
Below is a list of Rigbox's subdirectories and an overview of their respective contents.
The "data" package contains code pertaining to the organization and logging of data. It contains functions that generate and parse unique experiment reference ids, and return file paths where subject data and rig configuration information is stored. Other functions include those that manage experimental log entries and parameter profiles. A nice metaphor for this package is a lab notebook.
The "user interface" package contains code pertaining to the Rigbox user interface. It contains code for constructing the mc GUI (MControl.m), and for plotting live experiment data or generating tables for viewing experiment parameters and subject logs.
This package is exclusively used by the master computer.
The "experiments" package is for the initialization and running of behavioural experiments. It contains code that define a framework for event- and state-based experiments. Actions such as visual stimulus presentation or reward delivery can be controlled by experiment phases, and experiment phases are managed by an event-handling system (e.g. ResponseEventInfo).
The package also triggers auxiliary services (e.g. starting remote acquisition software), and loads parameters for presentation for each trail. The principle two base classes that control these experiments are 'Experiment' and its "signals package" counterpart, 'SignalsExp'.
This package is almost exclusively used by the stimulus computer.
The "hardware" package is for configuring, and interfacing with, hardware (such as screens, DAQ devices, weighing scales and lick detectors). Within this is the "+ptb" package which contains classes for interacting with PsychToolbox.
'devices.m' loads and initializes all the hardware for a specific experimental rig. There are also classes for unifying system and hardware clocks.
The "psychometrics" package contains simple functions for processing and plotting psychometric data.
The "stim server" package contains the 'expServer' function as well as classes that manage communications between rig computers.
The 'Service' base class allows the stimulus computer to start and stop auxiliary acquisition systems at the beginning and end of experiments.
The 'StimulusControl' class is used by the master computer to manage the stimulus computer.
- Note: Lower-level communication protocol code is found in the "cortexlab/+io" package.
"Burgbox" contains many simple helper functions that are used by the main packages. Within this directory are additional packages:
- +bui --- Classes for managing graphics objects such as axes
- +aud --- Functions for interacting with PsychoPortAudio
- +file --- Functions for simplifying directory and file management, for instance returning the modified dates for specified folders or filtering an array of directories by those that exist
- +fun --- Convenience functions for working with function handles in MATLAB, e.g. functions similar cellfun that are agnostic of input type, or ones that cache function outputs
- +img --- Classes that deal with image and frame data (DEPRECATED)
- +io --- Lower-level communications classes for managing UDP and TCP/IP Web sockets
- +plt --- A few small plotting functions (DEPRECATED)
- +vis --- Functions for returning various windowed visual stimuli (i.g. gabor gratings)
- +ws --- An early Web socket package using SuperWebSocket (DEPRECATED)
The "cortexlab" directory is intended for functions and classes that are rig or CortexLab specific, for example, code that allows compatibility with other stimulus presentation packages used by CortexLab (e.g. MPEP)
The "tests" directory contains code for running unit tests within Rigbox.
Contains various guides for how to configure and use Rigbox.
Additional information on the alyx-matlab, npy-matlab, signals and wheelAnalysis submodules can be found in their respective github repositories.
- GUI Layout Toolbox for code pertaining to Rigbox's UI
- Psychophsics Toolbox for code pertaining to visual stimulus presentation
- NI-DAQmx for code pertaining to inerfacing with a NI-DAQ device
- TooTallNate for code pertaining to using Java Websockets
Please read CONTRIBUTING.md for details on how to contribute code to this repository and our code of conduct.
The majority of the Rigbox code was written by Chris Burgess in 2013. It is now maintained and developed by Miles Wells (miles.wells@ucl.ac.uk), Jai Bhagat (j.bhagat@ucl.ac.uk) and a number of others at CortexLab. See also the full list of contributors.
Rigbox is described in-depth in this publication. Please cite this source appropriately in publications which use Rigbox to acquire data.