moabb.datasets.Peterson2020#

class moabb.datasets.Peterson2020(subjects=None, sessions=None, *, return_all_modalities=False)[source]#

Bases: OpenNeuroMirrorMixin, BaseBIDSDataset

[source]

Dataset Snapshot

Peterson2020

Imagery, 2 classes (motor_imagery vs rest)

AuthorsVictoria Peterson, Catalina Maria Galvan, Hugo Sacha Hernadez, Ruben Spies

🇦🇷 IMAL, CONICET-UNL, AR·2020
Imagery Code: Peterson2020 10 subjects 1 session 15 ch 125 Hz 2 classes 4.0 s trials

Class Labels: motor_imagery, rest

Read Paper Compare Similar Report Issue

Overview

Motor imagery vs rest low-cost EEG dataset from Peterson et al 2020

10 novice participants (12 recruited, two excluded by the authors), 15-channel consumer-grade EEG (OpenBCI Cyton + Daisy board with an Electro-Cap, reference left / ground right ear lobe) at 125 Hz, recorded in a non-shielded office. Subjects either imagined grasping with their dominant hand (motor_imagery) or stayed idle (rest) for 4 s after the cue; no feedback was presented. RUN0 (real-movement demonstration) is excluded; RUN1-RUN4 hold 20 MI + 20 rest trials each. Events are native EDF annotations (OpenViBE labels OVTK_GDF_Right = MI cue, OVTK_GDF_Tongue = rest).

Open in Overview tab →

Citation & Impact

Stimulus Protocol
../_images/Peterson2020.svg

4s task window per trial · 2-class imagery paradigm · 4 runs/session across 1 sessions

HED Event Tags
HED tags2/2 events annotated

Source: MOABB BIDS HED annotation mapping.

Sensory-event
2
Experimental-stimulus
1
Label
1
Rest
1
Visual-presentation
1
rest
Sensory-eventExperimental-stimulusVisual-presentationRest
motor_imagery
Sensory-eventLabel

HED tree view

Tree · rest
├─ Sensory-event
├─ Experimental-stimulus
├─ Visual-presentation
└─ Rest
Tree · motor_imagery
├─ Sensory-event
└─ Label
Channel Summary
Total channels15
EEG15
Montage10-20
Sampling125 Hz
Referenceleft ear lobe
Filterpaper: 0.5-45 Hz 3rd-order Butterworth band-pass applied in OpenViBE during acquisition; BIDS sidecars: n/a
Notch / line50 Hz

This diagram is automatically generated from MOABB metadata. Please consult the original publication to confirm the experimental protocol details.

Motor imagery vs rest low-cost EEG dataset from Peterson et al 2020 [1].

10 novice participants (12 recruited, two excluded by the authors), 15-channel consumer-grade EEG (OpenBCI Cyton + Daisy board with an Electro-Cap, reference left / ground right ear lobe) at 125 Hz, recorded in a non-shielded office. Subjects either imagined grasping with their dominant hand (motor_imagery) or stayed idle (rest) for 4 s after the cue; no feedback was presented. RUN0 (real-movement demonstration) is excluded; RUN1-RUN4 hold 20 MI + 20 rest trials each. Events are native EDF annotations (OpenViBE labels OVTK_GDF_Right = MI cue, OVTK_GDF_Tongue = rest).

References

[1]

Peterson, V., Galvan, C., Hernandez, H., & Spies, R. (2020). A feasibility study of a complete low-cost consumer-grade brain-computer interface system. Heliyon, 6(3), e03425. https://doi.org/10.1016/j.heliyon.2020.e03425

from moabb.datasets import Peterson2020
dataset = Peterson2020()
data = dataset.get_data(subjects=[2])
print(data[2])

Dataset summary

#Subj

10

#Chan

15

#Classes

2

#Trials / class

80

Trials length

4 s

Freq

125 Hz

#Sessions

1

#Runs

4

Total_trials

1600

Participants

  • Population: healthy

  • BCI experience: naive

Equipment

  • Amplifier: OpenBCI Cyton + Daisy (16-channel) with Electro-Cap System II

  • Montage: 10-20

  • Reference: left ear lobe

Preprocessing

  • Data state: raw

  • Notes: BIDS sidecars declare no hardware/software filters; the paper reports a 0.5-45 Hz 3rd-order Butterworth band-pass applied in OpenViBE during acquisition and a 1-40 Hz 5th-order Butterworth post-processing filter for its analysis.

Data Access

Experimental Protocol

  • Paradigm: imagery

  • Feedback: none

  • Stimulus: visual cue (red arrow) after an auditory beep

Notes

The EDF physical-dimension fields are blank; the channels sidecars specify microvolts. The reader is given units="uV" so MNE returns SI volts without a second post-read scaling. Bad-channel flags are kept.

The paper states that “during acquisition, the EEG signals were filtered between 0.5 and 45 Hz with a 3rd order Butterworth bandpass-filter” (OpenViBE), whereas the BIDS sidecars declare no hardware/software filters; whether the released EDF files carry that online filter has not been verified on the data. The 1-40 Hz 5th-order Butterworth filter of the paper was applied offline for the published analysis only.

__init__(subjects=None, sessions=None, *, return_all_modalities=False)[source]#
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.

When the dataset declares a nemar_id and the download provider is not "upstream", the files come from NEMAR’s sourcedata/ – the original pre-BIDS distribution, byte-identical to what the upstream host serves. On any NEMAR failure this falls back to the dataset’s own downloader with a warning (unless the provider is pinned to "nemar"). See sourcedata_path() and moabb.set_download_provider().

Parameters:

  • subject_list (list of int | None) – List of subjects id to download, if None all subjects are downloaded. On the NEMAR path each subject is resolved through the deposit’s sourcedata_provenance.json; deposits enriched before that manifest recorded subjects fetch the whole tree.

  • 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. Not used on the NEMAR path.

  • accept (bool) – Accept licence term to download the data, if any. Default: False. Only relevant to the dataset’s own downloader; NEMAR mirrors are already public.

  • 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, n_jobs=1)[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.

  • n_jobs (int) – Number of jobs to run in parallel over subjects (passed to joblib.Parallel). Default 1 (sequential). Per-subject processing (reading, filtering, resampling, epoching) is independent, so this gives a near-linear speedup for datasets with many subjects.

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
sourcedata_path(subject=None, path=None, force_update=False, verbose=None)[source]#

Get the dataset’s original pre-BIDS distribution from NEMAR.

Where data_path() fetches the original files from the upstream host, this fetches the copy NEMAR mirrors under sourcedata/. The files keep their upstream names, so the two are interchangeable in content – but NEMAR stays reachable when the upstream host is slow, rate-limited, behind a bot gate, or retired.

Parameters:

  • subject (int | str | None) – Restrict the download to one subject, resolved through the deposit’s sourcedata_provenance.json. Deposits enriched before that manifest recorded subjects fall back to the whole tree with a warning. When None the whole tree is fetched.

  • path (None | str) – Base path where MOABB stores datasets.

  • force_update (bool) – Re-fetch even when a local copy is present.

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

Returns:

Local path to the sourcedata directory.

Return type:

str

Raises:

  • ValueError – If the dataset declares no nemar_id.

  • moabb.datasets.download.NemarDownloadError – If the download fails or the deposit publishes no sourcedata/.