Pose estimation importers

Import single DLC CSV file

simba.pose_importers.dlc_importer_csv.import_dlc_csv(config_path: Union[str, PathLike], source: str) → List[str][source]

Import file or folder of DLC pose-estimation CSV files to SimBA project. Returns list of file paths that has been imported.

Parameters

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

  • source (str) – path to file or folder containing DLC pose-estimation CSV files

Return List[str]

Paths of imported files.

Example

>>> import_dlc_csv(config_path='project_folder/project_config.ini', source='CSV_import/Together_1.csv')
>>> ['project_folder/csv/input_csv/Together_1.csv']

Import multiple DLC CSV files

Import MARS pose-estimation data

class simba.pose_importers.import_mars.MarsImporter(config_path: Union[str, PathLike], data_path: Union[str, PathLike], interpolation_method: str, smoothing_method: dict)[source]

Bases: object

Import two animal MARS pose-estimation data (in JSON format) into a SimBA project in parquet or CSV format.

Parameters

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

  • data_folder (str) – Path to file (or directory) with data in .json format.

  • interpolation_settings (str) – String defining the pose-estimation interpolation method. OPTIONS: ‘None’, ‘Animal(s): Nearest’, ‘Animal(s): Linear’, ‘Animal(s): Quadratic’,’Body-parts: Nearest’, ‘Body-parts: Linear’, ‘Body-parts: Quadratic’. See this image <https://gist.github.com/gyassine/b47b90e8de935cc06ef856401f7582b0>>_ for comparison of interpolation methods.

  • smoothing_method (dict) – Dictionary defining the pose estimation smoothing method. EXAMPLE: {‘Method’: ‘Savitzky Golay’, ‘Parameters’: {‘Time_window’: ‘200’}})

Note

Multi-animal import tutorial.

Examples

>>> mars_importer = MarsImporter(config_path=r'MyConfigPath', data_folder=r'MyMarsDataFolder', interpolation_settings='None', smoothing_settings={'Method': 'None', 'Parameters': {'Time_window': '200'}})
>>> mars_importer.import_data()

References

1

Segalin et al., The Mouse Action Recognition System (MARS) software pipeline for automated analysis of social behaviors in mice, eLife, 2021.

Import DANNCE pose-estimation data

Import SLEAP CSV pose-estimation data

class simba.pose_importers.sleap_csv_importer.SLEAPImporterCSV(config_path: str, data_folder: str, id_lst: list, interpolation_settings: str, smoothing_settings: dict)[source]

Bases: ConfigReader, PoseImporterMixin

Importing SLEAP pose-estimation data into SimBA project in CSV format.

Note

Google Colab notebook for converting SLEAP .slp to CSV written by @Toshea111. Example expected SLEAP csv data file for 5 animals / 4 pose-estimated body-parts.

Parameters

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

  • data_folder (str) – Path to folder containing SLEAP data in csv format.

  • id_lst (List[str]) – Animal names. This will be ignored in one animal projects and default to Animal_1.

  • interpolation_settings (str) – String defining the pose-estimation interpolation method. OPTIONS: ‘None’, ‘Animal(s): Nearest’, ‘Animal(s): Linear’, ‘Animal(s): Quadratic’,’Body-parts: Nearest’, ‘Body-parts: Linear’, ‘Body-parts: Quadratic’.

  • smoothing_settings (str) – Dictionary defining the pose estimation smoothing method. EXAMPLE: {‘Method’: ‘Savitzky Golay’, ‘Parameters’: {‘Time_window’: ‘200’}})

References

1

Pereira et al., SLEAP: A deep learning system for multi-animal pose tracking, Nature Methods, 2022.

>>> sleap_csv_importer = SLEAPImporterCSV(config_path=r'project_folder/project_config.ini', data_folder=r'data_folder', actor_IDs=['Termite_1', 'Termite_2', 'Termite_3', 'Termite_4', 'Termite_5'], interpolation_settings="Body-parts: Nearest", smoothing_settings = {'Method': 'Savitzky Golay', 'Parameters': {'Time_window': '200'}})
>>> sleap_csv_importer.run()

Import SLEAP H5 pose-estimation data

class simba.pose_importers.sleap_h5_importer.SLEAPImporterH5(config_path: str, data_folder: str, id_lst: list, interpolation_settings: str, smoothing_settings: dict)[source]

Bases: ConfigReader, PoseImporterMixin

Importing SLEAP pose-estimation data into SimBA project in H5 format

Parameters

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

  • data_folder (str) – Path to folder containing SLEAP data in csv format.

  • id_lst (List[str]) – Animal names. This will be ignored in one animal projects and default to Animal_1.

  • interpolation_settings (str) – String defining the pose-estimation interpolation method. OPTIONS: ‘None’, ‘Animal(s): Nearest’, ‘Animal(s): Linear’, ‘Animal(s): Quadratic’,’Body-parts: Nearest’, ‘Body-parts: Linear’, ‘Body-parts: Quadratic’.

  • smoothing_settings (str) – Dictionary defining the pose estimation smoothing method. EXAMPLE: {‘Method’: ‘Savitzky Golay’, ‘Parameters’: {‘Time_window’: ‘200’}}

Note

Multi-animal import tutorial.

References

1

Pereira et al., SLEAP: A deep learning system for multi-animal pose tracking, Nature Methods, 2022.

>>> sleap_h5_importer = SLEAPImporterH5(config_path=r'project_folder/project_config.ini', data_folder=r'data_folder', actor_IDs=['Termite_1', 'Termite_2', 'Termite_3', 'Termite_4', 'Termite_5'], interpolation_settings="Body-parts: Nearest", smoothing_settings = {'Method': 'Savitzky Golay', 'Parameters': {'Time_window': '200'}})
>>> sleap_h5_importer.run()

Import SLEAP SLP pose-estimation data

class simba.pose_importers.sleap_slp_importer.SLEAPImporterSLP(project_path: str, data_folder: str, id_lst: list, interpolation_settings: str, smoothing_settings: dict)[source]

Bases: ConfigReader, PoseImporterMixin

Class for importing SLEAP pose-estimation data into a SimBA project.

Note

Importing SLEAP .SLP files into SimBA come at long runtimes. For fater runtimes, use simba.pose_importers.sleap_h5_importer.SLEAPImporterH5() or simba.pose_importers.sleap_csv_importer.SLEAPImporterCSV()

Parameters

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

  • data_folder (str) – Path to folder containing SLEAP data in csv format.

  • id_lst (List[str]) – Animal names. This will be ignored in one animal projects and default to Animal_1.

  • interpolation_settings (str) – String defining the pose-estimation interpolation method. OPTIONS: ‘None’, ‘Animal(s): Nearest’, ‘Animal(s): Linear’, ‘Animal(s): Quadratic’,’Body-parts: Nearest’, ‘Body-parts: Linear’, ‘Body-parts: Quadratic’.

  • smoothing_settings (str) – Dictionary defining the pose estimation smoothing method. EXAMPLE: {‘Method’: ‘Savitzky Golay’, ‘Parameters’: {‘Time_window’: ‘200’}}.

Example

>>> slp_importer = SLEAPImporterSLP(project_path="MyConfigPath", data_folder=r'MySLPDataFolder', actor_IDs=['Mouse_1', 'Mouse_2'], interpolation_settings="Body-parts: Nearest", smoothing_settings = {'Method': 'Savitzky Golay', 'Parameters': {'Time_window': '200'}})
>>> slp_importer.run()

References

1

Pereira et al., SLEAP: A deep learning system for multi-animal pose tracking, Nature Methods, 2022.

Import APT TRK pose-estimation data

class simba.pose_importers.trk_importer.TRKImporter(config_path: str, data_path: str, animal_id_lst: list, interpolation_method: str, smoothing_settings: dict)[source]

Bases: ConfigReader

Import DLC H5 files

class simba.pose_importers.madlc_importer.MADLCImporterH5(config_path: str, data_folder: str, file_type: str, id_lst: list, interpolation_settings: str, smoothing_settings: dict)[source]

Bases: ConfigReader, PoseImporterMixin

Importing multi-animal deeplabcut (maDLC) pose-estimation data (in H5 format) into a SimBA project in parquet or CSV format.

Parameters

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

  • data_folder (str) – Path to folder containing maDLC data in .h5 format.

  • file_type (str) – Method used to perform pose-estimation in maDLC. OPTIONS: skeleton, box, ellipse.

  • id_lst (List[str]) – Names of animals.

  • interpolation_setting (str) – String defining the pose-estimation interpolation method. OPTIONS: ‘None’, ‘Animal(s): Nearest’, ‘Animal(s): Linear’, ‘Animal(s): Quadratic’,’Body-parts: Nearest’, ‘Body-parts: Linear’, ‘Body-parts: Quadratic’.

  • smoothing_settings (dict) – Dictionary defining the pose estimation smoothing method. EXAMPLE: {‘Method’: ‘Savitzky Golay’, ‘Parameters’: {‘Time_window’: ‘200’}})

Note

Multi-animal import tutorial.

Examples

>>> _ = MADLCImporterH5(config_path=r'MyConfigPath', data_folder=r'maDLCDataFolder', file_type='ellipse', id_lst=['Animal_1', 'Animal_2'], interpolation_settings='None', smoothing_settings={'Method': 'None', 'Parameters': {'Time_window': '200'}}).run()

References

1

Lauer et al., Multi-animal pose estimation, identification and tracking with DeepLabCut, Nature Methods, 2022.