Third-party behavior labels (annotation) appenders

BENTO

class simba.third_party_label_appenders.BENTO_appender.BentoAppender(config_path: str, data_dir: str)[source]

Bases: ConfigReader

Append BENTO annotation to SimBA featurized datasets.

Parameters

config_path (str) – path to SimBA project config file in Configparser format
data_dir (str) – Path to folder containing BENTO data.

Note

Example BENTO input file.

‘GitHub tutorial <https://github.com/sgoldenlab/simba/blob/master/docs/third_party_annot.md>`_.

Examples

>>> bento_dir = 'tests/test_data/bento_example'
>>> config_path = 'tests/test_data/import_tests/project_folder/project_config.ini'
>>> bento_appender = BentoAppender(config_path=config_path, data_dir=bento_dir)
>>> bento_appender.run()

References

1: Segalin et al., eLife, https://doi.org/10.7554/eLife.63720

BORIS

class simba.third_party_label_appenders.BORIS_appender.BorisAppender(config_path: str, data_dir: str)[source]

Bases: ConfigReader

Append BORIS human annotations onto featurized pose-estimation data.

Parameters

config_path (str) – path to SimBA project config file in Configparser format
data_dir (str) – path to folder holding BORIS data files is CSV format

Note

Third-party import tutorials. Example I BORIS input file. Example II BORIS input file.

Examples

>>> boris_appender = BorisAppender(config_path='MyProjectConfigPath', data_dir=r'BorisDataFolder')
>>> boris_appender.create_boris_master_file()
>>> boris_appender.run()

References

1: Behavioral Observation Research Interactive Software (BORIS) user guide.

create_boris_master_file()[source]

Method to create concatenated dataframe of BORIS annotations.

Returns: Attribute – master_boris_df
Return type: pd.Dataframe

run()[source]: Method to append BORIS annotations created in create_boris_master_file() to the featurized pose-estimation data in the SimBA project. Results (parquets’ or CSVs) are saved within the the project_folder/csv/targets_inserted directory of the SimBA project.

Deepethogram

class simba.third_party_label_appenders.deepethogram_importer.DeepEthogramImporter(data_dir: str, config_path: str)[source]

Bases: ConfigReader

Append DeepEthogram optical flow annotations onto featurized pose-estimation data.

Parameters

config_path (str) – path to SimBA project config file in Configparser format
data_dir (str) – path to folder holding DeepEthogram data files is CSV format

Note

Third-party import tutorials. Example expected input.

Examples

>>> deepethogram_importer = DeepEthogramImporter(config_path=r'MySimBAConfigPath', data_dir=r'MyDeepEthogramDir')
>>> deepethogram_importer.run()

References

1: DeepEthogram repo.
2: Example DeepEthogram input file.

Ethovison

class simba.third_party_label_appenders.ethovision_import.ImportEthovision(config_path: str, data_dir: str)[source]

Bases: ConfigReader

Append ETHOVISION human annotations onto featurized pose-estimation data. Results are saved within the project_folder/csv/targets_inserted directory of the SimBA project (as parquets’ or CSVs).

Parameters

config_path (str) – path to SimBA project config file in Configparser format
data_dir (str) – path to folder holding ETHOVISION data files is XLSX or XLS format

Note

Third-party import GitHub tutorial. Example of expected ETHOVISION file.

Examples

>>> ethovision_importer = ImportEthovision(config_path="MyConfigPath", data_dir="MyEthovisionFolderPath")
>>> ethovision_importer.run()

Noldus Observer

class simba.third_party_label_appenders.observer_importer.NoldusObserverImporter(config_path: str, data_dir: str)[source]

Bases: ConfigReader

Append Noldus Observer human annotations onto featurized pose-estimation data. Results are saved within the project_folder/csv/targets_inserted directory of the SimBA project (as parquets’ or CSVs).

Parameters

config_path (str) – path to SimBA project config file in Configparser format
data_dir (str) – path to folder holding Observer data files is XLSX or XLS format

Note

Third-party import GitHub tutorial. Expected input example 1. Expected input example 2.

Examples

>>> _ = NoldusObserverImporter(config_path='MyConfigPath', data_dir='MyNoldusObserverDataDir').run()

Solomon coder

class simba.third_party_label_appenders.solomon_importer.SolomonImporter(config_path: str, data_dir: str)[source]

Bases: ConfigReader

Append SOLOMON human annotations onto featurized pose-estimation data.

Parameters

config_path (str) – path to SimBA project config file in Configparser format
data_dir (str) – path to folder holding SOLOMON data files is CSV format

Note

Third-party import tutorials. Example of expected SOLOMON file format.

Examples

>>> solomon_imported = SolomonImporter(config_path=r'MySimBAConfigPath', data_dir=r'MySolomonDir')
>>> solomon_imported.run()

References

1: SOLOMON CODER USER-GUIDE (PDF).

Generic third-party appender tool

class simba.third_party_label_appenders.third_party_appender.ThirdPartyLabelAppender(config_path: Union[str, PathLike], data_dir: Union[str, PathLike], app: typing_extensions.Literal['BENTO', 'BORIS', 'DEEPETHOGRAM', 'ETHOVISION', 'SOLOMON', 'OBSERVER'], file_format: str, error_settings: Dict[str, str], log: Optional[bool] = False)[source]

Bases: ConfigReader

Concatenate third-party annotations to featurized pose-estimation datasets in SimBA.

Parameters

app (str) – Third-party application. OPTIONS: [‘BORIS’, ‘BENTO’, ‘DEEPETHOGRAM’, ‘ETHOVISION’, ‘OBSERVER’, ‘SOLOMON’].
config_path (str) – path to SimBA project config file in Configparser format.
data_dir (str) – Directory holding third-party annotation data files.
settings (dict) – User-defined settings including how to handle errors, logging, and data file types associated with the third-party application.

… note::

Third-party import tutorials.

`BENTO: expected input <https://github.com/sgoldenlab/simba/blob/master/misc/bento_example.annot`__. BORIS: expected input.. DEEPETHOGRAM: expected input. ETHOVISION: expected input. OBSERVER: expected input I. OBSERVER: expected input II. SOLOMON: expected input II.

Example

>>>test = ThirdPartyLabelAppender(config_path=’/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/project_folder/project_config.ini’, >>> data_dir=’/Users/simon/Desktop/envs/simba/simba/tests/data/test_projects/two_c57/observer_annotations’, >>> app=OBSERVER, >>> file_format=’.xlsx’, >>> error_settings=error_settings, >>> log=log) >>> test.run()

References

1: DeepEthogram repo.
2: Segalin et al., eLife, https://doi.org/10.7554/eLife.63720
3: Behavioral Observation Research Interactive Software (BORIS) user guide.
4: Noldus Ethovision XT.
5: Noldus Observer XT.
6: Solomon coder user-guide (PDF).