Skip to content

How to use main commands⚓︎

Command Line Interface (CLI) usage⚓︎

See dcm2bids -h or dcm2bids --help to show the complete list of options and arguments.

 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
usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION]
                -c CONFIG [-o OUTPUT_DIR]
                [--auto_extract_entities | --do_not_reorder_entities]
                [-b BIDS_VERSION] [--bids_validate] [--force_dcm2bids]
                [--skip_dcm2niix] [--clobber]
                [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]

Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure

options:
  -h, --help            show this help message and exit
  -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
                        Path to one or more directories or archives (tar, tar.bz2, tar.gz or zip) containing the DICOM files for a single participant and session to be converted to BIDS.
  -p PARTICIPANT, --participant PARTICIPANT
                        Participant ID to be used in the BIDS dataset filenames (e.g. sub-<PARTICIPANT>).
  -s SESSION, --session SESSION
                        Session ID to be used in the BIDS dataset filenames (e.g. ses-<SESSION>). If not provided, no session entity will be added to the BIDS filenames.
  -c CONFIG, --config CONFIG
                        JSON configuration that specifies additional parameters for BIDS conversion. See the documentation for more information: 
                        https://unfmontreal.github.io/Dcm2Bids/3.3.0.rc2/how-to/create-config-file/
  -o OUTPUT_DIR, --output_dir OUTPUT_DIR
                        Output BIDS directory. Defaults to the current working directory.
  --auto_extract_entities
                        If set, it will automatically try to extract entity information [task, dir, echo] based on the suffix and datatype. Default is [False]
  --do_not_reorder_entities
                        If set, it will not reorder entities according to the relative ordering indicated in the BIDS specification and use the order defined in custom_entities by the user.
                        Cannot be used with --auto_extract_entities.  Default is [False]
  -b BIDS_VERSION, --bids_version BIDS_VERSION
                        Set the BIDS specification version to follow (e.g. 'v1.11.1', 'stable', 'latest' or 'default').
                        This controls which BIDS schema and rules dcm2bids uses for automatic entity extraction and ordering.
                        If not provided, dcm2bids uses the 'default' BIDS spec for reproducible, offline-friendly behavior.
                        For long-running or shared pipelines, consider pinning a specific tag (e.g. 'v1.11.1').
                        When internet is available, it will check once whether the remote 'stable' is newer and, if so, 
                        suggest updating to that specific version tag.
  --bids_validate       If set, once your conversion is done it will check if your output folder is BIDS valid. [False]
                        bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart
  --force_dcm2bids      Overwrite previous temporary dcm2bids output if it exists.
  --skip_dcm2niix       Skip dcm2niix conversion. Option -d should contains NIFTI and json files.
  --clobber             Overwrite output if it exists.
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set logging level to the console. The default level is [INFO]
  -v, --version         Report dcm2bids version and the default BIDS specification version it follows by default.

Documentation at https://unfmontreal.github.io/Dcm2Bids/

Main command: dcm2bids⚓︎

1
dcm2bids -d DICOM_DIR -p PARTICIPANT_ID -c CONFIG_FILE

If your participant have a session ID:

1
dcm2bids -d DICOM_DIR -p PARTICIPANT_ID -s SESSION_ID -c CONFIG_FILE

Important

If your directory or file names have space in them, we recommend that you change all the spaces for another character (_ or -) but if you can't change the names, you have to wrap each argument with quotes as in the example below:

dcm2bids -d "DICOM DIR" -p PARTICIPANT_ID -c "path/with spaces to/CONFIG FILE.json"

Output⚓︎

dcm2bids creates a sub-<PARTICIPANT_ID> directory in the output directory (by default the folder where the script is launched).

Sidecars with one matching description will be converted to BIDS. If a file already exists, dcm2bids won't overwrite it. You should use the --clobber option to overwrite files.

If a description matches several sidecars, dcm2bids will add automatically the custom label run- to the filename.

Sidecars with no or more than one matching descriptions are kept in tmp_dcm2bids directory. Users can review these mismatches to change the configuration file accordingly.

dcm2bids creates log files inside tmp_dcm2bids/log directory.

Tools⚓︎

Scaffold⚓︎

the dcm2bids_scaffold command creates basic BIDS files and directories based on the bids-starter-kit. The output directory is set to the location where the script is launched by default.

1
dcm2bids_scaffold [-o OUTPUT_DIR]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
usage: dcm2bids_scaffold [-h] [-o OUTPUT_DIR] [--force]

    Create basic BIDS files and directories.

    Based on the material provided by
    https://github.com/bids-standard/bids-starter-kit

options:
  -h, --help            show this help message and exit
  -o OUTPUT_DIR, --output_dir OUTPUT_DIR
                        Output BIDS directory. Default: [/home/runner/work/Dcm2Bids/Dcm2Bids]
  --force               Force overwriting of the output files.

Documentation at https://unfmontreal.github.io/Dcm2Bids/

Helper⚓︎

To build the configuration file, you need to have examples of sidecar files. You can use dcm2bids_helper with the DICOMs of one participant. It will launch dcm2niix and save the result inside the tmp_dcm2bids/helper directory by default.

1
dcm2bids_helper -d DICOM_DIR [-o OUTPUT_DIR]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
usage: dcm2bids_helper [-h] -d DICOM_DIR [DICOM_DIR ...] [-o OUTPUT_DIR]
                       [-n [NEST]] [--force]
                       [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

Converts DICOM files to NIfTI files including their JSON sidecars in a
temporary directory which can be inspected to make a dcm2bids config file.

options:
  -h, --help            show this help message and exit
  -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
                        DICOM directory(ies) or archive(s) (tar, tar.bz2, tar.gz or zip).
  -o OUTPUT_DIR, --output_dir OUTPUT_DIR
                        Output directory. (Default: [/home/runner/work/Dcm2Bids/Dcm2Bids/tmp_dcm2bids/helper]
  -n [NEST], --nest [NEST]
                        Nest a directory in <output_dir>. Useful if many helper runs are needed
                        to make a config file due to slight variations in MRI acquisitions.
                        Defaults to DICOM_DIR if no name is provided.
                        (Default: [False])
  --force, --force_dcm2bids
                        Force command to overwrite existing output files.
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set logging level to the console. [INFO]

Documentation at https://unfmontreal.github.io/Dcm2Bids/

  1. For each acquisition, dcm2niix creates an associated .json file, containing information from the dicom header. These are known as sidecars. These are the sidecars dcm2bids uses to filter the groups of acquisitions.

    To define this filtering you will probably need to review these sidecars. You can generate all the sidecars for an individual participant using dcm2bids_helper. ↩