SimBA bounding-box tools (animal-anchoired ROIs)

Methods for analyzing animal interactions through overlapping bounding boxes.

Aggregate Statistics

class simba.bounding_box_tools.agg_boundary_stats.AggBoundaryStatisticsCalculator(config_path: Union[str, PathLike], measures: List[typing_extensions.Literal['INTERACTION TIME (s)', 'INTERACTION BOUT COUNT', 'INTERACTION BOUT MEAN (s)', 'INTERACTION BOUT MEDIAN (s)']], shortest_allowed_interaction: int)[source]

Bases: ConfigReader

Compute aggregate boundary statistics

Parameters

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

  • measures (List[str]) – Aggregate statistics measurements. OPTIONS: ‘DETAILED INTERACTIONS TABLE’, ‘INTERACTION TIME (s)’, ‘INTERACTION BOUT COUNT’, ‘INTERACTION BOUT MEAN (s)’, ‘INTERACTION BOUT MEDIAN (s)’

  • shortest_allowed_interaction (int) – The shortest allowed animal-anchored ROI intersection in millisecond.

Notes

Tutorial.

Examples

>>> boundary_stats_calculator = AggBoundaryStatisticsCalculator('MyProjectConfig', measures=['INTERACTION TIME (s)'], shortest_allowed_interaction=200)
>>> boundary_stats_calculator.run()
>>> boundary_stats_calculator.save()

GUI Tool

class simba.bounding_box_tools.boundary_menus.BoundaryMenus(config_path: Union[str, PathLike])[source]

Bases: ConfigReader, PopUpMixin

Launch GUI interface for extrapolating bounding boxes from pose-estimation data, and calculating statstics on bounding boxes and pose-estimated key-point intersections.

Parameters

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

Notes

Tutorial.

Examples

>>> _ = BoundaryMenus(config_path='/Users/simon/Desktop/troubleshooting/train_model_project/project_folder/project_config.ini')

Statistics

class simba.bounding_box_tools.boundary_statistics.BoundaryStatisticsCalculator(config_path: str, roi_intersections: bool, roi_keypoint_intersections: bool, save_format: str)[source]

Bases: ConfigReader

Compute boundary intersection statistics.

Parameters

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

  • roi_intersections (bool) – If True, calculates intersection of animal-anchored ROIs

  • roi_keypoint_intersections (bool) – If True, calculates intersection of animal-anchored ROIs and pose-estimated animal key-points.

  • save_format (str) – Output data format. OPTIONS: CSV, PARQUET, PICKLE.

Notes

Bounding boxes tutorial.

Examples

>>> boundary_stats_calculator = BoundaryStatisticsCalculator(config_path='MyConfigFile',roi_intersections=True, roi_keypoint_intersections=True, save_format='CSV')
>>> boundary_stats_calculator.save_results()

Find Boundaries

class simba.bounding_box_tools.find_boundaries.AnimalBoundaryFinder(config_path: str, roi_type: str, force_rectangle: bool, body_parts: Optional[dict] = None, parallel_offset: Optional[int] = None)[source]

Bases: ConfigReader, FeatureExtractionMixin

Compute boundaries (animal-anchored) ROIs for animals in each frame. Result is saved as a pickle in the project_folder/logs directory of the SimBA project.

Parameters

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

  • roi_type (str) –

    shape type of ROI. OPTIONS: “ENTIRE ANIMAL”, “SINGLE BODY-PART SQUARE”, “SINGLE BODY-PART CIRCLE”. For more information/examples, see Tutorial.

  • force_rectangle (bool) – If True, forces roi shape into minimum bounding rectangle. If False, then polygon.

  • body_parts (Optional[dict] or None) – If roi_type is ‘SINGLE BODY-PART CIRCLE’ or ‘SINGLE BODY-PART SQUARE’, then body-parts to anchor the ROI to with keys as animal names and values as body-parts. E.g., body_parts={‘Animal_1’: ‘Head_1’, ‘Animal_2’: ‘Head_2’}.

  • parallel_offset (Optional[int]) – Offset of ROI from the animal outer bounds in millimeter. If None, then no offset.

Examples

>>> animal_boundary_finder = AnimalBoundaryFinder(config_path='project_folder/project_config.ini', roi_type='SINGLE BODY-PART CIRCLE',body_parts={'Animal_1': 'Head_1', 'Animal_2': 'Head_2'}, force_rectangle=False, parallel_offset=15)
>>> animal_boundary_finder.run()

Visualize

class simba.bounding_box_tools.visualize_boundaries.BoundaryVisualizer(config_path: Union[str, PathLike], video_name: str, include_key_points: bool, greyscale: bool, show_intersections: bool, roi_attributes: dict)[source]

Bases: ConfigReader, PlottingMixin

Visualisation of user-specified animal-anchored ROI boundaries. Results are stored in the project_folder/frames/output/anchored_rois directory of the SimBA project

Parameters

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

  • video_name (str) – Name of the video in the SimBA project to create bounding box video for

  • include_key_points (bool) – If True, includes pose-estimated body-parts in the video.

  • greyscale (bool) – If True, converts the video (but not the shapes/keypoints) to greyscale.

  • show_intersections (bool) – If True, then produce highlight boundaries/keypoints to signify present intersections. See this example for highlighted intersections

Note

Bounding boxes tutorial.

Examples

>>> boundary_visualizer = BoundaryVisualizer(config_path='MySimBAConfig', video_name='MyVideoName', include_key_points=True, greyscale=True)
>>> boundary_visualizer.run()