BIDS Tutorial Series: Introductory Walkthrough

February 22, 2018

Introduction

Welcome to part 1A of the tutorial series “Getting Started with BIDS”. The tutorial series will introduce you to converting brain data into the BIDS organizational standard, provide an example of how to convert a dataset into BIDS (manually and an automated solution), and examine different off-the-shelf automated solutions. This tutorial will show a detailed step-by-step organizational guide to convert DICOMs into a BIDS validated dataset. The step-by-step guide will iteratively add one modality at a time until the full dataset is organized and validated. Even though performing the conversation manually is not expected we show it here for educational purposes. An automated solution is strongly recommended. An automated custom solution is discussed in the next part of the tutorial series. Throughout the tutorial series, we will be using DICOMs from the Nathan Kline Institute (NKI) Rockland Sample – Multiband Imaging Test-Retest Pilot Dataset. We will be following the specifications described in the BIDS Specification version 1.0.2. The next parts of this tutorial series will examine an automated custom solution and off-the-shelf solutions to consider using to convert your dataset into the BIDS standard.

Table of Contents
A. Manual conversation

  1. Download data
  2. Folder creation
  3. Dataset_description file
  4. Download MRIcroGL
  5. Create anatomical folders and convert dicoms
  6. Rename anatomical files
  7. Organize anatomical files and validate
  8. Create diffusion folders and convert dicoms
  9. Rename diffusion files
  10. Organize diffusion files and validate
  11. Create functional folders and convert dicoms
  12. Rename and organize functional files
  13. Task event tsv files
  14. Fix errors
  15. Add participant and check warnings

 

1A. Manual conversation of DICOM images to BIDS

Step 1. To begin, please navigate to the NKI-RS Multiband Imaging Test-Retest Pilot Dataset and scroll down to the bottom of the page to download the DICOM images for participants 2475376 and 3893245.

NKI_website_startingpoint

NKI dicom download-ARROW

NKI Download 2 sample subjects

Step 2. Once the DICOMs are downloaded, please create a folder with what the dataset is called and create a Dicom directory within this. In this case, our dataset is called BIDS_NKI_walkthrough. Then put the participant folders containing the DICOMs into that folder. The folder structure can be seen below.

Man Dicom createMan Dicom with both subjs

Now, create a Nifti folder at the same level as the Dicom folder, pictured below.

Man create Nifti folder

Step 3. Then we need to create the dataset_description.json file. There is an online json editor that can help create this file. Once the json file is written, one can save -> save to disk. Then move this file to within the Nifti folder. The dataset_description.json file only needs to be made once. At this time, it is optional to add a participant file, README, or CHANGES. Learn more about json files

json online editor with completed dataset json

Man datasetdescrip in Nifti

Step 4. Now, please download MRIcroGL. This will allow one to convert the dicom files to nifti and the sidecar json files through a GUI.  

nitrc dl MRIcroGL

At this step, we will be breaking down the process of building the validated BIDS dataset by taking participant 2475376 and iteratively adding a modality once the previous modality has been validated. This means we will first go through the process of validating this dataset using 1 participant with anatomical scans. Next adding in the diffusion scans. Lastly adding in the functional scans.

Step 5. Before converting the anatomical scans, we will be creating the folder structure in the Nifti directory. To do this, we create a sub-2475376 folder. Within that a ses-1 folder and in that an anat folder. This can be visualized below.

Man sub structure

To begin conversation, we will take participant 2475376’s anat folder.

sub247_justanat

To open the converter dcm2nii, please go to the MRIcroGL folder from the download above, click MRIcro, and click Import -> Convert DICOM to NIfTI. Dcm2nii GUI should appear.

contents of dcm2niix-ARROW

import dcm2nii

dcm2nii

Listed below is the default and different options for choosing the Output name. We used the default for this conversation.dcm2nii naming optionsAn example of the of the output filename is shown in the GUI on the first line. In the picture above the example output filename is: ‘/myfolder_MPRAGE.nii’.

The output folder will be the Nifti folder.  For input please select the participant directory. One may have to try this process a few times to find the best output name to work with. It is recommended that [participant number]_[protocol] be the output of dcm2nii. The output of performing the dcm2nii conversation are nii and json files. The nii file is the brain image and the sidecar json file stores the metadata to describe the nii file. dataset_descrip

Step 6. Now we are ready to rename the nifti and json file names. The template for naming anatomical images. The not bracketed elements are required and the bracketed elements are optional. (i.e. modality label is required, acq is optional). Note that the nifti and json file have the same filename, the crop does not have a json file because the json file describes this nifii image as well.

Man Anat rename

Step 7. We are ready to organize the nii and json files into the appropriate folder. In this case, the three files we renamed will be placed in the ses-1/anat folder. One can try to validate the dataset.

anat organized

Man Anat upload

 

 

 

 

 

 

 

 

Bids valid datasetStep 8. We will now be adding in the diffusion scans. The diffusion scans can be found in session 1 and 2 folders marked DTI_mx_137 within the originally downloaded subject folder. We will now take the two diffusion folders, move them into our Dicom folder, and convert the images. For conversation, input the session folder and output the Nifti folder. One will run the converter twice, once for each session folder. This will output the nii, json, bval, and bvec files. In addition, please create a ses-2 folder within the subject folder in the Nifti folder and add a dwi folder to each session.

raw diff in Dicom

converted diff dwi folder

Step 9. We are ready to rename the diffusion scans. In this case, there are two diffusion scans, one for each session. Pictured below is the renaming of each session to the BIDS filenames for the nii, json, bval, and bvec. Notice that within the same session number, all the files have the same filename.

Diff namechange arrow

Step 10. Now we can organize the diffusion scans into their appropriate session folder and try validating this dataset.

diff organized

Man dwi upload

Bids valid datasetStep 11. We are ready to add in the functional scans to the Dicom directory. This will be the rest of the folders in the originally downloaded subject. The folders are: TfMRI_breathHold_1400, TfMRI_eyeMovementCalibration_645, TfMRI_eyeMovementCalibration_1400, TfMRI_visualCheckerboard_645, TfMRI_visualCheckerboard_1400, and the three RfMRI folders within the session1 and session2 folders.

func in Dicom

Please convert the functional Dicom folders into the Nifti folder. This will output the nii and json files. In addition, please create func folders within both session folders.

func converted Nifti

 

folder organization func

 

 

 

 

 

 

Step 12. Now let’s name the functional filenames. To complete this, one may look back at the NKI webpage and identify the different tasks for the functional images. This will provide a better sense of how to name these files. We see that there are four different tasks: checkerboard, eye movement, breath hold, and rest. We also notice that there are different TR’s for some tasks and the rest tasks have 2 session scans. To break this down, we will go through each task separately.

Let’s begin with the checkerboard task. We notice there are two different TR’s. For TR=645ms, we define this as acq-TR645. Similarly, for TR=1400ms, we define this as acq-TR1400. The acq label was chosen because it is an acquisition difference between the scans. For determining session number, there is not a clear delineation of which session this scan was taken on. Therefore, we defined these scans into session 1, therefore ses-1 will be added as well.

Applying this, we can see how the name will be changed. Both the nii and json will have the same filename (this may be the rule-of-thumb for more beginner users, superusers may reference the Inheritance Principle). Please note the ordering of the filename. This is not optional, the order described in the template has to be followed. (i.e. we could not have switched the placement of acq and task, the validator will fail this)

Func checker namechange arrow

Proceeding onto renaming the eye movement calibrations. The filename will be similar to the checkerboard naming, with the main difference being the different task label.

Func eye namechange arrow

Now for the breath hold task. The naming will be similar to the previous tasks, but there is only one TR.

Func breath namechange arrow

Finally, the rest task. For this task we notice there is 3 different acquisitions (TR=645,1400, and 2500 with differing voxel size and duration). In addition, these are repeated sessions. Therefore, the session identified in the filename will correspond to what ses number to use (i.e. session 2 will be ses-2). The complete filenames are pictured below. Note the CAP image is the TR=2500ms, this can be found on the protocol sheet .

Func rest namechange arrow

We are ready to organize the files into the appropriate folder. The session 1 tasks will go into the ses-1/func folder and session 2 tasks will go into ses-2/func. The completed structure is pictured below.

func file folder organized

Step 13. With the files organized, we will now add the task event .tsv files to describe the task design. For this dataset, there will be five events.tsv files. There is 1 event file for breathhold and 2 for checkerboard and eyemovement (because there are 2 different acq, these event files will have the same content, but different filenames). Rest will not have an events.tsv file. If the events are consistent across the subjects, one can put the events file on the level where the dataset_description.json and subject folders are. If the events are different for each subject, then a sub-# and ses-# needs to precede task-<TakeName>_acq-TR#_events.tsv (i.e. sub-2475376_ses-1_task-Checkerboard_acq-TR1400_events.tsv) and placed at the nii and json level. For this case, since the task is consistent across subjects and sessions, we will put it on the dataset_description level. The contents of these files can be determined from looking at the stimulus design files on the NKI website.

good checker design file

 

events files

 

Step 14. We will now try and validate this dataset. One will receive 2 errors, pictured below. We will now go through fixing both these errors.

errors manually

Let’s begin with the defining ‘TaskName’. To do this, we will be editing the functional scan’s json files. There are required fields that need to be present in each func json file. For this dataset, we notice upon opening the json’s that they have defined repetition time and slice timing, but not task name. The task name needs to be the same name given as the task-<TaskName> in the filename. For example sub-2475376_ses-1_task-Checkerboard_acq-TR645_bold ; the json will have “TaskName”: “Checkerboard”, as pictured below.

TaskName addchange arrowed

Once that is complete, we can try validating again and notice that a single error remains (Error 2 from above): SliceTiming cannot be greater than RepetitionTime.

To fix this error, we first need to understand what is causing this error. The source of this error can be traced back to the fact that this is a multiband imaging dataset. The GUI version of dcm2nii is an earlier version that was not able to properly record the slice timings for some multiband imaging files, causing an error in the slice timing. A fix for this error has been developed.

For this particular dataset, there is a corrected time slicing for each of the TR’s.

To correct the slice timing error, one can copy the time slicing found on the github to the slice timing for each of the tasks json files (the files that need to be changed are identified in the error message) Be careful to divide by 1000 because those times are currently in milliseconds not seconds, we need them to be in seconds. 

After those numbers have been pasted in. One can run the validator

Man func upload

Bids valid dataset

Step 15. You have completed manually creating a BIDSified dataset for 1 subject across 2 sessions and 3 modalities! Now try to complete this same process again with participant 3893245. The only difference is that there is no session 1 for the diffusion scan. Pictured below is the structure for participant 3893245.

389 manual organized

We find after validating there are 2 warnings (pictured below). The first warning is because there is no ses-1 dwi scan for participant 3893245. The second warning is because the time series length is different between the two subjects. These messages are warnings versus errors, therefore they can be interpreted as something to understand before moving on, but this is not an error and one can move on after understanding the reason for the warning.

warning after 2subs

Now we will go through this same process again in the next part, but walking through an automated custom solution.

 

This tutorial illustrated how to manually step-by-step convert DICOMs from the NKI Test-Retest dataset to a validated BIDS dataset. The next tutorial will show how to complete this conversation using an automated custom solution. 

3 Comments

  1. simon jones 6 months

    I am trying to access the data advertised at http://reproducibility.stanford.edu/bids-tutorial-series-part-1a/#man1 but receive a message “You have not chosen a tool/resource, or you have chosen a private tool/resource that you do not have permission to access.” when I try to download it.

  2. irjyu 6 months

    I have the same problems as Simon Jones. I’m logged in (NITRC), but still received a message ” You have not chosen a tool/resource, or you have chosen a private tool/resource that you do not have permission to access.” Could you please help with issue.

  3. Franklin Feingold 5 months

    Hello,
    Thank you for the comments. To confirm, have you created an account with both NITRC and 1000 Functional Connectomes Project? (http://fcon_1000.projects.nitrc.org/indi/req_access.html) In addition to being signed into NITRC when trying to download?