From DICOMS to BIDS: mic2bids
- This section describes how to organize a database from sorted DICOMs files to BIDS format. As the naming and sorting of DICOMs can be quite unique to each imaging protocol,
MRI sequence names and outputs must be adapted to be compatible with each dataset.
First, you will have to look at the organization of the sorted DICOM directory. This directory should contain subdirectories in which the DICOM images are sorted according to each sequence completed by the participant. You must identify the sequences in the protocol that you want to transform to NIfTI: These sequences will then populate the BIDS directory.
Let’s suppose that your sorted DICOM directory looks like the following:
S1_02_AAHead_Scout_64ch-head-coil_MPR_sag
S1_03_AAHead_Scout_64ch-head-coil_MPR_cor
S1_04_AAHead_Scout_64ch-head-coil_MPR_tra
S1_08_mprage-0.8iso_ORIG
S1_10_dwi_b2000_90
S1_11_dwi_b700_40
S1_12_dwi_b300_10
S1_13_dwi_b0_5PA
S1_16_rsfmri-3mm-bold_AP
S1_17_rsfmri-3mm_se_AP
S1_18_rsfmri-3mm_se_PA
S1_20_mprage-0.8iso_ORIG
S1_29_mp2rage-0.8iso-sess2_INV1
S1_30_mp2rage-0.8iso-sess2_T1_Images
S1_31_mp2rage-0.8iso-sess2_UNI_Images
S1_32_mp2rage-0.8iso-sess2_INV2
In this example, we don’t want images in the DICOM directories containing the string AAHead_Scout_64ch-head-coil_MPR to be included in the BIDS directory, because those acquisitions are for calibration purposes only.
Once you’ve determined which directories you want to transform to NIfTI and organize into BIDS, you should identify their corresponding MRI sequence. You should determine the BIDS naming equivalent of each unique sequence in your dataset. In other words, you should match the string of each DICOM directory to a BIDS string that will identify the corresponding sequence.
BIDS naming 🗄
Take a look at the BIDS specifications if you have any doubts about the BIDS string that best matches your MRI acquisition.
The next step is to transform your DICOM directory to a NIfTI file with the matching BIDS naming, and place it under its corresponding BIDS directory. Different online tools can transform DICOMs to NIfTI. For example, we use dcm2niix with the flag -b, which creates a json card for each NIfTI file.
We can refer to to the following table to see the DICOM and BIDS naming of each sequence, and which BIDS subdirectory it will store each file. This example uses sub-01 as subject’s identification and
ses-01 as the session name. As we acquired two distinct T1w images, using the string -run will differentiate them.
Sequence |
DICOM directory name |
BIDS string |
BIDS directory |
Example subject naming |
|---|---|---|---|---|
T1 weighted (T1w) |
S1_08_mprage-0.8iso_ORIG |
|
/anat |
|
T1 weighted (T1w) |
S1_20_mprage-0.8iso_ORIG |
|
/anat |
|
Quantitative T1 (qT1), first inversion time |
S1_29_mp2rage-0.8iso-sess2_INV1 |
|
/anat |
|
Quantitative T1 (qT1), second inversion time |
S1_32_mp2rage-0.8iso-sess2_INV2 |
|
/anat |
|
Quantitative T1 (qT1), T1 map |
S1_30_mp2rage-0.8iso-sess2_T1_Images |
|
/anat |
|
Quantitative T1 (qT1), synthetic T1 |
S1_31_mp2rage-0.8iso-sess2_UNI_Images |
|
/anat |
|
Diffusion weighted Imaging (DWI), b=2000 |
S1_10_dwi_b2000_90 |
|
/dwi |
|
Diffusion weighted Imaging (DWI), b=700 |
S1_11_dwi_b700_40 |
|
/dwi |
|
Diffusion weighted Imaging (DWI), b=300 |
S1_12_dwi_b300_10 |
|
/dwi |
|
Diffusion weighted Imaging (DWI), b=0 |
S1_13_dwi_b0_5PA |
|
/dwi |
|
Blood-oxygen-level dependent imaging (BOLD) |
S1_16_rsfmri-3mm-bold_AP |
|
/func |
|
Fieldmap for BOLD (AP) |
S1_17_rsfmri-3mm_se_AP |
|
/func |
|
Fieldmap for BOLD (PA) |
S1_18_rsfmri-3mm_se_PA |
|
/func |
|
Let’s suppose we are organizing the directories of sub-01_ses-01, the main BIDS structure should be as follows:
sub-01
└── ses-01
├── anat
├── dwi
└── func
The final BIDS structure should look like:
sub-HC001
└── ses-01
├── anat
│ ├── sub-01_ses-01_acq-inv1_T1map.json
│ ├── sub-01_ses-01_acq-inv1_T1map.nii.gz
│ ├── sub-01_ses-01_acq-inv2_T1map.json
│ ├── sub-01_ses-01_acq-inv2_T1map.nii.gz
│ ├── sub-01_ses-01_acq-mp2rage_T1map.json
│ ├── sub-01_ses-01_acq-mp2rage_T1map.nii.gz
│ ├── sub-01_ses-01_acq-uni_T1map.json
│ ├── sub-01_ses-01_acq-uni_T1map.nii.gz
│ ├── sub-01_ses-01_T1w.json
│ └── sub-01_ses-01_T1w.nii.gz
├── dwi
│ ├── sub-01_ses-01_acq-b2000_dir-AP_dwi.bval
│ ├── sub-01_ses-01_acq-b2000_dir-AP_dwi.bvec
│ ├── sub-01_ses-01_acq-b2000_dir-AP_dwi.json
│ ├── sub-01_ses-01_acq-b2000_dir-AP_dwi.nii.gz
│ ├── sub-01_ses-01_acq-b300_dir-AP_dwi.bval
│ ├── sub-01_ses-01_acq-b300_dir-AP_dwi.bvec
│ ├── sub-01_ses-01_acq-b300_dir-AP_dwi.json
│ ├── sub-01_ses-01_acq-b300_dir-AP_dwi.nii.gz
│ ├── sub-01_ses-01_acq-b700_dir-AP_dwi.bval
│ ├── sub-01_ses-01_acq-b700_dir-AP_dwi.bvec
│ ├── sub-01_ses-01_acq-b700_dir-AP_dwi.json
│ ├── sub-01_ses-01_acq-b700_dir-AP_dwi.nii.gz
│ ├── sub-01_ses-01_dir-PA_dwi.bval
│ ├── sub-01_ses-01_dir-PA_dwi.bvec
│ ├── sub-01_ses-01_dir-PA_dwi.json
│ └── sub-01_ses-01_dir-PA_dwi.nii.gz
└── func
├── sub-01_ses-01_task-rest_acq-AP_bold.json
├── sub-01_ses-01_task-rest_acq-AP_bold.nii.gz
├── sub-01_ses-01_task-rest_acq-APse_bold.json
├── sub-01_ses-01_task-rest_acq-APse_bold.nii.gz
├── sub-01_ses-01_task-rest_acq-PAse_bold.json
└── sub-01_ses-01_task-rest_acq-PAse_bold.nii.gz
It is the same procedure for each subject in your dataset.
The bash script mic2bids completes all the previous steps automatically using dcm2niix. However it was written to match the name of the DICOMs in the MICA-MICs dataset with their corresponding BIDS name. Feel free to adapt it to your own needs, by modifying the DICOM strings and BIDS names in the lines 138-146 of mic2bids, or use it as a guideline to build your own script.
# -----------------------------------------------------------------------------------------------
# CHANGE THIS regex (regular expressions) ACCORDING TO YOUR DICOMS NAMING
orig=("mprage-0.8iso" "_INV1" "*_INV2" "*_T1_Images" "*UNI_Images" "*FLAIR" "rsfmri-3mm-bold_AP" "*rsfmri-3mm_se_AP" "*rsfmri-3mm_se_PA")
origDWI=("*dwi_b700_40" "*dwi_b300_10" "*dwi_b0_5PA" "*_dwi_b2000")
# New BIDS-naming, follow the BIDS specification:
# https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html
bids=(T1w acq-inv1_T1map acq-inv2_T1map acq-mp2rage_T1map acq-uni_T1map FLAIR task-rest_acq-AP_bold task-rest_acq-APse_bold task-rest_acq-PAse_bold)
bidsDWI=(acq-b700-NUM_dir-AP_dwi acq-b300-NUM_dir-AP_dwi dir-PA_dwi acq-b2000-NUM_dir-AP_dwi)
Once you’ve done all the necessary modifications you can run the scrip:
mic2bids -in <DICOMS_directory> -bids <BIDS directory path> -id <subject> -ses <session>
Argument |
Description |
|---|---|
|
Input directory with the subject’s DICOMS directories (FULL PATH) |
|
Subject identification for the new BIDS directory |
|
Flag to specify the session name (Default is |
|
Path to BIDS directory ( . or FULL PATH) |
|
This flag will overwrite the existing BIDS directory for that subject |
Once you have ordered all your subjects, add the rest of the mandatory files to your BIDS directory:
CHANGES
dataset_description.json
participants.json
participants.tsv
README
Finally, remember to validate your dataset with the BIDS validator tool prior to running micapipe!