Skip to content

BIDS

Author: S. Herbst ksherbst@gmail.com

Clarification of terms: BIDS vs. mne-bids-pipeline

BIDS: the Brain Imaging Data Structure, is a standard that describes how to organize neuroimaging and electrophysiological data (See definitions and datatypes here: [https://bids-specification.readthedocs.io/en/stable/]{.underline}). It defines:

  • which file formats to use

  • how to name your files

  • where to place your files within a directory structure

  • what additional information to store (events, bad channels, MRI coordinates, metadata..)

In order to read and write BIDS-formatted data in MNE, use the mne-bids package: [https://mne.tools/mne-bids/stable/index.html]{.underline}

For an example, see the [jupyter notebook]{.underline} by Jacques Pesnot-Lerousseau in the same folder as this document.

! You can transform a dataset to BIDS at any time (from directly after recording to after acceptance for publication; you can also add information, e.g. coregistration)

The MNE-BIDS-Pipeline is a full-fledged processing pipeline for your MEG and EEG data. It is a further development of the [MNE Study Template]{.underline} and the [pipeline developed in collaboration with our team]{.underline}. It runs from raw data to sensor averages and source space, and can do decoding using MNE Python.

  • Prerequisite: your data need to be formatted in BIDS

  • [Steps:]{.underline} Preprocessing / Sensor / Source (including Freesurfer)

  • Usage: From the command line

  • The user only edits a custom [config.py]{.underline}

  • Interactive mode is possible for data checking

  • HTML reports are created for data checking

  • Custom code can be used to perform analyses or visualization based on the output of the pipeline{width="5.135553368328959in" height="2.2100021872265967in"}

Pros and cons + recommendations

Should I use BIDS?

Pros Cons
Standardized & universal
- no need to think about your file names / folder structure
- human & machine readable without further intervention/ documentation

Highly recommended or even mandatory format when publicly sharing data (after publication)

A BIDS dataset can easily be anonymized (one command)		 BIDS is well advanced for raw data, but not for preprocessed data ('derivatives')

The transformation to BIDS requires some knowledge about the data and extra time

The standard is still evolving, sometimes amendments of the standard are necessary to accommodate a use case

Recommendation:

If you have little or no experience with M/EEG data: start without BIDS and transform your data to BIDS later if you need to share it.

If you have processed some datasets (participants) before, convert to BIDS right after recording. In that case, come information can be added during processing, e.g. coregistration.

If you are working on a collaborative project and/or know that you will share the data, it might still be better to convert to BIDS from the start

Should I use the mne-bids-pipeline?

Pros cons
All basic steps implemented:
- preprocessing (filter, ICA, .. )
- sensor space analyses: decoding in time and time-frequency, temporal generalization
- complete source pipeline

Flexible options and verified defaults

Code and outcomes checked by expert programmers and tested on examples

No need to write code apart from editing config.py

Interactive checking of data quality made easy by html reports		 Cannot yet accommodate all use cases such as complex multi-session designs (evolving)

Harder to understand what is going on 'under the hood' (code not directly visible, requires good python knowledge to find it), the automatic caching can be confusing

If you need to update your install version, the pipeline automatically runs all steps again → takes time

Still relatively young and evolving a lot (release 1.6. -> 1.9. in the last 4 weeks)

Standardized output: big subject folders

Recommendation:

If you are a newbie, write your own code to understand what is going on, take examples from 'the old pipeline'

If you are python proficient and processed several M/EEG datasets before you might prefer the mne-bids-pipeline

If you have to process a large dataset in a more automated way (maybe 50pp or more) the pipeline is a good option

⚠️ If you use the mne-bids-pipeline, do not rely on the defaults, they might not be appropriate for your research question. Carefully construct your config.py by trying things out and use the interactive plotting and html reports to check results!

If you decide to use the MNE-BIDS pipeline, please note that you have to perform this step

Updating MRI Landmarks in BIDS After Manual Coregistration

When is this needed?

After performing a manual coregistration in the MNE-Python GUI, the anatomical landmarks (nasion, LPA, RPA) must be updated in the BIDS dataset to ensure consistency between the MRI and MEG coordinate frames. This is because according to the BIDS standard, the coordinates are stored with the anatomical brain image, and not as a transformation file.

How to do it

Do your coregistration with the gui and save the transformation file to the participant's derivatives/meg folder when prompted.

Next, retrieve the updated landmarks from the MRI image using mne_bids.get_anat_landmarks. Then, overwrite the old ones in your BIDS dataset with mne_bids.update_anat_landmarks.

Example: update anatomical landmarks after manual coregistration 

from mne_bids import get_anat_landmarks, update_anat_landmarks

# Read the transformation file you created using the gui:
trans_path = ‘bids_root/derivatives/subject/meg/manual_coreg-trans.fif’
trans = mne.read_trans(trans_path)

# Extract the updated MRI landmarks
mri_landmarks = get_anat_landmarks(bids_path_t1, trans=trans, fs_subjects_dir)

# Update the landmarks in the BIDS dataset
update_anat_landmarks(
    bids_path=bids_path_t1,
    landmarks=mri_landmarks
)

This ensures that your BIDS dataset reflects the correct MRI--MEG alignment after manual adjustment.