fw-gear-dcm2niix 2.1.0

A Flywheel Gear for implementing Chris Rorden's dcm2niix for converting DICOM (or PAR/REC) to NIfTI (or NRRD).

dcm2niix Gear

Overview

A Flywheel Gear for implementing Chris Rorden's dcm2niix for converting DICOM (or PAR/REC) to NIfTI (or NRRD).

Summary

Chris Rorden's dcm2niix is a popular tool for converting images from the complicated formats used by scanner manufacturers (DICOM, PAR/REC) to the NIfTI format used by many scientific tools. Alternatively, this tool also outputs the NRRD format. dcm2niix works for all modalities (CT, MRI, PET, SPECT) and sequence types.

Cite

dcm2niix doi: 10.1016/j.jneumeth.2016.03.001

License

License: Other

Chris Rorden's dcm2niix is provided through its license.

Classification

Category: converter

Gear Level:

• Project
• Subject
• Session
• Acquisition
• Analysis

---

[[TOC]]

---

Inputs

• Required
  • Name: dcm2niix_input
  • Type: file, dicom or parrec
  • Optional: False
  • Description: Main input file for the Gear. This can be either a DICOM archive (<dicom>.zip), a PAR/REC archive (<parrec>.zip), or a single PAR file (image.PAR or image.par).
• Optional
  • Name: rec_file_input
  • Type: file, parrec
  • Optional: True
  • Description: If dcm2niix_input is a single PAR file, the corresponding REC file (image.REC or image.rec) for one PAR/REC file pair as inputs to the Gear.

Config

• anonymize_bids
  • Name: anonymize_bids
  • Type: Boolean
  • Description: Anonymize BIDS. Options: true (default), false. bids_sidecar config option must be enabled (i.e., 'y' or 'o' options).
  • Default: True
• bids_sidecar
  • Name: bids_sidecar
  • Type: string
  • Description: Output BIDS sidecar in JSON format. Options are 'y'=yes(default), 'n'=no, 'o'=only (whereby no NIfTI file will be generated). Note: bids_sidecar is always invoked when running dcm2niix to be used as metadata. User configuration preference is handled after acquiring metadata. If JSON file not present, NIfTI(s), even if produced may not be copied into final output.
  • Default: "y"
• coil_combine
  • Name: coil_combine
  • Type: Boolean
  • Description: For sequences with individual coil data, saved as individual volumes, this option will save a NIfTI file with ONLY the combined coil data (i.e., the last volume). Options: true, false (default). WARNING: Expert Option. We make no effort to check for independent coil data; we trust that you know what you are asking for if you have selected this option.
  • Default: False
• comment
  • Name: comment
  • Type: string
  • Description: If non-empty, store comment as NIfTI aux_file. Options: non-empty string, 24 characters maximum. Note: The 24 character comment is placed in (1) all NIfTI output files in the aux_file variable. You can use fslhdr to access the NIfTI header data and see this comment; and (2) all JSON files (i.e., BIDS sidecars), which means the comment is stored as metadata for all associated output files and would be included in the 'bids_sidecar' file, if invoked.
  • Default: ""
• compress_images
  • Name: compress_images
  • Type: string
  • Description: Gzip compress images. Options: 'y'=yes (default), 'i'=internal, 'n'=no, '3'=no,3D. Note: If option '3' is chosen, the filename flag will be set to '-f %p_%s' to prevent overwriting files. Tip: For .nrrd output, select 'n'.
  • Default: "y"
• compression_level
  • Name: compression_level
  • Type: number, minimum:1, maximum:9
  • Description: Set the gz compression level. Options: 1 (fastest) to 9 (smallest), 6 (default).
  • Default: 6
• convert_only_series
  • Name: convert_only_series
  • Type: string
  • Description: Selectively convert by series number - can be used up to 16 times. Options: 'all' (default), space-separated list of series numbers (e.g., '2 12 20'). WARNING: Expert Option. We trust that if you have selected this option, you know what you are asking for.
  • Default: "all"
• crop
  • Name: crop
  • Type: Boolean
  • Description: Crop 3D T1 images. Options: true, false (default).
  • Default: False
• dcm2niix_verbose
  • Name: dcm2niix_verbose
  • Type: Boolean
  • Description: Whether to include verbose output from dcm2niix call. Options: true, false (default).
  • Default: False
• debug
  • Name: debug
  • Type: Boolean
  • Description: Log debug messages.
  • Default: False
• decompress_dicoms
  • Name: decompress_dicoms
  • Type: Boolean
  • Description: Decompress DICOM files before conversion. This will perform decompression using gdcmconv and then perform the conversion using dcm2niix. Options: true, false (default).
  • Default: False
• filename
  • Name: filename
  • Type: string
  • Description: Output filename template. Options: %a=antenna (coil) name, %b=basename, %c=comments, %d=series description, %e=echo number, %f=folder name, %i=ID of patient, %j=seriesInstanceUID, %k=studyInstanceUID, %m=manufacturer, %n=name of patient, %o=mediaObjectInstanceUID, %p=protocol, %r=instance number, %s=series number, %t=time, %u=acquisition number, %v=vendor, %x=study ID, %z=sequence name tag(0018,0024), %q sequence name tag(0018,1020). Defaults: dcm2niix tool %f_%p_%t_%s. Tip: A more informative filename can be useful for downstream BIDS curation by simply accessing relevant information in the extracted filename. For example, including echo number or protocol.
  • Default: "%f_%p_%t_%s"
• ignore_derived
  • Name: ignore_derived
  • Type: Boolean
  • Description: Ignore derived, localizer, and 2D images. Options: true, false (default).
  • Default: False
• ignore_errors
  • Name: ignore_errors
  • Type: Boolean
  • Description: Ignore dcm2niix errors and the exit status, and preserve outputs. Options: true, false (default). By default, when dcm2niix exits non-zero, outputs are not preserved. WARNING: Expert Option. We trust that if you have selected this option, you know what you are asking for.
  • Default: False
• lossless_scaling
  • Name: lossless_scaling
  • Type: string
  • Description: Losslessly scale 16-bit integers to use dynamic range. Options: 'y'=scale, 'n'=no, but unit16->int16, 'o'=original (default).
  • Default: "o"
• merge2d
  • Name: merge2d
  • Type: number
  • Description: Merge 2D slices from the same series regardless of study time, echo, coil, orientation, etc. Options: 0=no, 1=yes, 2=auto (default)
  • Default: 2
• output_nrrd
  • Name: output_nrrd
  • Type: Boolean
  • Description: Export as NRRD instead of NIfTI. Options: true, false (default). Tip: To export .nrrd, change the compress_images config option to 'n'; otherwise, the output will split into two files (.raw.gz and .nhdr).
  • Default: False
• philips_scaling
  • Name: philips_scaling
  • Type: Boolean
  • Description: Philips precise float (not display) scaling. Options: true (default), false.
  • Default: True
• remove_incomplete_volumes
  • Name: remove_incomplete_volumes
  • Type: Boolean
  • Description: Remove incomplete trailing volumes for 4D scans aborted mid-acquisition before dcm2niix conversion. Options: true, false (default).
  • Default: False
• sanitize_filename
  • Name: sanitize_filename
  • Type: Boolean
  • Description: Sanitize filename by removing invalid characters.
  • Default: True
• save_sidecar_as_metadata
  • Name: save_sidecar_as_metadata
  • Type: string
  • Description: Whether to save sidecar information in file.info metadata to be compatible with previous BIDS workflow. Options: 'y'=yes, 'n'=no, or leave blank (default). If left blank, gear will check project.info and attempt to identify if the previous BIDS curation method is being utilized for the parent project.
  • Default: ""
• single_file_mode
  • Name: single_file_mode
  • Type: Boolean
  • Description: Single file mode, do not convert other images in the folder. Options: true, false (default).
  • Default: False
• tag
  • Name: tag
  • Type: string
  • Description: The tag to be added to one output file upon run completion.
  • Default: ""
• tag_on_failure
  • Name: tag_on_failure
  • Type: Boolean
  • Description: If True, tag the input file with "dcm2nii-failure" if the gear fails to generate any nifti images.
  • Default: False
• text_notes_private
  • Name: text_notes_private
  • Type: Boolean
  • Description: Text notes include private patient details. Options: true, false (default).
  • Default: False

Outputs

Files

• Default

  • Name: <filename>.nii.gz
  • Type: Compressed NIfTI

• Modifications:

  • If compress_images == "n":
    • Name: <filename>.nii
    • Type: NIfTI
  • If output_nrrd == True:
    • Name: <filename>.nrrd
    • Type: NRRD
    • Note: If compress_images == y, output will split into two files (.raw.gz and .nhdr).
  • If bids_sidecar == "y":
    • Name: <filename>.json
    • Type: JSON

Metadata

The dcm2niix tool extracts DICOM tags and collates these into a JSON file (i.e., the BIDS sidecar). What is extracted depends on the input data. If present, the following DICOM tags are extracted via the dcm2niix tool and applied as metadata to the output files of the dcm2niix Gear:

• AcquisitionMatrixPE
• AcquisitionTime
• BaseResolution
• BodyPartExamined
• CoilString
• ConversionSoftware
• ConversionSoftwareVersion
• DeviceSerialNumber
• EchoTime
• EchoTrainLength
• EffectiveEchoSpacing
• EstimatedEffectiveEchoSpacing
• EstimatedTotalReadoutTime
• FlipAngle
• FrameTimesStart
• ImageComments
• ImageOrientationPatientDICOM
• ImageType
• ImagingFrequency
• InPlanePhaseEncodingDirectionDICOM
• InstitutionAddress
• InstitutionalDepartmentName
• InstitutionName
• InternalPulseSequenceName
• MagneticFieldStrength
• Manufacturer
• ManufacturersModelName
• Modality
• MRAcquisitionType
• ParallelReductionFactorInPlane
• ParallelReductionOutOfPlane
• PartialFourier
• PatientPosition
• PercentPhaseFOV
• PercentSampling
• PhaseEncodingAxis
• PhaseEncodingDirection
• PhaseEncodingPolarityGE
• PhaseEncodingSteps
• PhaseResolution
• PhilipsRescaleIntercept
• PhilipsRescaleSlope
• PhilipsRWVIntercept
• PhilipsRWVSlope
• PixelBandwidth
• ProcedureStepDescription
• ProtocolName
• PulseSequenceDetails
• ReceiveCoilName
• ReconMatrixPE
• RepetitionTime
• SAR
• ScanningSequence
• ScanOptions
• SequenceName
• SequenceVariant
• SeriesDescription
• SeriesNumber
• ShimSetting
• SliceThickness
• SliceTiming
• SoftwareVersions
• SpacingBetweenSlices
• StationName
• TotalReadoutTime
• TxRefAmp
• UsePhilipsFloatNotDisplayScaling
• WaterFatShift

If the Gear inputs are DICOMs, additional metadata is captured. If present, the following DICOM tags are extracted using Pydicom and applied as metadata to the output files of the dcm2niix Gear:

• AcquisitionDuration, tag(0018,9073)
• AcquisitionMatrix
• Columns
• InPlanePhaseEncodingDirection
• PercentPhaseFieldOfView
• PercentSampling
• PixelSpacing
• PrepulseDelay, tag(2001,101B)
• PrepulseType, tag(2001,101C)
• Rows
• ScanningTechnique, tag(2001,1020)
• ScanType, tag(2005,10A1)
• SliceOrientation, tag(2001,100B)
• SpacingBetweenSlices
• NumberOfEchos, tag(2001,1014)
• NumberOfSlices, tag(2001,1018)
• NumberOfTemporalPositions

All metadata applied to the output files from the dcm2niix Gear are extracted from the raw DICOM tags. As such, the units of measurement remain consistent with the DICOM standard.

Tags

If a value is provided in the "tag" config option, that tag will be added to the input file on completion of the gear execution.

If the "tag_on_failure" config option is checked, the tag "dcm2niix-failure" will be added to the input file if the gear does not complete successfully.

The gear will REMOVE a "dcm2niix-failure" tag from a file if it is present and the gear completes successfully.

Workflow

graph LR
    dz["dicom.zip"] --> A[One Required] ===> dcm[dcm2niix_input]
    dt["dicom.tgz"] --> A
    pz["parrec.zip"] --> A
    pt["parrec.tgz"] --> A
    par["image.par"] --> A
    rec["image.rec"] -.->|optional| B[rec_file_input]
    dcm ==> gear
    B -.-> gear
    C["configuration"] ==> gear{{Dcm2niix Gear}}
    gear ==>|default| E["filename.nii.gz"]
    gear -.->|if diffusion| F["filename.bval, filename.bvec"]
    gear -.->|if not compress_images| G["filename.nii"]
    gear -.->|if output_nrrd and not compress_images| H["filename.nrrd"]
    gear -.->|if output_nrrd and compress_images| I["filename.nhdr, filename.raw.gz"]
    gear -.->|if bids_sidecar| J["filename.json"]

Description of workflow

1. Upload compressed DICOM or PAR/REC file(s) to container
2. Select file as dcm2niix_input to gear, with optional rec_file_input for .rec file if dcm2niix_input is a .par file
3. Gear converts files to NIfTI (or NRRD) as specified by configuration

FAQ

FAQ.md

Contributing

[For more information about how to get started contributing to this gear, check out CONTRIBUTING.md.]