Command Line Interfaces
This package provides the Command Line Interfaces (CLIs) for interfacing with all user-facing library components, exposed by installing the library into a Python environment.
sl-run
Runs data acquisition and system maintenance sessions supported by the data acquisition system managed by the host-machine.
Usage
sl-run [OPTIONS] COMMAND [ARGS]...
maintenance
Runs the data acquisition system maintenance session.
Calling this command exposes a GUI for directly interfacing with a small subset of the managed data acquisition system’s components that require frequent maintenance. It does not collect any data during runtime and does not interface with the remote data storage infrastructure accessible to the data acquisition system. It is designed to perform minor (day-to-day) maintenance tasks that do not require disassembling the system’s components.
Usage
sl-run maintenance [OPTIONS]
session
Runs the specified data acquisition session for the target animal and project combination.
Usage
sl-run session [OPTIONS] COMMAND [ARGS]...
Options
- -u, --user <user>
Required The ID of the user supervising the session.
- -p, --project <project>
Required The name of the project to which the animal belongs.
- -a, --animal <animal>
Required The ID of the animal undergoing the session.
- -w, --animal_weight <animal_weight>
Required The weight of the animal, in grams, at the beginning of the session.
check-window
Runs the cranial window quality checking session.
The primary purpose of the cranial window quality checking session is to ensure that the animal is suitable for collecting high-quality brain activity data. Additionally, the session is used to generate the animal-specific data acquisition system configuration reused during all future data acquisition sessions to fine-tune the system to work for the target animal.
Usage
sl-run session check-window [OPTIONS]
experiment
Runs the specified experiment session.
Experiment runtimes are carried out after the lick and run training sessions. This command allows running any valid Sun lab experiment supported by the data acquisition system managed by the host-machine. To create a new experiment configuration for the local data-acquisition system, use the ‘sl-configure experiment’ CLI command.
Usage
sl-run session experiment [OPTIONS]
Options
- -e, --experiment <experiment>
Required The name of the experiment to carry out during runtime.
- -ur, --unconsumed_rewards <unconsumed_rewards>
The maximum number of rewards that can be delivered without the animal consuming them. If the unconsumed reward count exceeds this threshold, the system stops delivering new water rewards until the animal consumes the already delivered rewards. Setting this argument to 0 disables the reward consumption tracking.
lick-training
Runs the lick training session.
Lick training is the first phase of preparing the animal for experiment sessions, and is usually carried out over the first two days of the pre-experiment training sequence. This session teaches the animal to operate the lick-port and associate licking at the port with water delivery.
Usage
sl-run session lick-training [OPTIONS]
Options
- -t, --maximum_time <maximum_time>
The maximum time to run the training session, in minutes. Defaults to 20 minutes.
- -min, --minimum_delay <minimum_delay>
The minimum number of seconds that has to pass between two consecutive reward deliveries during training. Defaults to 6 seconds.
- -max, --maximum_delay <maximum_delay>
The maximum number of seconds that can pass between two consecutive reward deliveries during training. Defaults to 18 seconds.
- -v, --maximum_volume <maximum_volume>
The maximum volume of water, in milliliters, that can be delivered during training. Defaults to 1.0 mL.
- -ur, --unconsumed_rewards <unconsumed_rewards>
The maximum number of rewards that can be delivered without the animal consuming them. If the unconsumed reward count exceeds this threshold, the system stops delivering new water rewards until the animal consumes the already delivered rewards. Setting this argument to 0 disables the reward consumption tracking. Defaults to 1.
run-training
Runs the run training session.
Run training is the second phase of preparing the animal for experiment sessions, and is usually carried out over the five days following the lick training sessions. This session teaches the animal to run on the wheel treadmill while being head-fixed and associate getting water rewards with running on the treadmill. Over the course of training, the task requirements are adjusted to prepare the animal to perform as many laps as possible during experiment sessions lasting ~60 minutes.
Usage
sl-run session run-training [OPTIONS]
Options
- -t, --maximum_time <maximum_time>
The maximum time to run the training session, in minutes. Defaults to 40 minutes.
- -is, --initial_speed <initial_speed>
The initial speed, in centimeters per second, the animal must maintain to obtain water rewards. Defaults to 0.8 cm/s.
- -id, --initial_duration <initial_duration>
The initial duration, in seconds, the animal must maintain above-threshold running speed to obtain water rewards. Defaults to 1.5 seconds.
- -it, --increase_threshold <increase_threshold>
The volume of water delivered to the animal, in milliliters, after which the speed and duration thresholds are increased by the specified step-sizes. This is used to make the training progressively harder for the animal over the course of the training session. Defaults to 0.1 mL.
- -ss, --speed_step <speed_step>
The amount, in centimeters per second, to increase the speed threshold each time the animal receives the volume of water specified by the ‘increase-threshold’ parameter. Defaults to 0.05 cm/s.
- -ds, --duration_step <duration_step>
The amount, in seconds, to increase the duration threshold each time the animal receives the volume of water specified by the ‘increase-threshold’ parameter. Defaults to 0.1 seconds.
- -v, --maximum_volume <maximum_volume>
The maximum volume of water, in milliliters, that can be delivered during training. Defaults to 1.0 mL.
- -mit, --maximum_idle_time <maximum_idle_time>
The maximum time, in seconds, the animal is allowed to maintain the speed that is below the speed threshold and still receive the water reward. Setting this argument to 0 forces the animal to maintain the above-threshold speed at all times. Defaults to 0.3 seconds.
- -ur, --unconsumed_rewards <unconsumed_rewards>
The maximum number of rewards that can be delivered without the animal consuming them. If the unconsumed reward count exceeds this threshold, the system stops delivering new water rewards until the animal consumes the already delivered rewards. Setting this argument to 0 disables the reward consumption tracking. Defaults to 1.
sl-manage
Manages the data accessible to the data acquisition system managed by the local host-machine.
Usage
sl-manage [OPTIONS] COMMAND [ARGS]...
delete
Removes the target session’s data from all destinations accessible to the data acquisition system.
This is an extremely dangerous command that can potentially delete valuable data if used carelessly. This command removes the session’s data from all machines of the data acquisition system and all long-term storage destinations accessible to the data acquisition system.
Usage
sl-manage delete [OPTIONS]
Options
- -sp, --session-path <session_path>
Required The path to the data acquisition session’s directory to remove.
mcp
Starts the MCP server for agentic access to sl-manage tools.
Usage
sl-manage mcp [OPTIONS]
Options
- -t, --transport <transport>
The MCP transport type (‘stdio’, ‘sse’, or ‘streamable-http’).
- Default:
'stdio'
migrate
Transfers all sessions for the specified animal from the source project to the target project.
Usage
sl-manage migrate [OPTIONS]
Options
- -s, --source <source>
Required The name of the project from which to migrate the data.
- -d, --destination <destination>
Required The name of the project to which to migrate the data.
- -a, --animal <animal>
Required The ID of the animal whose data to migrate.
preprocess
Preprocesses the target session’s data stored on the data acquisition system’s host-machine.
Usage
sl-manage preprocess [OPTIONS]
Options
- -sp, --session-path <session_path>
Required The path to the data acquisition session’s directory to preprocess.
sl-get
Evaluates the composition of the data acquisition system managed by the host-machine.
Usage
sl-get [OPTIONS] COMMAND [ARGS]...
cameras
Identifies the cameras accessible to the data acquisition system.
Usage
sl-get cameras [OPTIONS]
checksum
Calculates the CRC32-XFER checksum for the input string.
Usage
sl-get checksum [OPTIONS]
Options
- -i, --input_string <input_string>
The string for which to compute the checksum.
controllers
Identifies the microcontrollers accessible to the data acquisition system.
Usage
sl-get controllers [OPTIONS]
experiments
Identifies the target project’s experiment configurations accessible to the data acquisition system.
Usage
sl-get experiments [OPTIONS]
Options
- -p, --project <project>
Required The name of the project for which to discover the available experiment configurations.
mcp
Starts the MCP server for agentic access to sl-get tools.
Usage
sl-get mcp [OPTIONS]
Options
- -t, --transport <transport>
The MCP transport type (‘stdio’, ‘sse’, or ‘streamable-http’).
- Default:
'stdio'
ports
Identifies the serial communication ports accessible to the data acquisition system.
Usage
sl-get ports [OPTIONS]
projects
Identifies the projects accessible to the data acquisition system.
Usage
sl-get projects [OPTIONS]
zaber
Identifies the Zaber devices accessible to the data acquisition system.
Usage
sl-get zaber [OPTIONS]
Mesoscope-VR Acquisition System
This package provides the assets for acquiring and preprocessing data via the Mesoscope-VR data acquisition system.
- class sl_experiment.mesoscope_vr.CRCCalculator
Bases:
objectExposes methods for calculating CRC32-XFER checksums for ASCII strings.
- _calculator
The configured Calculator instance used to calculate the checksums.
- string_checksum(string)
Calculates the CRC32-XFER checksum for the input string.
- Parameters:
string (
str) – The string for which to calculate the CRC checksum.- Return type:
int- Returns:
The integer CRC32-XFER checksum.
- class sl_experiment.mesoscope_vr.ZaberDeviceSettings(device_label, axis_label, checksum, shutdown_flag, unsafe_flag, park_position, maintenance_position, mount_position, limit_min, limit_max, current_position)
Bases:
objectStores configuration settings read from a Zaber device’s non-volatile memory.
-
axis_label:
str The user-assigned name of the axis.
-
checksum:
int The CRC32-XFER checksum stored in USER_DATA_0.
-
current_position:
float The current absolute position of the motor in native motor units.
-
device_label:
str The user-assigned name of the device.
-
limit_max:
float The maximum allowed position relative to home in native motor units.
-
limit_min:
float The minimum allowed position relative to home in native motor units.
-
maintenance_position:
int The maintenance position in native motor units stored in USER_DATA_12.
-
mount_position:
int The mount position in native motor units stored in USER_DATA_13.
-
park_position:
int The park position in native motor units stored in USER_DATA_11.
-
shutdown_flag:
int The shutdown flag stored in USER_DATA_1 (1 = proper shutdown, 0 = abnormal).
-
unsafe_flag:
int The unsafe flag stored in USER_DATA_10 (1 = requires safe position for homing).
-
axis_label:
- class sl_experiment.mesoscope_vr.ZaberValidationResult(is_valid, checksum_valid, positions_valid, errors, warnings)
Bases:
objectStores the results of validating a Zaber device’s configuration.
-
checksum_valid:
bool Determines whether the stored checksum matches the calculated checksum for the device label.
-
errors:
tuple[str,...] Contains critical issues that prevent the device from being used with the binding library.
-
is_valid:
bool Determines whether the device configuration is valid for use with the binding library.
-
positions_valid:
bool Determines whether all predefined positions are within the device motion limits.
-
warnings:
tuple[str,...] Contains non-critical issues that may affect device operation.
-
checksum_valid:
- sl_experiment.mesoscope_vr.discover_zaber_devices()
Scans all available serial ports and displays information about connected Zaber devices.
Note
Connection errors encountered during scanning are logged at DEBUG level and do not interrupt the discovery process. Ports that cannot be connected are listed as having “No Devices”.
- Return type:
None
- sl_experiment.mesoscope_vr.experiment_logic(experimenter, project_name, experiment_name, animal_id, animal_weight, maximum_unconsumed_rewards=None)
Runs experiments using the Virtual Reality task environments and collects the brain activity data via the mesoscope.
Notes
Each experiment is conceptualized as a sequence of experiment states (phases), which define the task and the types of data being collected while the system maintains the state. During the session, the system executes the predefined sequence of states defines in the experiment’s configuration file. Once all states are executed, the experiment session ends.
During the session’s runtime, the task logic and the Virtual Reality world are resolved by the Unity game engine. This function handles the data collection and the overall runtime management.
The maximum_unconsumed_rewards argument is an optional override. If not provided, the system loads the argument’s value used during a previous session (if available) or uses a system-defined default value.
- Parameters:
experimenter (
str) – The unique identifier of the experimenter conducting the experiment session.project_name (
str) – The name of the project in which the experimental animal participates.experiment_name (
str) – The name of the experiment to be conducted.animal_id (
str) – The unique identifier of the animal participating in the experiment.animal_weight (
float) – The weight of the animal, in grams, at the beginning of the session.maximum_unconsumed_rewards (
int|None, default:None) – The maximum number of rewards that can be delivered without the animal consuming them, before the system suspends delivering water rewards until the animal consumes all available rewards. Setting this argument to 0 disables forcing reward consumption.
- Return type:
None
- sl_experiment.mesoscope_vr.get_zaber_device_settings(port, device_index)
Reads configuration settings from a Zaber device’s non-volatile memory.
- Parameters:
port (
str) – Serial port path (e.g., “/dev/ttyUSB0”).device_index (
int) – Zero-based index in the daisy-chain (0 = closest to USB port).
- Return type:
- Returns:
A ZaberDeviceSettings instance containing the device configuration including labels, positions, flags, and motion limits.
- Raises:
ConnectionError – If unable to connect to the specified port.
IndexError – If device_index is out of range for the connected devices.
- sl_experiment.mesoscope_vr.get_zaber_devices_info()
Scans all available serial ports for Zaber devices and returns formatted device information.
- Return type:
str- Returns:
A formatted table string containing port, device, and axis information for all discovered Zaber devices. Ports with connection errors are listed as having “No Devices”.
Notes
This function is designed for programmatic access to Zaber device information, such as from MCP tools. Connection errors encountered during scanning are logged at DEBUG level and do not interrupt the discovery process.
- sl_experiment.mesoscope_vr.lick_training_logic(experimenter, project_name, animal_id, animal_weight, reward_size=None, reward_tone_duration=None, minimum_reward_delay=None, maximum_reward_delay=None, maximum_water_volume=None, maximum_training_time=None, maximum_unconsumed_rewards=None)
Trains the animal to operate the lickport used by the Mesoscope-VR data acquisition system.
Notes
The training consists of delivering water rewards via the lickport at pseudorandom intervals to teach the animal that rewards come out of the lick port. The training continues either until the valve delivers the ‘maximum_water_volume’ in milliliters or until the ‘maximum_training_time’ in minutes is reached, whichever comes first.
Most arguments to this function are optional overrides. If an argument is not provided, the system loads the argument’s value used during a previous runtime (if available) or uses a system-defined default value.
- Parameters:
experimenter (
str) – The unique identifier of the experimenter conducting the training session.project_name (
str) – The name of the project in which the trained animal participates.animal_id (
str) – The unique identifier of the animal being trained.animal_weight (
float) – The weight of the animal, in grams, at the beginning of the session.reward_size (
float|None, default:None) – The volume of water, in microliters, to use when delivering water rewards to the animal.reward_tone_duration (
int|None, default:None) – The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards.minimum_reward_delay (
int|None, default:None) – The minimum time, in seconds, that has to pass between delivering two consecutive rewards.maximum_reward_delay (
int|None, default:None) – The maximum time, in seconds, that can pass between delivering two consecutive rewards.maximum_water_volume (
float|None, default:None) – The maximum volume of water, in milliliters, that can be delivered to the animal during the session.maximum_training_time (
int|None, default:None) – The maximum training time, in minutes.maximum_unconsumed_rewards (
int|None, default:None) – The maximum number of rewards that can be delivered without the animal consuming them, before the system suspends delivering water rewards until the animal consumes all available rewards. Setting this argument to 0 disables forcing reward consumption.
- Return type:
None
- sl_experiment.mesoscope_vr.maintenance_logic()
Encapsulates the logic used to maintain a subset of the Mesoscope-VR system’s hardware components.
- Return type:
None
- sl_experiment.mesoscope_vr.migrate_animal_between_projects(animal, source_project, target_project)
Transfers all sessions performed by the specified animal from the source project to the target project across all storage locations.
- Parameters:
animal (
str) – The animal for which to migrate the data.source_project (
str) – The name of the project from which to migrate the data.target_project (
str) – The name of the project to which the data should be migrated.
- Return type:
None
- sl_experiment.mesoscope_vr.preprocess_session_data(session_data)
Aggregates all session’s data on VRPC, compresses it for efficient network transmission, transfers the data to the BioHPC server and the Synology NAS, and removes the local data copy from the VRPC.
- Parameters:
session_data (
SessionData) – The SessionData instance that defines the processed session.- Return type:
None
- sl_experiment.mesoscope_vr.purge_session(session_data)
Removes all data and directories associated with the input session from all Mesoscope-VR system machines and long-term storage destinations.
Notes
This function is extremely dangerous and should be used with caution. It is designed to remove all data from failed or no longer necessary sessions from all storage locations. Never use this function on sessions that contain valid scientific data.
- Parameters:
session_data (
SessionData) – The SessionData instance that defines the session whose data needs to be removed.- Return type:
None
- sl_experiment.mesoscope_vr.run_training_logic(experimenter, project_name, animal_id, animal_weight, reward_size=None, reward_tone_duration=None, initial_speed_threshold=None, initial_duration_threshold=None, speed_increase_step=None, duration_increase_step=None, increase_threshold=None, maximum_water_volume=None, maximum_training_time=None, maximum_idle_time=None, maximum_unconsumed_rewards=None)
Trains the animal to run on the wheel treadmill while being head-fixed.
Notes
The run training consists of making the animal run on the wheel with a desired speed, in centimeters per second, maintained for the desired duration of time, in seconds. Each time the animal satisfies the speed and duration thresholds, it receives a water reward, and the speed and duration trackers reset for the next training ‘epoch’. Each time the animal receives ‘increase_threshold’ of water, the speed and duration thresholds increase to make the task progressively more challenging. The training continues either until the training time exceeds the ‘maximum_training_time’, or the animal receives the ‘maximum_water_volume’ of water, whichever happens earlier.
Most arguments to this function are optional overrides. If an argument is not provided, the system loads the argument’s value used during a previous session (if available) or uses a system-defined default value.
- Parameters:
experimenter (
str) – The unique identifier of the experimenter conducting the training session.project_name (
str) – The name of the project in which the trained animal participates.animal_id (
str) – The unique identifier of the animal being trained.animal_weight (
float) – The weight of the animal, in grams, at the beginning of the session.reward_size (
float|None, default:None) – The volume of water, in microliters, to use when delivering water rewards to the animal.reward_tone_duration (
int|None, default:None) – The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards.initial_speed_threshold (
float|None, default:None) – The initial running speed threshold, in centimeters per second, that the animal must maintain to receive water rewards.initial_duration_threshold (
float|None, default:None) – The initial duration threshold, in seconds, that the animal must maintain above-threshold running speed to receive water rewards.speed_increase_step (
float|None, default:None) – The step size, in centimeters per second, by which to increase the speed threshold each time the animal receives ‘increase_threshold’ milliliters of water.duration_increase_step (
float|None, default:None) – The step size, in seconds, by which to increase the duration threshold each time the animal receives ‘increase_threshold’ milliliters of water.increase_threshold (
float|None, default:None) – The volume of water received by the animal, in milliliters, after which the speed and duration thresholds are increased by one step.maximum_water_volume (
float|None, default:None) – The maximum volume of water, in milliliters, that can be delivered to the animal during the session.maximum_training_time (
int|None, default:None) – The maximum training time, in minutes.maximum_idle_time (
float|None, default:None) – The maximum time, in seconds, the animal’s speed can be below the speed threshold to still receive water rewards. This parameter is designed to help animals with a distinct ‘step’ pattern to not lose water rewards due to taking many large steps, rather than continuously running at a stable speed. Setting this argument to 0 disables this functionality.maximum_unconsumed_rewards (
int|None, default:None) – The maximum number of rewards that can be delivered without the animal consuming them, before the system suspends delivering water rewards until the animal consumes all available rewards. Setting this argument to 0 disables forcing reward consumption.
- Return type:
None
- sl_experiment.mesoscope_vr.set_zaber_device_setting(port, device_index, setting, value)
Writes a configuration setting to a Zaber device’s non-volatile memory.
Notes
Position values are validated against device motion limits before writing. Label changes automatically update the checksum (USER_DATA_0) to maintain device validation. The checksum setting cannot be modified directly as it is managed by the binding library.
- Parameters:
port (
str) – Serial port path (e.g., “/dev/ttyUSB0”).device_index (
int) – Zero-based index in the daisy-chain (0 = closest to USB port).setting (
str) – Setting name. Valid options are park_position, maintenance_position, mount_position, unsafe_flag, shutdown_flag, device_label, and axis_label.value (
int|str) – Value to write. Use integers for positions and flags, strings for labels.
- Return type:
str- Returns:
A success message containing the old and new values.
- Raises:
ConnectionError – If unable to connect to the specified port.
IndexError – If device_index is out of range for the connected devices.
ValueError – If the setting name is invalid, the value type is incorrect, or the value is out of range.
- sl_experiment.mesoscope_vr.validate_zaber_device_configuration(port, device_index)
Validates a Zaber device’s configuration for use with the binding library.
Notes
Performs comprehensive validation including checksum verification against the device label, position bounds checking against motion limits, and configuration completeness verification.
- Parameters:
port (
str) – Serial port path (e.g., “/dev/ttyUSB0”).device_index (
int) – Zero-based index in the daisy-chain (0 = closest to USB port).
- Return type:
- Returns:
A ZaberValidationResult instance containing validation status, error messages, and warnings.
- Raises:
ConnectionError – If unable to connect to the specified port.
IndexError – If device_index is out of range for the connected devices.
- sl_experiment.mesoscope_vr.window_checking_logic(experimenter, project_name, animal_id)
Guides the user though verifying the quality of the implanted cranial window and generating the initial Mesoscope-VR system configuration for the target animal.
- Parameters:
experimenter (
str) – The unique identifier of the experimenter conducting the window checking session.project_name (
str) – The name of the project in which the evaluated animal participates.animal_id (
str) – The unique identifier of the animal being evaluated.
- Return type:
None