DOCSEARCHbyAlgolia
Submit Docs

HeuDiConv (Heuristic DICOM Converter)

repository·master·Indexed 43 days ago

https://github.com/nipy/heudiconv

A flexible, heuristic-centric DICOM to NIfTI converter that organizes brain imaging data into structured layouts, such as BIDS. It utilizes Python-based heuristics and the dcm2niix engine to process DICOM files and convert them into user-defined paths.

Tokens
20.2K
Snippets
71
Records
99
Agent score
55%

What's inside HeuDiConv

  1. What is HeuDiConv?

    master

    HeuDiConv is a heuristic-centric DICOM converter designed to organize brain imaging data into structured directory layouts.

    Key features include:

    • Customizable Heuristics: Uses Python-based heuristics to define flexible directory layouts and naming schemes.
    • Selective Conversion: Only converts necessary DICOM files and ignores others in a directory.
    • Fast Conversion: Utilizes dcm2niix under the hood for high-performance NIfTI conversion.
    • Provenance Tracking: Tracks the conversion process from DICOM to NIfTI using the W3C PROV format.
    • BIDS Assistance: Helps in converting data to the Brain Imaging Data Structure (BIDS) format.
    • DataLad Integration: Works with DataLad to manage version control (git/git-annex) and handle sensitive information (e.g., non-defaced anatomicals).

  2. How HeuDiConv works: The conversion workflow

    master

    HeuDiConv takes a file tree of DICOMs and produces a restructured file tree of NIfTI files along with accompanying metadata. The core mechanism is a Python file called a heuristic, which defines how to read the input structure and how to name the resulting files.

    There are two main ways to run a conversion:

    1. Automatic Conversion: Runs the conversion immediately, producing a .heudiconv directory that stores the parameters used.
    2. Manual/Customized Conversion:
      • Generate default parameters.
      • Edit the parameters to customize file naming (using <something>.edit.text mapping files).
      • Re-run heudiconv to perform the actual conversion with the customized settings.

  3. Reproin scanner sequence naming convention

    master

    Reproin uses a specific naming scheme for scanner sequences that maps to BIDS entities. Sequence names are composed of ordered key-value pairs (entities) joined by underscores (_), where keys and values are joined by dashes (-).

    General Scheme: sequence type-modality label session-session name task-task name acquisition-acquisition detail run-run number direction-direction label

    Example: func-bold_ses-pre_task-faces_acq-1mm_run-01_dir-AP

    Modality Defaults: Reproin simplifies names by using predictable defaults for certain seqtype keys:

    • anat: Defaults to T1W (e.g., anat becomes sub-001_T1w.nii.gz).
    • fmap: Defaults to epi (e.g., fmap_dir-PA becomes sub-001_dir-PA_epi.nii.gz).
    • func: Defaults to bold (e.g., func_task-rest becomes sub-001_task-rest_bold.nii.gz).

    Note on Sessions: If multiple sessions exist, you only need to include the session name (e.g., ses-pre) in a single sequence name (usually the scout/localizer). Reproin will propagate that session information to other sequences in the same Program.

  4. Understand the Reproin output directory structure

    master

    When using the reproin converter, HeuDiConv produces a specific hierarchy. By default, it nests the dataset under two levels: Region (e.g., Patterson) and Exam (e.g., Coben), based on the DICOM "Study Description" field. You can override this hierarchy using the --locator PATH option.

    Key components of the output:

    • sourcedata/: Contains tarred gzipped (.tgz) sets of DICOM images corresponding to the generated NIfTI images.
    • sub-XXX/: Contains the BIDS-compliant subject data (e.g., anat, dwi, fmap, func).
    • .heudiconv/: A hidden directory (e.g., REPROIN/data/Patterson/Coben/.heudiconv) containing derived mapping data used for inspection or re-conversion.

    Example structure:

    data
└── Patterson
    └── Coben
        ├── sourcedata
        │   └── sub-001
        │       ├── anat
        │       └── ...
        └── sub-001
            ├── anat
            ├── dwi
            ├── fmap
            └── func

  5. Understand the .heudiconv hidden directory

    master

    When you run HeuDiConv, it creates a hidden .heudiconv directory within your output folder (e.g., Nifti/.heudiconv). This directory contains:

    • A skeleton heuristic.py file.
    • A dicominfo.tsv file.

    Provenance and Troubleshooting

    • Provenance: The directory acts as a detailed record of your conversions, storing a copy of the heuristic.py module used for each subject and session. This is valuable for data provenance.
    • Troubleshooting Warning: If you rerun heuristic.py for a subject/session that has already been processed, HeuDiConv may quietly use the conversion routines stored in the .heudiconv directory instead of your updated code.
    • Resetting: To ensure you are running your latest heuristic.py logic, you can remove the .heudiconv directory entirely. Your code in the main project directory will still function.

  6. Use tuples as criteria in heuristic.py

    master

    Some DICOM metadata fields, such as image_type, are returned as Python tuple objects rather than strings or numbers. Because they are tuples, you cannot use substring matching (e.g., 'TEST' in s.image_type will fail if the tuple contains 'TTEST'). Instead, you must check for exact membership or equality.

    To identify the data type of a column during development, add print(type(s.column_name)) inside your heuristic loop.

    Example: Filtering by tuple membership

    if ('ASL_3D_tra_iso' == s.protocol_name) and ('TTEST' in s.image_type):
    info[asl_der].append(s.series_id)
    if ('ASL_3D_tra_iso' == s.protocol_name) and ('TTEST' in s.image_type):
    info[asl_der].append(s.series_id)

  7. Use existing or custom heuristics

    master

    HeuDiConv provides several ways to handle data conversion logic:

    • Existing Heuristics: Use built-in heuristics (e.g., convertall which extracts standard metadata from all matching DICOMs).
    • Custom Heuristics: For retrospective studies, you can write a custom Python heuristic following the documentation guides.
    • ReproIn Heuristic: A generic and powerful heuristic that can be used for almost any study. For prospective studies, you can name your sequences following the ReproIn convention. For retrospective studies, you can often create a versatile heuristic by providing remappings into ReproIn.

  8. Manage subject metadata in participants.tsv

    master

    HeuDiConv automatically extracts age and sex from DICOM headers into the participants.tsv file.

    If the extracted information is incorrect (due to placeholder values in DICOM or privacy masking), you must manually edit the values in the participants.tsv file in your BIDS output directory. You can also use a DICOM editor like Horos to correct the source headers before running HeuDiConv.

  9. Use HeuDiConv containers via ReproNim and DataLad (YODA style)

    master

    ReproNim provides a collection of Singularity container images (including BIDS-Apps) via a DataLad dataset. In this collection, the HeuDiConv image is named nipy-heudiconv.

    Workflow:

    1. Install the DataLad dataset located at ///repronim/containers.
    2. Use the datalad containers-run command to execute the containers.

    macOS Support: When using datalad containers-run with the repronim/containers collection, the helpers automatically handle running Singularity containers via Docker on macOS.

  11. Install HeuDiConv via Docker

    master

    If you have Docker installed, you can pull the official HeuDiConv container images from Docker Hub.

    Note on Versioning: To maintain data provenance, avoid using the latest tag for production workflows. Instead, use an explicit version tag and record it alongside your produced data. Use latest only for testing.

    To pull the latest release:

    docker pull nipy/heudiconv:latest

    Alternatively, HeuDiConv is available via the repronim/reproin image provided by the ReproIn heuristic project.

    docker pull nipy/heudiconv:latest

  12. Run heudiconv using a Docker container

    master

    If you are using the Docker container instead of a local installation, you must prefix all heudiconv commands with docker run nipy/heudiconv:latest. For example, to check the version, use:

    docker run nipy/heudiconv:latest --version
    docker run nipy/heudiconv:latest [heudiconv options]