Skip to content

Converting dicom to BIDS format .nii.gz a walkthrough

Jump to bottom
Jhelum Paul edited this page Jun 23, 2022 · 6 revisions

BIDS walkthrough

Introduction:

The Brain Imaging Data Structure (BIDS) is a standard format that is used to organize neuro-imaging and behavioral data. This is a simple and easy method to adopt. All the data that come off the scanner are converted to NIFTI and JSON files, organized into a specific directory schema, and labeled following a precise naming convention and this structure will help researchers to share data among themselves and interpret it better. The BIDS standard uses file formats compatible with existing software, unifies most practices already common in the field, and captures the metadata necessary for most common data processing operations. You can click this link to follow the paper for more information: (https://www.nature.com/articles/sdata201644)

Steps to create the BIDS structure:

  1. To start with the whole process, you need to first check for dependencies. You will need Python 3.7 or above to run dcm2bids properly. If you are unsure what to install between Anaconda and Miniconda read this section to help you choose.
  2. Load miniconda and install dcm2bids:

conda install -c -forge dcm2bids

conda install -c -forge dcm2niix

  1. Create environment.yml - dedicated environment file. Open a text document and save the following with .yml extension (The name: key refers to the name of the dedicated environment. You will have to use this name to activate your environment and use software installed inside. The name is arbitrary, you can name it however you want. The channels: key tells conda where to look for the declared dependencies. The dependencies: key lists all the dependencies to be installed inside the environment. If you are creating an environment for your analysis project, this is where you would list other dependencies such as nilearn, pandas, and especially as pip since you don't want to use the pip outside of your environment Note that we specify python>=3.7 to make sure the requirement is satisfied for dcm2bids as the newer version of dcm2bids may face issue with Python 3.6 and below)
  2. Open a terminal and go in the directory where you put the environment.yml run this command:

conda env create –file environment.yml

  1. Activate environment:

conda activate dcm2bids

  1. Verify that dcm2bids work by executing dcm2bids –help
  2. After creating a directory for the data and where you want to save your folder, go to your folder which has data through the terminal and type

dcm2bids _scaffold -d data directory -o output directory you can mention the output directory where you want the scaffolding to happen to be or else it will happen in the folder that you are currently in. You can also check the format of this command by typing dcm2bids_scaffold –help (Scaffolding is highly recommended when you plan to convert data to bids structure. This step creates a tree structure.)

  1. dcm2bids _helper --helper will help us to find out what all we need to run the dcm2bids_helper command for the reconstruction from dicom to bids structure.

  2. Scaffold_directory will also have another folder called tmp_dcm2bids/helper which will have all the output of the data in NIFTI and their respective JSON files known as sidecars. (For each acquisition, dcm2niix creates an associated .json file, containing information from the dicom header. These are known as sidecars. These are the sidecars that dcm2bids uses to filter the groups of acquisitions.) These sidecars contain the information as metadata ( in the form of Description and Level Keys) that the scanner has provided which in the case here is a Phillips Achieva 3T.

  3. Next we need to manually build our configuration file of descriptions for all the data that we have, called dcm2bids_config.json This must be in JSON format. This is generally put in code/dcm2bids_config.json This is a long step. First, you need to check these already-created JSON files for finding unique keys to pair up with our config file. Why? you must go through their sidecar files to find unique identifiers for one acquisition you want to BIDSify.
    You can check the difference in two JSON sidecars by

diff –side-by-side tmp_dcm2bids/helper/”filename.json” tmp_dcm2bids/helper/”filename.json”

Or To match the "SeriesDescription" field, a pattern like pCASL_M0* could match it. However, you need to make sure you will match only one acquisition.

grep “pCASL_M0” tmp_dcm2bids/helper/*.json

Having done all the thorough checks for how and what is unique and which descriptions you could use for matching your data while creating your config file you can dive into code/dcm2bids_config.json The following descriptions were provided to write up the config file for T1w, rs-fMRI with its b0 scan, pCASL with its m0 scan: (You can find the config file in the server to relate)

a) datatype: mandatory field: Data type - a functional group of different types of data. In BIDS we define six data types: func (task-based and resting-state functional MRI), dwi (diffusion weighted imaging), fmap (field inhomogeneity mapping data such as field maps), anat (structural imaging such as T1, T2, etc.), meg (magnetoencephalography), beh (behavioral). In my case, I had anat, func, perf, fmap.

b) modalityLabel: mandatory field: It is a mandatory field. It describes the modality of the acquisition like T1w, T2w or dwi, bold. In my case, I had T1w, bold, epi, pCASL, m0scan.

c) customLabels: optional: For some acquisitions, you need to add information in the file name. For resting state fMRI, it is usually task-rest. In my case, I had the one for fMRI, task-rest.

d) criteria: mandatory: dcm2bids will try to match the sidecars of dcm2niix to the descriptions of the configuration file. The values you enter inside the criteria dictionary are patterns that will be compared to the corresponding key of the sidecar. The pattern matching is shell-style. It's possible to use wildcard *, single character ? You can enter several criteria. All criteria must match for a description to be linked to a sidecar. For more information, you can look into the (https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)

e) sidecarchanges: Optional field to change or add information in a sidecar.

f) IntendedFor: Optional field to add an IntendedFor entry in the sidecar of a fieldmap. Just put the index or a list of indices of the description(s) that's intended for. Python index begins at 0 so in the example, 1 means it is intended for task-rest_bold.

g) Phillips scanners do not provide slicetiming(ascending, descending, interleaved) information in the dicoms so, it is not possible to further pre-process fMRI data that is there within the BIDS, by slicetime correction process. Hence you must add this as sidecarChanges. In this case, this information was provided by the MR Technician. If you know the Repetition Time (TR) of the pulse sequence used during fMRI and #slices and the slice order, you can calculate the slice order. I used a small Matlab code to get the timing for 47 slices interleaved ascending and added the description inside the fMRI JSON file.

  1. After the dcm2bids_config.json is ready make sure you have it in proper JSON format as you might get the error “Unexpected UTF-8 BOM error. To resolve this error, you can put you config file format in any online JSON validator and check for errors if you are not sure.
  2. Final step is to run the dcm2bids command, which will create a directory that will be named after the argument specified for -p, and put the BIDSified data in it. Make sure the subject id is without _ and -, it will give you warning as BIDS do not support underscore or hyphen in their naming convention.

dcm2bids -d path/to/source/data -p subject_id -c path/to/config/file.json -o output directory

This is how the structure gets created. It contains the NIFTI format of the imaging data along with the metadata in the JSON files

Clone this wiki locally