View on GitHub

A BIDS cookbook !

A simple recipe to convert your neuroimaging data into a BIDS dataset.

DOI License: CC BY 4.0

Preparing a BIDS dataset by hand and from scratch

⚠️ Note that this is purely for learning purposes and it is NOT recommended to BIDSify real datasets by hand . ⚠️

Table of content

CLICK ME
... to see what I hide !!!


Ingredients and tools

Get them fresh from your local market:

🧠 some source data to be converted into BIDS

We will work with the multi-modal face dataset from SPM .

Very often MRI source data will be in a DICOM format and will require to be converted. Here the MRI data is in "3D" Nifti format .hdr/.img and we will need to change that to a "4D" Nifti .nii format.

This dataset contains EEG, MEG and fMRI data on the same subject within the same paradigm. We also extracted some of the information about the data from the SPM manual and put it into the source/README.md.

Similarly when you have DICOM data, it is usually a good idea to keep the PDF of MRI acquisition parameters with your source data.

🖋 a text editor
Several common options top choose from:
♻ some format conversion tools

For the MRI data we will be using some of the SPM built-in functions to convert Nifti files into the proper format.

📥 [OPTIONAL] BIDS validator
  • Install Node.js (at least version 12.12.0).
  • Update npm to be at least version 7 (npm install --global npm@^7)
  • From a terminal run npm install -g bids-validator
  • Run bids-validator to start validating datasets.
See the full instruction here.
[OPTIONAL] Datalad to version control your data

You can follow the installation instruction in the Datalad handbook.

🐳 [OPTIONAL] Docker

Check the install instruction for your system here.


Recipe

1. Preheat the oven: creating folders

By now you should have this. 
  ├── code
  │   └── conversion
  ├── sourcedata
  │   ├── multimodal_fmri
  │   │   └── fMRI
  │   │       ├── Session1
  │   │       └── Session2
  │   └── multimodal_smri
  │       └── sMRI
  └── sub-01
      └── ses-mri
          ├── anat
          └── func


2. Starters: converting the anatomical MRI file

a. Cooking is not just about the taste, it is also about how things look: naming files

✅ Valid BIDS filenames
  • BIDS filenames are composed of:
    • extension
    • suffix preceded by a _
    • entity-label pairs separated by a _
  • So a BIDS filename can look like: entity1-label1_entity2-label2_suffix.extension
  • entities and labels can only contain letters and / or numbers.
  • For a given suffix, some entities are required and some others are [optional].
  • entity-label pairs pairs have a specific order in which they must appear in filename.

In case you do not remember which suffix to use and which entities are required or optional, the BIDS specification has:

b. Taste your dish while you prepare it: using the BIDS validator

Try it directly in your browser.

c. Season to taste: adding missing files

You can get content for those files from:

Suggestion:

Add the “table” output of the BIDS validator to your README to give a quick overview of the content of your dataset.

🚨 About JSON files
JSON files are text files to store key-value pairs. If your editor cannot help you format them properly, you can always use the online editor.

More information on how read and write JSON files is available on the BIDS stater kit. 

JSON CONTENT EXAMPLE:

{
  "key": "value",
  "key2": "value2",
  "key3": {
    "subkey1": "subvalue1"
  },
  "array": [ 1, 2, 3 ],
  "boolean": true,
  "color": "gold",
  "null": null,
  "number": 123,
  "object": {
    "a": "b",
    "c": "d"
  },
  "string": "Hello World"
}

d. Icing on the cake: adding extra information

🚨 About TSV files
A Tab-Separate Values (TSV) file is a text file where tab characters (\t) separate fields that are in the file. It is structured as a table, with each column representing a field of interest, and each row representing a single data point.

More information on how read and write TSV files is available on the BIDS stater kit 

TSV CONTENT EXAMPLE:

participant_id\tage\tgender\n
sub-01\t34\tM
By now you should have this. 
  ├── code
  ├── sourcedata
  ├── sub-01
  │   └── ses-mri
  │       ├── anat
│ │       │   ├── sub-01_ses-mri_T1w.json
│ │       │   └── sub-01_ses-mri_T1w.nii
  │       └── func
  ├── README
  ├── participants.tsv
  ├── participants.json
  └── dataset_description.json

e. BIDS is data jam: let’s preserve some

[OPTIONAL]

datalad create --force -c text2git .
datalad save -m 'initial commit'


3. Main course: converting the functional MRI files

By now you should have this. 
  ├── code
  ├── sourcedata
  ├── sub-01
  │   └── ses-mri
  │       ├── anat
│ │       │   └── sub-01_ses-mri_T1w.nii
  │       └── func
  │           ├── sub-01_ses-mri_task-FaceSymmetry_run-1_bold.nii
  │           ├── sub-01_ses-mri_task-FaceSymmetry_run-1_events.tsv
  │           ├── sub-01_ses-mri_task-FaceSymmetry_run-2_bold.nii
  │           └── sub-01_ses-mri_task-FaceSymmetry_run-2_events.tsv
  ├── README
  ├── participants.tsv
  ├── participants.json
  ├── T1w.json
  ├── task-FaceSymmetry_bold.json
  └── dataset_description.json


4. Dessert: defacing, quality control, upload your data to GIN...

Defacing

MRIQC

# from within the `raw` folder

bids_dir=`pwd`

output_dir=${bids_dir}/../derivatives/mriqc

docker run -it --rm \
  -v ${bids_dir}:/data:ro \
  -v ${output_dir}:/out \
  poldracklab/mriqc:0.16.1 /data /out \
  --participant_label sub-01 \
  --verbose-reports \
  participant

uploading your data on GIN

Things to improve ?