Outlier correction

Location outlier removed

class simba.outlier_tools.outlier_corrector_location.OutlierCorrecterLocation(config_path, data_dir=None, save_dir=None, animal_dict=None, criterion=None)

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

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 using heuristic rules.

Uses heuristic rules critera is grabbed from the SimBA project project_config.ini under the [Outlier settings] header.

Note

Documentation.

Parameters

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

• data_dir (Optional[Union[str, os.PathLike]]) – The directory storing the input data. If None, then the outlier_corrected_movement directory of the SimBA project.

• save_dir (Optional[Union[str, os.PathLike]]) – The directory to store the results. If None, then the outlier_corrected_movement_location directory of the SimBA project.

• animal_dict (Optional[Dict[str, Dict[str, str]]]) – Dictionary holding the animal names, and the two body-parts to use to measure the mean or median size of the animals. If None, grabs the info from the SimBA project config.

• criterion (Optional[float]) – The criterion multiplier. If None, grabs the info from the SimBA project config.

Example

>>> _ = OutlierCorrecterLocation(config_path='MyProjectConfig').run()

Movement outlier remover

class simba.outlier_tools.outlier_corrector_movement.OutlierCorrecterMovement(config_path, data_dir=None, save_dir=None)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.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.

Note

Outlier correction documentation.

Parameters

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

Example

>>> outlier_correcter_movement = OutlierCorrecterMovement(config_path='MyProjectConfig')
>>> outlier_correcter_movement.run()

run()

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

Movement outlier remover: multi-core

class simba.outlier_tools.outlier_corrector_movement_mp.OutlierCorrecterMovementMultiProcess(config_path, data_dir=None, save_dir=None, core_cnt=- 1, animal_dict=None, criterion=None)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.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. If not passed, then uses critera stored in the SimBA project project_config.ini under the [Outlier settings] headed. Uses multiprocessing.

Parameters

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

• data_dir (Optional[Union[str, os.PathLike]]) – The directory storing the input data. If None, then the input_csv directory of the SimBA project.

• save_dir (Optional[Union[str, os.PathLike]]) – The directory to store the results. If None, then the outlier_corrected_movement directory of the SimBA project.

• core_cnt (Optional[int]) – The number of cores to use. If -1, then all available cores. Default: -1.

• animal_dict (Optional[Dict[str, Dict[str, str]]]) – Dictionary holding the animal names, and the two body-parts to use to measure the mean or median size of the animals. If None, grabs the info from the SimBA project config.

• criterion (Optional[float]) – The criterion multiplier. If None, grabs the info from the SimBA project config.

Note

Outlier correction documentation.

Example

>>> outlier_correcter_movement = OutlierCorrecterMovementMultiProcess(config_path='MyProjectConfig')
>>> outlier_correcter_movement.run()

Location outlier remover: multi-core

class simba.outlier_tools.outlier_corrector_location_mp.OutlierCorrecterLocationMultiprocess(config_path, data_dir=None, save_dir=None, core_cnt=- 1, animal_dict=None, criterion=None)

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

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 using heuristic rules.

Uses heuristic rules critera is grabbed from the SimBA project project_config.ini under the [Outlier settings] header.

Note

Documentation.

Parameters

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

• data_dir (Optional[Union[str, os.PathLike]]) – The directory storing the input data. If None, then the outlier_corrected_movement directory of the SimBA project.

• save_dir (Optional[Union[str, os.PathLike]]) – The directory to store the results. If None, then the outlier_corrected_movement_location directory of the SimBA project.

• core_cnt (Optional[int]) – The number of cores to use. If -1, then all available cores. Default: -1.

• animal_dict (Optional[Dict[str, Dict[str, str]]]) – Dictionary holding the animal names, and the two body-parts to use to measure the mean or median size of the animals. If None, grabs the info from the SimBA project config.

• criterion (Optional[float]) – The criterion multiplier. If None, grabs the info from the SimBA project config.

Example

>>> _ = OutlierCorrecterLocationMultiprocess(config_path='MyProjectConfig').run()

Advanced movement outlier correction

class simba.outlier_tools.outlier_corrector_movement_advanced.OutlierCorrecterMovementAdvanced(config_path, input_dir, criterion_body_parts, type, agg_method, settings)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.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.

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, input_dir, type, agg_method, criterion_body_parts, settings)

Bases: simba.mixins.config_reader.ConfigReader, simba.mixins.feature_extraction_mixin.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.

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)

Bases: simba.mixins.config_reader.ConfigReader

Skip outlier correction in SimBA projects.

Parameters

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

Example

>>> _ = OutlierCorrectionSkipper(config_path='MyProjectConfig').run()

run()

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.