Open-source tools for automated behavioral training and testing, designed for the homecage environment.

Summary

CalliCog is an automated platform for behavioral experiments, designed for the homecage-based cognitive training of common marmosets (Callithrix jacchus) and other small nonhuman primates. It delivers behavioral tasks via touchscreens in custom-built operant chambers made from inexpensive and publicly available materials. CalliCog runs on open-source code based in Python, and includes a custom webapp for running experiments and recording behavioral data.

Build your own CalliCog setup! See a full inventory of materials and instructions here.

If you use CalliCog, please cite the paper:
Scott, J.T., Mendivez Vasquez, B.L., Stewart, B.J., Panacheril, D., Rajit, D.K., Fan, A.Y., Bourne, J.A. (2024) CalliCog: an open-source cognitive neuroscience toolkit for freely behaving nonhuman primates. bioRxiv.

✉️ Further info or support: callicog_support@mail.nih.gov

Hardware Requirements

CalliCog uses a central computer (Executive PC) that controls the operations of up to several (at least one) operant chambers, each controlled by its own computer (Agent PC). Operant chambers also contain a Reward Module for the delivery of liquid reward, and a Camera Module for surveillance. See inventory for full details.

For software installation, the following hardware is required:

• Computer running MacOS (Executive PC). Recommended: M2 Mac Mini (Apple).
• Mini PC running Ubuntu (Agent PC). Recommended: NUC 13 (Intel).
• Arduino microcontroller (Reward Module). Recommended: Uno Rev3
• Raspberry Pi microcomputer (Camera Module). Recommended: Raspberry Pi Zero W.

Installation

• Install Executive PC (Mac)
• Install Agent PC (Mini PC)
• Install Camera Module (Raspberry Pi)

To install the Reward Module, simply upload this code to the Arduino using Arduino IDE.

Running CalliCog

Initialise the database

The CalliCog database as repository for both collected experimental data and experimental designs. It must be initialised prior to sending commands to operant chambers, or accessing data via the web app. To initialise the database, open a terminal on the Executive PC, navigate to the callicog directory, and enter:

source .venv/bin/activate
callicog start webapp

Run the web app

The web app acts as the interface to the database. It allows the user to perform experimental design and to access experimental data. Follow these links for more details.

To access the webapp:

• Ensure the database is initialised
• Open your favorite web brower (e.g. Google Chrome)
• Navigate to http://localhost:5000

Run an experiment

All subsequent steps first require the Executive PC to first be connected to an active operant chamber (Agent PC) via wired LAN. Operant chamber Agent PCs automatically run a 'listener' script on boot, and await commands from an Executive PC. Therefore, the user controls experiments directly from the Executive PC.

To begin, open a new terminal on the Executive PC, navigate to the callicog directory, and activate the virtual environment:

source .venv/bin/activate

To run a NEW experiment:

callicog run <animal> <hostname>.local <template>

# <animal> = the name of the test subject. Must be first added to the database via the webapp tab 'Animals'.
# <hostname> = your operant chamber hostname.
# <template> = a template for the experiment of choice. Must be first added to the database via the webapp tab 'Templates'.

To resume an EXISTING experiment:

callicog resume <hostname>.local <experiment_id>

# <experiment_id> = ID of the experiment. Must be listed in the database under the webapp tab 'Experiments'

For help, run callicog --help

Important

CalliCog can run multiple operant chambers simultaneously, but only one operant chamber can be controlled at a time via a terminal. To send a command to a new operant chamber, open up a new terminal.

Monitor an experiment

For video surveillance:

If an active operant chamber contains a Camera Module, live video will be streamed by default over a configured wifi network. To access the video stream:

• Ensure the Executive PC is connected to the same network.
• Open a web browser and navigate to http://raspberrypi.local/html/ (replacing 'raspberrypi' with your Raspberry Pi's hostname). See here for more info.

For touchscreen mirroring:

Operant chambers are configured as VNC servers, meaning that the display can be remotely viewed during real time experimentation. To view a screen mirror:

• Open a VNC client, e.g. RealVNC Viewer for MacOS.
• Enter the IP address or hostname (.local) to view the screen mirror.

Timing Synchronization

Behavioral data from CalliCog can be synchronized with techniques for neural recording, such as electrocorticography (ECoG), obtained wirelessly while test subjects perform behavioral tasks. This is achieved by integrating a computer that acquires neural data into the local network, and configuring this computer as a Network Time Protocol (NTP) server that synchronizes the clock on an Agent PC. The behavioral and neural data can then be temporally aligned post hoc.

NTP configuration is not a supported function of CalliCog, and it will vary depending on the user’s hardware, software and operating system used for neural recording. However, instructions on how to configure NTP can be found here. For general considerations and a troubleshooting guide regarding timing precision in CalliCog, see here.

Note

NTP is a quick, easy and inexpensive method for synchronization. However, it may not be an appropriate method for certain applications (such as single-unit electrophysiology) that require high temporal precision. Development is currently underway in CalliCog for I/O functionality that will enable alternative synchronization methods.