= Export raw files in BIDS format =
''Author: Martin Cousineau, with minor edits by Sylvain Baillet.''

Brainstorm can export raw files following the standard organization of the [[http://bids.neuroimaging.io/|Brain Imaging Data Structure (BIDS)]].

'''Note:''' Only MEG data files (CTF and FIF) are supported for now. We will support EEG and e-phys BIDS exports when the specifications for those data types are finalized by the BIDS community.

<<TableOfContents(2,2)>>

== How to use ==
 * Select one or several raw files you would like to export and drag them in the process box.
 * Click on [Run] to open the pipeline editor window.
 * Select the process "'''File -> Export MEG-BIDS dataset'''".

{{attachment:meg_bids_process.png}}

== Process options ==
 * '''Output folder''': An empty folder where BIDS data will stored, or an existing BIDS-formatted folder where the selected recordings will be appended.
 * '''Subject names''': The naming convention for subjects (sub-XXXX)
  * __Custom names__: Choose this option to preserve Brainstorm's subject labels: non-alphanumeric characters will removed for compliance with MEG-BIDS. For example, if you have a subject label in Brainstorm as Subject01, the BIDS-formatted name for this subject will become sub-Subject01.
  * __Number index__: An auto-incremented 4 digit index number will be automatically assigned to each subject based on their alphabetical order. For example, Subject01 will become sub-0001. If the output folder is already an existing BIDS-formatted folder, numbering will start after the last subject ID found in the existing BIDS folder (no overwriting).
 * '''Session names''': The 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 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 start after the last session ID.
 * '''Keywords to detect empty-room recordings''': In order to properly register empty-room recordings with the special empty-room subject, the process will look for specificied comma-separated keywords in the condition name (raw folder). If you don't need to feature an empty-room subject, please leave this blank.
 * '''Overwrite existing files''': If the output folder is an existing BIDS-formatted folder, this option specifies whether to overwrite existing raw files or not. If not checked, the process will skip (not overwrite) existing files.

=== MEG sidecar required fields ===
The BIDS specification has required fields in both the general dataset description JSON file and the specific MEG sidecar JSON files. Using the raw files metadata, Brainstorm detects and specifies most of these required fields. However, two fields cannot be detected automatically and need to be specified by the user via these process options:

 * '''Power line frequency''': The frequency of the power line at the acquisition site (e.g., 50 Hz in Europe, 60 Hz in North America).
 * '''Position of the dewar during the MEG scan''': "upright", "supine" or "degrees" of angle from vertical: for example on CTF systems, upright=15°, supine = 90°.

=== MEG sidecar optional fields ===
The two following options need to be formatted in [[https://en.wikipedia.org/wiki/JSON|JSON]], see the examples below. 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 MEG sidecar JSON fields''': Any additional JSON fields you would like to add to the <sub-0001_ses-0001_task-taskName>_meg.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 '''

 * 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)<<BR>>[[https://www.nature.com/articles/sdata201644|The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments]], Scientific Data, 3, p.160044.
 * 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), [[https://dx.doi.org/10.1038/sdata.2018.110|MEG-BIDS, the brain imaging data structure extended to magnetoencephalography]], 5: 180110 EP