Skip to main content

Dcm2Bids helps you to reorganise the NIfTI files from dcm2niix into the Brain Imaging Data Structure (BIDS).

Before using this software, learn more about BIDS and read the specifications.

Install

git clone https://github.com/cbedetti/Dcm2Bids
cd Dcm2Bids
python setup.py install

Dependencies

  • Python 2 or 3 with the future module

  • dcm2niix : DICOM to NIfTI conversion is done with dcm2niix. See github for source code or NITRC for compiled versions.

Usage

usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION]
                -c CONFIG [-o OUTPUT_DIR] [--forceDcm2niix] [--clobber]
                [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a ANONYMIZER]

optional arguments:
  -h, --help            show this help message and exit
  -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
                        DICOM directory(ies)
  -p PARTICIPANT, --participant PARTICIPANT
                        Participant code
  -s SESSION, --session SESSION
                        Session code
  -c CONFIG, --config CONFIG
                        JSON configuration file (see example/config.json)
  -o OUTPUT_DIR, --output_dir OUTPUT_DIR
                        Output BIDS directory, Default: current directory
  --forceDcm2niix       Overwrite old temporary dcm2niix output if it exists
  --clobber             Overwrite output if it exists
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set logging level
  -a ANONYMIZER, --anonymizer ANONYMIZER
                        Anonymize each anat image by passing it to this shell
                        command (e.g., pydeface.py - the call syntax must be
                        anonymizer inputfile outputfile)

example:
  dcm2bids -d sourcedata/s101/DICOM/ -s S101 -c code/config_dcm2bids.json

You need to build the configuration file of your study to let dcm2bids associate your acquisitions through BIDS sidecar. Every study is different and this step needs a little bit of work.

Sidecar files are JSON files with meta informations about the acquisition. These are created automatically with dcm2niix.

The dcm2bids configuration file uses also the JSON format and one example is provided in the example directory.

Configuration file

{
    "descriptions": [
        {
            "dataType": "anat",
            "modalityLabel": "T2w",
            "criteria": {
                "SeriesDescription": "*T2*",
                "EchoTime": 0.1
            }
        },
        {
            "dataType": "func",
            "modalityLabel": "bold",
            "customLabels": "task-rest",
            "criteria": {
                "SidecarFilename": "006*"
            }
        }
    ]
}

The descriptions field is a list of description, each describing some acquisition. In this example, the configuration describes two acquisitions, a T2 weigthed and resting state fMRI.

dataType

It is a mandatory field. Here is a definition from bids_specs1.0.2 pdf:

A functional group of different types of MRI data. In BIDS we define four 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.)

modalityLabel

It is a mandatory field. It describes the modality of the acquisition like T1w, T2w or bold.

customLabels

It is an optional field. For some acquisitions, you need to add information in the file name. For resting state fMRI, it is usally task-rest.

To know more on how to set these fields, read the BIDS specifications.

criteria

dcm2bids will try to match the sidecars of dcm2niix to the descriptions of the configuration file. The values you enter inside the criteria dictionnary are patterns. They will be compared to the corresponding key of the sidecar.

The pattern matching is shell-style. It’s possible to use wildcard *, single character ? etc … Please have a look at the GNU documentation to know more.

For example, in the first description, the pattern *T2* will be compared to the value of SeriesDescription of a sidecar. AXIAL_T2_SPACE will be a match, AXIAL_T1 won’t.

dcm2bids create a SidecarFilename key if you prefer to also match with the filename of the sidecar.

You can enter several criteria. All criteria must match for a description to be link to a sidecar.

Helper

dcm2bids_helper -d DICOM_DIR

To build the configuration file, you need to have a example of the sidecars. You can use dcm2bids_helper with the DICOMs of one participant. It will launch dcm2niix and save the result inside the tmp_dcm2bids/dcm2niix-example of the output directory.

Output

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

Sidecars with one matching description will be convert 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 the custom label run- to the filename.

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

Metadata

Release files for dcm2bids 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dcm2bids 1.0.1
File Size Uploaded Provenance Actions
dcm2bids-1.0.1.tar.gz 11.2 kB Without provenance Details for dcm2bids-1.0.1.tar.gz

Release files / dcm2bids-1.0.1.tar.gz

Download URL dcm2bids-1.0.1.tar.gz
Size 11.2 kB
Tags Source
SHA-256 checksum
How to use checksums
be45b6e6d48fa78f0a6590b2920cdace134cce816d494241603eebb17c26a9e1
BLAKE2b-256 checksum
How to use checksums
c6c33741225b049fc8417933618c96b18dc0f55d776a1ea3fbaa07f87556a0f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for dcm2bids 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page