Cue-light tools

Cue light analyzer

class simba.data_processors.cue_light_analyzer.CueLightAnalyzer(config_path, data_dir, cue_light_names, save_dir=None, core_cnt=- 1, detailed_data=False, verbose=True)

Bases: simba.mixins.config_reader.ConfigReader

Analyze when cue lights are in ON and OFF states. Results are stored in the project_folder/csv/cue_lights cue lights directory.

For each cue-light ROI, the mean pixel intensity inside the ROI is measured every frame; a 1D k-means (k=2) splits the intensity series into a low (OFF) and high (ON) cluster, assigning each frame an ON/OFF label. Brief flicker bouts (shorter than a small time threshold) are dropped, and ON-bout onsets/offsets are written out.

Parameters

• config_path (Union[str, os.PathLike],) – path to SimBA project config file in Configparser format

• data_dir (Union[str, os.PathLike],) – directory holding pose-estimation data. E.g., project_folder/csv/outlier_corrected_movement_location

• cue_light_names (List[str]) – Names of cue light ROIs, as defined in the SimBA ROI interface.

Note

Cue light tutorials.

References

1

López-Moraga, A., Luyten, L., & Beckers, T. (2025). Generalization and extinction of platform-mediated avoidance in male and female rats. Scientific Reports, 15, 9730.

Example

>>> cue_light_analyzer = CueLightAnalyzer(config_path='MyProjectConfig', in_dir='project_folder/csv/outlier_corrected_movement_location', cue_light_names=['Cue_light'])
>>> cue_light_analyzer.run()

Cue light classification statistics

class simba.data_processors.cue_light_clf_statistics.CueLightClfAnalyzer(config_path, cue_light_names, clf_names, data_dir=None, pre_window=0, post_window=0)

Bases: simba.mixins.config_reader.ConfigReader

Compute aggregate statistics when classified behaviors are occurring in relation to the cue light ON and OFF states.

For every cue-light ON bout, the time each classifier is PRESENT vs ABSENT is tallied in three windows: the pre_window seconds before bout onset, DURING the bout, and the post_window seconds after bout offset. Present seconds are the classified frames divided by FPS; absent seconds are the window remainder.

Parameters

• config_path (Union[str, os.PathLike]) – path to SimBA project config file in Configparser format

• pre_window (int) – Time period (in millisecond) before the onset of each cue light to compute aggregate classification statistics within.

• post_window (int) – Time period (in millisecond) after the offset of each cue light to compute aggregate classification statistics within.

• cue_light_names (List[str]) – Names of cue lights, as defined in the SimBA ROI interface.

• list (List[str]) – Names of the classifiers we want to compute aggregate statistics for.

Note

Cue light tutorials.

Example

>>> test = CueLightClfAnalyzer(config_path=r"C:     roubleshooting\cue_light        1\project_folder\project_config.ini",
>>>                            pre_window=1,
>>>                            post_window=1,
>>>                            cue_light_names=['cl'],
>>>                            clf_names=['freeze'])
>>> test.run()
>>> test.save()

Cue light movement statistics

class simba.data_processors.cue_light_movement_statistics.CueLightMovementAnalyzer(config_path, cue_light_names, bp_name, data_dir=None, pre_window=0, post_window=0, verbose=True)

Bases: simba.mixins.config_reader.ConfigReader

Compute aggregate statistics of animal movement in relation to the cue light ON and OFF states.

For every cue-light ON bout, a body-part’s distance moved (cm) and mean velocity (cm/s) are computed in three windows: the pre_window seconds before bout onset, DURING the bout, and the post_window seconds after bout offset (distance summed over frames, velocity averaged over 1-second windows).

Parameters

• config_path (str) – path to SimBA project config file in Configparser format

• pre_window (int) – Time period (in millisecond) before the onset of each cue light to compute aggregate classification statistics within.

• post_window (int) – Time period (in millisecond) after the offset of each cue light to compute aggregate classification statistics within.

• cue_light_names (List[str]) – Names of cue lights, as defined in the SimBA ROI interface.

• threshold (float) – The body-part post-estimation probability threshold. SimBA omits movement calculations for frames where the body-part probability threshold is lower than the user-specified threshold.

Note

Cue light tutorials.

Examples

>>> test = CueLightMovementAnalyzer(config_path=r"C:        roubleshooting\cue_light        1\project_folder\project_config.ini",
>>>                                 pre_window=0,
>>>                                 post_window=0,
>>>                                 cue_light_names=['cl'],
>>>                                 data_dir=r"C:   roubleshooting\cue_light        1\project_folder\csv\cue_lights",
>>>                                 bp_name='Nose')
>>>
>>> test.run()
>>> test.save()

Cue light plotting

class simba.plotting.cue_light_visualizer.CueLightVisualizer(config_path, cue_light_names, video_path, data_path, frame_setting=False, video_setting=True, core_cnt=- 1, show_pose=True, verbose=True)

Bases: simba.mixins.config_reader.ConfigReader

Visualize SimBA computed cue-light ON and OFF states and the aggregate statistics of ON and OFF states.

Parameters

• config_path (str) – path to SimBA project config file in Configparser format.

• cue_light_names (List[str]) – Names of cue lights, as defined in the SimBA ROI interface.

• video_path (str) – Path to video which user wants to create visualizations of cue light states and aggregate statistics for.

• frame_setting (bool) – If True, creates individual frames in png format. Defaults to False.

• video_setting (bool) – If True, creates compressed videos in mp4 format. Defaults to True.

Examples

>>> cue_light_visualizer = CueLightVisualizer(config_path='SimBAConfig', cue_light_names=['Cue_light'], video_path='VideoPath', video_setting=True, frame_setting=False)
>>> cue_light_visualizer.run()