Feature extraction wrappers

Default feature extractor for 2 animals and 14 body-parts

class simba.feature_extractors.feature_extractor_14bp.ExtractFeaturesFrom14bps(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Extracts hard-coded set of features from pose-estimation data from two animals with 7 tracked body-parts each. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Note

• Feature extraction tutorial.

• Expected pose configuration

Parameters

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

Example

>>> feature_extractor = ExtractFeaturesFrom14bps(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Method to compute and save features to disk. Results are saved in the project_folder/csv/features_extracted directory of the SimBA project.

Return type

None

Default feature extractor for 1 animals and 16 body-parts

class simba.feature_extractors.feature_extractor_16bp.ExtractFeaturesFrom16bps(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Extracts hard-coded set of features from pose-estimation data from two animals with 8 tracked body-parts each. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Parameters

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

Note

Feature extraction tutorial. Expected pose configuration

Example

>>> feature_extractor = ExtractFeaturesFrom16bps(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Method to compute and save feature battery to disk. Results are saved in the project_folder/csv/features_extracted directory of the SimBA project.

Return type

None

Default feature extractor for 1 animals and 4 body-parts

class simba.feature_extractors.feature_extractor_4bp.ExtractFeaturesFrom4bps(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Extracts hard-coded set of features from pose-estimation data with one animal and 4 tracked body-parts. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Note

• Feature extraction tutorial.

• Expected pose configuration

Parameters

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

Example

>>> feature_extractor = ExtractFeaturesFrom4bps(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Method to compute and save features to disk. Results are saved in the project_folder/csv/features_extracted directory of the SimBA project.

Return type

None

Default feature extractor for 1 animals and 7 body-parts

class simba.feature_extractors.feature_extractor_7bp.ExtractFeaturesFrom7bps(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Extracts hard-coded set of features from pose-estimation data from single animals with 7 tracked body-parts. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Note

• Feature extraction tutorial.

• Expected pose configuration

Parameters

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

Example

>>> feature_extractor = ExtractFeaturesFrom7bps(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Method to compute and save features to disk. Results are saved in the project_folder/csv/features_extracted directory of the SimBA project.

Return type

None

Default feature extractor for 1 animals and 8 body-parts

class simba.feature_extractors.feature_extractor_8bp.ExtractFeaturesFrom8bps(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Extracts hard-coded set of features from pose-estimation data from single animals with 8 tracked body-parts. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Note

• Feature extraction tutorial.

• Expected pose configuration

Parameters

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

Example

>>> feature_extractor = ExtractFeaturesFrom8bps(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Method to compute and save features to disk. Results are saved in the project_folder/csv/features_extracted directory of the SimBA project.

Return type

None

Default feature extractor for 2 animals and 16 body-parts

class simba.feature_extractors.feature_extractor_8bps_2_animals.ExtractFeaturesFrom8bps2Animals(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Extracts hard-coded set of features from pose-estimation data from two animals with 4 tracked body-parts each. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Note

• Feature extraction tutorial.

• Expected pose configuration

Parameters

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

Example

>>> feature_extractor = ExtractFeaturesFrom8bps2Animals(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Method to compute and save feature battery to disk. Results are saved in the project_folder/csv/features_extracted directory of the SimBA project.

Return type

None

Default feature extractor for 1 animals and 9 body-parts

class simba.feature_extractors.feature_extractor_9bp.ExtractFeaturesFrom9bps(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Extracts hard-coded set of features from pose-estimation data from single animals with 9 tracked body-parts. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Note

• Feature extraction tutorial.

• Expected pose configuration

Parameters

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

Example

>>> feature_extractor = ExtractFeaturesFrom9bps(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Default feature extractor for user-defined body-parts

class simba.feature_extractors.feature_extractor_user_defined.UserDefinedFeatureExtractor(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Generic featurizer of data within SimBA project using user-defined body-parts in the pose-estimation data. Results are stored in the project_folder/csv/features_extracted directory of the SimBA project.

Note

Feature extraction tutorial.

Parameters

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

Example

>>> feature_extractor = UserDefinedFeatureExtractor(config_path='MyProjectConfig')
>>> feature_extractor.run()

run()

Feature extractor for feature subset family

class simba.feature_extractors.feature_subsets.FeatureSubsetsCalculator(config_path, feature_families, file_checks=False, save_dir=None, data_dir=None, append_to_features_extracted=False, append_to_targets_inserted=False)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.train_model_mixin.TrainModelMixin

Computes a subset of features from pose for non-ML downstream purposes. E.g., returns the size of animal convex hull in each frame.

Parameters

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

• save_dir (Optional[Union[str, os.PathLike]]) – directory where to store results.

• feature_family (List[str]) – List of feature subtype to calculate. E.g., [‘TWO-POINT BODY-PART DISTANCES (MM)”].

• file_checks (bool) – If true, checks that the files which the data is appended too contains the anticipated number of rows and no duplicate columns after appending. Default False.

• save_dir – Directory where to save the data. If None, then the data is only appended.

• data_dir (Optional[Union[str, os.PathLike]]) – Directory of pose-estimation data to compute feature subsets for. If None, then the /project_folder/csv/outlier_corrected_movement_locations directory.

• append_to_features_extracted (bool) – If True, appends the data to the file sin the features_extracted directory. Default: False.

• append_to_targets_inserted (bool) – If True, appends the data to the file sin the targets_inserted directory. Default: False.

Note

Tutorial <https://github.com/sgoldenlab/simba/blob/master/docs/feature_subsets.md>_

Example

>>> test = FeatureSubsetsCalculator(config_path=r"C:/troubleshooting/mitra/project_folder/project_config.ini",
>>>                               feature_families=[FRAME_BP_MOVEMENT, WITHIN_ANIMAL_THREE_POINT_ANGLES],
>>>                               append_to_features_extracted=False,
>>>                               file_checks=False,
>>>                               append_to_targets_inserted=False,
>>>                               save_dir=r"C:/troubleshooting/mitra/project_folder/csv/new_features")
>>> test.run()

run()

Jitted methods for convex-hull related calculations

simba.feature_extractors.perimeter_jit.get_hull_sizes(points, target='perimeter', pixels_per_mm=None)

Convex hull perimeter or area per frame, with validation and optional conversion to mm.

Calls jitted_hull() after checking array shape/dtype; if pixels_per_mm is given, divides result to get mm.

Parameters

• points – (n_frames, n_body_parts, 2) non-negative numeric [x, y] in pixels.

• target – 'perimeter' or 'area'.

• pixels_per_mm – If set, result is divided by this (output in mm).

Returns

(n_frames,) float32; hull size per frame (pixels or mm); NaN where hull fails.

Example

>>> points = np.random.randint(0, 500, size=(100, 7, 2)).astype(np.float32)
>>> get_hull_sizes(points, target='perimeter')
>>> get_hull_sizes(points, target='area', pixels_per_mm=2.5)

simba.feature_extractors.perimeter_jit.jitted_centroid(points)

Centroid of the convex hull per frame (mean of hull vertex coordinates).

For each frame: quickhull → hull vertex indices → centroid = (mean(x), mean(y)) of those vertices.

Parameters

points – (n_frames, n_body_parts, 2) [x, y] coordinates.

Returns

(n_frames, 2) int32; centroid (x, y) per frame; NaN where hull fails.

Example

>>> points = np.random.randint(1, 50, size=(50, 5, 2)).astype(np.float32)
>>> centroids = jitted_centroid(points)

simba.feature_extractors.perimeter_jit.jitted_hull(points, target='perimeter')

Convex hull perimeter or area per frame from body-part (x,y) coordinates.

For each frame, builds the 2D convex hull (quickhull), then: - perimeter: sum of edge lengths |v_{i+1} - v_i| (with wrap). - area: shoelace formula, 0.5 * |Σ(x_i y_{i+1} - y_i x_{i+1})|.

Parameters

• points – (n_frames, n_body_parts, 2) float32, [x, y] per point.

• target – 'perimeter' or 'area'.

Returns

(n_frames,) float64; NaN where hull fails.

See also

simba.feature_extractors.perimeter_jit.get_hull_sizes() (wrapper with validation).

simba.feature_extractors.perimeter_jit.process(S, P, a, b)

One step of the quickhull algorithm: partition points by signed distance to line (a,b), recurse on the subset above the line. Uses 2D cross product for signed distance; farthest point becomes new hull vertex. Returns hull vertex indices from a to b (excluding b).

Rearing and grooming feature extraction wrapper

class simba.feature_extractors.mitra_feature_extractor.MitraFeatureExtractor(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.abstract_classes.AbstractFeatureExtraction

Feature extractor used for grooming and rearing classifications. A subset is of created features are further used for straub-tail classifications.

Parameters

config_path (Union[str, os.PathLike]) – Path to SimBA project_config.ini.

Returns

None. Featurized pose-estimation data is saved in the simba project project_folder/csv/features_extracted directory.

Example

>>> feature_extractor = MitraFeatureExtractor(config_path=r"D:      roubleshooting\mitra\project_folder\project_config.ini")
>>> feature_extractor.run()

References

1

Lazaro et al., Brainwide Genetic Capture for Conscious State Transitions, biorxiv, doi: https://doi.org/10.1101/2025.03.28.646066

run()

save(df, save_path)

Straub tail feature extraction wrapper

class simba.feature_extractors.straub_tail_analyzer.StraubTailAnalyzer(config_path, anchor_points, body_parts, save_dir, data_dir=None, video_dir=None)

Bases: simba.mixins.config_reader.ConfigReader

Class using background removed - egocentrically rotated - videos, to featurize tail behavior for downstream straub tail classification.

Parameters

• config_path (Union[str, os.PathLike]) – Path to SimBA project_config.ini.

• data_dir (Optional[Union[str, os.PathLike]]) – Path to directory holding pose-estimation data. If None, the uses project_folder/csv/outlier_corrected_movement_location directory in SimBA project.

• video_dir (Union[str, os.PathLike]) – Path to directory holding videos. If None, the uses project_folder/videos directory in SimBA project.

• save_dir (Union[str, os.PathLike]) – Path to directory where to saved featurized pose-estimation data.

• anchor_points (Iterable[str]) – Iterable holding the names od the pose-estimated body-parts belonging to the tail.

• body_parts (Iterable[str]) – Iterable holding the names od the pose-estimated body-parts belonging to the animal hull.

References

1

Lazaro et al., Brainwide Genetic Capture for Conscious State Transitions, biorxiv, doi: https://doi.org/10.1101/2025.03.28.646066

Example

>>> runner = StraubTailAnalyzer(config_path=r"C:/troubleshooting/mitra/project_folder/project_config.ini",
>>>                            data_dir=r'C:/troubleshooting/mitra/project_folder/videos/additional/bg_removed/rotated',
>>>                            video_dir=r'C:/troubleshooting/mitra/project_folder/videos/additional/bg_removed/rotated',
>>>                            save_dir=r'C:/troubleshooting/mitra/project_folder/videos/additional/bg_removed/rotated/tail_features_additional',
>>>                            anchor_points=('tail_base', 'tail_center', 'tail_tip'),
>>>                            body_parts=('nose', 'left_ear', 'right_ear', 'right_side', 'left_side', 'tail_base'))
>>> runner.run()

run()

Mexican cave fish feature extraction wrapper

class simba.feature_extractors.cave_fish_featurizer.CaveFishFeaturizer(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Feature extractor used to score anxiety behaviors in Mexican cave fish species.

Note

This class has previously been named as fish_feature_extractor_2023_version_5.FishFeatureExtractor

Parameters

config_path (Union[str, os.PathLike]) – Path to SimBA project_config.ini.

Returns

None. Featurized pose-estimation data is saved in the simba project project_folder/csv/features_extracted directory.

Example

>>> _ = CaveFishFeaturizer(config_path='/Users/simon/Desktop/envs/troubleshooting/naresh/project_folder/project_config.ini')

References

1

Padmanaban, Naresh, Rianna Ambosie, Stefan Choy, Shoshanah Marcus, Simon R.O. Nilsson, Alex C. Keene, Johanna E. Kowalko, and Erik R. Duboué. “Automated Behavioral Profiling Using Neural Networks Reveals Differences in Stress-like Behavior between Cave and Surface-Dwelling Astyanax Mexicanus.” Evolutionary Biology, February 5, 2025. https://doi.org/10.1101/2025.01.30.635725.

angle2pt_cos(angle_radians)

angle2pt_degrees(ax, ay, bx, by)

angle2pt_radians(degrees)

angle2pt_sin(angle_radians)

static angular_dispersion(cumsum_cos_np, cumsum_sin_np)

bouts_in_same_direction()

calc_45_degree_direction_switches()

calc_N_degree_direction_switches()

calc_X_relative_to_Y_movement()

calc_X_relative_to_Y_movement_rolling_windows()

calc_acceleration()

calc_angular_dispersion()

calc_border_distances()

calc_convex_hulls()

calc_directional_switches_in_rolling_windows()

calc_distances_between_body_part()

calc_movement()

calc_rotation()

calc_switch_direction(compass_digit_shifted, compass_digit)

calc_velocity()

static consecutive_frames_in_same_compass_direction(direction)

static convex_hull_calculator_mp(arr, px_per_mm)

Calculate single frame convex hull perimeter length in millimeters.

Note

For acceptable run-time, call using parallel processing.

See also

For numba CPU based acceleration, use simba.feature_extractors.perimeter_jit.jitted_hull(). For multicore based acceleration, use simba.mixins.geometry_mixin.GeometryMixin.bodyparts_to_polygon(). For numba CUDA based acceleration, use simba.data_processors.cuda.geometry.get_convex_hull(),

Parameters

• arr (np.ndarray) – 2D array of size len(body-parts) x 2.

• px_per_mm (float) – Video pixels per millimeter.

Returns

The length of the animal perimeter in millimeters.

Return type

float

Example

>>> coordinates = np.random.randint(1, 200, size=(6, 2)).astype(np.float32)
>>> FeatureExtractionMixin.convex_hull_calculator_mp(arr=coordinates, px_per_mm=4.56)
>>> 98.6676814218373

static count_values_in_range(data, ranges)

Jitted helper finding count of values that falls within ranges. E.g., count number of pose-estimated body-parts that fall within defined bracket of probabilities per frame.

See also

For GPU acceleration, use simba.data_processors.cuda.statistics.count_values_in_ranges()

Parameters

• data (np.ndarray) – 2D numpy array with frames on X.

• ranges (np.ndarray) – 2D numpy array representing the brackets. E.g., [[0, 0.1], [0.1, 0.5]]

Returns

2D numpy array of size data.shape[0], ranges.shape[1]

Return type

np.ndarray

Example

>>> FeatureExtractionMixin.count_values_in_range(data=np.random.random((3,10)), ranges=np.array([[0.0, 0.25], [0.25, 0.5]]))
>>> [[6, 1], [3, 2],[2, 1]]

distribution_tests()

static euclidian_distance_calc(bp1xVals, bp1yVals, bp2xVals, bp2yVals)

static framewise_degree_shift(clockwise_angle)

hot_end_encode_compass()

pose_confidence_probabilities()

save_file()

windowed_frequentist_distribution_tests(data, feature_name, fps)

Helper to compare feature value distributions in 1s sequential time-bins: Kolmogorov-Smirnov and T-tests Compares the feature values against a normal distribution: Lillefors, Shapiro. Find the number of peaks in rolling 1s long feature window.

Rat social behavior feature extraction wrapper

class simba.feature_extractors.rat_social_featurizer.RatSocialFeaturizer(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin, simba.mixins.geometry_mixin.GeometryMixin, simba.mixins.abstract_classes.AbstractFeatureExtraction

Featurization class for analyzing rat social behaviors.

Example

>>> extractor = RatSocialFeaturizer(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/piotr/project_folder/project_config.ini')
>>> extractor.run()

References

1

Popik, Piotr, Ewelina Cyrano, Joanna Golebiowska, Natalia Malikowska-Racia, Agnieszka Potasiewicz, and Agnieszka Nikiforuk. “Deep Learning Algorithms Reveal Increased Social Activity in Rats at the Onset of the Dark Phase of the Light/Dark Cycle.” Edited by Dragan Hrncic. PLOS ONE 19, no. 11 (November 8, 2024): e0307794. https://doi.org/10.1371/journal.pone.0307794.

2

Popik, Piotr, Ewelina Cyrano, Diana Piotrowska, Malgorzata Holuj, Joanna Golebiowska, Natalia Malikowska-Racia, Agnieszka Potasiewicz, and Agnieszka Nikiforuk. “Effects of Ketamine on Rat Social Behavior as Analyzed by DeepLabCut and SimBA Deep Learning Algorithms.” Frontiers in Pharmacology 14 (January 10, 2024): 1329424. https://doi.org/10.3389/fphar.2023.1329424.

run()

save(data, save_path)

Gerbil single body-part feature extraction wrapper

class simba.feature_extractors.gerbil_featurizer.GerbilFeaturizer(in_path, out_path)

Bases: object

Compute features from SLEAP pose-estimation data in NPY format with two animals and a single body-part tracked per animal.

Parameters

• folder_path (str) – folder path containing SLP tracking data in .npy format.

• out_path (str) – folder path storing featurized data in multiple .parquet files.

Example

>>> gerbil_featurizer = GerbilFeaturizer(in_path='_gerbil_data/pose_estimation_data', out_path='gerbil_data/featurized_data')
>>> gerbil_featurizer.extract_features()
>>> gerbil_featurizer.save()

References

1

Mitelut, C, M Diez Castro, Re Peterson, M Gonçalves, J Li, Mm Gamer, Sro Nilsson, Td Pereira, and Dh Sanes. “A Behavioral Roadmap for the Development of Agency in the Rodent.” Animal Behavior and Cognition, November 13, 2023. https://doi.org/10.1101/2023.11.10.566632.

2

Mitelut, Catalin, Marielisa Diez Castro, Ralph E. Peterson, et al. “Continuous Monitoring and Machine Vision Reveals That Developing Gerbils Exhibit Structured Social Behaviors Prior to the Emergence of Autonomy.” PLOS Biology 23, no. 9 (2025): e3003348. https://doi.org/10.1371/journal.pbio.3003348.

static calc_animal_distances_in_time_windows(input_array=<class 'numpy.ndarray'>, frm_windows=typing.List[int])

Jitted compute of individual frame-by-frame pixel distances and aggregate distance statistics (mean, sum) in rolling time-windows between the two animals.

Parameters

• input_array (np.ndarray) – array of size len(frames) x 4 representing body-part coordinates of two animals [x1, y1, x2, y2].

• frm_windows (List[int]) – list of ints representing frame window sizes to calculate aggregate statistics within.

Returns

np.ndarray single_frm_move: array of size len(frames) x 1 representing frame-by-frame body-part distances in pixels

Returns

np.ndarray agg_frm_move_mean: array of size len(frames) x len(frm_windows) representing mean frame-by-frame body-part distances in rolling time-windows

Returns

np.nparray agg_frm_move_sum: array of size len(frames) x len(frm_windows) representing summed frame-by-frame body-part distances in rolling time-windows

static calc_individual_animal_movements_in_time_windows(input_array=<class 'numpy.ndarray'>, frm_windows=typing.List[int])

Jitted compute of individual frame-by-frame pixel movement and aggregate movement statistics (mean, sum) in rolling time-windows for each animal.

Parameters

• input_array (np.ndarray) – array of size len(frames) x 2 representing body-part coordinates

• frm_windows – list of ints representing frame window sizes to calculate aggregate statistics within

Returns

np.ndarray single_frm_move: array of size len(frames) x 1 representing frame-by-frame body-part movements in pixels

Returns

np.ndarray agg_frm_move_mean: array of size len(frames) x len(frm_windows) representing mean frame-by-frame body-part movements in rolling time-windows

Returns

np.ndarray agg_frm_move_sum: array of size len(frames) x len(frm_windows) representing summed frame-by-frame body-part movements in rolling time-windows

static calc_relative_data_in_time_windows(input_array=<class 'numpy.ndarray'>, frm_windows=typing.List[int])

Jitted compute of individual frame-by-frame pixel distances and aggregate distance statistics (mean, sum) in rolling time-windows between the two animals. E.g., returns the relative distance between the two animals in the current frame vs 5, 10, 20, 40 frames earlier.

Parameters

• input_array (np.ndarray) – array of size len(frames) x 1 representing a distances or movements of body-parts (one value per framde)

• frm_windows (List[int]) – list of ints representing frame window sizes to calculate aggregate statistics within

Returns

np.ndarray relative_dist_results: array of size len(frames) x len(frm_windows) representing deviation between the current window value from the preceding window value.

check_file_is_readable(file_path)

extract_features()

Main entry for feature extraction

save()

Saves featurized data in parquet files (one per video) named after the video name indexed by the columns ‘FRAME’ and ‘VIDEO’

Aggression feature extractor (11/25)

class simba.feature_extractors.aggression_feature_extractor.AgressionFeatureExtractor(config_path, data_dir=None, save_dir=None)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.abstract_classes.AbstractFeatureExtraction

Extracts behavioral features from pose estimation data for aggression analysis between two animals (resident and intruder).

Note

Custom feature extraction class inhereting from AbstractFeatureExtraction which is not used by default in any of the standard SimBA entry-points.

Parameters

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

• data_dir (Union[str, os.PathLike]) – Directory containing input CSV files with pose estimation data. If None, uses the project’s outlier_corrected_dir from the config.

• save_dir (Union[str, os.PathLike]) – Directory where featurized CSV files will be saved. If None, uses the project’s features_dir from the config.

Example I

>>> extractor = AgressionFeatureExtractor(config_path='MyProjectConfig')
>>> extractor.run()

Example II

>>> f = AgressionFeatureExtractor(config_path=r"E:  roubleshooting  wo_black_animals_14bp\project_folder\project_config.ini")
>>> f.run()

run()

save(data, save_path)

AMBER pipeline feature extractor

class simba.feature_extractors.amber_feature_extractor.AmberFeatureExtractor(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin

Class for extracting features for the AMBER pipeline.

The AMBER pipeline was developed for quantifying home-cage maternal and mother-pup interactions from side-view recordings. Downstream behavior classifiers can be trained to assess maternal nest attendance, nursing, pup-directed licking and grooming, self-directed grooming, eating, and drinking.

Note

• AMBER publication.

• AMBER GitHub Repository.

• AMBER OSF Repository.

For more info, contact Hannah E. Lapp Hannah.Lapp@austin.utexas.edu.

Example

>>> AmberFeatureExtractor(config_path='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini')

References

1

Lapp, Hannah E., Melissa G. Salazar, and Frances A. Champagne. “Automated Maternal Behavior during Early Life in Rodents (AMBER) Pipeline.” Scientific Reports 13, no. 1 (October 25, 2023): 18277. https://doi.org/10.1038/s41598-023-45495-4.

run()

Boundary rearing feature extractor

class simba.feature_extractors.boundary_rearing_analyzer.BoundaryRearingFeaturizer(config_path, data_dir=None, save_dir=None)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.abstract_classes.AbstractFeatureExtraction

Example

>>> x = BoundaryRearingFeaturizer(config_path=r"C:  roubleshooting\open_field_rearing\project_folder\project_config.ini")
>>> x.run()

run()

save(data, save_path)

Riptortus pedestris feature extractor

class simba.feature_extractors.riptortus_featurizer.RiptortusFeaturizer(config_path)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.FeatureExtractionMixin, simba.mixins.abstract_classes.AbstractFeatureExtraction

Feature extractor used to score feeding behaviors in Riptortus pedestris.

Parameters

config_path (Union[str, os.PathLike]) – Path to SimBA project_config.ini.

Returns

None. Featurized pose-estimation data is saved in the simba project project_folder/csv/features_extracted directory.

Example

>>> _ = RiptortusFeaturizer(config_path='/Users/simon/Desktop/envs/troubleshooting/naresh/project_folder/project_config.ini')

angle2pt_cos(angle_radians)

angle2pt_degrees(ax, ay, bx, by)

angle2pt_radians(degrees)

angle2pt_sin(angle_radians)

static angular_dispersion(cumsum_cos_np, cumsum_sin_np)

bouts_in_same_direction()

calc_3pt_angles()

calc_45_degree_direction_switches()

calc_N_degree_direction_switches()

calc_X_relative_to_Y_movement()

calc_X_relative_to_Y_movement_rolling_windows()

calc_acceleration()

calc_angular_dispersion()

calc_directional_switches_in_rolling_windows()

calc_distances_between_body_part()

calc_movement()

calc_rotation()

calc_switch_direction(compass_digit_shifted, compass_digit)

calc_velocity()

static consecutive_frames_in_same_compass_direction(direction)

static convex_hull_calculator_mp(arr, px_per_mm)

Calculate single frame convex hull perimeter length in millimeters.

Note

For acceptable run-time, call using parallel processing.

See also

For numba CPU based acceleration, use simba.feature_extractors.perimeter_jit.jitted_hull(). For multicore based acceleration, use simba.mixins.geometry_mixin.GeometryMixin.bodyparts_to_polygon(). For numba CUDA based acceleration, use simba.data_processors.cuda.geometry.get_convex_hull(),

Parameters

• arr (np.ndarray) – 2D array of size len(body-parts) x 2.

• px_per_mm (float) – Video pixels per millimeter.

Returns

The length of the animal perimeter in millimeters.

Return type

float

Example

>>> coordinates = np.random.randint(1, 200, size=(6, 2)).astype(np.float32)
>>> FeatureExtractionMixin.convex_hull_calculator_mp(arr=coordinates, px_per_mm=4.56)
>>> 98.6676814218373

static count_values_in_range(data, ranges)

Jitted helper finding count of values that falls within ranges. E.g., count number of pose-estimated body-parts that fall within defined bracket of probabilities per frame.

See also

For GPU acceleration, use simba.data_processors.cuda.statistics.count_values_in_ranges()

Parameters

• data (np.ndarray) – 2D numpy array with frames on X.

• ranges (np.ndarray) – 2D numpy array representing the brackets. E.g., [[0, 0.1], [0.1, 0.5]]

Returns

2D numpy array of size data.shape[0], ranges.shape[1]

Return type

np.ndarray

Example

>>> FeatureExtractionMixin.count_values_in_range(data=np.random.random((3,10)), ranges=np.array([[0.0, 0.25], [0.25, 0.5]]))
>>> [[6, 1], [3, 2],[2, 1]]

distribution_tests()

static euclidian_distance_calc(bp1xVals, bp1yVals, bp2xVals, bp2yVals)

static framewise_degree_shift(clockwise_angle)

hot_end_encode_compass()

pose_confidence_probabilities()

run()

save(data, save_path)

windowed_frequentist_distribution_tests(data, feature_name, fps)

Helper to compare feature value distributions in 1s sequential time-bins: Kolmogorov-Smirnov and T-tests Compares the feature values against a normal distribution: Lillefors, Shapiro. Find the number of peaks in rolling 1s long feature window.

Custom feature extractor

class simba.utils.custom_feature_extractor.CustomFeatureExtractor(extractor_file_path, config_path)

Bases: simba.mixins.config_reader.ConfigReader

Class to execute a feature extraction process based on the user-defined Python script.

This method performs the following steps: 1. Parses the user-defined Python script. 2. Identifies class and function names in the script. 3. Checks for the presence of required imports and specific code patterns. 4. Handle cases of multiple classes and missing configuration arguments. 5. Invokes the feature extraction process if conditions are met.

Note

Tutorial.

The user defined feature extraction class needs to contain a config_path init argument

If the feature extraction class contains multiple classes, then the first class is used.

If the feature extraction class relies on argparse AND inherits simba.mixins.abstract_classes.AbstractFeatureExtraction then the feature extraction class will be executed thtough the subprocess module. This ensures that the GUI cannot interfere with the feature extraction process, and reliably execution of multicore processes, if present, in the feature-extraction class.

If the feature extraction class does not rely on argparse, then the class will be loaded and executed in python through sys. It might still be quick and reliable (it often is). However, I have noted that some function, in particular functions that rely on multiprocessing.imap, are disrupted by the GUI with unacceptable effects on runtime when executed thriugh sys.

Thus, it is recommended that the custom feature extraction class inherits simba.mixins.abstract_classes.AbstractFeatureExtraction and is executed through argparse.

For an example feature extraction class that inherits from simba.mixins.abstract_classes.AbstractFeatureExtraction and is executed through argparse, see this file. For an example feature extraction class that does NOT inherit from simba.mixins.abstract_classes.AbstractFeatureExtraction and does not use argparse, see this file. More examples can be found in this github documentation. We can give prompt help with troubleshooting through Gitter or GitHb.

Example

>>> test = CustomFeatureExtractor(extractor_file_path='/simba/misc/piotr.py', config_path='/Users/simon/Desktop/envs/troubleshooting/piotr/project_folder/train-20231108-sh9-frames-with-p-lt-2_plus3-&3_best-f1.ini')
>>> test.run()
>>> test = CustomFeatureExtractor(config_path='/Users/simon/Desktop/envs/troubleshooting/piotr/project_folder/train-20231108-sh9-frames-with-p-lt-2_plus3-&3_best-f1.ini', file_path='/simba/misc/piotr.py')
>>> test.run()
>>> test = CustomFeatureExtractor(extractor_file_path='/Users/simon/Desktop/envs/simba/simba/simba/feature_extractors/amber_feature_extractor.py', config_path='/Users/simon/Desktop/envs/simba/troubleshooting/Amber_test/project_folder/project_config.ini')
>>> test.run()

has_argparser_argument(file_path, target_argument)

Check if a Python script, using argparse, has a specific command-line argument.

Parameters

• file_path (Union[str, os.PathLike]) – Path to the Python script file.

• target_argument (str) – The name of the argument to check.

Return bool

True if the specified argument is found in the script’s argparse configuration, False otherwise.

has_block(file_path, target)

Check if a specified block of text exists in a file.

Parameters

• file_path (Union[str, os.PathLike]) – Path to the file to check.

• target (str) – The block of text to search for in the file.

Return bool

True if the specified block of text is found in the file, False otherwise.

run()