Preparing a BIDS dataset by hand and from scratch

Adapted from the BIDS cookbook.

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

Table of content

• Ingredients
• Recipe
  • Preheat the oven: folder structure
  • Starters: anatomical data
  • Main course: functional data
• Useful links

CLICK ME

... to see what I hide !!!

Ingredients and tools

Get them fresh from your local market:

• MRI scanner 🧲
• EEG amplifier 🌩
• MEG squid 🦑
• …

🧠 some source data to be converted into BIDS

For this workshop you can choose to work with several datasets that are adapted from some of the SPM12 tutorials. You can download them from OSF by using one of the following links:

• face repetition event-related design dataset
• auditory block design dataset
• multimodal face dataset

In the example below I will work with the multimodal face dataset.

Very often MRI source data will be in a DICOM format and will require to be converted to nifti. here the MRI data is already in "4D" Nifti format .nii format. It is also gziped (.nii.gz) to save space.

The dataset contains both structural data: should start with the letter s and functional data: should start with the letter f. It should also contain excel files that contain when each stimulus was presented to the subject.

This dataset originally contains EEG, MEG and fMRI data on the same subject within the same paradigm. Here we are only working with the MRI data. We also extracted some of the information about the data from the SPM manual and put it into the README.

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

A good choice is to use Visual Studio code (Notepad does not really count).

📥 [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.

Recipe

1. Preheat the oven: creating folders

• Create a raw folder to host your BIDS data and inside it create:

  • a sourcedata folder and put your source data in it
  • a subject folder: sub-01
    • with session folder: ses-mri
      • with an anat folder for the structural MRI data
      • with an func folder for the functional MRI data

By now you should have this.

  ├── sourcedata
  └── sub-01
      └── ses-mri
          ├── anat
          └── func
  

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

• Move the .nii.gz file you have just created into sub-01/ses-mri/anat.
• Give this file a valid BIDS filename.

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

• filename templates at the beginning of the section for each imaging modality,
• a summary entity table.

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

• README
• dataset_description.json

You can get template content for those files from:

• from the BIDS specification (use the search bar)
• the BIDS starter templates

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.

More information on how read and write JSON files is available on the BIDS stater kit and also on the bids stats model website.

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

• Add a T1w.json file. Use information from README to create it.
• Add a participants participants.tsv. You can use excel or google sheet to create them.

🚨 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.

  ├── 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
  

3. Main course: converting the functional MRI files

• Give the output files valid BIDS filenames. You will need to use task and the run entities.
• Use the BIDS validator and any eventual missing file (like *_bold.json file).
• Using the excel files, create events.tsv for each run.
• Put the events.tsv files in the func folders and give them BIDS valid names.
• Remove duplicate json files to make use of the “inheritance principle”

By now you should have this.

  ├── 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
  

Useful links

• BIDS specification
• BIDS starter kit
  • templates
  • wiki
    • validator
• BIDS validator
• BIDS examples

---