moabb.datasets.Iwama2023#

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

Bases: OpenNeuroMirrorMixin, BaseBIDSDataset

[source]

Dataset Snapshot

Iwama2023

Imagery, 2 classes (right_hand vs rest)

AuthorsSeitaro Iwama, Masumi Morishige, Midori Kodama, Yoshikazu Takahashi, Ryotaro Hirose, Junichi Ushiba

🇯🇵 Keio University, JP·2023
Imagery Code: Iwama2023 30 subjects 16 sessions 129 ch 1000 Hz 2 classes 21.0 s trials

Class Labels: right_hand, rest

Read Paper Compare Similar Report Issue

Overview

High-density (128ch) SMR-BMI motor imagery dataset, Dataset 1

Dataset 1 of the BMI-HDEEG collection: 30 healthy right-handed participants (25 males, 5 females), 128-channel EGI HydroCel net at 1000 Hz (the EDF carries 129 EEG channels, the extra one being the Cz reference; CPz was the ground). Each trial of the SMR neurofeedback task is rest (6 s, value = 1), ready (1 s), task (6 s kinesthetic right-hand motor imagery with ERD feedback, value = 3) and interval (8 s). MOABB exposes right_hand vs rest; each session (ses-01 .. ses-16, fewer for some subjects) has 20 trials. The paper describes, per day, a pre-evaluation block, 6 neurofeedback blocks and a post-evaluation block over two consecutive days (16 blocks, stored one EDF per block).

Open in Overview tab →

Citation & Impact

Stimulus Protocol
../_images/Iwama2023.svg

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

HED Event Tags
HED tags2/2 events annotated

Source: MOABB BIDS HED annotation mapping.

Sensory-event
2
Agent-action
1
Experimental-stimulus
1
Rest
1
Visual-presentation
1
right_hand
Sensory-eventAgent-action
rest
Sensory-eventExperimental-stimulusVisual-presentationRest

HED tree view

Tree · right_hand
├─ Sensory-event
│  ├─ Experimental-stimulus
│  └─ Visual-presentation
└─ Agent-action
   └─ Imagine
      ├─ Move
      └─ Right
         └─ Hand
Tree · rest
├─ Sensory-event
├─ Experimental-stimulus
├─ Visual-presentation
└─ Rest
Channel Summary
Total channels129
EEG129
MontageGSN-HydroCel-129
Sampling1000 Hz
ReferenceCz
Filter{'highpass': 0.1, 'lowpass': 100, 'notch': 50}
Notch / line50 Hz

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

High-density (128ch) SMR-BMI motor imagery dataset, Dataset 1 [1].

Dataset 1 of the BMI-HDEEG collection: 30 healthy right-handed participants (25 males, 5 females), 128-channel EGI HydroCel net at 1000 Hz (the EDF carries 129 EEG channels, the extra one being the Cz reference; CPz was the ground). Each trial of the SMR neurofeedback task is rest (6 s, value = 1), ready (1 s), task (6 s kinesthetic right-hand motor imagery with ERD feedback, value = 3) and interval (8 s). MOABB exposes right_hand vs rest; each session (ses-01 .. ses-16, fewer for some subjects) has 20 trials. The paper describes, per day, a pre-evaluation block, 6 neurofeedback blocks and a post-evaluation block over two consecutive days (16 blocks, stored one EDF per block).

Note

The BIDS events.tsv onsets are in milliseconds; this loader rescales them to seconds. The EDF’s own Status trigger channel is dropped because its codes do not follow events.tsv.

References

[1]

Iwama, S., Morishige, M., Kodama, M., Takahashi, Y., Hirose, R., & Ushiba, J. (2023). High-density scalp electroencephalogram dataset during sensorimotor rhythm-based brain-computer interfacing. Scientific Data, 10, 385. https://doi.org/10.1038/s41597-023-02260-6

from moabb.datasets import Iwama2023
dataset = Iwama2023()
data = dataset.get_data(subjects=[1])
print(data[1])

Dataset summary

#Subj

30

#Chan

129

#Classes

2

#Trials / class

320

Trials length

6 s

Freq

1000 Hz

#Sessions

16

#Runs

1

Total_trials

19200

Participants

  • Population: healthy

  • Age: 21.23 (range: 18-27) years

  • Handedness: right-handed

Equipment

  • Amplifier: Magstim EGI GES400

  • Montage: GSN-HydroCel-129

  • Reference: Cz

Data Access

Experimental Protocol

  • Paradigm: imagery

  • Feedback: visual ERD neurofeedback

  • Stimulus: visual instruction

__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/.