Configuratron

See the configuration guide for a detailed listing of configuration options.

Classes

DatasetConfig(name, config[, …])	Parses dataset entries in DN3 config
ExperimentConfig(config_filename[, …])	Parses DN3 configuration files.
RawOnTheFlyRecording(*args, **kwds)

class dn3.configuratron.config.DatasetConfig(name: str, config: dict, adopt_auxiliaries=True, ext_handlers=None, deep1010=None, samples=None, sfreq=None, preload=False, return_trial_ids=False)

Parses dataset entries in DN3 config

Methods

add_custom_raw_loader(custom_loader)	This is used to provide a custom implementation of taking a filename, and returning a mne.io.Raw() instance.
add_custom_thinker_loader(thinker_loader)	Add custom code to load a specific thinker from a set of session files.
add_extension_handler(extension, handler)	Provide callable code to create a raw instance from sessions with certain file extensions.
add_progress_callbacks([session_callback, …])	Add callbacks to be invoked on successful loading of session and/or thinker.
auto_construct_dataset([mapping])	This creates a dataset using the config values.
auto_mapping([files, reset_exclusions])	Generates a mapping of sessions and people of the dataset, assuming files are stored in the structure:
scan_toplevel()	Scan the provided toplevel for all files that may belong to the dataset.

add_custom_raw_loader(custom_loader)

This is used to provide a custom implementation of taking a filename, and returning a mne.io.Raw() instance. If properly constructed, all further configuratron options, such as resampling, epoching, filtering etc. should occur automatically.

This is used to load unconventional files, e.g. ‘.mat’ files from matlab, or custom ‘.npy’ arrays, etc.

Notes

Consider using mne.io.Raw.add_events() to integrate otherwise difficult (for the configuratron) to better specify events for each recording.

Parameters

custom_loader (callable) – A function that expects a single pathlib.Path() instance as argument and returns an instance of mne.io.Raw(). To gracefully ignore problematic sessions, raise DN3ConfigException within.

add_custom_thinker_loader(thinker_loader)

Add custom code to load a specific thinker from a set of session files.

Warning

For all intents and purposes, this circumvents most of the configuratron, and results in it being mostly a tool for organizing dataset files. Most of the options are not leveraged and must be implemented by the custom loader. Please open an issue if you’d like to develop this option further!

Parameters

thinker_loader – A function that takes a list argument that consists of the filenames (str) of all the detected session for the given thinker and a second argument for the detected name of the person. The function should return a single instance of type Thinker. To gracefully ignore the person, raise a DN3ConfigException

add_extension_handler(extension: str, handler)

Provide callable code to create a raw instance from sessions with certain file extensions. This is useful for handling of custom file formats, while preserving a consistent experiment framework.

Parameters

• extension (str) – An extension that includes the ‘.’, e.g. ‘.csv’

• handler (callable) – Callback with signature f(path_to_file: str) -> mne.io.Raw

add_progress_callbacks(session_callback=None, thinker_callback=None)

Add callbacks to be invoked on successful loading of session and/or thinker. Optionally, these can modify the respective loaded instances.

Parameters

• session_callback – A function that expects a single session argument and can modify the (or return an alternative) session.

• thinker_callback – The same as for session, but with Thinker instances.

auto_construct_dataset(mapping=None, **dsargs)

This creates a dataset using the config values. If tlen and tmin are specified in the config, creates epoched dataset, otherwise Raw.

Parameters

• mapping (dict, optional) –

  A dict specifying a list of sessions (as paths to files) for each person_id in the dataset. e.g. {

  person_1: [sess_1.edf, …], person_2: [sess_1.edf], …

  } If not specified, will use auto_mapping() to generate.

• dsargs – Any additional arguments to feed for the creation of the dataset. i.e. keyword arguments to Dataset’s constructor (which id’s to return). If dataset_info is provided here, it will override what was inferrable from the configuration file.

Returns

dataset – An instance of Dataset, constructed according to mapping.

Return type

Dataset

auto_mapping(files=None, reset_exclusions=True)

Generates a mapping of sessions and people of the dataset, assuming files are stored in the structure: toplevel/(*optional - <version>)/<person-id>/<session-id>.{ext}

Parameters

files (list) – Optional list of files (convertible to Path objects, e.g. relative or absolute strings) to be used. If not provided, will use scan_toplevel().

Returns

mapping – The keys are of all the people in the dataset, and each value another similar mapping to that person’s sessions.

Return type

dict

scan_toplevel()

Scan the provided toplevel for all files that may belong to the dataset.

Returns

files – A listing of all the candidate filepaths (before excluding those that match exclusion criteria).

Return type

list

class dn3.configuratron.config.ExperimentConfig(config_filename: str, adopt_auxiliaries=True)

Parses DN3 configuration files. Checking the DN3 token for listed datasets.

class dn3.configuratron.config.RawOnTheFlyRecording(*args, **kwds)

Methods

preprocess(preprocessor[, apply_transform])

Applies a preprocessor to the dataset

preprocess(preprocessor, apply_transform=True)

Applies a preprocessor to the dataset

Parameters

• preprocessor (Preprocessor) – A preprocessor to be applied

• apply_transform (bool) – Whether to apply the transform to this dataset (and all members e.g thinkers or sessions) after preprocessing them. Alternatively, the preprocessor is returned for manual application of its transform through Preprocessor.get_transform()

Returns

preprocessor – The preprocessor after application to all relevant thinkers

Return type

Preprocessor