01 - DICOM to BIDS

Step by step description of how to get from DICOM files to necessary nifti-files in BIDS format

1 DICOM-Files

• the raw files from the scanner are DICOM-Files
• not really useful since we need .nifti files for our analysis

\(\qquad\to\) first step is to transform the DICOM- to nifti-files

2 From Dicom to nifti in BIDS format

Even though we often get the data from the scanner already in BIDS format, there can be cases when you have to do this conversion by yourself. For this, you can either use bidscoiner, or a script from Adam: dcm2bids.sh (You can find this script here: /shared/website/dcm2bids.sh).

For both, you need access to Neurodesk!

2.1 About BIDS

Apart from a clear structure that is understandable (for other researchers as well) and standardized, the BIDS format offers further advantages. For example, various BIDS-Apps can perform different steps automatically (e.g. fmriprep), but they require the data to be BIDS-valid).

3 From Dicom to nifti in BIDS using bidscoiner

3.1 bidscoin

First, you need to start through the bird-icon on the bottom left of neurodesk, navigate to Neurodesk > All Applications > bidscoin and select a version (the process has been tested with v4.6.0 & v4.6.1)

3.2 Shell commands

After some time to load, it should look like this:

Then you can follow this script (running the lines separately can help you find/fix potential problems! For potential problems also see the subsections below!):

#!/bin/bash

# you can copypaste the following commands into the terminal window that is opened by BIDSCOINER

# define directories
sourceFolder=/home/jovyan/completion2/dcm
sortedFolder=/home/jovyan/completion2/dcm_sorted

# check the output of the source folder
ls -l $sourceFolder

# make the target directory with subdirectories
mkdir -p $sortedFolder

# change to the script folder
cd /home/jovyan/dicomsort/

# run the script
./DICOMsort.sh $sourceFolder $sortedFolder

# check the output of the target folder
ls -l $sortedFolder

# run bidsmapper
bidsmapper $sortedFolder /home/jovyan/completion2/bids
# note: in the intendedFor of the fieldmap, add func/sub-001_ses-1_xxx_bold.*

# once you are happy with the mapping, run bidscoiner
bidscoiner $sortedFolder /home/jovyan/completion2/bids

3.3 bismapper

Currently, to discover the data we need to delete the content of the “subprefix” field and then save the bids map in the default location. After this, run the same bidsmapper command again.

3.3.1 Subject and session

Now the bidsmapper discovered everything, but the files are not named correctly.

Edit subject and session first.

Now we need to rename the files by clicking “Edit” next to every file.

3.3.2 Editing file names: anatomical

anatmprage -> mprage in the “acq” filed

3.3.3 Editing file names: functional

Edit the task name and acq field

Do this for every functional file

3.3.4 Editing file names: fieldmap

Keep in mind, that we often need the option “epi” in the selection field of “suffix” (and not the “fieldmap” option)!

In the section “Metadata” you have to add which files should be selected for the “IntendedFor” field of the fieldmap. You can use a wildcard (*) to select all respective functional runs: “func/sub-001*_bold.*”. This includes all files in the directory “func” that start with “sub-001” and somewhere in the filename include “_bold.”. Watch out if you have more than one session! Then you might need to specify the respective session as well, e.g. “func/sub-001_ses-3*_bold.*”

3.4 bidscoiner after renaming all files

Once you are happy with the naming of the files, run bidscoiner-command to do the actual conversion

3.5 View files

3.6 MRICron

Now you can view the nifti files with any suitable software

4 From Dicom to nifti in BIDS format with Adam’s script

4.1 Preparations

4.1.1 Setting up the directory structure

First, you need to set up the correct structure for the script to run properly later. For this, you:

1. Create an empty directory named bids (right-click, Create New... > Folder)

2. Create a directory (name can be anything, for example dicoms) and copy/paste your folder with the DICOM-Files in this directory

It should look like this:

These two directories (bids & dicoms) need to be there for the script to work!

The directory scrips is not necessary for the script to run, but it may be helpful to gather and safe the scripts and notes that you need during the process from your raw files to the “final” analysis.

4.1.2 Naming of the nifti files

It is curcial for the BIDS format, that the resulting nifti-files are named properly (see here for the naming convention(s)).

To ensure that later, it might be helpful to write down the proper names for the files before you start the process. This could be done in a simple .txt file, where you specify all the file-names. You can then just open this .txt file and copy/paste the file-names whenever you need them. To have everything at one place, you could save this file in your scripts folder as well.

4.1.2.1 Create a naming.txt

1. navigate to your scripts folder, right-click, select Create New > Empty File

2. assign a name (in this case naming.txt)

3. fill this text file with the proper, BIDS-conform names for the nifti files and saveNow, you can just open this file when you need to change the name of a nifti.

4.2 Starting the script

1. To start the script, you first need to know where the script dcm2bids.sh is. In this case it is here: /home/jovyan/Website/scripts/dcm2bids.sh (you can copy/paste this file to your directory from /shared/website/dcm2bids.sh, or directly access)

2. Navigate to the location of the script, right-click it, and select Copy Path(s)

3. Open a Terminal (icon of a monitor at the bottom left of your screen):

4. Type ml freesurfer and press enter

5. Type bash, add a space, then right-click and select Paste to fill in the path to the script (or type in the path manually)Press enter to start the script.

4.3 (Installing all necessary packages)

It is possible (especially if you start the script for the first time), that some necessary packages are not installed. If this is the case, the script will tell you! If something is missing you´ll be asked, if you want to install these packages. By typing in y and pressing enter, the package will get installed (you might have to do this for more than one package):

If there is still a missing package after all “automatic” suggestions of packages to install, it is probably related to dcm2bids_scaffold (but again, the script will “show” you that there is something missing). In this case, type pip install dcm2bids and press enter

Now “restart” the script (see 2.d + 2.e):

4.4 Preparation: Provide Input and Output Directory

With all necessary packages installed, you are asked to provide the path to the nifti directory. It should look like this:

Nifti directory means the directory/folder, where the nifti-files should be saved to. This is our (currently empty) bids folder that we created in the beginning.

1. To indicate the nifti directory, we either type in the path manually, or get the path by navigating to the directory, right-clicking the bids directory and selecting Copy Path(s) (same procedure as when we needed the path of the script)

2. go back to the terminal window where dcm2bids is running

3. right-click and select Paste to enter the path

4. press enter

Subsequently, you are asked to indicate the dicom directory.

\(\to\) Repeat the steps a)-d) for the dicom directory where your dicoms are stored (that we also created in the beginning)

When both paths are set, you are asked to choose a dicom name (basically the files of a participant; in this case, there is only one scanning-session, but if you have more than one subject, you can select the one that you want do process) and it should look like this:

After selecting a subject/dicom name (Press enter), the script automatically suggest a BIDS “subject id” and asks if it is correct (Watch out! Generally the suggested ID is not BIDS-conform!)

For your data to be BIDS-conform at the end, the “subject id” has to have a structure like this: sub-001, sub-002,… (All necessary information about BIDS can be found here)

If the suggested name is correct, type in y and press enter.

If it is not correct, type in n, press enter and type in a/the correct subject id Once again, press enter

As a last preparative step, you are asked, if you would like to change the session folder from ses-1 to another session. If you only have one session, type n and press enter

If you want to change the session, type y and provide the name of the sessions (Important: to have/get a BIDS-conform structure at the end, subdirectories for sessions have to be named ses-x with x being a number)

Subsequently, you get a short reminder in which directories your files should be stored.

By pressing enter, the script starts to convert your dicom files to nifti’s. This can take a few seconds - be patient!

4.5 Assigning nifti’s to directories and adjusting file names

After the script converts the dicom’s to nifti’s, we have to potentially correct automatically assigned names and assign a directory. At the top of the terminal, you always see how many dicoms are left to categorize.

4.5.1 Possible Actions to perform for a dicom

Actions for a dicom

You can select one of three options for any dicom file (use up-/down arrow key to switch between the options and press enter to confirm your choice):

1. Keep: By selecting this option, you tell the script that the suggested name is correct and that you want to assign this file with the shown name to a directory (Since BIDS uses a specific naming convention, you´ll probably need this option only for “additional files”, like files related to denoising, that will be placed in a directory that is more or less independent of the BIDS-Format; see Section 4.5.3*)

2. Modify Name: This option tells the script that you want to change the suggested name. This is needed, when the suggested name is not BIDS-conform. After selecting this option (by pressing enter), you are asked to edit the name. Change the name (first delete the suggested one) to a BIDS-conform filename (Hint: the initially suggested name implies what type of scan it was, so you should be able to easily determine if it was an anatomical scan, which run of a functional scan, or the fieldmap). Using a previously created file with bids-conform names can help avoiding errors and typos here, by just copy/pasting the prepared filenames! After you changed the name, press enter to confirm

3. Delete (Do not convert): As the name suggests, selecting this option deletes the mentioned file (thus, there will be no corresponding nifti-file!). One case when this is generally used is for the anat-scout scan that is irrelevant for the preprocessing and analysis, since it is a short scan at the beginning of a scanning session to ensure a proper position of the participant and to adjust the parameters for the actual scans.

4.5.2 Assigning a file to a directory

After either keeping or modifying the name, you are asked to assign the file to a directory.

You can either:

1. Keep folder name: By selecting this option, you accept the suggested directory. In general, the correct directory is already suggested for most files (anatomical \(\to\) anat, functional \(\to\) func, fieldmap \(\to\) fmap)

2. Modify folder name: This option is only needed for files that were acquired “additionally”, for example, when a denoising sequence was used (files with .ph at the end, see here). As for the file name, you can edit the name of the directory after selecting this option. Entering a new/unique name for the directory here will result in an additional sub-directory in the subsequent BIDS-directory (if you enter the same name for all “additional” files, they will all be stored in this specified directory)

4.5.3 The “extra” directory

Sometimes we acquire files that are not part of the BIDS-Format (and, more importantly, are not used by BIDS-Apps), for example when running a denoising sequence during acquisition of the data. In the example of a denoising sequence, corresponding files are named with _ph at the end. When asked about the filename, we can just keep it as it is, since we use these files separately anyway.

Important!!

Those files have to be stored in a different directory! Thus, when asked about where to assign the file, we select Modify folder name. All “additional” files can be saved in a directory named extra (\(\to\) edit the name of the directory to extra and press enter)

After assigning the last file to its directory, you´ll see the information, that an additional file has been created, which we will use later. The script has finished:

5 The resulting BIDS-directory

This is how your bids-directory (which was initially created as an empty directory) should look like:

When you enter the sub-999 directory, you´ll find the sub-directory ses-1 (or whatever session you specified during the preparation). Inside, all sub-directories that you selected/edited to assign the files to are listed:

Each of these sub-directories contains all the files that you assigned, including the .nii.gz and a .json file

5.1 Edit “IntendedFor”-Section in the fmap

Before you continue, there is one last potential adaptation that should be considered.

With changing Versions of BIDS and BIDS-Apps, slight changes occur in how and where you have to include specific information. One example for this is the IntendedFor information in the fmap’s .json file.

Depending on the Version of fmriprep you plan to use, it may be necessary to change the IntendedFor field of the fmap’s .json file! The steps described below have to be done if you want to use fmriprep 24.0.0 or newer! (If you use an older Version, you don´t have to do the described steps)

1. Navigate to your bids directory

2. Open the file sub-999-bidsurifmap.json (double click, or right-click + gedit)

3. Select all content and copy it (since Strg + c/v does not always work, you can use right-click and select copy)

4. Navigate to the fmap directory (*/bids/sub-999/ses-1/fmap/) and open the .json file

5. After the file opens, scroll down to the very end of it. There should be a section that starts with IntendedFor and looks like this:

6. Remove all lines within the brackets after "IntendedFor" and paste the lines you copied from the bidsurifmap.json file. Remember to end every (but the last) line with a comma (,)!! It might also be good to keep the indentation at the beginning of each line (4 Spaches). At the end, it should look like this:

Don´t forget to save the file afterwards!!!

6 Congratuliations, you did it!

Congratulations! You successfully finished the process of converting your DICOM to nifti files in BIDS-Format and you are one step closer to analyzing your data!

Please return to the Overview-Page to check what to do next.

Alternatively, here is a list of potential next steps to continue with

1. Provide participants with their T1w-file?

2. Defacing

3. Remove Denoising Scans from your data?

4. fmriprep