moabb.datasets.base.LocalBIDSDataset#

class moabb.datasets.base.LocalBIDSDataset(bids_root: Path | str, path_search_params: dict[str, Any] | None = None, read_extra_params: dict[str, Any] | None = None, *, subjects: list[int] | None = None, sessions_per_subject: int | None = None, events, code='LocalBIDSDataset-', interval, paradigm, doi=None, unit_factor=1000000.0, return_all_modalities=False)[source]#

Bases: BaseBIDSDataset

Generic local/private BIDS datasets.

This class is useful if you have a local/private dataset in BIDS format and you want to use it with MOABB, without having to create a new dataset class.

param bids_root:

Local path to the root of the BIDS dataset.

type bids_root:

str | pathlib.Path

param path_search_params:

Additional kwargs for the mne_bids.find_matching_paths function.

type path_search_params:

dict[str, Any] | None

param read_extra_params:

Additional kwargs for the mne_bids.read_raw_bids function.

type read_extra_params:

dict[str, Any] | None

param subjects:

Optional list of subjects. If None, the subjects are inferred from the dataset.

type subjects:

list[int] | None

param sessions_per_subject:

Optional number of sessions per subject. If None, the number is inferred from the dataset.

type sessions_per_subject:

int | None

param events:

String codes for events matched with labels in the stim channel.

type events:

dict[str, str]

param interval:

Imagery interval as defined in the dataset description.

type interval:

list with 2 entries

param paradigm:

Defines what sort of dataset this is.

type paradigm:

str

param doi:

Optional DOI for dataset.

type doi:

str | None

param code:

Unique identifier for the dataset. for compatibility reasons, it should start with "LocalBIDSDataset"

type code:

str

param unit_factor:

Factor to convert units to microvolts. Defaults to 1e6.

type unit_factor:

float

from moabb.datasets import LocalBIDSDataset
dataset = LocalBIDSDataset()
data = dataset.get_data(subjects=[1])
print(data[1])
__init__(bids_root: Path | str, path_search_params: dict[str, Any] | None = None, read_extra_params: dict[str, Any] | None = None, *, subjects: list[int] | None = None, sessions_per_subject: int | None = None, events, code='LocalBIDSDataset-', interval, paradigm, doi=None, unit_factor=1000000.0, return_all_modalities=False)[source]#

Initialize function for the BaseDataset.

property all_subjects#

Full list of subjects available in this dataset (unfiltered).

convert_to_bids(path=None, subjects=None, overwrite=False, format='EDF', verbose=None, generate_figures=False)[source]#

Convert the dataset to BIDS format.

Saves the raw EEG data in a BIDS-compliant directory structure. Unlike the caching mechanism (see CacheConfig), the files produced here do not contain a processing-pipeline hash (desc-<hash>) in their names, making the output a clean, shareable BIDS dataset.

Parameters:

  • path (str | Path | None) – Directory under which the BIDS dataset will be written. If None the default MNE data directory is used (same default as the rest of MOABB).

  • subjects (list of int | None) – Subject numbers to convert. If None, all subjects in subject_list are converted.

  • overwrite (bool) – If True, existing BIDS files for a subject are removed before saving. Default is False.

  • format (str) – The file format for the raw EEG data. Supported values are "EDF" (default), "BrainVision", and "EEGLAB".

  • verbose (str | None) – Verbosity level forwarded to MNE/MNE-BIDS.

  • generate_figures (bool) – If True, generate interactive neural signature HTML figures in {bids_root}/derivatives/neural_signatures/. Requires plotly (pip install moabb[interactive]). Default is False.

Returns:

bids_root – Path to the root of the written BIDS dataset.

Return type:

pathlib.Path

Examples

>>> from moabb.datasets import AlexMI
>>> dataset = AlexMI()
>>> bids_root = dataset.convert_to_bids(path='/tmp/bids', subjects=[1])

Notes

Use CacheConfig to configure caching for get_data(). Use moabb.datasets.bids_interface.get_bids_root to get the BIDS root path.

Added in version 1.5.

data_path(subject, path=None, force_update=False, update_path=None, verbose=None)[source]#

Get path to local copy of a subject data.

Parameters:

  • subject (int) – Number of subject to use

  • path (None | str) – Location of where to look for the data storing location. If None, the environment variable or config parameter MNE_DATASETS_(dataset)_PATH is used. If it doesn’t exist, the “~/mne_data” directory is used. If the dataset is not found under the given path, the data will be automatically downloaded to the specified folder.

  • force_update (bool) – Force update of the dataset even if a local copy exists.

  • update_path (bool | None Deprecated) – If True, set the MNE_DATASETS_(dataset)_PATH in mne-python config to the given path. If None, the user is prompted.

  • verbose (bool, str, int, or None) – If not None, override default verbose level (see mne.verbose()).

Returns:

path – Local path to the given data file. This path is contained inside a list of length one, for compatibility.

Return type:

list of str

download(subject_list=None, path=None, force_update=False, update_path=None, accept=False, verbose=None)[source]#

Download all data from the dataset.

This function is only useful to download all the dataset at once.

Parameters:

  • subject_list (list of int | None) – List of subjects id to download, if None all subjects are downloaded.

  • path (None | str) – Location of where to look for the data storing location. If None, the environment variable or config parameter MNE_DATASETS_(dataset)_PATH is used. If it doesn’t exist, the “~/mne_data” directory is used. If the dataset is not found under the given path, the data will be automatically downloaded to the specified folder.

  • force_update (bool) – Force update of the dataset even if a local copy exists.

  • update_path (bool | None) – If True, set the MNE_DATASETS_(dataset)_PATH in mne-python config to the given path. If None, the user is prompted.

  • accept (bool) – Accept licence term to download the data, if any. Default: False

  • verbose (bool, str, int, or None) – If not None, override default verbose level (see mne.verbose()).

get_additional_metadata(subject: str, session: str, run: str)[source]#

Load additional metadata for a specific subject, session, and run.

Parameters:

  • subject (str) – The identifier for the subject.

  • session (str) – The identifier for the session.

  • run (str) – The identifier for the run.

Returns:

A DataFrame containing the additional metadata if available, otherwise None.

Return type:

None | pandas.DataFrame

get_block_repetition(paradigm, subjects, block_list, repetition_list)[source]#

Select data for all provided subjects, blocks and repetitions.

subject -> session -> run -> block -> repetition

See also

get_data

Parameters:

  • subjects (List of int) – List of subject number

  • block_list (List of int) – List of block number

  • repetition_list (List of int) – List of repetition number inside a block

Returns:

data – dict containing the raw data

Return type:

Dict

get_data(subjects=None, cache_config=None, process_pipeline=None)[source]#

Return the data corresponding to a list of subjects.

The returned data is a dictionary with the following structure:

data = {'subject_id' :
            {'session_id':
                {'run_id': run}
            }
        }

subjects are on top, then we have sessions, then runs. A sessions is a recording done in a single day, without removing the EEG cap. A session is constitued of at least one run. A run is a single contiguous recording. Some dataset break session in multiple runs.

Processing steps can optionally be applied to the data using the *_pipeline arguments. These pipelines are applied in the following order: raw_pipeline -> epochs_pipeline -> array_pipeline. If a *_pipeline argument is None, the step will be skipped. Therefore, the array_pipeline may either receive a mne.io.Raw or a mne.Epochs object as input depending on whether epochs_pipeline is None or not.

Parameters:

  • subjects (List of int) – List of subject number

  • cache_config (dict | CacheConfig) – Configuration for caching of datasets. See CacheConfig for details.

  • process_pipeline (sklearn.pipeline.Pipeline | None) – Optional processing pipeline to apply to the data. To generate an adequate pipeline, we recommend using moabb.make_process_pipelines(). This pipeline will receive mne.io.BaseRaw objects. The steps names of this pipeline should be elements of StepType. According to their name, the steps should either return a mne.io.BaseRaw, a mne.Epochs, or a numpy.ndarray. This pipeline must be “fixed” because it will not be trained, i.e. no call to fit will be made.

Returns:

data – dict containing the raw data

Return type:

Dict

property metadata[source]#

Return structured metadata for this dataset.

Returns the DatasetMetadata object from the centralized catalog, or None if metadata is not available for this dataset.

Returns:

The metadata object containing acquisition parameters, participant demographics, experiment details, and documentation. Returns None if no metadata is registered for this dataset.

Return type:

DatasetMetadata | None

Examples

>>> from moabb.datasets import BNCI2014_001
>>> dataset = BNCI2014_001()
>>> dataset.metadata.participants.n_subjects
9
>>> dataset.metadata.acquisition.sampling_rate
250.0

Examples using moabb.datasets.base.LocalBIDSDataset#

Tutorial 4: Creating custom datasets

Tutorial 4: Creating custom datasets