BIDSkit

Software that allows to convert from DICOM files to a structured and validated BIDS directory.

Installing

The procedure is to follow the instructions in this GitHub page. We provide some recommendations here.

Install Anaconda (Python 3.* version)
Create a new environment for bidskit and other BIDS-related tools with the following command
```
 conda create -n bids
```
Activate the environment
```
 conda activate bids
```
Install pip
```
 conda install pip
```

Install dcm2niix

 conda install -c conda-forge dcm2niix

Install bidskit
```
 pip install bidskit
```
Install the bids validator
```
 conda install bids-validator
```

Using

The Getting Started Guide provided is a nice tutorial. I’ll just note some details here.

This structure needs to be followed exactly (even when there is only one session):

DataFolderName/
├── sourcedata
│   ├── p0001
│   │   ├── 01
│   │   │   └── [DICOM Images]
│   │   └── 02
│   │       └── [DICOM Images]
│   └── p0002
│   │   ├── 01
│   │   │   └── [DICOM Images]
│   │   └── 02
│   │       └── [DICOM Images]

Note that “p0001” will be the participant label and “01” the session label. It does not matter if you have multiple folders inside the session folder.

First pass

In the terminal, cd to the DataFolderName folder and type

bidskit

This will run a first pass procedure, which includes recognition of all files in the directory, conversion from DICOM to NifTI, and creation of a BIDS compatible folder structure.

Now, the routine needs to know which series you want to include and to what they correspond. In folder ‘code’, a Protocol_Translator.json file was created, which we need to edit properly.

Here is an example of a .json file created for a session which includes a T1w structural image, one resting state MB fMRI sequence, one GRE fieldmap sequence and one PA acquisition. Initially, it will look like this, with the BIDS directory, filename suffix and IntendedFor fields set to their default values of “EXCLUDE_BIDS_Name”, “EXCLUDE_BIDS_Directory” and “UNASSIGNED”.

{
    "t1_mprage_sag_p2_iso":[
        "EXCLUDE_BIDS_Directory",
        "EXCLUDE_BIDS_Name",
        "UNASSIGNED"
    ],
    "RestingState_gre_loc_field_mapping_GAPzero":[
        "EXCLUDE_BIDS_Directory",
        "EXCLUDE_BIDS_Name",
        "UNASSIGNED"
    ],
    "RestingState_SMS3_PA_TR1000":[
        "EXCLUDE_BIDS_Directory",
        "EXCLUDE_BIDS_Name",
        "UNASSIGNED"
    ],
    "RestingState_SMS3_PA_TR1000_SBRef":[
        "EXCLUDE_BIDS_Directory",
        "EXCLUDE_BIDS_Name",
        "UNASSIGNED"
    ],
    "RestingState_SMS3_AP_TR1000_SBRef":[
        "EXCLUDE_BIDS_Directory",
        "EXCLUDE_BIDS_Name",
        "UNASSIGNED"
    ],
    "RestingState_SMS3_AP_TR1000":[
        "EXCLUDE_BIDS_Directory",
        "EXCLUDE_BIDS_Name",
        "UNASSIGNED"
    ]
}

We need to edit the BIDS directory and filename suffix entries for each series with the BIDS-compliant filename suffix (excluding the sub-xxxx_ses-xxxx_ prefix and any file extensions) and the BIDS purpose directory name (anat, func, fmap, etc).

The IntendedFor field is only relevant for fieldmap series and specifies which EPI series (BOLD, DWI, etc) are to be corrected by given fieldmap data.

This is the result:

{
    "t1_mprage_sag_p2_iso":[
        "anat",
        "T1w",
        "UNASSIGNED"
    ],
    "RestingState_gre_loc_field_mapping_GAPzero":[
        "fmap",
        "acq-rest_run-1",
        ["task-rest_run-1_bold"]
    ],
    "RestingState_SMS3_PA_TR1000":[
        "fmap",
        "acq-rest_dir-PA_epi",
        ["task-rest_run-1_bold"]
    ],
    "RestingState_SMS3_PA_TR1000_SBRef":[
        "EXCLUDE_BIDS_Directory",
        "EXCLUDE_BIDS_Name",
        "UNASSIGNED"
    ],
    "RestingState_SMS3_AP_TR1000_SBRef":[
        "func",
        "task-rest_run-1_sbref",
        "UNASSIGNED"
    ],
    "RestingState_SMS3_AP_TR1000":[
        "func",
        "task-rest_run-1_bold",
        "UNASSIGNED"
    ]
}

Notes

We are excluding the SBRef image for the PA sequence
PA sequences, acording to the BIDS specification, need to be put in the fmap directory with the _epi suffix. I also supply the “dir” field with value “PA” to be clear what the image is.
IntendedFor field always need the brackets [], even if only one value is inside.
The “run” field should be used to incorporate several runs of the same task (even if the events are in a different order, aka, the protocol is different but the task is the same)

Second pass

bidskit now has enough information to organize the converted Nifti images and JSON sidecars in the work/ folder according to the BIDS specification.

We just run the same command again:

bidskit

If you want bidskit to search for the “best” fieldmap sequence for each functional run (i.e. the one closest in time), run the following command instead:

bidskit --bind-fmaps

Add more subjects

To add more subjects, simply add the raw DICOM files to the sourcedata folder, and run bidskit again. It should identify the new subjects and arrange and convert files accordingly. Always check the console output!

If you provide the flag –overwrite bidskit will overwrite all current data.