Outlier correction tools

Location outlier methods

class simba.outlier_tools.outlier_corrector_location.OutlierCorrecterLocation(config_path: str)[source]

Bases: ConfigReader

Detect and amend outliers in pose-estimation data based in the location of the body-parts in the current frame relative to the location of the body-part in the preceding frame. Uses critera stored in the SimBA project project_config.ini under the [Outlier settings] header.

Note

Documentation.

_images/location_outlier.png
Parameters

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

Examples

>>> _ = OutlierCorrecterLocation(config_path='MyProjectConfig').run()
run()[source]

Runs outlier detection and correction. Results are stored in the project_folder/csv/outlier_corrected_movement_location directory of the SimBA project.

Movement outlier methods

class simba.outlier_tools.outlier_corrector_movement.OutlierCorrecterMovement(config_path: str)[source]

Bases: ConfigReader, FeatureExtractionMixin

Detect and ammend outliers in pose-estimation data based on movement lenghth (Euclidean) of the body-parts in the current frame from preceeding frame. Uses critera stored in the SimBA project project_config.ini under the [Outlier settings] header.

Parameters

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

_images/movement_outlier.png

Note

Outlier correction documentation.

Examples

>>> outlier_correcter_movement = OutlierCorrecterMovement(config_path='MyProjectConfig')
>>> outlier_correcter_movement.run()
run()[source]

Runs outlier detection and correction. Results are stored in the project_folder/csv/outlier_corrected_movement directory of the SimBA project.

Advanced movement outlier correction

class simba.outlier_tools.outlier_corrector_movement_advanced.OutlierCorrecterMovementAdvanced(config_path: Union[str, PathLike], input_dir: Union[str, PathLike], criterion_body_parts: dict, type: typing_extensions.Literal['animal', 'body-part'], agg_method: typing_extensions.Literal['mean', 'median'], settings: dict)[source]

Bases: ConfigReader, FeatureExtractionMixin

Performs outlier correction that allows different heuristic outlier criteria for different animals or body-parts. For example, correct some outlier body-parts with a movement heuristic criteria of 2x above the mean movement, and other body-parts with a heuristic critera of 1.5x above the mean movement.

Note

See notebook. for example use-case.

_images/movement_outlier.png
Parameters

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

  • input_dir (str) – Directory containing input files. E.g., project_folder/csv/input_csv directory.

  • type (Literal['animal', 'body-part']) – If the rules are defined on animal or body-part level. E.g., If one heuristic rule per animal then animal. If one heurstic rule prr body-part then body-parts

  • agg_method (Literal['mean', 'median']) – If to use the mean or median to compute criterion.

  • criterion_body_parts (dict) – The body-parts used to calculate the size of the animals.

  • settings (dict) – The heuristic multiplier rules to use for each body part or animal.

Example

>>> settings = {'Simon': 1.1, 'JJ': 1.2}
>>> criterion_body_parts = {'Simon': ['Nose_1', 'Tail_base_1'], 'JJ': ['Nose_2', 'Tail_base_2']}
>>> outlier_corrector = OutlierCorrecterMovementAdvanced(config_path='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini', input_dir='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/csv/input_csv', type='animal', agg_method='mean', criterion_body_parts=criterion_body_parts, settings=settings)
>>> outlier_corrector.run()
>>> settings = {'Simon': {'Ear_left_1': 1.1, 'Ear_right_1': 5.1, 'Nose_1': 2.1, 'Center_1': 1.5, 'Lat_left_1': 3.1, 'Lat_right_1': 1.9, 'Tail_base_1': 2.3, 'Tail_end_1': 1.4}, 'JJ': {'Ear_left_2': 1.2, 'Ear_right_2': 1.2, 'Nose_2': 2, 'Center_2': 4.1, 'Lat_left_2': 9, 'Lat_right_2': 1.2, 'Tail_base_2': 1.6, 'Tail_end_2': 2.2}}
>>> outlier_corrector = OutlierCorrecterMovementAdvanced(config_path='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini', input_dir='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/csv/input_csv', type='body-part', agg_method='mean', criterion_body_parts=criterion_body_parts, settings=settings)

Advanced location outlier correction

class simba.outlier_tools.outlier_corrector_location_advanced.OutlierCorrecterLocationAdvanced(config_path: Union[str, PathLike], input_dir: Union[str, PathLike], type: str, agg_method: str, criterion_body_parts: dict, settings: dict)[source]

Bases: ConfigReader, FeatureExtractionMixin

Performs location outlier correction that allows different heuristic outlier criteria for different animals or body-parts. For example, correct some outlier body-parts with a location heuristic criteria of 4x above the mean movement, and other body-parts with a heuristic critera of 2x above the mean movement.

Note

See notebook. for example use-case.

_images/location_outlier.png
Parameters

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

  • input_dir (str) – Directory containing input files. E.g., project_folder/csv/input_csv directory.

  • type (Literal['animal', 'body-part']) – If the rules are defined on animal or body-part level. E.g., If one heuristic rule per animal then animal. If one heurstic rule prr body-part then body-parts

  • agg_method (Literal['mean', 'median']) – If to use the mean or median to compute criterion.

  • criterion_body_parts (dict) – The body-parts used to calculate the size of the animals.

  • settings (dict) – The heuristic multiplier rules to use for each body part or animal.

Example

>>> settings = {'Simon': 1.1, 'JJ': 1.2}
>>> criterion_body_parts = {'Simon': ['Nose_1', 'Tail_base_1'], 'JJ': ['Nose_2', 'Tail_base_2']}
>>> outlier_corrector = OutlierCorrecterLocationAdvanced(config_path='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini', input_dir='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/csv/input_csv', type='animal', agg_method='mean', criterion_body_parts=criterion_body_parts, settings=settings)
>>> outlier_corrector.run()
>>> settings = {'Simon': {'Ear_left_1': 1.1, 'Ear_right_1': 5.1, 'Nose_1': 2.1, 'Center_1': 1.5, 'Lat_left_1': 3.1, 'Lat_right_1': 1.9, 'Tail_base_1': 2.3, 'Tail_end_1': 1.4}, 'JJ': {'Ear_left_2': 1.2, 'Ear_right_2': 1.2, 'Nose_2': 2, 'Center_2': 4.1, 'Lat_left_2': 9, 'Lat_right_2': 1.2, 'Tail_base_2': 1.6, 'Tail_end_2': 2.2}}
>>> outlier_corrector = OutlierCorrecterLocationAdvanced(config_path='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini', input_dir='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/csv/input_csv', type='body-part', agg_method='mean', criterion_body_parts=criterion_body_parts, settings=settings)

Skipping outlier correction

class simba.outlier_tools.skip_outlier_correction.OutlierCorrectionSkipper(config_path: str)[source]

Bases: ConfigReader

Skip outlier correction in SimBA projects.

Parameters

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

Examples

>>> _ = OutlierCorrectionSkipper(config_path='MyProjectConfig').run()
run()[source]

Standardizes pose-estimation data (i.e., headers) from different pose-estimation packages. Results are stored in the project_folder/csv/outlier_corrected_movement_location` directory of the SimBA project