This repository contains an exemplary pipeline for processing MEG/EEG data using MNE-Python and the Brain Imaging Data Structure (BIDS).
The study template expects input data to adhere to BIDS. You can check whether your data complies with the BIDS standard using the BIDS validator.
First, you need to make sure you have MNE-Python installed and working on your system. See the installation instructions. Once this is done, you should be able to run this in a terminal:
$ python -c "import mne; mne.sys_info()"
You can then install the following additional packages via pip. Note that
the URL points to the bleeding edge version of mne_bids:
$ pip install https://github.com/mne-tools/mne-bids/zipball/master
You can run the template on the mne sample subject, which you need to convert to BIDS as described here.
Another option is to fetch the data, see the section on Contributing.
Generally, there is a single config.py file, which contains all parameters
for the analysis of the data. Many parameters are automatically inferred from
the BIDS structure of the data.
All other scripts should not be edited.
To ease interaction with the study template, there is a Makefile. Simply
type make from the root of your study template to see a summary of what
you can do, or inspect the file directly.
For Windows users, it might be necessary to install GNU make.
-
Make sure your data is formatted according to the BIDS standard. It is of great importance that
-
the BIDS data are anonymized if you require anonymization, as the
mne-study-templatedoes not allow you to anonymize data.This was a conscious design decision, not a technical limitation per se. If you think this decision should be reconsidered, please get in touch with the developers.
-
faulty channels are marked as "bad" in the BIDS dataset. While we do run automated bad channel detection in the
mne-study-template, it is considered good practice to flag obviously problematic channels as such in the BIDS dataset. In the future, we will offer a way to alter the relevant entries in the BIDS data directly from the pipeline.
-
-
Set an environment variable
BIDS_ROOTto point to your dataset. -
(optional) Set an environment variable
MNE_BIDS_STUDY_CONFIGto point to a customconfig_<dataset_name>.pyfile that you created to overwrite the standard parameters in the mainconfig.pyfile. -
Use the
Makefileto run your analyses.
The following table provides a concise summary of each step in the pipeline.
| Script | Description |
|---|---|
| config.py | The only file you need to modify in principle. This file contain all your parameters. |
| 01-import_and_maxfilter.py | Import raw data and apply Maxwell filter. |
| 02-frequency_filter.py | Apply low- and high-pass filters. |
| 03-make_epochs.py | Extract epochs. |
| 04a-run_ica.py | Run Independant Component Analysis (ICA) for artifact correction. |
| 04b-run_ssp.py | Run Signal Subspace Projections (SSP) for artifact correction. These are often also referred to as PCA vectors. |
| 05a-apply_ica.py | As an alternative to ICA, you can use SSP projections to correct for eye blink and heart artifacts. Use either 5a/6a, or 5b/6b. |
| 05b-apply_ssp.py | Apply SSP projections and obtain the cleaned epochs. |
| 06-make_evoked.py | Extract evoked data for each condition. |
| 07-group_average_sensors.py | Make a group average of the time domain data. |
| 08-sliding_estimator.py | Running a time-by-time decoder with sliding window. |
| 09-time_frequency.py | Running a time-frequency analysis. |
| 10-make_forward.py | Compute forward operators. You will need to have computed the coregistration to obtain the -trans.fif files for each subject. |
| 11-make_cov.py | Compute noise covariances for each subject. |
| 12-make_inverse.py | Compute inverse problem to obtain source estimates. |
| 13-group_average_source.py | Compute source estimates average over subjects. |
| 99-make_reports.py | Compute HTML reports for each subject. |
The original pipeline for MEG/EEG data processing with MNE python was build jointly by the Cognition and Brain Dynamics Team and the MNE Python Team, based on scripts originally developed for this publication:
M. Jas, E. Larson, D. A. Engemann, J. Leppäkangas, S. Taulu, M. Hämäläinen, A. Gramfort (2018). A reproducible MEG/EEG group study with the MNE software: recommendations, quality assessments, and good practices. Frontiers in neuroscience, 12. https://doi.org/10.3389/fnins.2018.00530
The current iteration is based on BIDS and relies on the extensions to BIDS for EEG and MEG. See the following two references:
Pernet, C. R., Appelhoff, S., Gorgolewski, K. J., Flandin, G., Phillips, C., Delorme, A., Oostenveld, R. (2019). EEG-BIDS, an extension to the brain imaging data structure for electroencephalography. Scientific Data, 6, 103. https://doi.org/10.1038/s41597-019-0104-8
Niso, G., Gorgolewski, K. J., Bock, E., Brooks, T. L., Flandin, G., Gramfort, A., Henson, R. N., Jas, M., Litvak, V., Moreau, J., Oostenveld, R., Schoffelen, J., Tadel, F., Wexler, J., Baillet, S. (2018). MEG-BIDS, the brain imaging data structure extended to magnetoencephalography. Scientific Data, 5, 180110. https://doi.org/10.1038/sdata.2018.110