Export raw files in BIDS format
Authors: Martin Cousineau, Sylvain Baillet.
Brainstorm can export raw EEG and MEG files following the standard data organization of the Brain Imaging Data Structure (BIDS).
For an example of how to import an existing BIDS dataset, refer to the following tutorial.
Note: Only EEG and MEG data files are supported for now. We will support electrophysiology BIDS exports when the specifications for those data types are finalized by the BIDS community.
How to use
- Select one or several raw files you want to export and drag them in the process box.
- Click on [Run] to open the pipeline editor window.
Select the process "File -> Export BIDS dataset".
Process options
Output folder: An empty folder where the BIDS-formatted data will be stored, or an existing BIDS-formatted folder to which the selected recordings will be appended.
Subject names: Naming convention for participant IDs (sub-XXXX)
Custom names: Choose this option to preserve Brainstorm's subject labels: non-alphanumeric characters will be removed for compliance with BIDS. For example, if you have a subject labelled in Brainstorm as Subject01, his/her BIDS-formatted ID will become sub-Subject01.
Number index: An auto-incremented 4-digit index will be automatically assigned to each subject based on their alphabetical order of their original Brainstorm ID. For example, Subject01 will become sub-0001. If the output folder is already an existing BIDS-formatted folder, BIDS ID numbering will resume incrementing from the last subject ID found in the existing BIDS folder (no overwriting).
Session names: Naming convention used for sessions (ses-XXXX)
Acquisition date: The acquisition date extracted from the raw file metadata, or the date the data was imported in Brainstorm if the latter fails (e.g., ses-20181023). This is the default behavior for the emptyroom "subject", regardless of the value of this option.
Number index: An auto-incremented 4-digit index number will be automatically assigned to each session of a subject, ordered by acquisition date. For example, if Subject01 has two sessions recorded at 10AM and 2PM on the same day, the 10AM session will be labelled ses-0001 and the 2PM session will be labelled ses-0002. If the output folder is an existing BIDS-formatted folder with previous sessions of the same subject already present, the numbering will resume incrementally from the last session ID.
Keywords to detect empty-room recordings: In order to properly register empty-room recordings with the special BIDS empty-room subject, the process looks for specificied comma-separated keywords in the condition name (raw folder). If you don't need to feature an empty-room subject, leave this field blank.
Overwrite existing files: If the output folder is an existing BIDS-formatted folder, this option specifies whether to overwrite existing raw files in that folder or not. If not checked, the process will skip (not overwrite) existing files, including the sidecar JSON and README files.
Sidecar required fields
The BIDS specification has required fields in both the general dataset description JSON file and the specific data sidecar JSON files. Using the raw files metadata, Brainstorm detects and specifies most of these required fields. However, some of these fields fields cannot be extracted automatically and therefore need to be specified by the user:
Power-line frequency: The frequency of the power line at the acquisition site (e.g., 50 Hz in Europe, 60 Hz in North America).
MEG: Position of the dewar during the scan: "upright", "supine" or "degrees" of angle from vertical: for example on CTF systems, upright=15°, supine = 90°.
EEG: Electrode reference used: Description of the type of reference used and (when applicable) of location of the reference electrode (ex.: "common reference placed at the left mastoid (M1)", "average", "CMS/DRL", "bipolar").
Additional metadata
Additional metadata can be entered in order to generate a README.txt file describing your dataset, as well as adding custom fields in the BIDS JSON sidecar files. Click the Edit... button to open up a new window with additional fields.
Project Name: Name of your project specified in the README.txt. If left blank, the name of your Brainstorm protocol will be used.
Project ID: ID of your project specified in the README.txt. If left blank, the name of your Brainstorm protocol will be used.
Project Description: Freeform description of your project, experiment, study, design, etc.
Participant Categories: A freeform description of the participant categories invoved (e.g., 1. Healthy controls, 2. Epileptic patients, etc.).
The two following options need to be formatted in JSON. Please refer to the examples shown in the screenshot. To add more fields, add a comma at the end of the "field": "value" lines. You may leave these blank if you do not want to provide additional optional fields.
Additional dataset description JSON fields: Any additional JSON fields you would like to add to the dataset_description.json file at the root of your BIDS directory.
Additional sidecar JSON fields: Any additional JSON fields you would like to add to the <sub-0001_ses-0001_task-taskName>_<meg/eeg>.json files that accompany your data files.
Additional documentation
Website
BIDS official website: http://bids.neuroimaging.io/
JSON format description: https://en.wikipedia.org/wiki/JSON
Articles
BIDS: Gorgolewski, K.J., Auer, T., Calhoun, V.D., Craddock, R.C., Das, S., Duff, E.P., Flandin, G., Ghosh, S.S., Glatard, T., Halchenko, Y.O. and Handwerker, D.A. (2016)
The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments, Scientific Data, 3, p.160044.MEG-BIDS: Niso G, Flandin G, Gramfort, A Henson, RN, Jas M, Litvak V, Moreau JT, Oostenveld R, SchoffelenJ-M, Tadel F, Wexler J, Baillet S (2018), MEG-BIDS, the brain imaging data structure extended to magnetoencephalography, Scientific Data, 5: 180110 EP
EEG-BIDS: Pernet CR, Appelhoff S, Flandin G, Phillips C, Delorme A, Oostenveld R (2018), BIDS-EEG: an extension to the Brain Imaging Data Structure (BIDS) Specification for electroencephalography, PsyArXiv doi:10.31234/osf.io/63a4y