Region-of-interest tools

ROI analyzer

class simba.roi_tools.ROI_analyzer.ROIAnalyzer(config_path: Union[str, PathLike], data_path: Optional[Union[str, PathLike, List[str]]] = None, detailed_bout_data: Optional[bool] = False, calculate_distances: Optional[bool] = False, threshold: Optional[float] = 0.0, body_parts: Optional[List[str]] = None)[source]

Bases: ConfigReader, FeatureExtractionMixin

Analyze movements, entries, exits, and time-spent-in user-defined ROIs. Results are stored in the ‘project_folder/logs’ directory of the SimBA project.

Parameters

config_path (str) – Path to SimBA project config file in Configparser format.
data_path (Optional[str]) – Path to folder or file holding the data used to calculate ROI aggregate statistics. If None, then defaults to the project_folder/csv/outlier_corrected_movement_location directory of the SimBA project. Default: None.
calculate_distances (Optional[bool]) – If True, then calculate movements aggregate statistics (distances and velocities) inside ROIs. Results are saved in project_folder/logs/ directory. Default: False.
detailed_bout_data (Optional[bool]) – If True, saves a file with a row for every entry into each ROI for each animal in each video. Results are saved in project_folder/logs/ directory. Default: False.
threshold (Optional[float]) – Float between 0 and 1. Body-part locations detected below this confidence threshold are filtered. Default: 0.0.
threshold – List of body-parts to perform ROI analysis on.

Note

ROI tutorials.

Example

>>> test = ROIAnalyzer(config_path = r"/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini", calculate_distances=True, detailed_bout_data=True, body_parts=['Nose_1', 'Nose_2'], threshold=0.0)
>>> test.run()
>>> test.save()

ROI classification calculator

class simba.roi_tools.ROI_clf_calculator.ROIClfCalculator(config_ini: str)[source]

Bases: ConfigReader

Compute aggregate statistics of classification results within user-defined ROIs. Results are stored in project_folder/logs directory of the SimBA project.

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

Examples

>>> clf_ROI_analyzer = ROIClfCalculator(config_ini="MyConfigPath")
>>> clf_ROI_analyzer.run(behavior_list=['Attack', 'Sniffing'], ROI_dict_lists={'Rectangle': ['rec'], 'Circle': ['Stimulus 1', 'Stimulus 2', 'Stimulus 3']}, body_part_list=['Nose_1'], measurements=['Total time by ROI (s)', 'Started bouts by ROI (count)', 'Ended bouts by ROI (count)'])

run(ROI_dict_lists: dict, measurements: list, behavior_list: list, body_part_list: list)[source]

Parameters

ROI_dict_lists (dict) – A dictionary with the shape type as keys (i.e., Rectangle, Circle, Polygon) and lists of shape names as values.
measurements (list) – Measurements to calculate aggregate statistics for. E.g., [‘Total time by ROI (s)’, ‘Started bouts’, ‘Ended bouts’]
behavior_list (list) – Classifier names to calculate ROI statistics. E.g., [‘Attack’, ‘Sniffing’]
body_part_list (list) – Body-part names to use to infer animal location. Eg., [‘Nose_1’].

ROI GUI

class simba.roi_tools.ROI_define.ROI_definitions(config_path: str, video_path: str)[source]

Bases: ConfigReader, PopUpMixin

Launch ROI user-interface for drawing user-defined shapes in a video.

Parameters

config_path (str) – path to SimBA project config file in Configparser format
video_path (str) – path to video file for which ROIs should be defined.

Notes

ROI tutorials.

Examples

>>> _ = ROI_definitions(config_path='MyProjectConfig', video_path='MyVideoPath')

ROI directing analyzer

class simba.roi_tools.ROI_directing_analyzer.DirectingROIAnalyzer(config_path: Union[str, PathLike], data_path: Optional[Union[str, PathLike]] = None)[source]

Bases: ConfigReader, FeatureExtractionMixin

Compute aggregate statistics for animals directing towards ROIs.

Parameters

config_path (str) – Path to SimBA project config file in Configparser format
data_path (Optional[Union[str, os.PathLike]]) – Path to folder or file holding the data used to calculate ROI aggregate statistics. If None, then defaults to the project_folder/csv/outlier_corrected_movement_location directory of the SimBA project. Default: None.

Note

ROI tutorials.

Example expected output file.

Example

>>> test = DirectingROIAnalyzer(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini')
>>> test.run()
>>> test.save()

ROI feature analyzer

class simba.roi_tools.ROI_feature_analyzer.ROIFeatureCreator(config_path: Union[str, PathLike], body_parts: List[str], data_path: Optional[Union[str, PathLike]] = None, append_data: Optional[bool] = False)[source]

Bases: ConfigReader, FeatureExtractionMixin

Compute features based on the relationships between the location of the animals and the location of user-defined ROIs. This includes the distance to the ROIs, if the animals are inside the ROIs, and if the animals are directing towards the ROIs (if viable)

Note

ROI tutorials.

Parameters

config_path (Union[str, os.PathLike]) – Path to SimBA project config file in Configparser format.
body_parts (List[str]) – List of the body-parts to use as proxy for animal location(s).
data_path (Optional[Union[str, os.PathLike]]) – Path to folder or file holding the data used to calculate ROI aggregate statistics. If None, then defaults to the project_folder/csv/outlier_corrected_movement_location directory of the SimBA project. Default: None.
append_data (Optional[bool]) – If True, adds the features to the data in the project_folder/csv/features_extracted directory. Else, held in memory.

Example

>>> roi_featurizer = ROIFeatureCreator(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini',
>>>                                    body_parts=['Nose_1', 'Nose_2'])
>>> roi_featurizer.run()
>>> roi_featurizer.save()

ROI GUI - IMAGE

ROI GUI

simba.roi_tools.ROI_menus.hxtScrollbar(master)[source]: Create canvas. Create a frame and put it in the canvas. Create two scrollbar and insert command of canvas x and y view Use canvas to create a window, where window = frame Bind the frame to the canvas

simba.roi_tools.ROI_menus.onFrameConfigure(canvas)[source]: Reset the scroll region to encompass the inner frame

class simba.roi_tools.ROI_menus.roitableRow(parent=None, dirname='', filename='', widths='', indexs='', projectini='')[source]: Bases: Frame

Moving roi shapes

ROI Movement analyzer

Multiply ROIs

ROI resetter

ROI size calculators

simba.roi_tools.ROI_size_calculations.circle_size_calc(circle_dict, px_mm) → dict[source]

Compute metric radius and area of circle.

Parameters

circle_dict (dict) – The circle radius in pixels
px_mm (float) – Pixels per millimeter in the video.

Example

>>> circle_size_calc(circle_dict={'radius': 100}, px_mm=5)
>>> {'radius': 100, 'radius_cm': 2.0, 'area_cm': 12.57}

simba.roi_tools.ROI_size_calculations.polygon_size_calc(polygon_dict, px_mm) → dict[source]

Compute metric area of polygon.

Parameters

polygon_dict (dict) – The polygon vertices as np.ndarray
px_mm (float) – Pixels per millimeter in the video.

Example

>>> polygon_size_calc(polygon_dict={'vertices': np.array([[0, 2], [200, 98], [100, 876], [10, 702]])}, px_mm=5)
>>> {'vertices': [[  0,   2], [200,  98], [100, 876], [ 10, 702]], 'area_cm': 45.29}

simba.roi_tools.ROI_size_calculations.rectangle_size_calc(rectangle_dict: dict, px_mm: float) → dict[source]

Compute metric height, width and area of rectangle.

Parameters

rectangle_dict (dict) – The rectangle width and height in pixels.
px_mm (float) – Pixels per millimeter in the video.

Example

>>> rectangle_size_calc(rectangle_dict={'height': 500, 'width': 500}, px_mm=10)
>>> {'height': 500, 'width': 500, 'height_cm': 5.0, 'width_cm': 5.0, 'area_cm': 25.0}

ROI size standardizer through pixels by millimeter

class simba.roi_tools.ROI_size_standardizer.ROISizeStandardizer(config_path: str, reference_video: str)[source]

Bases: ConfigReader, FeatureExtractionMixin

Standardize ROI sizes according to a reference video.

Note

Example: You select a “baseline” video, say that this baseline video has a pixel per millimeter of 10. Say there are a further two videos in the project with ROIs, and these videos has pixels per millimeter of 9 and 11. At runtime, the area of the rectangles, circles and polygons in the two additional videos get their ROI areas increased/decreased with 10% while the baseline video ROIs are unchanged.

Parameters: config_path (str) – path to SimBA project config file in Configparser format.
Parameter: str join_bouts_within_delta: Name of baseline video without extension, e.g., Video_1.
Example

>>> test = ROISizeStandardizer(config_path='/Users/simon/Desktop/envs/troubleshooting/DLC_2_Black_animals/project_folder/project_config.ini', reference_video='Together_1')
>>> test.run()
>>> test.save()

ROI time-bin calculator

class simba.roi_tools.ROI_time_bin_calculator.ROITimebinCalculator(config_path: Union[str, PathLike], bin_length: float, body_parts: List[str], data_path: Optional[Union[str, PathLike, List[str]]] = None, threshold: Optional[float] = 0.0, movement: Optional[bool] = False)[source]

Bases: ConfigReader

Compute how much time and how many entries animals are making into user-defined ROIs within user-defined time bins. Also compute the average velocity and distance moved within user-defined ROIs split by time-bins.

Results are stored in the project_folder/logs directory of the SimBA project.

Parameters

config_path (Union[str, os.PathLike]) – path to SimBA project config file in Configparser format
bin_length (float) – length of time bins in seconds.
body_parts (List[str]) – List of body-parts to use as proxy of animal locations.
threshold (float) – Filter pose-estimation data detected below defined threshold.
movement (Optional[bool]) – If True, compute the distances and velocities within time-bins. Default False.

Note

Example anticipated ROI time-bins entry results. Example anticipated ROI time-bins latency results. Example anticipated movement results.

Example

>>> calculator = ROITimebinCalculator(config_path=r"/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini", bin_length=1.0, body_parts=['Nose_1'], threshold=0.00, movement=True)
>>> calculator.run()
>>> calculator.save()

ROI zoom methods

: