BIDS Tutorial Series: Automate the Introductory Walkthrough
Welcome to part 1B of the tutorial series “Getting Started with BIDS”. This tutorial will illustrate how one can automate the conversation of DICOMs into a valid BIDS dataset. This tutorial will follow the same workflow detailed in part 1A of this 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. If you are running into issues, please post your questions on NeuroStars with the bids tag. The next parts of this tutorial series will examine off-the-shelf solutions to consider using to convert your dataset into the BIDS standard.
Table of Contents
- Initialize script and create the dataset_description file
- Create anatomical folders and convert dicoms
- Rename anatomical files
- Organize anatomical files and validate
- Create diffusion folders and convert dicoms
- Rename diffusion files
- Organize diffusion files and validate
- Create functional folders and convert dicoms
- Rename and organize functional files
- Task event tsv files
- Fix errors
- Validate and add participant
The automated custom solution is going through the same process done in part 1A, but with a script. The automated custom solution is written in a bash shell script. This script is dependent upon homebrew, jo, jq, dcm2niix (jo and jq can be installed from homebrew). The script assumes that the Dicom folder with subjects needed to be converted exists. Each code snippet is part of the larger script.
Step 1. To begin, we need to define our paths and create the Nifti directory. These paths need to be changed according to what your paths are. These path variables are important to remember because these path variables are called throughout the script. (i.e. the variable niidir is defined as the path: /Users/franklinfeingold/Desktop/NKI_script/Nifti)
Then we can generate the dataset_description.json file.
Step 2. To begin the workflow, the loop prints out the subject currently being processed and creates the session and anat folder within the subject folder. Then we convert with dcm2niix the anatomical dicoms into the nifti and json file, and output them in the subject folder within the Nifti folder (output pictured below). Please note that the converter input is the anat folder within the subjects Dicom folder.
The for loop can iterate through every subject defined in the Dicom directory. For this walkthrough, we are only running through participant 2475376. One may add participant 3893245 when comfortable with the workflow. A participant will go through the entire workflow before the next one begins.
We changed the directory to where the converted nifti images are. In that directory, we can more easily change the filenames for the anat nii and json files.
Step 3. Now we can rename the anat files, following the same rule applied in step 6 of part A. This code snippet will capture the number of anat files needed to be changed, go through each anat file and rename it to the valid BIDS filename.
We have completed organizing the anat files. One can try confirming this is a validated BIDS dataset at this point. Once the validation is confirmed, we are ready to organize the diffusion files.
Step 5. To begin organizing the diffusion scans, we will generate the folder structure by creating a dwi folder within ses-1 and ses-2. Then we can convert the Dicom DTI folders within session1 and session2 and output the nii and json files to the participants Nifti folder. The output and current file structure can be seen below.
Next, we change the directory into the participants Nifti folder, where the converted nii and json files are.
Step 6. Now we can rename the diffusion nii and json files, similar to step 9 in part A. The original filename and BIDS filename are printed out.
We have completed the organization of the diffusion scans. One may confirm this is still a valid BIDS dataset through validation. Once validated, we are ready to organize the functional scans.
Step 8. To begin organizing the functional scans, we will create the functional folder structure by adding a func folder to both ses-1 and ses-2. With the folders created, we can now convert the functional dicom files to nifti and json files. To do this, we converted the folders that comprise the functional dicoms and output the nii and json files to within the participant’s folders in the Nifti directory. The folder names are contained within the for loop. The output and folder structure is visualized below.
We changed the directory into where the converted nii and json files are, in the participant’s Nifti folder.
Step 9. Now we can rename the func files, similar to step 12 in part A. To do this, we changed filenames task by task. The order we renamed in: Checkerboard, eye movement, breath hold, and rest. Note that the rest scans still span across 2 sessions.
Checkerboard files renamed
Eye movement calibration files renamed
Breath holding files renamed
Rest files renamed
Next, we will organize the files into the correct directories. We have shown below, the filenames and organization.
Step 10. Now we need to create the task event tsv files for each of our tasks. The task designs can be found on the NKI webpage. To determine the Checkerboard events file, one will look at the Checkerboard task design. Here we generated the Checkerboard TR=645 event file.
Since both acquisitions have the same task design, we can simply copy the events file, but renamed.
Now, we will generate the event file for eye movement. We downloaded the eye movement paradigm. The path that we set for eye movement paradigm was: /Users/franklinfeingold/Desktop/EyemovementCalibParadigm.txt . This needs to be edited in the script to where one placed their paradigm file.
Since the task design is consistent across different TR, we can simply copy the task design, but with a different filename.
Lastly, we will create the event file for the breath hold task by looking at the breath hold design file.
Pictured below is the current file structure.
Step 11. At this point, one may try validating. However, one will receive the same error message from part A regarding defining TaskName in the task json files. The slice timing for multiband imaging was corrected in the version of dcm2niix implemented in the script.
To correct this error, we will confirm that each task json file has the required fields: RepetitionTime, VolumeTiming or SliceTiming, and TaskName. This code snippet will evaluate if RepetitionTime exists, if SliceTiming (or VolumeTiming) exist and the timings are all less than the RepetitionTime, and if TaskName is defined. In addition, if TaskName is not defined, TaskName will be added to the json file with TaskName being the task label in the filename.
Step 12. Now if we try to validate, we find that this dataset is a valid BIDS dataset! To capture both subjects, one can change the subj for loop at the top of the script to replace participant 3893245 for 2475376 in the loop. After running participant 3893245 through the workflow, we find the same warnings as the part A curated dataset; the checkerboard scans across subjects have different time dimensions and the dwi may be missing scans because there is only 1 diffusion scan for participant 3893245 and 2 diffusion scans for participant 2475376. Note: Do not have both participants in the for loop if one has already been run and organized, this will cause an error.
This first tutorial part illustrated how to convert DICOMs from the NKI Test-Retest dataset to a validated BIDS dataset. We illustrated doing it A. manually and B. an automated custom solution. The next tutorial will show how to complete this conversation using an off-the-shelf BIDS converter: HeuDiconv.