Command Line Interfaces

sl-behavior

Processes the behavior data stored inside one or more .npz log archives of the target session.

This command functions as the entry point for processing the data stored in the .npz log archives generated by the sl-experiment library during runtime. If no specific job flags or job identifiers are provided, the pipeline processes all available log files. If a unique job identifier is provided, the pipeline only executes that specific job.

Usage

sl-behavior [OPTIONS]

Options

-sp, --session-path <session_path>: Required The absolute path to the session’s root data directory to process.

-id, --job-id <job_id>: The unique hexadecimal identifier for this processing job. If provided, runs only the matching job (remote mode).

--runtime: Determines whether to process the session’s runtime data.

--face-camera: Determines whether to process the face camera timestamps.

--body-camera: Determines whether to process the body camera timestamps.

--actor: Determines whether to process the Actor microcontroller data.

--sensor: Determines whether to process the Sensor microcontroller data.

--encoder: Determines whether to process the Encoder microcontroller data.

-w, --workers <workers>: The number of worker processes to use. Set to -1 (default) to use all available CPU cores.

Camera Data Processing

This module provides the assets for extracting the camera frame acquisition timestamps from the .npz log archives generated by behavior video cameras used in the Sun lab.

sl_behavior.camera.CAMERA_OUTPUT_NAMES: dict[int, str] = {CameraLogIds.FACE: 'face_camera_timestamps', CameraLogIds.BODY: 'body_camera_timestamps'}: Maps supported camera log identifiers to output file names.

class sl_behavior.camera.CameraLogIds(*values)

Bases: IntEnum

Defines the log file identifiers for behavior video cameras used by the Mesoscope-VR system.

BODY = 62: The log file identifier for the body camera.

FACE = 51: The log file identifier for the face camera.

sl_behavior.camera.process_camera_timestamps(session_path, log_id, workers=-1)

Reads the specified camera log .npz file and extracts the frame acquisition timestamps as an uncompressed .feather file.

This function is used to process the log archives generated by Mesoscope-VR video cameras used in the Sun lab. It assumes that the data was logged using the assets from the ataraxis-video-system library.

Parameters:

session_path (Path) – The path to the session’s data directory for which to process the camera log file.
log_id (int) – The unique identifier of the camera log file to process: 51 (face) or 62 (body).
workers (int, default: -1) – The number of worker processes to use for extracting the camera frame timestamps in parallel. Setting this argument to a value less than 1 uses all available CPU cores. Setting this to a value of 1 conducts the processing sequentially.

Return type:

None

Runtime Data Processing

This module provides the assets for extracting the acquisition-system and runtime task data from the .npz log archives generated by data acquisition systems used in the Sun lab.

sl_behavior.runtime.process_runtime_data(session_path)

Extracts acquisition system and runtime (task) data from the data acquisition system .npz log file.

Notes

This function is used to process the log archives generated by the Mesoscope-VR data acquisition system used in the Sun lab. It assumes that the data was logged using the assets from the sl-experiment library and that the acquisition system log file uses the source ID ‘1’.

Parameters:: session_path (Path) – The path to the session directory for which to process the acquisition system log file.
Return type:: None

MicroController Data Processing

This module provides the assets for extracting the behavior data from the .npz log archives generated by the microcontrollers (hardware modules) used in the Sun lab.

class sl_behavior.microcontrollers.MicrocontrollerLogIds(*values)

Bases: IntEnum

Defines the log file identifiers for microcontrollers used by the Mesoscope-VR data acquisition system.

ACTOR = 101: The log file identifier for the Actor microcontroller.

ENCODER = 203: The log file identifier for the Encoder microcontroller.

SENSOR = 152: The log file identifier for the Sensor microcontroller.

sl_behavior.microcontrollers.process_microcontroller_data(session_path, log_id, workers=-1)

Reads the specified microcontroller log .npz file and extracts the behavior data recorded by the hardware modules managed by the microcontroller as uncompressed .feather files.

This function is used to process the log archives generated by the microcontrollers used in the Sun lab. It assumes that the data was logged using the assets from the ataraxis-communication-interface library.

Parameters:

session_path (Path) – The path to the session directory for which to process the microcontroller log file.
log_id (int) – The unique identifier of the microcontroller log file to process: 101 (actor), 152 (sensor), or 203 (encoder).
workers (int, default: -1) – The number of worker processes to use for extracting the hardware module messages in parallel. Setting this argument to a value less than 1 uses all available CPU cores. Setting this to a value of 1 conducts the processing sequentially.

Return type:

None