Tutorial - First steps⚓︎
How to use this tutorial⚓︎
This tutorial was developed assuming no prior knowledge of the tool, and little knowledge of the command line (terminal). It aims to be beginner-friendly by giving a lot of details. To get the most out of it, you recommend that you run the commands throughout the tutorial and compare your outputs with the outputs from the example.
Every time you need to run a command, you will see two tabs, one for the command you need to run, and another one with the expected output. While you can copy the command, you recommend that you type each command, which is good for your procedural memory :brain:. The Command and Output tabs will look like these:
1 |
|
1 2 |
|
Note that in the Output tab, the content before the command prompt ($
) will be
dependent or your operating system and terminal configuration. What you want to
compare is what follows it and the output below the command that was ran. The
output you see was taken directly out of your terminal when you tested the
tutorial.
Setup⚓︎
dcm2bids must be installed
If you have not installed dcm2bids yet, now is the time to go to the installation page and install dcm2bids with its dependencies. This tutorial does not cover the installation part and assumes you have dcm2bids properly installed.
Activate your dcm2bids environment⚓︎
If you followed the installation procedure, you have to activate your dedicated environment for dcm2bids.
Note that you use dcm2bids
as the name of the environment but you should use
the name you gave your environment when you created it.
If you used Anaconda Navigator to install dcm2bids and create you environment, make sure to open your environment from Navigator as indicated in Create your environment with the Anaconda Navigator GUI.
1 |
|
1 2 |
|
Test your environment⚓︎
It is always good to make sure you have access to the software you want to use.
You can test it with any command but a safe way is to use the --help
command.
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
What you can do if you did not get this output
If you got dcm2bids: command not found
, it means dcm2bids is not either not installed or not accessible in your current environment. Did you activate your environment?
Visit the installation page for more info.
Create a new directory for this tutorial⚓︎
For the tutorial, we recommend that you create a new directory (folder) instead
of jumping straight into a real project directory with real data. In this
tutorial, we decided to named our project directory dcm2bids-tutorial
.
1 2 |
|
1 2 3 4 5 |
|
Scaffolding⚓︎
While scaffolding is a not mandatory step before converting data with the main
dcm2bids
command, it is highly recommended when you plan to convert data.
dcm2bids has a command named dcm2bids_scaffold
that will help you
structure and organize your data in an efficient way by creating automatically
for you a basic directory structure and the core files according to the Brain
Imaging Data Structure (BIDS) specification.
Tree structure of the scaffold created by dcm2bids⚓︎
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Describing the function of each directory and files is out of the scope of this tutorial but if you want to learn more about BIDS, you encourage you to go through the BIDS Starter Kit.
Run dcm2bids_scaffold
⚓︎
To find out how to run dcm2bids_scaffold
work, you can use the --help
option.
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
As you can see at lines 9-10, dcm2bids_scaffold
has an --output_dir
(or -o
for short) option with a default option, which means you can either specify
where you want the scaffolding to happen to be or it will create the scaffold in
the current directory as a default.
Below you can see the difference between specifying -o output_dir
and NOT
specifying (using the default) the -o
option.
Note that you don't have to create the directory where you want to put the scaffold beforehand, the command will create it for you.
1 |
|
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
|
For the purpose of the tutorial, you chose to specify the output directory
bids_project
as if it were the start of a new project. For your real
projects, you can choose to create a new directory with the commands or not, it
is entirely up to you.
Change directory to go in your scaffold⚓︎
For those who created the scaffold in another directory, you must go inside that directory.
1 |
|
1 2 |
|
Download neuroimaging data⚓︎
For this tutorial, you will use a set of DICOMs made available by [neurolabusc][dcm_qa_nih] on GitHub.
Why use these data in particular?
You use the dcm_qa_nih data because it is the data used by the dcm2niix developers to validate the DICOM to NIfTI conversion process and it has been proven stable since 2017. It also includes data from both GE as well as Siemens MRI scanners so it gives a bit a diversity of data provenance.
To download the data, you can use your terminal or the GitHub interface. You can do it any way you want as long as the directory with the dicoms is in sourcedata directory with the name dcm_qa_nih.
In general, dicoms are considered sourcedata and should be placed in the sourcedata directory. There is no explicit BIDS organization for sourcedata, but having all of a subject's dicoms in a folder with the subject's name is an intuitive organization (with sub-folders for sessions, as necessary).
-
Download the zipped file from https://github.com/neurolabusc/dcm_qa_nih/archive/refs/heads/master.zip.
1
wget -O dcm_qa_nih-master.zip https://github.com/neurolabusc/dcm_qa_nih/archive/refs/heads/master.zip
-
Extract/unzip the zipped file into sourcedata/.
1
unzip dcm_qa_nih-master.zip -d sourcedata/
-
Rename the directory dcm_qa_nih.
1
mv sourcedata/dcm_qa_nih-master sourcedata/dcm_qa_nih
OR
- You can clone the repository if you are familiar with Git. If you did the
steps above, move on.
1
git clone https://github.com/neurolabusc/dcm_qa_nih/ sourcedata/dcm_qa_nih
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
|
- Go to: https://github.com/neurolabusc/dcm_qa_nih and click on the green button (Code) to download ZIP.
- Download the zipped file.
- Extract/unzip the zipped file to the sourcedata directory inside your scaffold and rename the newly created directory dcm_qa_nih.
You should now have a dcm_qa_nih
directory nested in sourcedata
with a bunch
of files and directories:
1 |
|
1 2 |
|
Building the configuration file⚓︎
The configuration file is the central element for dcm2bids to organize your data into the Brain Imaging Data Structure standard. dcm2bids uses information from the config file to determine which data in the protocol will be converted, and how they will be renamed based on a set of rules. For this reason, it is important to have a little understanding of the core BIDS principles. The BIDS Starter Kit a good place to start Tutorial on Annotating a BIDS dataset from .
As you will see below, the configuration file must be structured in the Javascript Object Notation (JSON) format.
More info about the configuration file
The How-to guide on creating a config file provides useful information about required and optional fields, and the inner working of a config file.
In short you need a configuration file because, for each acquisition, dcm2niix
creates an associated .json
file, containing information from the dicom
header. These are known as sidecar files. These are the sidecars that
dcm2bids
uses to filter the groups of acquisitions based on the configuration
file.
You have to input the filters yourself, which is way easier to define when you have access to an example of the sidecar files.
You can generate all the sidecar files for an individual participant using the dcm2bids_helper command.
dcm2bids_helper
command⚓︎
This command will convert the DICOM files it finds to NIfTI files and save them inside a temporary directory for you to inspect and make some filters for the config file.
As usual the first command will be to request the help info.
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
To run the commands, you have to specify the -d
option, namely the input
directory containing the DICOM files. The -o
option is optional, defaulting to
moving the files inside a new tmp_dcm2bids/helper
directory from where you run
the command, the current directory.
Use one participant only
For this tutorial, it is easy since there are only few data. However, in general, each folder of dicoms should be specific to a participant and session. This will not only be more computationally efficient, but also avoid any confusion with overlapping file names between sessions if protocols are repeated.
In this tutorial, there are two directories with data, one with data coming from a
Siemens scanner (20180918Si
), and one with data coming from GE (20180918GE).
The tutorial will use the data acquired on both scanners and Siemens scanner
located in sourcedata/dcm_qa_nih/In/
and pretend it is one participant only.
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Finding what you need in tmp_dcm2bids/helper⚓︎
You should now able to see a list of compressed NIfTI files (nii.gz
) with
their respective sidecar files (.json
). You can tell which file goes with
which file based on their identical names, only with a
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
As you can see, it is not necessarily easy to tell which scan files (nii.gz
)
refer to which acquisitions from their names only. That is why you have to go
through their sidecar files to find unique identifiers for one acquisition you
want to BIDSify.
Go ahead and use any code editor, file viewer or your terminal to inspect the sidecar files.
Here, we compare two files that have similar names to highlight their differences:
1 |
|
- Note than in this example, the filename are wrapped with quotes (
"
) as in"filename.ext"
because there is an=
include in the name. You have to wrap your filenames if they contains special characters, including spaces. To avoid weird problems, we highly recommend to use alphanumeric only names when you can choose the name of your MRI protocols and sequences.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 |
|
Again, when you will do it with your DICOMs, you will want to run
dcm2bids_helper
on a typical session of one of your participants. You will
probably get more files than this example
For the purpose of the tutorial, we will be interested in three specific acquisitions, namely:
004_In_DCM2NIIX_regression_test_20180918114023
003_In_EPI_PE=AP_20180918121230
004_In_EPI_PE=PA_20180918121230
The first is an resting-state fMRI acquisition whereas the second and third are fieldmap EPI.
Setting up the configuration file⚓︎
Once you found the data you want to BIDSify, you can start setting up your
configuration file. The file name is arbitrary but for the readability purpose,
you can name it dcm2bids_config.json
like in the tutorial. You can create in
the code/
directory. Use any code editor to create the file and add the
following content:
1 2 3 |
|
1 |
|
1 2 3 |
|
Populating the config file⚓︎
To populate the config file, you need to inspect each sidecar files one at a
time and make sure there is a unique match for the acquisition you target. For
example, with the resting-state fMRI data
(004_In_DCM2NIIX_regression_test_20180918114023
). You can inspect its sidecar
file and look for the "SeriesDescription"
field for example. It is often a
good unique identifier.
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
|
To match the "SeriesDescription"
field, a pattern like Axial EPI-FMRI*
could
match it. However, we need to make sure we will match only one acquisition. You
can test it by looking manually at inside all sidecar files but it is now
recommend. It is rather trivial for the computer to look in all the .json files
for you with the grep
command:
1 |
|
1 2 3 4 5 |
|
Unfortunately, this criteria is not enough and it could match other 4 files.
In this situation, you can add another criteria to match the specific
acquisition. Which one do you think would be more appropriate? Go back to the
content of the fMRI sidecar file and find a another criteria that, in
combination with the "SeriesDescription"
, will uniquely match the fMRI data.
Right, maybe instead of trying to look for another field, you could simply
extend the criteria for the "SeriesDescription"
. How many files does it match
if you extend it to the full value (Axial EPI-FMRI (Interleaved I to S)
?
1 |
|
1 2 |
|
, there is only one match! It means you can now update your configuration file by adding a couple of necessary fields for which you can find a description in How to create a config file. Since it is a resting-stage fMRI acquisition, you want to specify it like this then make dcm2bids change your task name:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
Avoid using filename as criteria
While you can take file names to match as criteria, we do not recommend this as different versions of dcm2niix can lead to different file names (Refer to the release notes of version 17-March-2021 (v1.0.20210317) of dcmniix to now more, especially the GE file naming behavior changes (%p protocol name and %d description) section.
Use SeriesNumber with caution
It is not uncommon for runs to be repeated due to motion or the participant leaving the scanner to take a break (leading to an extra Scout acquisition). This will throw off the scan order for all subsequent acquisitions, potentially invalidating several matching criteria.
Moving to the fieldmaps, if you inspect their sidecar files (the same ones that
were compared in the
dcm2bids_helper section), you can
see a pattern of "EPI PE=AP"
, "EPI PE=PA"
, "EPI PE=RL"
and "EPI PE=LR"
in the SeriesDescription
once again.
You can test it, of course!
1 2 3 4 |
|
There are two matches per pattern but they come from the same file, so it is okay.
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Now, Dcm2bids new feature --auto_extract_entities
will help you with this
specific situations. Following BIDS naming scheme fieldmaps need to be named
with a dir entity. If you take a look each json file you'll find in their
respective sidecar PhaseEncodedDirection a different direction
1 |
|
There are four matches per pattern but they come from the same file, so it is okay.
1 2 3 4 5 |
|
This entity will be different for each fieldmap so there's no need to be more specific.
Please check the different use cases for this feature
Once you are sure of you matching criteria, you can update your configuration file with the appropriate info.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
For fieldmaps, you need to add an "intendedFor"
as well as id
field to show
that these fieldmaps should be used with your fMRI acquisition. Have a look at
the explanation of intendedFor in
the documentation or in the BIDS specification.
Use an online JSON validator
Editing JSON file is prone to errors such as misplacing or forgetting a comma or
not having matched opening and closing []
or {}
. JSON linters are useful to
validate that we did enter all information successfully. You can find these
tools online, for example https://jsonlint.com.
Now that you have a configuration file ready, it is time to finally run
dcm2bids
.
Running dcm2bids
⚓︎
By now, you should be used to getting the --help
information before running a
command.
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
|
As you can see, to run the dcm2bids
command, you have to specify at least 3
required options with their argument.
1 |
|
dcm2bids
will create a directory which will be named after the argument
specified for -p
, and put the BIDSified data in it.
For the tutorial, pretend that the subID is simply ID01
.
Note that if you don't specify the -o
option, your current directory will be
populated with the sub-<label>
directories.
Using the option --auto_extract_entities
will allow dcm2bids to look for some
specific entities without having to put them in the config file.
That being said, you can run the command:
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
|
A bunch of information is printed to the terminal as well as to a log file
located at tmp_dcm2bids/log/sub-<label>_<datetime>.log
. It is useful to keep
these log files in case you notice an error after a while and need to find which
participants are affected.
You can see that dcm2bids was able to pair and match the files you specified at lines 14-16 in the previous output tab.
You can now have a look in the newly created directory sub-ID01
and discover
your converted data!
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Files that were not paired stay in a temporary directory
tmp_dcm2bids/sub-<label>
. In your case : tmp_dcm2bids/sub-ID01
.
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
That is it, you are done with the tutorial! You can now browse through the documentation to find information about the different commands.
Go to the How-to guides section
Acknowledgment
Thanks to @Remi-gau for letting us know that our tutorial needed an update, and for providing us with a clean and working configuration file through an issue #142 on GitHub .
Created: 2022-04-19