ibllib.io.extractors.base

Base Extractor classes.

A module for the base Extractor classes. The Extractor, given a session path, will extract the processed data from raw hardware files and optionally save them.

Functions

`get_bpod_extractor_class`	Get the Bpod trials extractor class associated with a given Bpod session.
`get_pipeline`	Get the pre-processing pipeline name from a session path.
`get_session_extractor_type`	Infer trials extractor type from task settings.
`get_task_extractor_type`	Returns the task type string from the full pybpod task name.
`get_task_protocol`	Return the task protocol name from task settings.
`protocol2extractor`	Get the Bpod trials extractor class associated with a given Bpod task protocol.
`run_extractor_classes`	Run a set of extractors with the same inputs.

Classes

`BaseBpodTrialsExtractor`	Base (abstract) extractor class for bpod jsonable data set.
`BaseExtractor`	Base extractor class.

class BaseExtractor(session_path=None)[source]

Bases: ABC

Base extractor class.

Writing an extractor checklist:

on the child class, overload the _extract method
this method should output one or several numpy.arrays or dataframe with a consistent shape
save_names is a list or a string of filenames, there should be one per dataset
set save_names to None for a dataset that doesn’t need saving (could be set dynamically in the _extract method)

Parameters:: session_path (str/Path) – Absolute path of session folder

save_names = None

The filenames of each extracted dataset, or None if array should not be saved.

Type:: tuple of str

var_names = None

A list of names for the extracted variables. These become the returned output keys.

Type:: tuple of str

default_path = PosixPath('alf')

The default output folder relative to session_path.

Type:: pathlib.Path

session_path = None

Absolute path of session folder.

Type:: pathlib.Path

extract(save=False, path_out=None, **kwargs)[source]

Returns:: dict of numpy.array, list of filenames

class BaseBpodTrialsExtractor(session_path=None)[source]

Bases: BaseExtractor

Base (abstract) extractor class for bpod jsonable data set.

Wraps the _extract private method.

Parameters:: session_path (str) – Absolute path of session folder.

:param bpod_trials :param settings

bpod_trials = None

settings = None

task_collection = None

frame2ttl = None

audio = None

extract(bpod_trials=None, settings=None, **kwargs)[source]

Param:: bpod_trials (optional) bpod trials from jsonable in a dictionary
Param:: settings (optional) bpod iblrig settings json file in a dictionary
Param:: save (bool) write output ALF files, defaults to False
Param:: path_out (pathlib.Path) output path (defaults to {session_path}/alf)
Returns:: numpy.ndarray or list of ndarrays, list of filenames
Return type:: dtype(‘float64’)

property alf_path

The full task collection filepath.

Type:: pathlib.Path

run_extractor_classes(classes, session_path=None, **kwargs)[source]

Run a set of extractors with the same inputs.

Parameters:

classes – list of Extractor class
save – True/False
path_out – (defaults to alf path)
kwargs – extractor arguments (session_path…)

Returns:

dictionary of arrays, list of files

get_task_protocol(session_path, task_collection='raw_behavior_data')[source]

Return the task protocol name from task settings.

If the session path and/or task collection do not exist, the settings file is missing or otherwise can not be parsed, or if the ‘PYBPOD_PROTOCOL’ key is absent, None is returned. A warning is logged if the session path or settings file doesn’t exist. An error is logged if the settings file can not be parsed.

Parameters:

session_path (str, pathlib.Path) – The absolute session path.
task_collection (str) – The session path directory containing the task settings file.

Returns:

The Pybpod task protocol name or None if not found.

Return type:

str or None

get_task_extractor_type(task_name)[source]

Returns the task type string from the full pybpod task name.

Parameters:: task_name (str) – The complete task protocol name from the PYBPOD_PROTOCOL field of the task settings.
Returns:: The extractor type identifier. Examples include ‘biased’, ‘habituation’, ‘training’, ‘ephys’, ‘mock_ephys’ and ‘sync_ephys’.
Return type:: str

Examples

>>> get_task_extractor_type('_iblrig_tasks_biasedChoiceWorld3.7.0')
'biased'

>>> get_task_extractor_type('_iblrig_tasks_trainingChoiceWorld3.6.0')
'training'

get_session_extractor_type(session_path, task_collection='raw_behavior_data')[source]

Infer trials extractor type from task settings.

From a session path, loads the settings file, finds the task and checks if extractors exist. Examples include ‘biased’, ‘habituation’, ‘training’, ‘ephys’, ‘mock_ephys’, and ‘sync_ephys’. Note this should only be used for legacy sessions, i.e. those without an experiment description file.

Parameters:

session_path (str, pathlib.Path) – The session path for which to determine the pipeline.
task_collection (str) – The session path directory containing the raw task data.

Returns:

The task extractor type, e.g. ‘biased’, ‘habituation’, ‘ephys’, or False if unknown.

Return type:

str or False

get_pipeline(session_path, task_collection='raw_behavior_data')[source]

Get the pre-processing pipeline name from a session path.

Note this is only suitable for legacy sessions, i.e. those without an experiment description file. This function will be removed in the future.

Parameters:

session_path (str, pathlib.Path) – The session path for which to determine the pipeline.
task_collection (str) – The session path directory containing the raw task data.

Returns:

The pipeline name inferred from the extractor type, e.g. ‘ephys’, ‘training’, ‘widefield’.

Return type:

str

get_bpod_extractor_class(session_path, task_collection='raw_behavior_data')[source]

Get the Bpod trials extractor class associated with a given Bpod session.

Note that unlike get_session_extractor_type(), this function maps directly to the Bpod trials extractor class name. This is hardware invariant and is purly to determine the Bpod only trials extractor.

Parameters:

session_path (str, pathlib.Path) – The session path containing Bpod behaviour data.
task_collection (str) – The session_path sub-folder containing the Bpod settings file.

Returns:

The extractor class name.

Return type:

str

protocol2extractor(protocol)[source]

Get the Bpod trials extractor class associated with a given Bpod task protocol.

The Bpod task protocol can be found in the ‘PYBPOD_PROTOCOL’ field of the _iblrig_taskSettings.raw.json file.

Parameters:: protocol (str) – A Bpod task protocol name.
Returns:: The extractor class name.
Return type:: str