Direction between animals

Create videos visualizing when animals direct their gaze toward body parts of other animals (single-threaded).

Draws directional lines from eye positions (calculated from nose and ear coordinates) to target body parts. For faster processing of large videos, use DirectingOtherAnimalsVisualizerMultiprocess.

Important

Requires pose-estimation data for left ear, right ear, and nose of each animal. Project must contain at least 2 animals.

Note

Tutorial.

See also

For improved runtime, consider multiprocess class at simba.plotting.directing_animals_visualizer_mp.DirectingOtherAnimalsVisualizerMultiprocess().

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Union[str, os.PathLike] video_path

Path to video file. Corresponding data file must exist in outlier_corrected_movement_location directory.

param Dict[str, Any] style_attr

Video style attributes with required keys: ‘show_pose’ (bool), ‘animal_names’ (bool), ‘circle_size’ (int or None), ‘directionality_color’ (RGB tuple, list of tuples, or ‘Random’), ‘direction_thickness’ (int or None), ‘highlight_endpoints’ (bool).

param Optional[str] left_ear_name

Left ear body part name. If None, auto-detected. Must provide all three body part names or none.

param Optional[str] right_ear_name

Right ear body part name. If None, auto-detected.

param Optional[str] nose_name

Nose body part name. If None, auto-detected.

raises AnimalNumberError

If project contains fewer than 2 animals.

raises NoFilesFoundError

If pose-estimation data file not found.

raises InvalidInputError

If body part names partially provided.

example

>>> style_attr = {'show_pose': True, 'animal_names': True, 'circle_size': 3, 'directionality_color': [(255, 0, 0), (0, 0, 255)], 'direction_thickness': 10, 'highlight_endpoints': True}
>>> visualizer = DirectingOtherAnimalsVisualizer(config_path='project_config.ini', video_path='video.avi', style_attr=style_attr)
>>> visualizer.run()

Direction between animals - multiprocess

Create videos visualizing when animals direct their gaze toward body parts of other animals using multiprocessing.

Draws directional lines from eye positions (calculated from nose and ear coordinates) to target body parts. Uses parallel processing across CPU cores for faster video creation.

Important

Requires pose-estimation data for left ear, right ear, and nose of each animal. Project must contain at least 2 animals.

Note

Tutorial.

See also

For single core function, see simba.plotting.directing_animals_visualizer.DirectingOtherAnimalsVisualizer().

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Union[str, os.PathLike] video_path

Path to video file. Corresponding pose data must exist in outlier_corrected_movement_location directory.

param Dict[str, Any] style_attr

Style attributes with keys: ‘show_pose’, ‘animal_names’, ‘circle_size’, ‘directionality_color’, ‘direction_thickness’, ‘highlight_endpoints’. See example.

param Optional[int] core_cnt

Number of CPU cores. -1 = all available. Default -1.

param Optional[Dict[str, str]] time_slice

If set, restrict to time period. Dict with keys ‘start_time’ and ‘end_time’ (HH:MM:SS). Default None.

param Optional[str] left_ear_name

Left ear body-part name. If None, auto-detected. Must provide all three body parts or none.

param Optional[str] right_ear_name

Right ear body-part name. If None, auto-detected.

param Optional[str] nose_name

Nose body-part name. If None, auto-detected.

param float line_opacity

Opacity of direction lines (0.0–1.0). Default 1.0.

raises AnimalNumberError

If project contains fewer than 2 animals.

raises NoFilesFoundError

If pose-estimation data file not found.

raises InvalidInputError

If body part names partially provided.

example

>>> style_attr = {'show_pose': True, 'animal_names': False, 'circle_size': 3, 'directionality_color': [(255, 0, 0), (0, 0, 255)], 'direction_thickness': None, 'highlight_endpoints': True}
>>> visualizer = DirectingOtherAnimalsVisualizerMultiprocess(config_path='project_config.ini', video_path='video.avi', style_attr=style_attr, core_cnt=-1)
>>> visualizer.run()

ROI feature visualization

Visualizing features that depend on the relationships between the location of the animals and user-defined ROIs. E.g., distances to centroids of ROIs, if animals are directing towards ROIs, and if animals are within ROIs.

Note

For improved run-time, see simba.ROI_feature_visualizer_mp.ROIfeatureVisualizerMultiprocess() for multiprocess class. Tutorials.

param Union[str, os.PathLike] config_path

Path to SimBA project config file in Configparser format

param Union[str, os.PathLike] video_path

Path to video file to overlay ROI features on.

param List[str] body_parts

List of body-parts to use as proxy for animal location(s).

param Dict[str, Any] style_attr

User-defined styles (sizes, colors etc.)

example

>>> style_attr = {'roi_centers': True, 'roi_ear_tags': True, 'directionality': True, 'directionality_style': 'funnel', 'border_color': (0, 0, 0), 'pose_estimation': True, 'animal_names': True}
>>> test = ROIfeatureVisualizer(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/project_config.ini', video_path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/2022-06-20_NOB_DOT_4.mp4', style_attr=style_attr, body_parts=['Nose'])
>>> test.run()

ROI feature visualization - multiprocess

Visualize features that depend on the relationships between the location of the animals and user-defined ROIs. E.g., distances to centroids of ROIs, cumulative time spent in ROIs, if animals are directing towards ROIs etc. Uses multiprocessing for faster rendering.

param Union[str, os.PathLike] config_path

Path to SimBA project config file in Configparser format.

param Union[str, os.PathLike] video_path

Path to video file to overlay ROI features on.

param List[str] body_parts

List of body-parts to use as proxy for animal location(s). One per animal.

param bool show_roi_centers

If True, draw the center point of each ROI on the video. Default True.

param bool show_roi_eartags

If True, draw ear-tag labels on ROI shapes. Default False.

param bool show_animal_names

If True, display animal names on the video. Default False.

param Tuple[int, int, int] border_bg_clr

RGB tuple for the background color of the border panel where ROI stats are shown. Default (0, 0, 0).

param Optional[Literal[‘funnel’, ‘lines’]] direction

If not None, draw directionality (animal directing towards ROI). 'funnel' or 'lines' style. Default None (no directionality).

param Optional[Literal[‘axis-aligned’, ‘animal-aligned’]] bbox

If not None, draw bounding boxes around each animal. 'axis-aligned' = rectangle aligned with video axes; 'animal-aligned' = minimum rotated rectangle. Default None (no bounding boxes).

param Optional[Union[str, os.PathLike]] roi_coordinates_path

Optional path to ROI definitions file. If None, uses project default from config. Default None.

param bool show_pose

If True, draw pose-estimation keypoints (circles) on the video. Default True.

param int core_cnt

Number of CPU cores for multiprocessing. -1 uses all available. Default -1.

param bool gpu

If True, use GPU for video concatenation when available. Default False.

Note

Tutorials. See simba.ROI_feature_visualizer.ROIfeatureVisualizer() for single process class. Would be slower but potentially more reliable.

example

>>> test = ROIfeatureVisualizerMultiprocess(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/spontenous_alternation/project_folder/project_config.ini',
...     video_path='/Users/simon/Desktop/envs/simba/troubleshooting/spontenous_alternation/project_folder/videos/NOR ENCODING FExMP8.mp4',
...     body_parts=['Center'],
...     show_roi_centers=True,
...     show_roi_eartags=False,
...     direction='funnel',
...     show_pose=True,
...     show_animal_names=True,
...     core_cnt=-1)
>>> test.run()

ROI directing visualization

class simba.plotting.roi_directing_visualizer.DirectingROIVisualizer(config_path: Union[str, PathLike], video_path: Union[str, PathLike], direction_style: typing_extensions.Literal['funnel', 'lines'] = 'lines', direction_color: Tuple[int, int, int] = (0, 0, 255), direction_thickness: Optional[int] = None, circle_size: Optional[int] = None, show_pose: bool = True, show_roi_centers: bool = True, show_animal_names: bool = False, border_bg_clr: Tuple[int, int, int] = (0, 0, 0), time_slice: Optional[Dict[str, str]] = None, roi_coordinates_path: Optional[Union[str, PathLike]] = None, left_ear_name: Optional[str] = None, right_ear_name: Optional[str] = None, nose_name: Optional[str] = None, core_cnt: int = -1, gpu: bool = False, verbose: bool = True)

Bases: ConfigReader, PlottingMixin

Visualize when animals are directing towards ROIs. Draws the ROIs on the video frames, overlays pose-estimation body-parts, and draws directing lines (funnel or line style) from the animal eye midpoint to the ROI when the animal is directing towards the ROI. A text panel shows the directing boolean for each animal-ROI combination per frame. Uses multiprocessing.

Parameters

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

• video_path (Union[str, os.PathLike]) – Path to video file to overlay directing visualization on.

• direction_style (Literal['funnel', 'lines']) – Style of direction line. Default ‘funnel’.

• direction_color (Tuple[int, int, int]) – BGR color of the directing line. Default (0, 0, 255) (red).

• direction_thickness (Optional[int]) – Thickness of the directing line (used for ‘lines’ style). If None, computed automatically based on video resolution. Default None.

• circle_size (Optional[int]) – Size of the pose-estimation keypoint circles. If None, computed automatically based on video resolution. Default None.

• show_pose (bool) – If True, draw pose-estimation keypoints on the video. Default True.

• show_roi_centers (bool) – If True, draw the center of each ROI. Default True.

• show_animal_names (bool) – If True, display animal names on the video. Default False.

• border_bg_clr (Tuple[int, int, int]) – BGR color for the text panel background. Default (0, 0, 0).

• time_slice (Optional[Dict[str, str]]) – Optional dict with ‘start_time’ and ‘end_time’ keys (HH:MM:SS format) to visualize a sub-clip. Default None.

• roi_coordinates_path (Optional[Union[str, os.PathLike]]) – Optional path to ROI definitions file. If None, uses the project default. Default None.

• left_ear_name (Optional[str]) – Optional custom left ear body-part name. Default None.

• right_ear_name (Optional[str]) – Optional custom right ear body-part name. Default None.

• nose_name (Optional[str]) – Optional custom nose body-part name. Default None.

• core_cnt (int) – Number of CPU cores for multiprocessing. -1 uses all available. Default -1.

• gpu (bool) – If True, use GPU for video concatenation when available. Default False.

• verbose (bool) – If True, print progress messages during visualization. Default True.

Example

>>> viz = DirectingROIVisualizer(config_path='/path/to/project_config.ini',
...                              video_path='/path/to/video.mp4',
...                              direction_style='funnel',
...                              show_pose=True,
...                              core_cnt=4)
>>> viz.run()

ROI visualizer

Visualize the ROI data (number of entries/exits, time-spent in ROIs etc).

Note

ROI tutorials.

See also

Use simba.plotting.ROI_plotter_mp.ROIPlotMultiprocess() for improved run-time.

param Union[str, os.PathLike] config_path

Path to SimBA project config file in Configparser format.

param Union[str, os.PathLike] video_path

Path to video file to create ROI visualizations for.

param List[str] body_parts

List of the body-parts to use as proxy for animal locations.

param bool outside_roi

If True, SimBA will treat all areas NOT covered by a ROI drawing as a single additional ROI and visualize the stats for this single ROI. Default: False.

param float threshold

Float between 0 and 1. Body-part locations detected below this confidence threshold are filtered. Default: 0.0.

param Optional[bool] verbose

If True, print progress messages during video creation. Default: True.

param bool show_animal_name

If True, display animal names on the video frames. Default: False.

param bool show_body_part

If True, display body-part locations as circles on the video frames. Default: True.

param Optional[Union[str, os.PathLike]] data_path

Optional path to the pose-estimation data. If None, then locates file in outlier_corrected_movement_location directory. Default: None.

param Optional[Union[str, os.PathLike]] save_path

Optional path to where to save video. If None, then saves it in frames/output/roi_analysis directory of SimBA project. Default: None.

param Optional[List[Tuple[int, int, int]]] bp_colors

Optional list of tuples of same length as body_parts representing the colors of the body-parts in RGB format. Defaults to None and colors are automatically chosen. Default: None.

param Optional[List[Union[int]]] bp_sizes

Optional list of integers representing the sizes of the pose estimated body-part location circles. Defaults to None and size is automatically inferred. Default: None.

param Tuple[int, int, int] border_bg_clr

RGB tuple representing the background color of the border area where statistics are displayed. Default: (0, 0, 0).

example

>>> test = ROIPlotter(config_path=r'/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/project_config.ini',
>>>                video_path="/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/SI_DAY3_308_CD1_PRESENT.mp4",
>>>                body_parts=['Nose'],
>>>                show_body_part=True,
>>>                show_animal_name=True)
>>> test.run()

example II

>>> test = ROIPlotter(config_path=r"C:      roubleshooting\mitra\project_folder\project_config.ini",
>>>               video_path=r"C:   roubleshooting\mitra\project_folder

ideosŁ_MA142_Gi_Saline_0513.mp4”,

>>>               body_parts=['Nose'],
>>>               show_body_part=True,
>>>               show_animal_name=False)
>>> test.run()

ROI visualizer - multiprocess

Visualize the ROI data (number of entries/exits, time-spent in ROIs) using multiprocessing for improved performance.

Note

ROI tutorials.

param Union[str, os.PathLike] config_path

Path to SimBA project config file in Configparser format.

param Union[str, os.PathLike] video_path

Path to video file to create ROI visualizations for.

param List[str] body_parts

List of the body-parts to use as proxy for animal locations.

param float threshold

Float between 0 and 1. Body-part locations detected below this confidence threshold are filtered. Default: 0.0.

param int core_cnt

Number of cores to use for multiprocessing. Default: -1 (uses all available cores).

param bool verbose

If True, print progress messages during video creation. Default: True.

param bool outside_roi

If True, SimBA will treat all areas NOT covered by a ROI drawing as a single additional ROI and visualize the stats for this single ROI. Default: False.

param bool show_body_part

If True, display body-part locations as circles on the video frames. Default: True.

param bool show_animal_name

If True, display animal names on the video frames. Default: False.

param Optional[Literal[‘axis-aligned’, ‘animal-aligned’]] bbox

If not None, draw bounding boxes around each animal. 'axis-aligned' = rectangle aligned with video axes; 'animal-aligned' = minimum rotated rectangle aligned with the animal’s orientation. Default: None (no bounding boxes).

param Literal[‘seconds’, ‘hh:mm:ss.ssss’] print_timer

Timer format for behavior/ROI counters shown in the border panel. 'seconds' = numeric seconds, 'hh:mm:ss.ssss' = clock-style timestamp with fractional seconds. Default: 'seconds'.

param Tuple[int, int, int] border_bg_clr

RGB tuple representing the background color of the border area where statistics are displayed. Default: (0, 0, 0).

param Optional[Union[str, os.PathLike]] data_path

Optional path to the pose-estimation data. If None, then locates file in outlier_corrected_movement_location directory. Default: None.

param Optional[Union[str, os.PathLike]] save_path

Optional path to where to save video. If None, then saves it in frames/output/roi_analysis directory of SimBA project. Default: None.

param Optional[List[Tuple[int, int, int]]] bp_colors

Optional list of tuples of same length as body_parts representing the colors of the body-parts in RGB format. Defaults to None and colors are automatically chosen. Default: None.

param Optional[List[Union[int]]] bp_sizes

Optional list of integers representing the sizes of the pose estimated body-part location circles. Defaults to None and size is automatically inferred. Default: None.

param bool gpu

If True, use GPU acceleration for video concatenation. Default: False.

example

>>> test = ROIPlotMultiprocess(config_path=r'/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/project_config.ini',
>>>                            video_path="/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/SI_DAY3_308_CD1_PRESENT.mp4",
>>>                            core_cnt=7,
>>>                            body_parts=['Nose'],
>>>                            show_body_part=True,
>>>                            show_animal_name=False)
>>> test.run()

Circular base feature plotter

Create visualization of base angular features overlay on video. E.g., use to confirm accurate cardinality and angle degree computation.

param Union[str, os.PathLike] config_path

path to SimBA project config file in Configparser format

param Union[str, os.PathLike] data_path

Path to file containing angular features.

param dict settings

Dictionary containing visualization attributes.

example

>>> settings = {'center': {'Animal_1': 'SwimBladder'}, 'text_settings': False, "palette": 'bwr'}
>>> circular_feature_plotter = CircularFeaturePlotter(config_path='/Users/simon/Desktop/envs/troubleshooting/circular_features_zebrafish/project_folder/project_config.ini', data_path='/Users/simon/Desktop/envs/troubleshooting/circular_features_zebrafish/project_folder/csv/circular_features/20200730_AB_7dpf_850nm_0002.csv', settings=settings)
>>> circular_feature_plotter.run()

Circular diffusion plotting

Methods for visualizations

Classifier validation

Create video clips with overlaid classified events for detection of false positive event bouts.

parameter str config_path

path to SimBA project config file in Configparser format

parameter int window

Number of seconds before and after the event bout that should be included in the output video.

parameter str clf_name

Name of the classifier to create validation videos for.

parameter bool clips

If True, creates individual video file clips for each validation bout.

parameter Tuple[int, int, int] text_clr

Color of text overlay in BGR.

parameter Optional[Tuple[int, int, int]] highlight_clr

Color of text when probability values are above threshold. If None, same as text_clr.

parameter float video_speed

FPS rate in relation to original video. E.g., the same as original video if 1.0. Default: 1.0.

parameter bool concat_video

If True, creates a single video including all events bouts for each video. Default: False.

Note

Tutorial.

examples

>>> _ = ClassifierValidationClips(config_path='MyProjectConfigPath', window=5, clf_name='Attack', text_clr=(255,255,0), clips=False, concat_video=True).run()

Classifier validation - multiprocess

Create video clips with overlaid classified events for detection of false positive event bouts using multiple cores for improved runtime.

parameter str config_path

path to SimBA project config file in Configparser format

parameter int window

Number of seconds before and after the event bout that should be included in the output video.

parameter str clf_name

Name of the classifier to create validation videos for.

parameter bool clips

If True, creates individual video file clips for each validation bout.

parameter List[Union[str, os.PathLike]] data_paths

List of files with classification results to create videos for.

parameter Tuple[int, int, int] text_clr

Color of text overlay in BGR.

parameter Optional[Tuple[int, int, int]] highlight_clr

Color of text when probability values are above threshold. If None, same as text_clr.

parameter float video_speed

FPS rate in relation to original video. E.g., the same as original video if 1.0. If output should be half the speed relative to input, set to 0.5. Default: 1.0.

parameter bool concat_video

If True, creates a single video including all events bouts for each video. Default: False.

parameter Optional[int] core_cnt

Integer dictating the numbers of cores to use. If -1, all available cores are used.

Note

Tutorial.

Examples

>>> _ = ClassifierValidationClipsMultiprocess(config_path='MyProjectConfigPath', window=5, clf_name='Attack', text_clr=(255,255,0), clips=False, concat_video=True).run()

Data plotter

Tabular data visualization of animal movement and distances in the current frame and their aggregate statistics.

param Union[str, os.PathLike] config_path

Path to the SimBA project config file in ConfigParser format.

param List[Tuple[str, Tuple[int, int, int]]] body_parts

A list of tuples, where each tuple consists of a body-part name (str) and an RGB tuple (int, int, int) indicating the text color used for that body-part in plots.

param List[Union[str, os.PathLike]] data_paths

List of paths to the CSV files containing time-binned animal movement data.

param Tuple[int, int, int] bg_clr

Background color of the output image(s) as an RGB tuple. Default is white (255, 255, 255).

param Tuple[int, int, int] header_clr

Text color for the header labels (e.g., “ANIMAL”, “TOTAL MOVEMENT”) as an RGB tuple. Default is black (0, 0, 0).

param int font_thickness

Thickness of the font used in output images. Must be >= 1. Default is 2.

param Tuple[int, int] img_size

Size of the output image as a tuple (width, height). Default is (640, 480).

param int decimals

Number of decimal places to round movement and velocity values. Must be >= 0. Default is 2.

param bool video_setting

Whether to generate a video output of the data plot. At least one of video_setting or frame_setting must be True.

param bool frame_setting

Whether to generate individual frame image outputs for each time bin.

param bool verbose

Whether to print progress information during execution. Default is True.

Note

Tutorial <https://github.com/sgoldenlab/simba/blob/master/docs/Scenario2.md#visualizing-data-tables>_.

examples

>>> _ = DataPlotter(config_path='MyConfigPath').run()

Distance plotter

Visualize frame-wise body-part distances as line plots using single-core processing.

Produces one or more of: (i) frame-by-frame plot images, (ii) a dynamic distance-plot video, (iii) a final static distance plot (PNG or SVG).

Note

For better runtime, use simba.plotting.distance_plotter_mp.DistancePlotterMultiCore(). GitHub tutorial/documentation.

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param List[Union[str, os.PathLike]] data_paths

One or more pose data files to process.

param Dict[str, int] style_attr

Plot style dictionary. Expected keys include width, height, line width, font size, y_max, and opacity.

param List[List[str]] line_attr

Distance definitions. Each entry is [body_part_1, body_part_2, color_name].

param bool frame_setting

If True, save one plot image per frame. Default: False.

param bool video_setting

If True, save a video of the plot building over time. Default: False.

param bool last_frame_as_svg

If True, final static distance image is saved as SVG; else PNG. Default: False.

param bool final_img

If True, save a final static distance plot for each video. Default: False.

examples

>>> style_attr = {'width': 640, 'height': 480, 'line width': 6, 'font size': 8, 'opacity': 0.5}
>>> line_attr = {0: ['Center_1', 'Center_2', 'Green'], 1: ['Ear_left_2', 'Ear_left_1', 'Red']}
>>> distance_plotter = DistancePlotterSingleCore(config_path=r'MyProjectConfig', files_found=['test/two_c57s/project_folder/csv/outlier_corrected_movement_location/Video_1.csv'], frame_setting=False, video_setting=True, final_img=True)
>>> distance_plotter.run()

Distance plotter - multiprocess

Visualize frame-wise body-part distances as line plots using multiprocessing.

Produces one or more of: (i) frame-by-frame plot images, (ii) a dynamic distance-plot video, (iii) a final static distance plot (PNG or SVG).

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param List[Union[str, os.PathLike]] data_paths

One or more pose data files to process.

param bool frame_setting

If True, save one plot image per frame.

param bool video_setting

If True, save a video of the plot building over time.

param bool final_img

If True, save a final static distance plot for each video.

param Dict[str, int] style_attr

Plot style dictionary. Expected keys include width, height, line width, font size, y_max, and opacity.

param List[List[str]] line_attr

Distance definitions. Each entry is [body_part_1, body_part_2, color_name].

param Optional[int] core_cnt

Number of CPU cores. -1 uses all available cores. Default: -1.

param bool last_frame_as_svg

If True, final static distance image is saved as SVG; else PNG. Default: False.

Note

GitHub tutorial/documentation.

example

>>> style_attr = {'width': 640, 'height': 480, 'line width': 6, 'font size': 8, 'opacity': 0.5}
>>> line_attr = {0: ['Center_1', 'Center_2', 'Green'], 1: ['Ear_left_2', 'Ear_left_1', 'Red']}
>>> distance_plotter = DistancePlotterMultiCore(config_path=r'/tests_/project_folder/project_config.ini', frame_setting=False, video_setting=True, final_img=True, style_attr=style_attr, line_attr=line_attr,  files_found=['/test_/project_folder/csv/machine_results/Together_1.csv'], core_cnt=5)
>>> distance_plotter.run()

Quick path plot (Ez path plot)

Create a simpler path plot for a single path in a single video.

Note

For more refined / complex path plots with/without multiprocessing for inproved speed, see simba.plotting.path_plotter.PathPlotterSingleCore and simba.plotting.path_plotter_mp.PathPlotterMulticore.

param Union[str, os.PathLike] data_path

The path to the data file in H5c or CSV format containing the pose estimation coordinates.

param Optional[Union[str, os.PathLike]] video_path

The path to the video file. Optional. If provided, the FPS and size is grabbed from the metadata of the video file. If None, then pass fps and size.

param Optional[Tuple[int, int]] size

Size of the path plot (width, height). Used if video_path is None.

param Optional[int] fps

The FPS of the path plot. Used if video_path is None.

param str body_part

The specific body part to plot the path for.

param Optional[bool] last_frm_only

If True, creates just a single .png image representing the full path in last image in the video.

param Optional[Tuple[int, int, int]] bg_color

The background color of the plot. Defaults to (255, 255, 255).

param Optional[Tuple[int, int, int]] line_color

The color of the path line. Defaults to (147, 20, 255).

param Optional[int] line_thickness

The thickness of the path line. Defaults to 10.

param Optional[int] circle_size

The size of the circle indicating each data point. Defaults to 5.

param Optional[Union[str, os.PathLike]] save_path

The location to store the path plot. If None, then use the same path as the data path with _line_plot suffix.

example I

>>> path_plotter = EzPathPlot(data_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/h5/Together_1DLC_resnet50_two_black_mice_DLC_052820May27shuffle1_150000_el.h5', video_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/videos/Together_1.avi', body_part='Mouse_1_Nose', bg_color=(255, 255, 255), line_color=(147,20,255))
>>> path_plotter.run()

example II

>>> path_plotter = EzPathPlot(data_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/h5/Together_1DLC_resnet50_two_black_mice_DLC_052820May27shuffle1_150000_el.h5', size=(2056, 1549), fps=30, body_part='Mouse_1_Nose', bg_color=(255, 255, 255), line_color=(147,20,255))
>>> path_plotter.run()

Merge videos

Merge separate visualizations of classifications, descriptive statistics etc., into single video mosaic.

Note

GitHub tutorial.

parameter str config_path

Optional path to SimBA project config file in Configparser format.

parameter Literal[“horizontal”, “vertical”, “mosaic”, “mixed_mosaic”] concat_type

Type of concatenation. OPTIONS: ‘horizontal’, ‘vertical’, ‘mosaic’, ‘mixed_mosaic’.

parameter List[Union[str, os.PathLike]] video_paths

List with videos to concatenate.

param int quality

Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.

parameter Optional[int] video_height

Optional height of the canatenated videos. Required if concat concat_type is not mixed_mosaic.

parameter int video_width

Optional wisth of the canatenated videos. Required if concat concat_type is not mixed_mosaic.

parameter Optional[bool] gpu

If True, use NVIDEA FFMpeg GPU codecs. Default False.

example

>>> video_paths = ['/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/SI_DAY3_308_CD1_PRESENT_downsampled.mp4', '/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/SI_DAY3_308_CD1_PRESENT_downsampled.mp4']
>>> merger = FrameMergererFFmpeg(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini', video_paths=videos, video_height=600, video_width=600, concat_type='mosaic')
>>> merger.run()

Gantt plot

Create classifier Gantt charts using single-process execution.

Generates one or more of: (i) frame-by-frame Gantt images, (ii) dynamic Gantt videos, (iii) a final static Gantt image (PNG or SVG).

Note

GitHub gantt tutorial.

See also

For multiprocessing alternative, see simba.plotting.gantt_creator_mp.GanttCreatorMultiprocess.

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Optional[Union[Union[str, os.PathLike], List[Union[str, os.PathLike]]]] data_paths

File path, list of file paths, or None (all machine result files in project).

param int width

Width of output images/videos in pixels. Default: 640.

param int height

Height of output images/videos in pixels. Default: 480.

param int font_size

Font size for behavior labels. Default: 8.

param int font_rotation

Rotation angle for y-axis labels in degrees (0-180). Default: 45.

param Optional[str] font

Matplotlib font name. If None, default font is used.

param str palette

Color palette name for behaviors. Default: ‘Set1’.

param bool frame_setting

If True, creates individual frame images. Default: False.

param bool video_setting

If True, creates dynamic Gantt videos. Default: False.

param bool last_frm_setting

If True, creates a final static Gantt image. Default: True.

param bool last_frame_as_svg

If True, saves final static frame as SVG; else PNG. Default: False.

param bool hhmmss

If True, x-axis labels are formatted as HH:MM:SS. If False, seconds are used. Default: True.

param Optional[List[str]] clf_names

Optional subset of classifiers to include. If None, uses all project classifiers.

example

>>> gantt_creator = GanttCreatorSingleProcess(config_path='project_config.ini', video_setting=True, data_paths=['csv/machine_results/video1.csv'], hhmmss=True, last_frm_setting=True)
>>> gantt_creator.run()

Gantt plot - multiprocess

Create classifier Gantt charts using multiprocessing for faster generation.

Generates one or more of: (i) frame-by-frame Gantt images, (ii) dynamic Gantt videos, (iii) a final static Gantt image (PNG or SVG).

Note

GitHub gantt tutorial.

See also

For single-process alternative, see simba.plotting.gantt_creator.GanttCreatorSingleProcess.

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Optional[Union[Union[str, os.PathLike], List[Union[str, os.PathLike]]]] data_paths

File path, list of file paths, or None (all machine result files in project).

param bool frame_setting

If True, creates individual frame images. Default: False.

param bool video_setting

If True, creates dynamic Gantt videos. Default: False.

param bool last_frm_setting

If True, creates a final static Gantt image. Default: True.

param bool last_frame_as_svg

If True, saves final static frame as SVG; else PNG. Default: False.

param int width

Width of output images/videos in pixels. Default: 640.

param int height

Height of output images/videos in pixels. Default: 480.

param int font_size

Font size for behavior labels. Default: 8.

param int font_rotation

Rotation angle for y-axis labels in degrees (0-180). Default: 45.

param Optional[str] font

Matplotlib font name. If None, default font is used.

param float bar_opacity

Opacity of Gantt bars in range (0, 1]. Default: 0.85.

param str palette

Color palette name for behaviors. Default: ‘Set1’.

param Optional[int] core_cnt

Number of CPU cores to use. If -1, uses all available cores. Default: -1.

param bool hhmmss

If True, x-axis labels are formatted as HH:MM:SS. If False, seconds are used. Default: False.

param Optional[List[str]] clf_names

Optional subset of classifiers to include. If None, uses all project classifiers.

example

>>> gantt_creator = GanttCreatorMultiprocess(config_path='project_config.ini', video_setting=True, data_paths=['csv/machine_results/video1.csv'], core_cnt=5, hhmmss=True, last_frm_setting=True)
>>> gantt_creator.run()

Gantt plot - fancy

Generates a Gantt chart using Plotly to visualize bout events over time.

Creates a horizontal bar chart where each row represents an event (e.g., animal behavior) over time, with estensive customization options.

param pd.DataFrame bouts_df

A pandas DataFrame containing the bout events data. Can be created by detect_bouts().

param Optional[Tuple[int, int]] img_size

The size of the output image as (width, height). Default (640, 480).

param Optional[str] bg_clr

The color of the background as a string. Deafult: white.

param Optional[str] title

The title of image. Deafult: None.

param Optional[int] font_size

The font size for the title, labels, ticks. deafult 12.

param Optional[str] y_lbl

The label on the y-axis. Deafult: Event.

param Optional[str] x_lbl

The label on the x-axis. Deafult: ‘Session time (s)’.

param Optional[bool] show_grid

Whether to show the grid on the plot. Default is True.

param Optional[str] color_palette

The name of the color palette to use for event bars. Default: Set.

param Optional[int] x_length

The maximum value of the x-axis. If None, the x-axis is determined based on the data.

param Optional[str] bar_height

The height of each bar in the Gantt chart. Default is 0.4.

param Optional[Union[int, float]] x_tick_spacing

The spacing between x-axis ticks. Can be either an integer or float. If float, it is treated as a fraction of the x-axis range (between 0 and 1). If integer, then interpreted as seconds. Default is 30.

param Optional[str] marker_line_color

Color of the bar borders. Default is ‘black’.

param Optional[float] marker_line_width

Width of the bar borders. Default is 0.5.

param Optional[str] time_format

Format for x-axis tick labels. Supported formats are: - ‘HH:MM:SS’: Converts seconds to hours:minutes:seconds format. - ‘seconds’: Displays tick labels as raw seconds. Default is ‘HH:MM:SS’.

param Optional[int] tick_angle

Angle for rotating x-axis tick labels. Default is 45 degrees.

param Optional[str] font

Font name. E.g., “Arial”, “Verdana”, “Helvetica”, “Tahoma”, “Trebuchet MS”, “Times New Roman”, “Georgia”, “Courier New”, “Lucida Console”. Default is None, which uses the default Plotly font.

return

A Gantt chart image as a NumPy array (dtype=np.uint8).

rtype

np.ndarray

example

>>> FILE_PATH = r"D:        roubleshooting\mitra\project_folder\logsll92_MA147_CNO1_0515.csv"
>>> data = read_df(file_path=FILE_PATH, file_type='csv')
>>> bouts_df = detect_bouts(data_df=data, target_lst=list(data.columns), fps=30)
>>> img = gantt_plotly(bouts_df=bouts_df, x_tick_spacing=120, color_palette='Set1', img_size=(1200, 700), font_size=32, show_grid=True)

Classifier heatmaps

Create heatmaps representing the locations of the classified behavior.

Note

GitHub visualizations tutorial. For improved run-time, see simba.heat_mapper_clf_mp.HeatMapperClfMultiprocess() for multiprocess class.

param str config_path

path to SimBA project config file in Configparser format

param bool final_img_setting

If True, then create a single image representing the last frame of the input video

param bool video_setting

If True, then create a video of heatmaps.

param bool frame_setting

If True, then create individual heatmap frames.

param str clf_name

The name of the classified behavior.

param str bodypart

The name of the body-part used to infer the location of the classified behavior

param Dict style_attr

Dict containing settings for colormap, bin-size, max scale, and smooothing operations. For example: {‘palette’: ‘jet’, ‘shading’: ‘gouraud’, ‘bin_size’: 50, ‘max_scale’: ‘auto’}.

example

>>> test = HeatMapperClfSingleCore(config_path=r"C: roubleshooting\RAT_NOR\project_folder\project_config.ini",
>>>                  style_attr = {'palette': 'jet', 'shading': 'gouraud', 'bin_size': 50, 'max_scale': 'auto'},
>>>                  final_img_setting=True,
>>>                  video_setting=True,
>>>                  frame_setting=False,
>>>                  bodypart='Ear_left',
>>>                  clf_name='straub_tail',
>>>                  data_paths=[r"C:       roubleshooting\RAT_NOR\project_folder\csv       est‚2-06-20_NOB_DOT_4.csv"])
>>> test.run()

Classifier heatmaps - multiprocess

Create heatmaps representing the locations of the classified behavior.

Note

GitHub visualizations tutorial.

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param str bodypart

Body-part used to locate where the behavior occurs. When the classifier fires, SimBA records this body-part’s position.

param str clf_name

Name of the classifier/behavior to visualize (e.g. ‘Attack’, ‘Grooming’).

param List[str] data_paths

Path(s) to classifier results CSV files (from machine_results). Must match videos in project.

param Dict[str, Any] style_attr

Dict with keys ‘palette’, ‘shading’, ‘bin_size’, ‘max_scale’. E.g. {‘palette’: ‘jet’, ‘shading’: ‘gouraud’, ‘bin_size’: 50, ‘max_scale’: ‘auto’}.

param bool show_legend

If True, append color bar showing seconds scale. Default True.

param bool final_img_setting

If True, create a single cumulative heatmap image. Default True.

param Optional[int] bg_img

If set, overlay heatmap on video frame. -1 or None = no background. Non-negative int = frame index for static background.

param Optional[float] heatmap_opacity

Opacity of heatmap over background (0–1). Used when bg_img is set. Default None.

param bool video_setting

If True, create heatmap video. Default False.

param bool verbose

If True, print progress. Default True.

param bool show_keypoint

If True, draw body-part position as dot on each frame. Default False.

param Optional[int] min_seconds

Hide bins with time below this (seconds). Bins below threshold appear empty. Default None.

param bool frame_setting

If True, create individual heatmap frame images. Default False.

param Optional[Dict[str, str]] time_slice

If set, restrict analysis to time period. Dict with keys ‘start_time’ and ‘end_time’ (HH:MM:SS). Default None.

param int core_cnt

Number of CPU cores. -1 = use all available. Default -1.

example

>>> style_attr = {'palette': 'jet', 'shading': 'gouraud', 'bin_size': 50, 'max_scale': 'auto'}
>>> heatmapper = HeatMapperClfMultiprocess(config_path='project_config.ini', bodypart='Nose_1', clf_name='Attack', data_paths=['csv/machine_results/Video1.csv'], style_attr=style_attr, final_img_setting=True, video_setting=False, frame_setting=False, core_cnt=-1)
>>> heatmapper.run()

Location heatmaps

Create heatmaps representing the location where animals spend time. For improved run-time, see simba.heat_mapper_location_mp.HeatMapperLocationMultiprocess() for multiprocess class.

..note::

GitHub visualizations tutorial.

For improved run-time of videos, see simba.heat_mapper_location_mp.HeatMapperLocationMultiprocess() for multiprocess class.

param str config_path

path to SimBA project config file in Configparser format

param str bodypart

The name of the body-part used to infer the location of the animal.

param int bin_size

The rectangular size of each heatmap location in millimeters. For example, 50 will divide the video frames into 5 centimeter rectangular spatial bins.

param str palette

Heatmap pallette. Eg. ‘jet’, ‘magma’, ‘inferno’,’plasma’, ‘viridis’, ‘gnuplot2’

param int or ‘auto’ max_scale

The max value in the heatmap in seconds. E.g., with a value of 10, if the classified behavior has occured >= 10s within a rectangular bins, it will be filled with the same color.

param bool final_img_setting

If True, create a single image representing the last frame of the input video

param bool video_setting

If True, then create a video of heatmaps.

param bool frame_setting

If True, then create individual heatmap frames.

example

>>> style_attr = {'palette': 'jet', 'shading': 'gouraud', 'bin_size': 100, 'max_scale': 'auto'}
>>> heatmapper = HeatmapperLocationSingleCore(config_path='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini', style_attr = style_attr, final_img_setting=True, video_setting=True, frame_setting=False, bodypart='Nose_1', files_found=['/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/csv/machine_results/Together_1.csv'])
>>> heatmapper.run()

Location heatmaps - multiprocess

Create heatmaps representing the location where animals spend time.

Note

GitHub visualizations tutorial.

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Union[List[Union[str, os.PathLike]], str, os.PathLike] data_paths

Path(s) to outlier-corrected movement or location CSV file(s). If None, uses all files in project.

param str bodypart

Body-part name used for location heatmap (e.g. ‘Nose_1’). The heatmap shows where this body-part spends time.

param Dict[str, Any] style_attr

Dict with keys ‘palette’, ‘shading’, ‘bin_size’, ‘max_scale’. E.g. {‘palette’: ‘jet’, ‘shading’: ‘gouraud’, ‘bin_size’: 50, ‘max_scale’: ‘auto’}.

param Optional[int] bg_img

If set, overlay heatmap on video frame. -1 or None = no background. Non-negative int = frame index to use as background.

param Optional[Dict[str, str]] time_slice

If set, restrict analysis to time period. Dict with keys ‘start_time’ and ‘end_time’ (HH:MM:SS). Default None.

param bool show_keypoint

If True, draw body-part position as dot on each frame. Default False.

param bool show_legend

If True, append color bar showing seconds scale. Default True.

param Optional[float] heatmap_opacity

Opacity of heatmap over background (0–1). Used when bg_img is set. Default None.

param Optional[int] min_seconds

Hide bins with time below this (seconds). Bins below threshold shown as empty. Default None.

param Optional[str] line_clr

Color for grid lines between bins (e.g. ‘white’, ‘red’). None = no grid. Default None.

param Optional[bool] final_img_setting

If True, create a single cumulative heatmap image. Default True.

param Optional[bool] video_setting

If True, create heatmap video. Default False.

param Optional[bool] frame_setting

If True, create individual heatmap frame images. Default False.

param Optional[int] core_cnt

Number of CPU cores. -1 = use all available. Default -1.

param bool verbose

If True, print progress. Default True.

example

>>> style_attr = {'palette': 'jet', 'shading': 'gouraud', 'bin_size': 100, 'max_scale': 'auto'}
>>> heatmapper = HeatMapperLocationMultiprocess(config_path='project_config.ini', data_paths='csv/outlier_corrected_movement_location/Together_1.csv', bodypart='Nose_1', style_attr=style_attr, core_cnt=-1, final_img_setting=True, video_setting=False, frame_setting=False)
>>> heatmapper.run()

Interactive classifier probability plotter

Launch interactive GUI for inspecting classifier probabilities with synchronized video playback.

Displays probability plot with interactive navigation. Double-click plot to jump to frame, use arrow keys to navigate, space to play/pause.

Note

Validation tutorial.

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Union[str, os.PathLike] file_path

Path to CSV file with classification probability data.

param Union[str, os.PathLike] model_path

Path to classifier pickle file (.sav) used to generate probabilities.

param int lbl_font_size

Font size for axis labels. Default: 16.

param Tuple[int, int, int] data_clr

RGB color for probability line (0-255). Default: (0, 0, 255) [blue].

param Tuple[int, int, int] line_clr

RGB color for current frame marker line (0-255). Default: (255, 0, 0) [red].

param bool show_thresholds

If True, displays threshold lines at 0.25, 0.5, and 0.75. Default: True.

param bool show_statistics_legend

If True, displays statistics box (max, mean, frame count). Default: True.

example

>>> interactive_plotter = InteractiveProbabilityGrapher(config_path='project_config.ini', file_path='features.csv', model_path='classifier.sav')
>>> interactive_plotter.run()

Path plotter

Create “path plots” videos and/or images detailing the movement paths of individual animals in SimBA.

Note

For improved run-time, see simba.path_plotter_mp.PathPlotterMulticore() for multiprocess class.

Visualization tutorials.

Notebook example.

param str config_path

Path to SimBA project config file in Configparser format

param bool frame_setting

If True, individual frames will be created.

param bool video_setting

If True, compressed videos will be created.

param List[str] files_found

Data paths to create from which to create plots

param dict animal_attr

Animal body-parts and colors

param dict style_attr

Plot sttributes (line thickness, color, etc..)

param Optional[dict] slicing

If Dict, start time and end time of video slice to create path plot from. E.g., {‘start_time’: ‘00:00:01’, ‘end_time’: ‘00:00:03’}. If None, creates path plot for entire video.

param Optional[bool] roi

If True, also plots the ROIs associated with the video. Default False.

Note

If style_attr[‘bg color’] is a dictionary, e.g., {‘opacity’: 100%}, then SimBA will use the video as background with set opacity.

examples

>>> style_attr = {'width': 'As input', 'height': 'As input', 'line width': 5, 'font size': 5, 'font thickness': 2, 'circle size': 5, 'bg color': 'White', 'max lines': 100, 'animal_names': True}
>>> animal_attr = {0: ['Ear_right_1', 'Red']}
>>> path_plotter = PathPlotterSingleCore(config_path=r'MyConfigPath', frame_setting=False, video_setting=True, style_attr=style_attr, animal_attr=animal_attr, files_found=['project_folder/csv/machine_results/MyVideo.csv'], print_animal_names=True).run()

references

1

Boorman, Damien C., Simran K. Rehal, Maryam Fazili, and Loren J. Martin. “Sex and Strain Differences in Analgesic and Hyperlocomotor Effects of Morphine and μ‐Opioid Receptor Expression in Mice.” Journal of Neuroscience Research 103, no. 4 (April 2025): e70039. https://doi.org/10.1002/jnr.70039.

Path plotter - multiprocess

Class for creating “path plots” videos and/or images detailing the movement paths of individual animals in SimBA. Uses multiprocessing.

param str config_path

Path to SimBA project config file in Configparser format

param bool frame_setting

If True, individual frames will be created.

param bool video_setting

If True, compressed videos will be created.

param bool last_frame

If True, png of the last frame will be created.

param List[str] files_found

Data paths to create path plots for (e.g., [‘project_folder/csv/machine_results/MyVideo.csv’])

param dict animal_attr

Animal body-parts to use when creating paths and their colors.

param Optional[dict] input_style_attr

Plot sttributes (line thickness, color, etc..). If None, then autocomputed. Max lines will be set to 2s.

param Optional[dict] input_clf_attr

Dict reprenting classified behavior locations, their color and size. If None, then no classified behavior locations are shown.

param Optional[dict] slicing

If Dict, start time and end time of video slice to create path plot from. E.g., {‘start_time’: ‘00:00:01’, ‘end_time’: ‘00:00:03’}. If None, creates path plot for entire video.

param Optional[bool] roi

If True, also plots the ROIs associated with the video. Default False.

param int cores

Number of cores to use.

Note

Visualization tutorials.

example

>>> input_style_attr = {'width': 'As input', 'height': 'As input', 'line width': 5, 'font size': 5, 'font thickness': 2, 'circle size': 5, 'bg color': 'White', 'max lines': 100}
>>> animal_attr = {0: ['Ear_right_1', 'Red']}
>>> input_clf_attr = {0: ['Attack', 'Black', 'Size: 30'], 1: ['Sniffing', 'Red', 'Size: 30']}
>>> path_plotter = PathPlotterMulticore(config_path=r'MyConfigPath', frame_setting=False, video_setting=True, style_attr=style_attr, animal_attr=animal_attr, files_found=['project_folder/csv/machine_results/MyVideo.csv'], cores=5, clf_attr=clf_attr, print_animal_names=True)
>>> path_plotter.run()

References

1

Battivelli, Dorian, Lucas Boldrini, Mohit Jaiswal, Pradnya Patil, Sofia Torchia, Elizabeth Engelen, Luca Spagnoletti, Sarah Kaspar, and Cornelius T. Gross. “Induction of Territorial Dominance and Subordination Behaviors in Laboratory Mice.” Scientific Reports 14, no. 1 (November 19, 2024): 28655. https://doi.org/10.1038/s41598-024-75545-4.

Classification plotter

Plot classification results overlays on videos. Results are stored in the project_folder/frames/output/sklearn_results directory of the SimBA project.

Note

For improved run-time, see simba.plotting.plot_clf_results_mp.PlotSklearnResultsMultiProcess() for multiprocess class. Scikit visualization documentation <https://github.com/sgoldenlab/simba/blob/master/docs/tutorial.md#step-10-sklearn-visualization__.

param Union[str, os.PathLike] config_path

path to SimBA project config file in Configparser format

param Optional[bool] video_setting

If True, SimBA will create compressed videos. Default True.

param Optional[bool] frame_setting

If True, SimBA will create individual frames. Default True.

param Optional[str] video_file_path

Path to video file to create classification visualizations for. If None, then all the videos in the csv/machine_results will be used. Default None.

param Optional[Union[Dict[str, float], bool]] text_settings

Dictionary holding the circle size, font size, spacing size, and text thickness of the printed text. If None, then these are autocomputed.

param Optional[bool] rotate

If True, the output video will be rotated 90 degrees from the input. Default False.

param Optional[str] palette

The name of the palette used for the pose-estimation key-points. Default Set1.

param Optional[bool] print_timers

If True, the output video will have the cumulative time of the classified behaviours overlaid. Default True.

param Optional[bool] show_bbox

If True, axis-aligned bounding boxes created from each anmals pose and displayed. Default True.

example

>>> text_settings = {'circle_scale': 5, 'font_size': 5, 'spacing_scale': 2, 'text_thickness': 10}
>>> test = PlotSklearnResultsSingleCore(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini',
>>>                                       video_setting=True,
>>>                                       frame_setting=False,
>>>                                       video_file_path='Together_1.avi',
>>>                                       print_timers=True,
>>>                                       text_settings=text_settings,
>>>                                       rotate=False)
>>> test.run()

Classification plotter - multiprocess

Plot classification results on videos using multiprocessing. Results are stored in the project_folder/frames/output/sklearn_results directory of the SimBA project.

This class creates annotated videos/frames showing classifier predictions overlaid on pose-estimation data, with optional Gantt charts, timers, and bounding boxes. Processing is parallelized across multiple CPU cores for faster rendering of large video datasets.

See also

Tutorial. For single-core processing, see simba.plotting.plot_clf_results.PlotSklearnResultsSingleCore().

param Union[str, os.PathLike] config_path

Path to SimBA project config file in Configparser format.

param bool video_setting

If True, creates compressed MP4 videos. Default True.

param bool frame_setting

If True, saves individual annotated frames as PNG images. Default False.

param Optional[Union[List[Union[str, os.PathLike]], Union[str, os.PathLike]]] video_paths

Path(s) to video file(s) to process. Accepts a single video file path, a list of video file paths, or a path to a directory containing videos (in which case all videos in that directory are processed). If None, processes all videos found in the project’s video directory. Default None.

param bool rotate

If True, rotates output videos 90 degrees clockwise. Default False.

param bool animal_names

If True, displays animal names on the video frames. Default False.

param bool show_pose

If True, overlays pose-estimation keypoints on the video. Default True.

param bool show_confidence

If True, displays per-frame classifier confidence values (probabilities) for each behavior. Default False.

param Optional[Union[int, float]] font_size

Font size for text overlays. If None, auto-computed based on video resolution. Default None.

param Optional[Union[int, float]] space_size

Vertical spacing between text lines. If None, auto-computed. Default None.

param Optional[Union[int, float]] text_thickness

Thickness of text characters. If None, uses default. Default None.

param Optional[Union[int, float]] text_opacity

Opacity of text background (0.0-1.0). If None, defaults to 0.8. Default None.

param Optional[Union[int, float]] circle_size

Radius of pose keypoint circles. If None, auto-computed based on video resolution. Default None.

param Optional[str] pose_palette

Name of color palette for pose keypoints. Must be from simba.utils.enums.Options.PALETTE_OPTIONS_CATEGORICAL or simba.utils.enums.Options.PALETTE_OPTIONS. Default ‘Set1’.

param Optional[Literal[‘seconds’, ‘hh:mm:ss.ssss’]] print_timer

Timer display mode for cumulative classifier durations. 'seconds' shows numeric seconds, 'hh:mm:ss.ssss' shows clock-style timestamps with sub-second precision, and None disables timer display. Default 'seconds'.

param bool overwrite

If True, existing output files in the target output location may be overwritten. Default True.

param Optional[Literal[‘axis-aligned’, ‘animal-aligned’]] bbox

If not None, draw bounding boxes around each animal. 'axis-aligned' = rectangle aligned with video axes; 'animal-aligned' = minimum rotated rectangle aligned with the animal’s orientation. Default None (no bounding boxes).

param Optional[Dict[str, str]] time_slice

Optional time interval to render in {'start_time': 'HH:MM:SS', 'end_time': 'HH:MM:SS'} format. If None, processes full video duration. Default None.

param Optional[int] show_gantt

If 1, appends static Gantt chart to video. If 2, appends dynamic Gantt chart that updates per frame. If None, no Gantt chart. Default None.

param Tuple[int, int, int] text_clr

RGB color tuple for text foreground. Default (255, 255, 255) (white).

param Tuple[int, int, int] text_bg_clr

RGB color tuple for text background. Default (0, 0, 0) (black).

param bool gpu

If True, uses GPU acceleration for video concatenation (requires CUDA-capable GPU). Default False.

param bool verbose

If True, prints progress and status messages during processing. Default True.

param int core_cnt

Number of CPU cores to use for parallel processing. Pass -1 to use all available cores. Default -1.

param Optional[Union[str, os.PathLike]] data_dir

Directory containing the classification data files (one per video, named <video_name>.<file_type>) to overlay on the videos. If None, defaults to the project’s machine_results_dir. Default None.

param Optional[Union[str, os.PathLike]] save_dir

Directory in which to write annotated videos/frames. Created if it does not exist. If None, defaults to the project’s sklearn_plot_dir. Default None.

param Optional[Union[List[str], Tuple[str, …]]] clf_names

Optional subset of classifier names to visualize. Each entry must match a classifier defined in the project config. If None, all project classifiers are plotted (current behavior). Default None.

example

>>> clf_plotter = PlotSklearnResultsMultiProcess(
...     config_path='/Users/simon/Desktop/envs/simba/troubleshooting/beepboop174/project_folder/project_config.ini',
...     video_setting=True,
...     frame_setting=False,
...     video_paths='Trial_10.mp4',
...     rotate=False,
...     show_pose=True,
...     bbox='axis-aligned',
...     print_timers=True,
...     show_gantt=1,
...     core_cnt=5
... )
>>> clf_plotter.run()

Annotation bout plotter

Create per-bout annotation videos from classifier target files.

For each selected classifier and video, detected annotation bouts are exported as individual MP4 clips. Optional pre/post windows can extend each bout. The rendered clips can include pose points, animal labels, bounding boxes, and a timer overlay.

param Union[str, os.PathLike] config_path

Path to the SimBA project_config.ini file.

param Optional[Union[List[Union[str, os.PathLike]], Union[str, os.PathLike]]] data_paths

Target annotation file path(s). If None, all target files in the project are used.

param bool animal_names

If True, print animal names near the first body-part.

param bool show_pose

If True, draw body-part circles.

param Optional[float] pre_window

Seconds added before each detected bout.

param Optional[float] post_window

Seconds added after each detected bout.

param Optional[Union[int, float]] font_size

Override auto font size.

param Optional[Union[int, float]] space_size

Override auto vertical text spacing.

param Optional[Union[int, float]] text_thickness

Text thickness.

param Optional[Union[int, float]] text_opacity

Text background opacity.

param Optional[Union[int, float]] circle_size

Pose marker radius.

param Optional[str] pose_palette

Color palette name for pose/body-part colors.

param Optional[List[str]] clf_names

Classifiers to visualize. If None, all project classifiers are used.

param Optional[Literal[‘seconds’, ‘hh:mm:ss.ssss’]] video_timer

Timer format to render on output frames.

param bool overwrite

Overwrite controls for output directory handling.

param Optional[Literal[‘axis-aligned’, ‘animal-aligned’]] bbox

Optional bounding-box style to draw for each animal.

param Tuple[int, int, int] text_clr

RGB text color.

param Tuple[int, int, int] text_bg_clr

RGB text background color.

param bool gpu

If True and an Nvidia GPU is available, enable GPU path.

param bool verbose

If True, print progress messages.

param int core_cnt

Number of CPU cores for multiprocessing. Use -1 for all available cores.

example

>>> plotter = PlotAnnotatedBouts(
...     config_path='project_folder/project_config.ini',
...     data_paths=['project_folder/csv/targets_inserted/video_1.csv'],
...     clf_names=['grooming'],
...     pre_window=1.0,
...     post_window=1.0,
...     show_pose=True,
...     animal_names=False,
...     core_cnt=4
... )
>>> plotter.run()

Pose-estimation plotter

Create pose-estimation visualizations from data within a SimBA project folder using multiprocessing.

param Union[str, os.PathLike] data_path

Path to a SimBA project directory containing pose-estimation data (parquet or CSV), or path to a single pose file. Must be under project_folder/csv/ so that project_config.ini can be located.

param Optional[Union[str, os.PathLike]] out_dir

Directory where pose-estimation videos are saved. If None, saves to a new folder under the input data directory. Default None.

param Optional[Dict[str, str]] palettes

Dict mapping animal names to color palette names (e.g. {'Animal_1': 'Set1', 'Animal_2': 'Pastel1'}). Must have one entry per animal. If None, uses project default body-part colors. Default None.

param Optional[int] circle_size

Radius of circles drawn at each body-part location. If None, auto-computed from video resolution. Default None.

param Optional[int] core_cnt

Number of CPU cores for multiprocessing. -1 uses all available cores. Default -1.

param Optional[bool] gpu

If True, use GPU for video concatenation when available. Default False.

param Optional[Literal[‘axis-aligned’, ‘animal-aligned’]] bbox

If not None, draw bounding boxes around each animal. 'axis-aligned' = rectangle aligned with video axes; 'animal-aligned' = minimum rotated rectangle aligned with the animal’s orientation. Default None (no bounding boxes).

param Optional[Tuple[int, int, int]] center_of_mass

If not None, RGB tuple (e.g. (255, 0, 0)) for drawing a center-of-mass dot per animal. Default None (no center of mass).

param Optional[int] sample_time

If not None, render only the first N seconds of each video (N = this value). Useful for quick previews. Default None (full video).

param bool verbose

If True, print progress messages during video creation. Default True.

example

>>> test = PosePlotterMultiProcess(data_path='project_folder/csv/outlier_corrected_movement_location', out_dir='/project_folder/test_viz', circle_size=10, core_cnt=1, palettes={'Animal_1': 'Set1', 'Animal_2': 'Pastel1'})
>>> test.run()

Skeleton video creator

class simba.plotting.skeleton_video_creator.SkeletonVideoCreator(config_path: Optional[Union[str, PathLike]] = None, data_path: Optional[Union[str, PathLike]] = None, save_dir: Optional[Union[str, PathLike]] = None, video_info_path: Optional[Union[str, PathLike]] = None, resolution: Tuple[int, int] = (500, 500), bg_color: Tuple[int, int, int] = (0, 0, 0), anchor_bp: Optional[str] = None, skeleton: Optional[List[Tuple[str, str]]] = None, circle_size: Optional[int] = None, line_thickness: Optional[int] = None, ego_anchor_1: Optional[str] = None, ego_anchor_2: Optional[str] = None, ego_direction: int = 0, omit_bps: Optional[List[str]] = None, palette: str = 'Set1', bp_threshold: float = 0.0, core_cnt: int = -1, verbose: bool = True)

Bases: object

Create pose-estimation videos rendered on a solid RGB background from SimBA CSV data.

Reads outlier-corrected pose CSV files (one row per frame), extracts body-part x/y columns, and renders keypoints and optional skeleton segments on a blank canvas—no source video is required. FPS for each output file is taken from video_info.csv for the matching video name.

Alignment modes (at most one applies; egocentric alignment takes precedence if both are set):

• Egocentric (ego_anchor_1 + ego_anchor_2): rotates/translates the pose so the segment from anchor 1 → anchor 2 matches ego_direction (see parameter).

• Center anchor (anchor_bp only, no egocentric anchors): each frame, shifts all keypoints so anchor_bp sits at the image center; no rotation.

Input CSVs must list body parts as <bp>_x / <bp>_y columns. Optional <bp>_p probability columns gate drawing; if any are missing, probabilities default to 1.0 for all body-parts. Skeleton edges are drawn in a fixed gray; keypoint disks use palette.

See also

PosePlotterMultiProcess — overlay pose on the original recording instead of a blank background. superimpose_overlay_video() — inset one video on another (for example, a skeleton clip over the raw recording).

Parameters

• config_path (Optional[Union[str, os.PathLike]]) – Path to SimBA project project_config.ini. If set, data_path, save_dir, and video_info_path default from the project unless overridden. Required unless all three of those are provided explicitly.

• data_path (Optional[Union[str, os.PathLike]]) – Path to one pose CSV or a directory of .csv files. If None and config_path is set, uses the project’s outlier-corrected movement directory.

• save_dir (Optional[Union[str, os.PathLike]]) – Directory for output <video_name>.mp4 files. If None and config_path is set, uses <project>/frames/output/pose_videos (created if needed).

• video_info_path (Optional[Union[str, os.PathLike]]) – Path to logs/video_info.csv (fps and video names). If None and config_path is set, uses the project’s video info path.

• resolution (Tuple[int, int]) – Output size (width, height) in pixels. Default (500, 500).

• bg_color (Tuple[int, int, int]) – Background color as RGB (R, G, B), each 0–255. Default (0, 0, 0) (black).

• anchor_bp (Optional[str]) – Body-part name whose location is pinned to the frame center each frame (case-insensitive match to CSV names). Ignored if egocentric anchors are set. Default None.

• skeleton (Optional[List[Tuple[str, str]]]) – Pairs of body-part names (from, to) for line segments. Omitted or skipped pairs involving omit_bps. If None, only keypoints are drawn.

• circle_size (Optional[int]) – Keypoint circle radius in pixels. If None, scaled from resolution.

• line_thickness (Optional[int]) – Skeleton line thickness in pixels. If None, scaled from resolution.

• ego_anchor_1 (Optional[str]) – First anchor body-part for egocentric alignment (e.g. tail_base). Must be given together with ego_anchor_2.

• ego_anchor_2 (Optional[str]) – Second anchor; together with ego_anchor_1 defines the forward axis before rotation.

• ego_direction (int) – Desired compass heading in degrees for the vector from ego_anchor_1 to ego_anchor_2 after alignment: 0 = north/up, 90 = east/right, 180 = south/down, 270 = west/left. Default 0.

• omit_bps (Optional[List[str]]) – Body-part names to exclude from dots and skeleton (lowercased internally).

• palette (str) – Matplotlib qualitative palette name for per-body-part keypoint colors. Default Set1.

• bp_threshold (float) – Minimum per-frame probability to draw a keypoint or use it in a skeleton edge. Default 0.0.

• core_cnt (int) – Worker processes for frame batches; -1 uses all CPUs. Default -1.

• verbose (bool) – Print batch and file progress. Default True.

Raises

• InvalidInputError – If neither config_path nor the triple (data_path, save_dir, video_info_path) is satisfactorily provided; or if only one of ego_anchor_1 / ego_anchor_2 is set.

• NoFilesFoundError – If data_path is not a valid file or directory.

Example

>>> creator = SkeletonVideoCreator(
...     config_path=r'E:/project/project_config.ini',
...     resolution=(500, 500),
...     bg_color=(0, 0, 0),
...     anchor_bp='tail_base',
...     skeleton=[('nose', 'left_ear'), ('nose', 'right_ear'), ('left_ear', 'center'), ('right_ear', 'center'), ('center', 'left_side'), ('center', 'right_side'), ('center', 'tail_base'), ('tail_base', 'tail_mid'), ('tail_mid', 'tail_end')],
...     ego_anchor_1='tail_base',
...     ego_anchor_2='nose',
... )
>>> creator.run()

run()

Render skeleton videos for every CSV in data_paths.

For each file, splits frames across a process pool, writes batch MP4s under <save_dir>/<video_name>/temp/, concatenates them to <save_dir>/<video_name>.mp4, then prints a completion summary. Does not return a value.

Classification probability plotter

Create classifier-probability line plots using single-process execution.

Produces one or more of: (i) frame-by-frame probability plot images, (ii) a dynamic probability-plot video, (iii) a final static probability plot (PNG or SVG).

Note

Documentation. For improved run-time, use simba.plotting.probability_plot_creator_mp.TresholdPlotCreatorMultiprocess()

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Union[List[Union[str, os.PathLike]], str, os.PathLike] data_path

Single machine-results file path or a list of file paths.

param str clf_name

Classifier name to visualize.

param bool frame_setting

If True, save one plot image per frame. Default: False.

param bool video_setting

If True, save a probability-plot video. Default: False.

param bool last_frame

If True, save a final static probability plot. Default: True.

param Tuple[int, int] size

Output image/video size as (width, height). Default: (640, 480).

param int font_size

Plot font size. Default: 10.

param int line_width

Probability line width. Default: 2.

param bool last_frame_as_svg

If True, save final static plot as SVG; else PNG. Default: False.

param Optional[int] y_max

Fixed y-axis max. If None, inferred from data.

param str line_color

Probability line color name. Default: 'Red'.

param float line_opacity

Probability line opacity in range (0, 1]. Default: 0.8.

param bool show_thresholds

If True, draw horizontal threshold guide lines. Default: True.

Examples

>>> style_attr = {'width': 640, 'height': 480, 'font size': 10, 'line width': 6, 'color': 'blue', 'circle size': 20}
>>> clf_name='Attack'
>>> files_found=['/_test/project_folder/csv/machine_results/Together_1.csv']

>>> threshold_plot_creator = TresholdPlotCreatorSingleProcess(config_path='/_test/project_folder/project_config.ini', frame_setting=False, video_setting=True, last_frame=True, clf_name=clf_name, files_found=files_found, style_attr=style_attr)
>>> threshold_plot_creator.run()

Classification probability plotter - multiprocess

Create classifier-probability line plots using multiprocessing.

Produces one or more of: (i) frame-by-frame probability plot images, (ii) a dynamic probability-plot video, (iii) a final static probability plot (PNG or SVG).

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param Union[List[Union[str, os.PathLike]], str, os.PathLike] data_path

Single machine-results file path or a list of file paths.

param str clf_name

Classifier name to visualize.

param bool frame_setting

If True, save one plot image per frame. Default: False.

param bool video_setting

If True, save a probability-plot video. Default: False.

param bool last_frame

If True, save a final static probability plot. Default: True.

param Tuple[int, int] size

Output image/video size as (width, height). Default: (640, 480).

param int font_size

Plot font size. Default: 10.

param int line_width

Probability line width. Default: 2.

param Optional[Union[int, float]] y_max

Fixed y-axis max. If None, inferred from data.

param str line_color

Probability line color name. Default: 'Red'.

param bool last_frame_as_svg

If True, save final static plot as SVG; else PNG. Default: False.

param float line_opacity

Probability line opacity in range (0, 1]. Default: 0.8.

param Optional[int] cores

Number of CPU cores. -1 uses all available cores. Default: -1.

param bool show_thresholds

If True, draw horizontal threshold guide lines. Default: True.

Note

Visualization tutorials.

example

>>> plot_creator = TresholdPlotCreatorMultiprocess(config_path='/Users/simon/Desktop/troubleshooting/train_model_project/project_folder/project_config.ini', frame_setting=True, video_setting=True, clf_name='Attack', style_attr={'width': 640, 'height': 480, 'font size': 10, 'line width': 6, 'color': 'magneta', 'circle size': 20}, cores=5)
>>> plot_creator.run()

SHAP aggregation plotter

Single video validation plotter

Create classifier validation video for a single input video with customizable visualization settings.

This class generates validation videos that overlay classifier predictions, pose estimations, and optional Gantt charts onto the original video. Results are stored in the project_folder/frames/output/validation directory.

Note

• For improved run-time with multiple cores, see simba.plotting.single_run_model_validation_video_mp.ValidateModelOneVideoMultiprocess().

• Video dimensions and optimal text/circle sizes are automatically calculated if not specified as a specific ratio of the image width/height.

param Union[str, os.PathLike] config_path

Path to SimBA project config file in Configparser format.

param Union[str, os.PathLike] feature_path

Path to SimBA file (parquet or CSV) containing pose-estimation and feature data.

param Union[str, os.PathLike] model_path

Path to pickled classifier object (.sav file).

param bool show_pose

If True, overlay pose estimation keypoints on the video. Default: True.

param bool show_animal_names

If True, display animal names near the first body part. Default: False.

param Optional[int] font_size

Font size for text overlays. If None, automatically calculated based on video dimensions.

param Optional[int] circle_size

Size of pose estimation circles. If None, automatically calculated based on video dimensions.

param Optional[int] text_spacing

Spacing between text lines. If None, automatically calculated.

param Optional[int] text_thickness

Thickness of text overlay. If None, uses default value.

param Optional[float] text_opacity

Opacity of text overlays (0.1-1.0). If None, defaults to 0.8.

param Optional[str] bp_palette

Optional name of the palette to use to color the animal body-parts (e.g., Pastel1). If None, spring is used.

param Optional[float] discrimination_threshold

Classification probability threshold (0.0-1.0). Default: 0.0.

param Optional[int] shortest_bout

Minimum classified bout length in milliseconds. Bouts shorter than this will be reclassified as absent. Default: 0.

param Optional[Union[None, int]] create_gantt

Gantt chart creation option:

• None: No Gantt chart

• 1: Static Gantt chart (final frame only, faster)

• 2: Dynamic Gantt chart (updated per frame)

example

>>> # Create validation video with pose overlay and static Gantt chart
>>> validator = ValidateModelOneVideo(
...     config_path=r'/path/to/project_config.ini',
...     feature_path=r'/path/to/features.csv',
...     model_path=r'/path/to/classifier.sav',
...     show_pose=True,
...     show_animal_names=True,
...     discrimination_threshold=0.6,
...     shortest_bout=500,
...     create_gantt=1
... )
>>> validator.run()

Single video validation plotter - multiprocess

Create classifier validation video for a single input video using multiprocessing for improved performance.

This class generates validation videos that overlay classifier predictions, pose estimations, and optional Gantt charts onto the original video using multiple CPU cores for faster processing. Results are stored in the project_folder/frames/output/validation directory.

Note

This multiprocess version provides significant speed improvements over the single-core simba.plotting.single_run_model_validation_video.ValidateModelOneVideo class.

param Union[str, os.PathLike] config_path

Path to SimBA project config file in Configparser format.

param Union[str, os.PathLike] feature_path

Path to SimBA file (parquet or CSV) containing pose-estimation and feature data.

param Union[str, os.PathLike] model_path

Path to pickled classifier object (.sav file).

param bool show_pose

If True, overlay pose estimation keypoints on the video. Default: True.

param bool show_animal_names

If True, display animal names near the first body part. Default: False.

param Optional[int] font_size

Font size for text overlays. If None, automatically calculated based on video dimensions.

param Optional[str] bp_palette

Optional name of the palette to use to color the animal body-parts (e.g., Pastel1). If None, spring is used.

param Optional[int] circle_size

Size of pose estimation circles. If None, automatically calculated based on video dimensions.

param Optional[int] text_spacing

Spacing between text lines. If None, automatically calculated.

param Optional[int] text_thickness

Thickness of text overlay. If None, uses default value.

param Optional[float] text_opacity

Opacity of text overlays (0.1-1.0). If None, defaults to 0.8.

param float discrimination_threshold

Classification probability threshold (0.0-1.0). Default: 0.0.

param int shortest_bout

Minimum classified bout length in milliseconds. Bouts shorter than this will be reclassified as absent. Default: 0.

param int core_cnt

Number of CPU cores to use for processing. If -1, uses all available cores. Default: -1.

param Optional[Union[None, int]] create_gantt

Gantt chart creation option:

• None: No Gantt chart

• 1: Static Gantt chart (final frame only, faster)

• 2: Dynamic Gantt chart (updated per frame)

example

>>> # Create multiprocess validation video with dynamic Gantt chart
>>> validator = ValidateModelOneVideoMultiprocess(
...     config_path=r'/path/to/project_config.ini',
...     feature_path=r'/path/to/features.csv',
...     model_path=r'/path/to/classifier.sav',
...     show_pose=True,
...     show_animal_names=True,
...     discrimination_threshold=0.6,
...     shortest_bout=500,
...     core_cnt=4,
...     create_gantt=2
... )
>>> validator.run()

Geometry plotter (generic)

class simba.plotting.geometry_plotter.GeometryPlotter(geometries: List[List[Union[LineString, Polygon, MultiPolygon, MultiLineString, Point]]], video_name: Union[str, PathLike], config_path: Optional[Union[str, PathLike]] = None, pool: Optional[Pool] = None, core_cnt: int = -1, save_dir: Optional[Union[str, PathLike]] = None, thickness: Optional[int] = None, circle_size: Optional[int] = None, intersection_clr: Optional[Tuple[int, int, int]] = None, bg_opacity: Optional[float] = 1, shape_opacity: float = 0.3, outline_clr: Optional[Tuple[int, int, int]] = None, time_slice: Optional[Dict[str, str]] = None, palette: Optional[str] = None, colors: Optional[List[Union[Tuple[int, int, int], str]]] = None, verbose: bool = True)

Bases: ConfigReader, PlottingMixin

A class for creating overlay geometry visualization videos based on provided geometries and video name.

See also

To quickly create static geometries on a white background (useful for troubleshooting unexpected geometries), see simba.mixins.geometry_mixin.GeometryMixin.view_shapes() and simba.mixins.geometry_mixin.GeometryMixin.geometry_video()

Parameters

• geometries (List[List[Union[Polygon, LineString, MultiPolygon, MultiLineString, Point]]]) – List of lists of geometries for each frame. Each list contains as many entries as frames. Each list may represent a track or unique tracked object.

• video_name (Union[str, os.PathLike]) – Name of the input video (path or filename; if filename, config_path must be provided).

• config_path (Optional[Union[str, os.PathLike]]) – Path to SimBA configuration file. Required when video_name is a filename. Default: None.

• pool (Optional[multiprocessing.Pool]) – Reusable process pool for parallel rendering. If None, a pool is created from core_cnt. Default: None.

• core_cnt (int) – Number of CPU cores to use for parallel processing. Ignored if pool is provided. Default: -1 (all available cores).

• save_dir (Optional[Union[str, os.PathLike]]) – Directory to save output videos. Required when config_path is None. Default: None.

• thickness (Optional[int]) – Thickness of geometry outlines and line strokes in pixels. Default: None (falls back to circle_size).

• circle_size (Optional[int]) – Radius in pixels for Point geometries. Default: None (auto from frame size).

• intersection_clr (Optional[Tuple[int, int, int]]) – BGR color for geometries that intersect another. None keeps original fill color. Default: None.

• bg_opacity (Optional[float]) – Background video opacity from 0.0 to 1.0. Default: 1.0.

• shape_opacity (float) – Shape fill opacity from 0.0 to 1.0. Default: 0.3.

• outline_clr (Optional[Tuple[int, int, int]]) – BGR color for polygon/line outlines. None disables outlines. Default: None.

• time_slice (Optional[Dict[str, str]]) – Restrict rendering to a time range. Must have keys 'start_time' and 'end_time' (HH:MM:SS). Default: None.

• palette (Optional[str]) – Color palette name for geometries. Provide either palette or colors. Default: None.

• colors (Optional[List[Union[str, Tuple[int, int, int]]]]) – Custom colors per geometry (names from SimBA color dict or BGR tuples). Length must match geometries. Default: None.

• verbose (Optional[bool]) – Print progress information. Default: True.

Raises

• InvalidInputError – If geometries are invalid, neither palette nor colors given, or video/config/save_dir inconsistent.

• CountError – If the number of shapes in the geometries does not match the number of frames in the video.

Spontaneous alternation plotter

Create plots representing delayed-alternation computations overlayed on video.

Note

Uses simba.data_processors.spontaneous_alternation_calculator.SpontaneousAlternationCalculator to compute alternation statistics.

param Union[str, os.PathLike] config_path

Path to SimBA project config file.

param List[str] arm_names

List of ROI names representing the arms.

param str center_name

Name of the ROI representing the center of the maze

param Optional[int] animal_area

Value between 51 and 100, representing the percent of the animal body that has to be situated in a ROI for it to be considered an entry.

param Optional[float] threshold

Value between 0.0 and 1.0. Body-parts with detection probabilities below this value will be (if possible) filtered when constructing the animal geometry.

param Optional[int] buffer

Millimeters area for which the animal geometry should be increased in size. Useful if the animal geometry does not fully cover the animal.

param Optional[int] core_cnt

The number of CPU cores to use when creating the visualization. Defaults to -1 which represents all avaialbale cores.

param Optional[Union[str, os.PathLike]] data_path

Path to the file to be analyzed, e.g., CSV file in project_folder/csv/outlier_corrected_movement_location` directory.

example

>>> config_path = '/Users/simon/Desktop/envs/simba/troubleshooting/spontenous_alternation/project_folder/project_config.ini'
>>> plotter = SpontaneousAlternationsPlotter(config_path=config_path, arm_names=['A', 'B', 'C'], center_name='Center', threshold=0.0, buffer=1, animal_area=60, data_path='/Users/simon/Desktop/envs/simba/troubleshooting/spontenous_alternation/project_folder/csv/outlier_corrected_movement_location/F1 HAB.csv')
>>> plotter.run()

“Blob” plotter

Plot the results of animal tracking based on blob.

See also

simba.mixins.plotting_mixin.PlottingMixin._plot_blobs(), simba.mixins.image_mixin.ImageMixin.get_blob_locations()

param Union[List[str], str, os.PathLike] data_path

Path(s) to video file(s) or directory containing video files.

param Optional[bool] gpu

Whether to use GPU for processing. Defaults to False.

param Optional[int] batch_size

Number of frames to process in each batch. Defaults to 2000. Increase if your RAM allows.

param Optional[Tuple[int, int, int]] circle_color

Color of the blobs as an RGB tuple. Defaults to pink (255, 105, 180).

param Optional[Union[str, os.PathLike]] save_dir

Directory to save output files. If None, no files will be saved.

param Optional[int] verbose

If True, then prints msgs informing on progress.

param Optional[str] smoothing

Savitzky Golay, Gaussian, or None. Smooths body-part coordinate data for more accurate blob representation. Default None.

param Optional[int] circle_size

The circle defining the x, y location of the animal in the data. Defaults to None and SimBA will try and retrieve the optimal circle size based in the video resolution.

param Optional[int] core_cnt

The number of cores to use for multiprocessing. Deafults to -1 which means all available cores.

example

>>> BlobPlotter(data_path=r"C:     roubleshooting\RAT_NOR\project_folder

ideos est‚2-06-20_NOB_DOT_4_downsampled.mp4”, smoothing=’Savitzky Golay’, circle_size=10).run()

“Blob” plotter

Visualize blob tracking data by overlaying geometric shapes and body part markers on video frames.

Processes blob tracking CSV data files and corresponding videos to create annotated output videos. It can visualize multiple body parts including convex hulls, anterior (nose), posterior (tail), center points, and left/right body parts. The visualizations are rendered with customizable colors, opacity, and circle sizes.

..seealso::

To create blob data, see simba.video_processors.blob_tracking_executor.BlobTrackingExecutor() To import blob data into SimBA project, see simba.pose_importers.simba_blob_importer.SimBABlobImporter()

param data_path

Path to a single CSV file or directory containing blob tracking CSV data files. CSV files must contain columns: ‘nose_x’, ‘nose_y’, ‘tail_x’, ‘tail_y’, ‘center_x’, ‘center_y’, ‘left_x’, ‘left_y’, ‘right_x’, ‘right_y’, and optionally ‘vertice_*’ columns for hull visualization.

param video_path

Path to a single video file or directory containing video files. Video filenames must match the corresponding CSV data filenames (without extension).

param save_dir

Directory path where annotated output videos will be saved. Directory will be created if it doesn’t exist.

param core_cnt

Number of CPU cores to use for video processing. Default: -1 (auto-detect). Set to -1 to use all available cores, or specify a positive integer.

param shape_opacity

Opacity of the drawn shapes (0.1-1.0). Default: 0.5. Lower values make shapes more transparent.

param bg_opacity

Opacity of the background video frames (0.1-1.0). Default: 1.0. Lower values make background more transparent.

param circle_size

Size of circles drawn for point markers (anterior, posterior, center, left, right). Default: None (uses default size). Set to None to use default, or specify a positive integer.

param hull

RGB color tuple (R, G, B) for convex hull visualization. Default: (178, 102, 255). Set to None to disable hull visualization.

param anterior

RGB color tuple (R, G, B) for anterior (nose) point visualization. Default: (0, 0, 255). Set to None to disable anterior visualization.

param posterior

RGB color tuple (R, G, B) for posterior (tail) point visualization. Default: (0, 128, 0). Set to None to disable posterior visualization.

param center

RGB color tuple (R, G, B) for center point visualization. Default: (0, 165, 255). Set to None to disable center visualization.

param left

RGB color tuple (R, G, B) for left body part point visualization. Default: (255, 51, 153). Set to None to disable left visualization.

param right

RGB color tuple (R, G, B) for right body part point visualization. Default: (255, 255, 102). Set to None to disable right visualization.

example

>>> visualizer = BlobVisualizer(data_path=r'/path/to/blob_data.csv',
...                             video_path=r'/path/to/video.mp4',
...                             save_dir=r'/path/to/output',
...                             core_cnt=4,
...                             shape_opacity=0.6,
...                             posterior=None,
...                             left=None,
...                             right=None)
>>> visualizer.run()

YOLO bounding-box plotter

class simba.plotting.yolo_visualize.YOLOVisualizer(data_path: Union[str, PathLike], video_path: Union[str, PathLike], save_dir: Union[str, PathLike], palette: Optional[str] = 'Set1', core_cnt: Optional[int] = -1, threshold: float = 0.0, padding: int = 0, pool: Optional[Pool] = None, thickness: Optional[int] = None, opacity: float = 0.6, outline_color: Optional[Tuple[int, int, int]] = None, color_by: typing_extensions.Literal['class', 'instance'] = 'class', verbose: bool = True)

Bases: object

Visualize YOLO bounding-box inference results on a source video.

See also

For bounding-box inference, see simba.model.yolo_inference.YoloInference.

Parameters

• data_path (Union[str, os.PathLike]) – Path to YOLO results CSV. Expected columns: FRAME, CLASS_ID, CLASS_NAME, CONFIDENCE, X1..Y4. Multiple rows sharing the same FRAME and CLASS_NAME (i.e. several detections of one class per frame, as produced by YoloInference with max_per_class > 1) are rendered as separate instances, each drawn as its own polygon track and color (ordered by detection confidence).

• video_path (Union[str, os.PathLike]) – Path to the video from which the data was produced.

• save_dir (Union[str, os.PathLike]) – Directory where to save visualization output.

• palette (Optional[str]) – Matplotlib color palette name for per-class geometry colors (e.g., 'Set1', 'tab10'). Default: 'Set1'.

• core_cnt (Optional[int]) – CPU core count for parallel processing. Use -1 for all available cores.

• threshold (float) – Confidence threshold in [0.0, 1.0]. Detections below threshold are masked before polygon conversion.

• padding (int) – Polygon offset in pixels used during multiframe bbox-to-polygon conversion for rendering. Defaults to 0 (draw the exact detection box). Positive values expand polygons outward, -1 shrinks them inward. This affects visualization geometry only, not the underlying YOLO detections in the input CSV.

• thickness (Optional[int]) – Polygon line thickness. If None, default geometry plotter thickness is used.

• opacity (float) – Polygon fill opacity in [0.0, 1.0]. Default: 0.6.

• outline_color (Optional[Tuple[int, int, int]]) – BGR color for polygon outlines. If None, no outlines are drawn. Default: None.

• color_by (Literal['class', 'instance']) – How detections are colored when multiple instances per class are present. 'class' (default) gives every instance of a class the same class color (avoids color flicker, since instance slots are confidence-ranked per frame and not identity-tracked). 'instance' gives each instance slot its own color (useful only when the data carries stable identities, e.g. from a tracker). For single-instance-per-class data both options are equivalent.

• verbose (bool) – If True, prints progress information. Default: True.

Raises

FrameRangeError – If YOLO result frame coverage does not match video frame count.

Example

>>> test = YOLOVisualizer(
...     data_path=r"/mnt/c/troubleshooting/yolo_inference/08102021_DOT_Rat7_8(2).csv",
...     video_path=r"/mnt/c/troubleshooting/RAT_NOR/project_folder/videos/08102021_DOT_Rat7_8(2).mp4",
...     save_dir="/mnt/c/troubleshooting/yolo_videos",
...     threshold=0.25,
...     core_cnt=4
... )
>>> test.run()

YOLO model comparator

class simba.plotting.compare_bbox_mdls.YoloModelComparator(weights: List[Union[str, PathLike]], video_path: Union[str, PathLike, List[Union[str, PathLike]]], out_dir: Union[str, PathLike], labels: Optional[List[str]] = None, threshold: float = 0.05, device: Union[typing_extensions.Literal['cpu'], int] = 0, batch_size: Optional[int] = None, imgsz: Optional[int] = None, max_detections: int = 300, max_per_class: Optional[int] = None, palette: Optional[str] = 'Set1', opacity: float = 0.6, thickness: Optional[int] = 2, padding: int = 0, outline_color: Optional[Tuple[int, int, int]] = None, color_by: typing_extensions.Literal['class', 'instance'] = 'class', core_cnt: Optional[int] = None, gpu: bool = False, overwrite: bool = True, overlay_labels: bool = True, time_window: Optional[Dict[str, str]] = None, verbose: bool = True)

Bases: object

Compare two or more YOLO models side-by-side on a set of test videos.

Per-model CSV detections and visualization videos are written to``out_dir/<label>/`` and the final comparison videos to out_dir/compare/.

See also

YoloInference (per-model inference) YOLOVisualizer (per-model rendering) horizontal_video_concatenator() (side-by-side concat)

Parameters

• weights (List[Union[str, os.PathLike]]) – List of YOLO model weight paths (length >= 2).

• video_path (Union[str, os.PathLike, List[Union[str, os.PathLike]]]) – One of: a single video file path; a directory of videos (searched non-recursively); or a list/tuple of video file paths.

• out_dir (Union[str, os.PathLike]) – Output directory. Per-model CSV/viz subdirectories and a compare/ subdirectory are created underneath.

• labels (Optional[List[str]]) – Display labels (one per model). If None, the weight file name (without extension) of each model is used. Must be unique and match len(weights).

• threshold (float) – YOLO detection confidence threshold in [0.0, 1.0].

• device (Union[Literal['cpu'], int]) – Inference device (‘cpu’ or CUDA index).

• batch_size (Optional[int]) – Frames per YOLO inference batch. If None, it is read per-model from the model metadata (required for .engine files); falls back to 400 when unavailable (e.g. .pt weights).

• imgsz (Optional[int]) – Model inference image size. If None, it is read per-model from the model metadata; falls back to 320 when unavailable. For .engine files the engine’s baked-in image size always wins (a mismatching explicit value is overridden with a warning).

• max_detections (int) – Maximum detections per frame (total, across all classes) returned by each model.

• max_per_class (Optional[int]) – Maximum number of detections to retain per class per frame. E.g., if one ‘resident’ and one ‘intruder’ is expected, set this to 1. Defaults to None, meaning all detected instances of each class are retained (up to max_detections). Passed through to each model’s YoloInference.

• palette (Optional[str]) – Matplotlib palette passed to YOLOVisualizer.

• opacity (float) – Polygon fill opacity in [0.0, 1.0] for the visualization.

• thickness (Optional[int]) – Polygon line thickness.

• padding (int) – Polygon offset in pixels for the visualization. Defaults to 0 (draw the exact detection box). Positive values expand polygons outward, -1 shrinks them inward.

• outline_color (Optional[Tuple[int, int, int]]) – BGR outline color for polygons.

• color_by (Literal['class', 'instance']) – Passed to YOLOVisualizer. 'class' (default) colors every instance of a class the same (avoids color flicker when max_per_class > 1, since instances are confidence-ranked per frame, not identity-tracked); 'instance' colors each instance slot separately. Equivalent for single-instance data.

• core_cnt (Optional[int]) – CPU core count for the visualizer. If None, defaults to a quarter of the available cores to leave headroom; -1 = all cores.

• gpu (bool) – Use the NVENC codec when concatenating side-by-side.

• overwrite (bool) – If True (default), always re-render comparison videos. If False, skip videos whose comparison output already exists.

• overlay_labels (bool) – If True, burns each model’s label into the top-left corner of its panel before side-by-side concatenation, so the panels are self-describing.

• time_window (Optional[Dict[str, str]]) – Analysis window as a dict with 'start' and 'end' keys, both in HH:MM:SS format (e.g. {'start': '00:00:05', 'end': '00:00:30'}). If provided, each video is clipped to the window (saved under out_dir/clips/) and the comparison runs on the clip. If None, the full video is analysed.

• verbose (bool) – Print progress information.

Example

>>> c = YoloModelComparator(
...     weights=[r"/mdl/train8/weights/best.pt", r"/mdl/train13/weights/best.pt"],
...     video_path=r"/test_videos",
...     out_dir=r"/yolo_comparison",
...     labels=["train8", "train13"],
...     threshold=0.05,
...     max_detections=1,
...     device=0,
... )
>>> c.run()

Plotting methods

class simba.mixins.plotting_mixin.PlottingMixin

Bases: object

Methods for visualizations

static categorical_scatter(data: Union[ndarray, DataFrame], columns: Optional[List[str]] = ('X', 'Y', 'Cluster'), palette: Optional[str] = 'Set1', show_box: Optional[bool] = False, size: Optional[int] = 10, title: Optional[str] = None, save_path: Optional[Union[str, PathLike]] = None)

Create a 2D scatterplot with a categorical legend.

Parameters

• data (Union[np.ndarray, pd.DataFrame]) – Input data, either a NumPy array or a pandas DataFrame.

• columns (Optional[List[str]]) – A list of column names for the x-axis, y-axis, and the categorical variable respectively. Default is [“X”, “Y”, “Cluster”].

• palette (Optional[str]) – The color palette to be used for the categorical variable. Default is “Set1”.

• show_box (Optional[bool]) – Whether to display the plot axis. Default is False.

• size (Optional[int]) – Size of markers in the scatterplot. Default is 10.

• title (Optional[str]) – Title for the plot. Default is None.

• save_path (Optional[Union[str, os.PathLike]]) – The path where the plot will be saved. Default is None which returns the image.

Returns matplotlib.axes._subplots.AxesSubplot or None

The scatterplot if ‘save_path’ is not provided, otherwise None.

static continuous_scatter(data: Union[ndarray, DataFrame], columns: Optional[List[str]] = ('X', 'Y', 'Cluster'), palette: Optional[str] = 'magma', show_box: Optional[bool] = False, size: Optional[int] = 10, title: Optional[str] = None, bg_clr: Optional[str] = None, save_path: Optional[Union[str, PathLike]] = None)

Create a 2D scatterplot with a continuous legend

create_gantt_img(bouts_df: DataFrame, clf_name: str, image_index: int, fps: int, gantt_img_title: str, header_font_size: int = 24, label_font_size: int = 12)

Helper to create a single gantt plot based on the data preceeding the input image

Parameters

• bouts_df (pd.DataFrame) – ataframe holding information on individual bouts created by simba.misc_tools.get_bouts_for_gantt().

• clf_name (str) – Name of the classifier.

• image_index (int) – The count of the image. E.g., 1000 will create a gantt image representing frame 1-1000.

• fps (int) – The fps of the input video.

• gantt_img_title (str) – Title of the image.

:return np.ndarray

create_single_color_lst(pallete_name: typing_extensions.Literal[<Options.PALETTE_OPTIONS: ['magma', 'jet', 'inferno', 'plasma', 'viridis', 'gnuplot2', 'RdBu', 'winter', 'coolwarm']>], increments: int, as_rgb_ratio: bool = False, as_hex: bool = False) → List[Union[str, int, float]]

Helper to create a color palette of bgr colors in a list.

Parameters

• pallete_name (str) – Palette name (e.g., ‘jet’)

• increments (int) – Numbers of colors in the color palette to create.

• as_rgb_ratio (bool) – If True returns the colors as RGB ratios (0-1).

• as_hex (bool) – If True, returns the colors as HEX.

:return list

Note

If as_rgb_ratio AND as_hex, then returns HEX.

static draw_lines_on_img(img: ndarray, start_positions: ndarray, end_positions: ndarray, color: Tuple[int, int, int], opacity: Optional[float] = None, highlight_endpoint: Optional[bool] = False, thickness: Optional[int] = 2, circle_size: Optional[int] = 2) → ndarray

Helper to draw a set of lines onto an image.

Parameters

• img (np.ndarray) – The image to draw the lines on.

• start_positions (np.ndarray) – 2D numpy array representing the start positions of the lines in x, y format.

• end_positions (np.ndarray) – 2D numpy array representing the end positions of the lines in x, y format.

• color (Tuple[int, int, int]) – The color of the lines in BGR format.

• highlight_endpoint (Optional[bool]) – If True, highlights the ends of the lines with circles.

• thickness (Optional[int]) – The thickness of the lines.

• circle_size (Optional[int]) – If highlight_endpoint is True, the size of the highlighted points.

Return np.ndarray

The image with the lines overlayed.

get_bouts_for_gantt(data_df: DataFrame, clf_name: str, fps: int) → DataFrame

Helper to detect all behavior bouts for a specific classifier.

Parameters

• data_df (pd.DataFrame) – Pandas Dataframe with classifier prediction data.

• clf_name (str) – Name of the classifier

• fps (int) – The fps of the input video.

Return pd.DataFrame

Holding the start time, end time, end frame, bout time etc of each classified bout.

get_optimal_circle_size(frame_size: Tuple[int, int], circle_frame_ratio: Optional[int] = 100) → int

Calculate the optimal circle size for fitting within a rectangular frame based on a given ratio.

This method computes the diameter of a circle that fits within the smallest dimension of a rectangular frame, scaled by a specified ratio. The resulting circle size ensures that it fits within the bounds of the frame while maintaining the specified size ratio.

Parameters

• frame_size (Tuple[int, int]) – A tuple representing the dimensions of the rectangular frame (width, height).

• circle_frame_ratio (Optional[int]) – An integer representing the ratio between the frame’s smallest dimension and the circle’s diameter. A lower ratio results in a larger circle, and a higher ratio results in a smaller circle.

Returns int

The computed diameter of the circle that fits within the smallest dimension of the frame, scaled by the circle_frame_ratio.

get_optimal_font_scales(text: Union[str, List[str]], accepted_px_width: int, accepted_px_height: int, text_thickness: Optional[int] = 2, font: Optional[int] = 4) → Tuple[float, int, int]

Get the optimal font size, column-wise and row-wise text distance of printed text for printing on images.

Parameters

• text (str) – The text to be printed. Either a string or a list of strings. If a list, then the longest string will be used to evaluate spacings/font.

• accepted_px_width (int) – The widest allowed string in pixels. E.g., 1/4th of the image width.

• accepted_px_height (int) – The highest allowed string in pixels. E.g., 1/10th of the image size.

• text_thickness (Optional[int]) – The thickness of the font. Default: 2.

• font (Optional[int]) – The font integer representation 0-7. See ``simba.utils.enums.Options.CV2_FONTS.values

Returns Tuple[int, int, int]

The font size, the shift on x between successive columns, the shift in y between successive rows.

Example

>>> img = cv2.imread('/Users/simon/Desktop/Screenshot 2024-07-08 at 4.46.03 PM.png')
>>> accepted_px_width = int(img.shape[1] / 4)
>>> accepted_px_height = int(img.shape[0] / 10)
>>>>text = 'HELLO MY FELLOW'
>>> PlottingMixin().get_optimal_font_scales(text=text, accepted_px_width=accepted_px_width, accepted_px_height=accepted_px_height, text_thickness=2)

static get_path_img(data: ndarray, size: Optional[Tuple[int, int]] = None, line_thickness: float = 2, line_color: Union[Tuple[int, int, int], typing_extensions.Literal['time', 'velocity']] = (147, 20, 255), bg_clr: Union[Tuple[int, int, int], ndarray] = (255, 255, 255), opacity: int = 1.0, smoothing_time: Optional[int] = None, save_path: Optional[Union[str, PathLike]] = None, svg: bool = False, dpi: int = 500) → Optional[Figure]

Create a path plot from NumPy array data.

Generates a path visualization with optional time or velocity-based coloring, background images, smoothing, and SVG/PNG output.

Parameters

• data (np.ndarray) – 2D array with shape (N, 2) containing x, y coordinates.

• size (Optional[Tuple[int, int]]) – Image size as (height, width) in pixels. If None, auto-calculated from data or bg_img.

• line_thickness (float) – Thickness of the path line. Default: 2.

• line_color (Tuple[int, int, int]) – RGB color tuple (0-255). Default: (147, 20, 255).

• bg_clr (Tuple[int, int, int]) – Background color RGB tuple (0-255). Default: (255, 255, 255).

• bg_img (Optional[np.ndarray]) – Background image array. If provided, overrides bg_clr. Default: None.

• opacity (float) – Line opacity (0.0-1.0). Default: 1.0.

• smoothing_time (Optional[int]) – Smoothing time window in milliseconds. Applies Savitzky-Golay filter. If None, no smoothing. Default: None.

• color_by (Optional[Literal['time', 'velocity']]) – Color path by time progression or velocity. If None, uses line_color. Default: None.

• save_path (Optional[Union[str, os.PathLike]]) – Path to save the image. If None, returns figure.

• svg (bool) – If True, saves as SVG format. If False, saves as PNG. Default: False.

• dpi (int) – Resolution for saved images. Default: 500.

Returns Optional[matplotlib.figure.Figure]

Returns matplotlib figure if save_path is None, otherwise None.

See also

For more complex path plots with multiprocessing and advanced features, see simba.plotting.path_plotter.PathPlotterSingleCore and simba.plotting.path_plotter_mp.PathPlotterMulticore.

Example

>>> df = pd.read_csv('/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/csv/outlier_corrected_movement_location/2022-06-20_NOB_DOT_4.csv')
>>> data = df[['Nose_x', 'Nose_y']].values
>>> img = read_frm_of_video(video_path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/2022-06-20_NOB_DOT_4.mp4', frame_index=400)
>>> PlottingMixin().get_path_img(data=data,
>>>          size=(1080, 1080),
>>>          line_thickness=0.5,
>>>          line_color=(0, 255, 0),
>>>          bg_clr=(255, 255, 255),
>>>          bg_img=img,
>>>          save_path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/csv/outlier_corrected_movement_location/2022-06-20_NOB_DOT_4_3.png',
>>>          dpi=600,
>>>          opacity=1.0,
>>>          color_by=None,
>>>          svg=False,
>>>          smoothing_time=5000)

static insert_directing_line(directing_df: DataFrame, img: ndarray, shape_name: str, animal_name: str, frame_id: int, color: Optional[Tuple[int]] = (0, 0, 255), thickness: Optional[int] = 2, style: Optional[str] = 'lines') → ndarray

Helper to insert lines between the actor ‘eye’ and the ROI centers.

Parameters

• directing_df – Dataframe containing eye and ROI locations. Stored as results in instance of simba.roi_tools.ROI_directing_analyzer.DirectingROIAnalyzer.

• img (np.ndarray) – The image to draw the line on.

• shape_name (str) – The name of the shape to draw the line to.

• animal_name (str) – The name of the animal

• frame_id (int) – The frame number in the video

• color (Optional[Tuple[int]]) – The color of the line

• thickness (Optional[int]) – The thickness of the line.

• style (Optional[str]) – The style of the line. “lines” or “funnel”.

Return np.ndarray

The input image with the line.

static joint_plot(data: Union[ndarray, DataFrame], columns: Optional[List[str]] = ('X', 'Y', 'Cluster'), palette: Optional[str] = 'Set1', kind: Optional[str] = 'scatter', size: Optional[int] = 10, title: Optional[str] = None, save_path: Optional[Union[str, PathLike]] = None)

Generate a joint plot.

Useful when visualizing embedded behavior data latent spaces with dense and overlapping scatters.

Parameters

• data (Union[np.ndarray, pd.DataFrame]) – Input data, either a NumPy array or a pandas DataFrame.

• columns (Optional[List[str]]) – Names of columns if input is dataframe, default is [“X”, “Y”, “Cluster”].

• palette (Optional[str]) – Palette for the plot, default is “Set1”.

• kind (Optional[str]) – Type of plot (“scatter”, “kde”, “hist”, or “reg”), default is “scatter”.

• size (Optional[int]) – Size of markers for scatter plot, default is 10.

• title (Optional[str]) – Title of the plot, default is None.

• save_path (Optional[Union[str, os.PathLike]]) – Path to save the plot image, default is None.

Returns sns.JointGrid or None

JointGrid object if save_path is None, else None.

Example

>>> data, lbls = make_blobs(n_samples=100000, n_features=2, centers=10, random_state=42)
>>> data = np.hstack((data, lbls.reshape(-1, 1)))
>>> PlottingMixin.joint_plot(data=data, columns=['X', 'Y', 'Cluster'], title='The plot')

static line_plot(df: DataFrame, x: str, y: Union[str, List[str]], error: Optional[Union[str, List[str]]] = None, x_label: Optional[str] = None, y_label: Optional[str] = None, title: Optional[str] = None, fig_size: Tuple[int] = (10, 6), error_opacity: float = 0.2, palette: str = 'Set1', grid: bool = True, bg_clr: str = 'white', line_width: float = 1.5, line_opacity: float = 1.0, save_path: Optional[Union[str, PathLike]] = None, dpi: Optional[int] = None, tight_layout: bool = True, show_legend: bool = True, legend_loc: Optional[str] = 'best', font_size: Optional[int] = None, title_font_size: Optional[int] = None, x_lim: Optional[Tuple[float, float]] = None, y_lim: Optional[Tuple[float, float]] = None, marker: Optional[str] = None, markersize: Optional[float] = None, linestyle: Optional[Union[str, List[str]]] = None, save_kwargs: Optional[Dict[str, Any]] = None, svg: bool = False, x_tick_lbl_rotation: Optional[int] = None, x_tick_interval: Optional[int] = None)

Line plot from DataFrame with optional error bands.

Optional styling arguments (useful for publication or clearer plots): - dpi: Resolution for saved figure (e.g. 150, 300). Ignored when svg=True. - tight_layout: If True, call fig.tight_layout() before save (default True). - show_legend: Whether to show the legend (default True). - legend_loc: Legend position, e.g. ‘best’, ‘upper right’, ‘lower left’. - font_size: Font size for axis labels and tick labels. - title_font_size: Font size for the title (default 15 if title set). - x_lim, y_lim: (min, max) tuples to fix axis limits. - marker: Matplotlib marker for data points (e.g. ‘o’, ‘s’, ‘^’). - markersize: Size of markers when marker is set. - linestyle: Single style or list of styles per series (‘-’, ‘–’, ‘-.’, ‘:’). - save_kwargs: Dict passed to plt.savefig (e.g. bbox_inches=’tight’, pad_inches=0.1). - svg: If True and save_path is set, save as SVG (path extension becomes .svg).

make_distance_plot(data: array, line_attr: Dict[int, str], style_attr: Dict[str, Any], fps: int, save_img: bool = False, save_path: Optional[str] = None) → ndarray

Helper to make a single line plot .png image with N lines.

Parameters

• data (np.array) – Two-dimensional array where rows represent frames and columns represent intertwined x and y coordinates.

• line_attr (dict) – Line color attributes.

• style_attr (dict) – Plot attributes (size, font size, line width etc).

• fps (int) – Video frame rate.

• save_path (Optionan[str]) – Location to store output .png image. If None, then return image.

Note

GitHub tutorial/documentation.

Example

>>> fps = 10
>>> data = np.random.random((100,2))
>>> line_attr = {0: ['Blue'], 1: ['Red']}
>>> save_path = '/_tests/final_frm.png'
>>> style_attr = {'width': 640, 'height': 480, 'line width': 6, 'font size': 8, 'y_max': 'auto'}
>>> self.make_distance_plot(fps=fps, data=data, line_attr=line_attr, style_attr=style_attr, save_path=save_path)

make_gantt_plot(bouts_df: DataFrame, clf_names: List[str], palette: List[Tuple[int, int, int]], fps: int, x_length: int, video_name: str, width: int = 640, height: int = 480, font_size: int = 8, bar_opacity: float = 0.85, font_rotation: int = 45, x_tick_lbl_rotation: int = 45, font: Optional[str] = None, title: Optional[str] = None, title_font_size: int = 24, save_path: Optional[str] = None, edge_clr: Optional[str] = 'black', hhmmss: bool = False, as_svg: bool = False) → Union[None, ndarray, str]

Create a Gantt chart visualization of behavioral bouts over time.

Generates a horizontal bar chart where each row represents a behavior class, and bars indicate when behaviors occurred. Supports SVG output for scalable figures or PNG/NumPy array for video overlays.

Parameters

• bouts_df (pd.DataFrame) – DataFrame containing bout data with columns ‘Event’, ‘Start_time’, and ‘Bout_time’.

• clf_names (List[str]) – List of behavior/classifier names to display. Must match ‘Event’ values in bouts_df.

• palette (List[Tuple[int, int, int]]) – List of RGB color tuples (0-255) for each behavior. Length should match clf_names.

• fps (int) – Frames per second of the source video. Used to convert frame counts to time.

• x_length (int) – Total length of the session in frames. Determines x-axis range.

• video_name (str) – Title displayed at the top of the chart.

• width (int) – Output image width in pixels (when not SVG). Default: 640.

• height (int) – Output image height in pixels (when not SVG). Default: 480.

• font_size (int) – Base font size for labels and ticks. Default: 8.

• bar_opacity (float) – Opacity of behavior bars (0.0-1.0). Default: 0.85.

• font_rotation (int) – Rotation angle in degrees for y-axis labels. Default: 45.

• x_tick_lbl_rotation (int) – Rotation angle in degrees for x-axis tick labels. Default: 0.

• font (Optional[str]) – Font family name. If None, uses matplotlib default.

• save_path (Optional[str]) – Path to save the image. If None and as_svg=False, returns NumPy array.

• edge_clr (Optional[str]) – Color of bar edges. Default: ‘black’.

• hhmmss (bool) – If True, displays x-axis time as HH:MM:SS. If False, displays seconds. Default: False.

• as_svg (bool) – If True, returns or saves SVG format. If False, uses PNG format. Default: False.

Returns Union[None, np.ndarray, str]

If as_svg=True and save_path=None, returns SVG string. If save_path provided, returns None (saves file). Otherwise returns NumPy array (BGR format).

static make_line_plot(data: List[ndarray], colors: List[str], show_box: Optional[bool] = True, width: Optional[int] = 640, height: Optional[int] = 480, line_width: Optional[int] = 6, font_size: Optional[int] = 8, bg_clr: Optional[str] = None, x_lbl_divisor: Optional[float] = None, title: Optional[str] = None, y_lbl: Optional[str] = None, x_lbl: Optional[str] = None, y_tick_lbls_as_int: bool = False, x_tick_lbls_as_int: bool = False, y_tick_cnt: int = 10, x_tick_cnt: int = 5, y_max: Optional[Union[float, int]] = -1, line_opacity: Optional[float] = 1.0, as_svg: bool = False, save_path: Optional[Union[str, PathLike]] = None, show_thresholds: bool = False)

Create a multi-line plot from NumPy arrays.

Generates a line plot with one or more data series, each with customizable colors and styling. Supports SVG output for scalable figures or PNG/NumPy array for video overlays.

Parameters

• data (List[np.ndarray]) – List of 1D or 2D NumPy arrays to plot. Each array becomes one line.

• colors (List[str]) – List of color names (must match length of data). Uses SimBA color dictionary.

• show_box (Optional[bool]) – If False, hides plot axes and borders. Default: True.

• width (Optional[int]) – Output image width in pixels (when not SVG). Default: 640.

• height (Optional[int]) – Output image height in pixels (when not SVG). Default: 480.

• line_width (Optional[int]) – Width of plotted lines. Default: 6.

• font_size (Optional[int]) – Font size for labels and ticks. Default: 8.

• bg_clr (Optional[str]) – Background color name. If None, uses matplotlib default.

• x_lbl_divisor (Optional[float]) – Divide x-axis tick labels by this value (e.g., convert frames to seconds). Default: None.

• title (Optional[str]) – Plot title displayed at top.

• y_lbl (Optional[str]) – Y-axis label.

• x_lbl (Optional[str]) – X-axis label.

• y_tick_lbls_as_int (bool) – If True, formats y-axis ticks as integers. Default: False.

• x_tick_lbls_as_int (bool) – If True, formats x-axis ticks as integers. Default: False.

• y_tick_cnt (int) – Number of y-axis tick marks. Default: 10.

• x_tick_cnt (int) – Number of x-axis tick marks. Default: 5.

• y_max (Optional[Union[int, float]]) – Maximum y-axis value. If -1, auto-scales to data maximum. Default: -1.

• line_opacity (Optional[float]) – Opacity of lines (0.0-1.0). Default: 1.0.

• as_svg (bool) – If True, returns or saves SVG format. If False, uses PNG format. Default: False.

• save_path (Optional[Union[str, os.PathLike]]) – Path to save the image. If None and as_svg=False, returns NumPy array.

• show_thresholds (bool) – If True, displays horizontal threshold lines at 25%, 50%, and 75%. Default: False.

Returns Union[None, np.ndarray, str]

If as_svg=True and save_path=None, returns SVG string. If save_path provided, returns None (saves file). Otherwise returns NumPy array (BGR format).

static make_line_plot_plotly(data: List[ndarray], colors: List[str], show_box: Optional[bool] = True, show_grid: Optional[bool] = False, width: Optional[int] = 640, height: Optional[int] = 480, line_width: Optional[int] = 6, font_size: Optional[int] = 8, bg_clr: Optional[str] = 'white', x_lbl_divisor: Optional[float] = None, title: Optional[str] = None, y_lbl: Optional[str] = None, x_lbl: Optional[str] = None, y_max: Optional[int] = -1, line_opacity: Optional[int] = 0.5, save_path: Optional[Union[str, PathLike]] = None)

Create a line plot using Plotly.

Note

Plotly can be more reliable than matplotlib on some systems when accessed through multprocessing calls.

If not called though multiprocessing, consider using simba.mixins.plotting_mixin.PlottingMixin.make_line_plot()

Uses kaleido for transform image to numpy array or save to disk.

Parameters

• data (List[np.ndarray]) – List of 1D numpy arrays representing lines.

• colors (List[str]) – List of named colors of size len(data).

• show_box (bool) – Whether to show the plot box (axes, title, etc.).

• show_grid (bool) – Whether to show gridlines on the plot.

• width (int) – Width of the plot in pixels.

• height (int) – Height of the plot in pixels.

• line_width (int) – Width of the lines in the plot.

• font_size (int) – Font size for axis labels and tick labels.

• bg_clr (str) – Background color of the plot.

• x_lbl_divisor (float) – Divisor for adjusting the tick spacing on the x-axis.

• title (str) – Title of the plot.

• y_lbl (str) – Label for the y-axis.

• x_lbl (str) – Label for the x-axis.

• y_max (int) – Maximum value for the y-axis.

• line_opacity (float) – Opacity of the lines in the plot.

• save_path (Union[str, os.PathLike]) – Path to save the plot image. If None, returns a numpy array of the plot.

Returns

If save_path is None, returns a numpy array representing the plot image.

Example

>>> p = np.random.randint(0, 50, (100,))
>>> y = np.random.randint(0, 50, (200,))
>>> img = PlottingMixin.make_line_plot_plotly(data=[p, y], show_box=False, font_size=20, bg_clr='white', show_grid=False, x_lbl_divisor=30, colors=['Red', 'Green'], save_path='/Users/simon/Desktop/envs/simba/troubleshooting/beepboop174/project_folder/frames/output/line_plot/Trial     3_final_img.png')

static make_path_plot(data: List[ndarray], colors: List[Union[Tuple[int, int, int], str]], width: Optional[int] = 640, height: Optional[int] = 480, max_lines: Optional[int] = None, bg_clr: Optional[Union[Tuple[int, int, int], ndarray]] = (255, 255, 255), circle_size: Optional[int] = 3, font_size: Optional[float] = 2.0, font_thickness: Optional[int] = 2, line_width: Optional[int] = 2, animal_names: Optional[List[str]] = None, clf_attr: Optional[Dict[str, Any]] = None, save_path: Optional[Union[str, PathLike]] = None) → Union[None, ndarray]

Creates a path plot visualization from the given data.

Parameters

• data (List[np.ndarray]) – List of numpy arrays containing path data.

• colors (List[Tuple[int, int, int]]) – List of RGB tuples, strings (names of palettes), or lists of list of tuples, representing colors for each path.

• width – Width of the output image (default is 640 pixels).

• height – Height of the output image (default is 480 pixels).

• max_lines – Maximum number of lines to plot from each path data.

• bg_clr – Background color of the plot (default is white).

• circle_size – Size of the circle marker at the end of each path (default is 3).

• font_size – Font size for displaying animal names (default is 2.0).

• font_thickness – Thickness of the font for displaying animal names (default is 2).

• line_width – Width of the lines representing paths (default is 2).

• animal_names – List of names for the animals corresponding to each path.

• clf_attr – Dictionary containing attributes for classification markers.

• save_path – Path to save the generated plot image.

Returns

If save_path is None, returns the generated image as a numpy array, otherwise, returns None.

Example

>>> x = np.random.randint(0, 500, (100, 2))
>>> y = np.random.randint(0, 500, (100, 2))
>>> position_data = np.random.randint(0, 500, (100, 2))
>>> clf_data_1 = np.random.randint(0, 2, (100,))
>>> clf_data_2 = np.random.randint(0, 2, (100,))
>>> clf_data = {'Attack': {'color': (155, 1, 10), 'size': 30, 'positions': position_data, 'clfs': clf_data_1},  'Sniffing': {'color': (155, 90, 10), 'size': 30, 'positions': position_data, 'clfs': clf_data_2}}
>>> PlottingMixin.make_path_plot(data=[x, y], colors=[(0, 255, 0), (255, 0, 0)], clf_attr=clf_data)

make_probability_plot(data: Series, style_attr: dict, clf_name: str, fps: int, save_path: str) → ndarray

Make a single classifier probability plot png image.

Parameters

• data (pd.Series) – row representing frames and field representing classification probabilities.

• line_attr (dict) – Line color attributes.

• style_attr (dict) – Image attributes (size, font size, line width etc).

• fps (int) – Video frame rate.

:param str ot :param str save_path: Location to store output .png image.

Example

>>> data = pd.Series(np.random.random((100, 1)).flatten())
>>> style_attr = {'width': 640, 'height': 480, 'font size': 10, 'line width': 6, 'color': 'blue', 'circle size': 20}
>>> clf_name='Attack'
>>> fps=10
>>> save_path = '/_test/frames/output/probability_plots/Together_1_final_frame.png'

>>> _ = self.make_probability_plot(data=data, style_attr=style_attr, clf_name=clf_name, fps=fps, save_path=save_path)

static plot_bar_chart(df: DataFrame, x: str, y: str, error: Optional[str] = None, x_label: Optional[str] = None, y_label: Optional[str] = None, title: Optional[str] = None, fig_size: Tuple[int, int] = (10, 8), palette: str = 'magma', error_clr: str = 'grey', bar_alpha: float = 1.0, dpi: int = 600, orientation: typing_extensions.Literal['vertical', 'horizontal'] = 'vertical', y_min: float = 0.0, y_max: Optional[float] = None, save_path: Optional[Union[str, PathLike]] = None, as_svg: bool = False)

Create a bar chart from DataFrame columns.

Generates a bar chart with optional error bars, supporting both vertical and horizontal orientations. Uses seaborn for styling with customizable colors, transparency, and axis limits.

Parameters

• df (pd.DataFrame) – DataFrame containing the data to plot.

• x (str) – Column name for x-axis categories.

• y (str) – Column name for y-axis values (must be numeric).

• error (Optional[str]) – Column name for error bar values. If None, no error bars are shown.

• x_label (Optional[str]) – X-axis label. If None, no label is displayed.

• y_label (Optional[str]) – Y-axis label. If None, no label is displayed.

• title (Optional[str]) – Chart title. If None, no title is displayed.

• fig_size (Tuple[int, int]) – Figure size (width, height) in inches. Default: (10, 8).

• palette (str) – Seaborn color palette name. Default: ‘magma’.

• error_clr (str) – Color name for error bars. Default: ‘grey’.

• bar_alpha (float) – Bar transparency (0.0-1.0). Default: 1.0.

• dpi (int) – Resolution for saved images. Default: 600.

• orientation (Literal['vertical', 'horizontal']) – Bar orientation. Default: ‘vertical’.

• y_min (float) – Minimum value for y-axis (or x-axis if horizontal). Default: 0.0.

• y_max (Optional[float]) – Maximum value for y-axis (or x-axis if horizontal). If None, auto-scales. Default: None.

• save_path (Optional[Union[str, os.PathLike]]) – Path to save the image. If None, returns matplotlib figure.

• as_svg (bool) – If True, saves as SVG format. If False, saves as PNG. Default: False.

Returns Optional[matplotlib.figure.Figure]

Returns matplotlib figure if save_path is None, otherwise returns None.

static plot_clf_cumcount(config_path: Union[str, PathLike], clf: str, data_dir: Optional[Union[str, PathLike]] = None, save_path: Optional[Union[str, PathLike]] = None, bouts: Optional[bool] = False, seconds: Optional[bool] = False) → None

Generates and saves a cumulative count plot of a specified classifier’s occurrences over video frames or time.

Parameters

• config_path (Union[str, os.PathLike]) – Path to the configuration file, which includes settings and paths for data processing and storage.

• clf (str) – The classifier name (e.g., ‘CIRCLING’) for which to calculate cumulative counts.

• data_dir (Optional[Union[str, os.PathLike]]) – Directory containing the log files to analyze. If not provided, the default path in the configuration is used.

• save_path (Optional[Union[str, os.PathLike]]) – Destination path to save the plot image. If None, saves to the logs path in the configuration.

• bouts (Optional[bool]) – If True, calculates the cumulative count in terms of detected bouts instead of time or frames.

• seconds (Optional[bool]) – If True, calculates time in seconds rather than frames.

Returns

None.

Example

>>> plot_clf_cumcount(config_path=r"D:  roubleshooting\mitra\project_folder\project_config.ini", clf='CIRCLING', data_dir=r'D:  roubleshooting\mitra\project_folder\logs        est', seconds=True, bouts=True)

put_text(img: ndarray, text: str, pos: Tuple[int, int], font_size: Union[int, float], font_thickness: Optional[int] = 2, font: Optional[int] = 2, text_color: Optional[Tuple[int, int, int]] = (255, 255, 255), text_color_bg: Optional[Tuple[int, int, int]] = (0, 0, 0), text_bg_alpha: float = 0.8) → ndarray

Draws text on an image with a background color and transparency.

This method overlays text on an image at the specified position, with options for adjusting font size, thickness, background color, and background transparency. The text is drawn with an optional background rectangle that can have a specified transparency level to ensure readability over various image backgrounds.

Parameters

• img – The image on which the text is to be drawn. This is a NumPy array representing the image data.

• text – The text string to be drawn on the image.

• pos – The position (x, y) where the text will be placed on the image. The coordinates correspond to the bottom-left corner of the text.

• font_size – The size of the font. It determines the scale factor that is multiplied by the font-specific base size.

• font_thickness – The thickness of the text strokes. It is an integer specifying the number of pixels for the thickness.

• font – The font type used to render the text. It corresponds to one of the predefined OpenCV font types.

• text_color – The color of the text in RGB format. By default, the text color is white.

• text_color_bg – The background color for the text in RGB format. By default, the background color is black.

• text_bg_alpha – The transparency level of the background rectangle. A value between 0 and 1, where 0 is fully transparent and 1 is fully opaque.

Returns

The image with the overlaid text and background rectangle.

remove_a_folder(folder_dir: str) → None

Helper to remove a directory, use for cleaning up smaller multiprocessed videos following concat

resize_gantt(gantt_img: array, img_height: int) → ndarray

Helper to resize image while retaining aspect ratio.

static rotate_img(img: ndarray, right: bool) → ndarray

Flip a color image 90 degrees to the left or right

Parameters

• img (np.ndarray) – Input image as numpy array in uint8 format.

• right (bool) – If True, flips to the right. If False, flips to the left.

Returns

The rotated image as a numpy array of uint8 format.

Example

>>> img = cv2.imread('/Users/simon/Desktop/test.png')
>>> rotated_img = PlottingMixin.rotate_img(img=img, right=False)

split_and_group_df(df: ~pandas.core.frame.DataFrame, splits: int, include_row_index: bool = False, include_split_order: bool = True) -> (typing.List[pandas.core.frame.DataFrame], <class 'int'>)

Helper to split a dataframe for multiprocessing. If include_split_order, then include the group number in split data as a column. If include_row_index, includes a column representing the row index in the array, which can be helpful for knowing the frame indexes while multiprocessing videos. Returns split data and approximations of number of observations per split.

Light-/Dark-box plotting

Generate annotated videos visualizing behavior episodes in a light/dark box setup.

See also

For light/dark box data analysis, see simba.data_processors.light_dark_box_analyzer.LightDarkBoxAnalyzer().

param (str or os.PathLike) data_dir

Directory containing pose estimation CSV files.

param (str or os.PathLike) video_dir

Directory containing video files corresponding with the names of the CSVs in data_dir.

param (str or os.PathLike) save_dir

Output directory to save the resulting annotated videos.

param (str) body_part

The name of the body part used to determine position and behavior.

:param (int or float) fps : Frames per second of the videos (used for timing episodes). :param (float) threshold: Threshold value for light/dark classification (between 0.0 and 1.0). :param (float) minimum_episode_duration : Minimum duration (in seconds) for an episode to be considered valid. :param (int) core_cnt: Number of CPU cores to use for parallel processing. If -1, uses all available cores.

references

1

For discussion about the development, see - GitHub issue 446.