Convert a MOABB dataset to BIDS

The Brain Imaging Data Structure (BIDS) format is standard for storing neuroimaging data. It follows fixed principles to facilitate the sharing of neuroimaging data between researchers.

The MOABB library allows to convert any MOABB dataset to BIDS [1] and [2].

In this example, we will convert the AlexMI dataset to BIDS using the convert_to_bids method from the dataset object.

This will automatically save the raw data in the BIDS format.

We will use the AlexMI dataset [3], one of the smallest in people and one that can be downloaded quickly.

# Authors: Pierre Guetschel <pierre.guetschel@gmail.com>
#
# License: BSD (3-clause)

import shutil
import tempfile
from pathlib import Path

import mne

from moabb import set_log_level
from moabb.datasets import AlexMI


set_log_level("info")

/home/runner/work/moabb/moabb/.venv/lib/python3.10/site-packages/optuna/integration/sklearn.py:14: FutureWarning: `optuna.integration.sklearn` has been deprecated in v4.9.0. This feature will be removed in v6.0.0. See https://github.com/optuna/optuna/releases/tag/v4.9.0. Use `optuna_integration.sklearn` instead.
  optuna_warn(f"{msg} Use `optuna_integration.sklearn` instead.", FutureWarning)

Basic usage

Here, we will save the BIDS version of the dataset in a temporary folder

temp_dir = Path(tempfile.mkdtemp())
# The conversion of any MOABB dataset to a BIDS-compliant structure can be done
# by simply calling its ``convert_to_bids`` method.
dataset = AlexMI()
# Reducing the number of subjects to speed up the example
subjects = dataset.subject_list[:1]
bids_root = dataset.convert_to_bids(path=temp_dir, subjects=subjects)

2026-06-29 12:11:11,588 INFO MainThread moabb.datasets.bids_interface Starting caching _BIDSInterfaceRawEDFNoDesc(dataset=AlexandreMotorImagery, subject=1, path=PosixPath('/tmp/tmpn9gpfpw7'), process_pipeline=None, verbose=None, _dataset_type='raw', _format='EDF')
2026-06-29 12:11:11,772 INFO MainThread moabb.datasets.bids_interface Finished caching _BIDSInterfaceRawEDFNoDesc(dataset=AlexandreMotorImagery, subject=1, path=PosixPath('/tmp/tmpn9gpfpw7'), process_pipeline=None, verbose=None, _dataset_type='raw', _format='EDF') to disk.

Before / after folder structure

To investigate what was saved, we will first define a function to print the folder structure of a given path:

def print_tree(p: Path, last=True, header=""):
    elbow = "└──"
    pipe = "│  "
    tee = "├──"
    blank = "   "
    print(header + (elbow if last else tee) + p.name)
    if p.is_dir():
        children = list(p.iterdir())
        for i, c in enumerate(children):
            print_tree(
                c, header=header + (blank if last else pipe), last=i == len(children) - 1
            )

Now, we will retrieve the location of the original dataset. It is stored in the MNE data directory, which can be found with the "MNE_DATA" key:

mne_data = Path(mne.get_config("MNE_DATA"))
print(f"MNE data directory: {mne_data}")

MNE data directory: /home/runner/work/moabb/moabb/mne_data

Now, we can print the folder structure of the original dataset:

print("Before conversion:")
print_tree(mne_data / "MNE-alexeeg-data")

Before conversion:
└──MNE-alexeeg-data
   └──zenodo
      └──806023
         └──subject1.raw.fif

As we can see, before conversion, all the data (i.e. from all subjects, sessions and runs) is stored in a single folder. This follows no particular standard and can vary from one dataset to another.

After conversion, the data is stored in a BIDS-compliant way:

print("After conversion:")
print_tree(bids_root)

After conversion:
└──MNE-BIDS-alexandre-motor-imagery
   ├──participants.json
   ├──participants.tsv
   ├──sub-1
   │  └──ses-0
   │     ├──eeg
   │     │  ├──sub-1_ses-0_task-imagery_run-0_channels.tsv
   │     │  ├──sub-1_ses-0_task-imagery_run-0_events.json
   │     │  ├──sub-1_ses-0_task-imagery_run-0_eeg.json
   │     │  ├──sub-1_ses-0_task-imagery_run-0_channels.json
   │     │  ├──sub-1_ses-0_task-imagery_run-0_eeg.edf
   │     │  └──sub-1_ses-0_task-imagery_run-0_events.tsv
   │     ├──sub-1_ses-0_scans.json
   │     └──sub-1_ses-0_scans.tsv
   ├──README
   ├──dataset_description.json
   ├──.bidsignore
   └──code
      └──AlexMI.metadata.yaml

In the BIDS version of our dataset, the raw files are saved in EDF. The data is organized in a hierarchy of folders, starting with the subjects, then the sessions, and then the runs. Metadata files are stored to describe the data. For more details on the BIDS structure, please refer to the BIDS website and the BIDS spec.

Only raw EEG files are officially supported by the BIDS specification.

Cleanup

Finally, we can delete the temporary folder:

shutil.rmtree(temp_dir)

References

[1]

Pernet, C.R., Appelhoff, S., Gorgolewski, K.J. et al. EEG-BIDS, An extension to the brain imaging data structure for electroencephalography. Sci Data 6, 103 (2019). https://doi.org/10.1038/s41597-019-0104-8

[2]

Appelhoff et al., (2019). MNE-BIDS: Organizing electrophysiological data into the BIDS format and facilitating their analysis. Journal of Open Source Software, 4(44), 1896, https://doi.org/10.21105/joss.01896

[3]

Barachant, A., 2012. Commande robuste d’un effecteur par une interface cerveau machine EEG asynchrone (Doctoral dissertation, Université de Grenoble). https://tel.archives-ouvertes.fr/tel-01196752