HeuDiConv

a heuristic-centric DICOM converter

Our Docker image GitHub Actions (test) CodeCoverage Readthedocs Zenodo (latest) Debian Unstable Gentoo (::science) PyPI

About

heudiconv is a flexible DICOM converter for organizing brain imaging data into structured directory layouts.

  • It allows flexible directory layouts and naming schemes through customizable heuristics implementations.

  • It only converts the necessary DICOMs and ignores everything else in a directory.

  • You can keep links to DICOM files in the participant layout.

  • Using dcm2niix under the hood, it’s fast.

  • It can track the provenance of the conversion from DICOM to NIfTI in W3C PROV format.

  • It provides assistance in converting to BIDS.

  • It integrates with DataLad to place converted and original data under git/git-annex version control while automatically annotating files with sensitive information (e.g., non-defaced anatomicals, etc).

Heudiconv can be inserted into your workflow to provide automatic conversion as part of a data acquisition pipeline, as seen in the figure below:

_images/environment.png

Installation

See our installation page on heudiconv.readthedocs.io .

HOWTO 101

In a nutshell – heudiconv is given a file tree of DICOMs, and it produces a restructured file tree of NifTI files (conversion handled by dcm2niix) with accompanying metadata files. The input and output structure is as flexible as your data, which is accomplished by using a Python file called a heuristic that knows how to read your input structure and decides how to name the resultant files. You can run your conversion automatically (which will produce a .heudiconv directory storing the used parameters), or generate the default parameters, edit them to customize file naming, and continue conversion via an additional invocation of heudiconv:

_images/workflow.png

heudiconv comes with existing heuristics which can be used as is, or as examples. For instance, the Heuristic convertall extracts standard metadata from all matching DICOMs. heudiconv creates mapping files, <something>.edit.text which lets researchers simply establish their own conversion mapping.

In most use-cases of retrospective study data conversion, you would need to create your custom heuristic following the examples and the “Heuristic” section in the documentation. Note that ReproIn heuristic is generic and powerful enough to be adopted virtually for any study: For prospective studies, you would just need to name your sequences following the ReproIn convention, and for retrospective conversions, you often would be able to create a new versatile heuristic by simply providing remappings into ReproIn as shown in this issue (documentation is coming).

Having decided on a heuristic, you could use the command line:

heudiconv -f HEURISTIC-FILE-OR-NAME -o OUTPUT-PATH --files INPUT-PATHs

with various additional options (see heudiconv --help or “Usage” in documentation) to tune its behavior to convert your data.

For detailed examples and guides, please check out ReproIn conversion invocation examples and the user tutorials in the documentation.

How to cite

Please use Zenodo record for your specific version of HeuDiConv. We also support gathering all relevant citations via DueCredit.

How to contribute

For a detailed into, see our contributing guide.

Our releases are packaged using Intuit auto, with the corresponding workflow including Docker image preparation being found in .github/workflows/release.yml.

3-rd party heuristics

Support

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/nipy/heudiconv/issues.

If you have a problem or would like to ask a question about how to use heudiconv, please submit a question to NeuroStars.org with a heudiconv tag. NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.

All previous heudiconv questions are available here: http://neurostars.org/tags/heudiconv/

Contributing to HeuDiConv

Files organization

  • heudiconv/ is the main Python module where major development is happening, with major submodules being:

    • cli/ - wrappers and argument parsers bringing the HeuDiConv functionality to the command line.

    • external/ - general compatibility layers for external functions HeuDiConv depends on.

    • heuristics/ - heuristic evaluators for workflows, pull requests here are particularly welcome.

  • docs/ - documentation directory.

  • utils/ - helper utilities used during development, testing, and distribution of HeuDiConv.

How to contribute

The preferred way to contribute to the HeuDiConv code base is to fork the main repository on GitHub.

If you are unsure what that means, here is a set-up workflow you may wish to follow:

  1. Fork the project repository on GitHub, by clicking on the “Fork” button near the top of the page — this will create a copy of the repository writeable by your GitHub user.

  2. Set up a clone of the repository on your local machine and connect it to both the “official” and your copy of the repository on GitHub:

    git clone git://github.com/nipy/heudiconv
    cd heudiconv
    git remote rename origin official
    git remote add origin git://github.com/YOUR_GITHUB_USERNAME/heudiconv
    
  3. When you wish to start a new contribution, create a new branch:

    git checkout -b topic_of_your_contribution
    
  4. When you are done making the changes you wish to contribute, record them in Git:

    git add the/paths/to/files/you/modified can/be/more/than/one
    git commit
    
  1. Push the changes to your copy of the code on GitHub, following which Git will provide you with a link which you can click to initiate a pull request:

    git push -u origin topic_of_your_contribution
    

(If any of the above seems overwhelming, you can look up the Git documentation on the web.)

Releases and Changelog

HeuDiConv uses the auto tool to generate the changelog and automatically release the project.

auto is used in the HeuDiConv GitHub actions, which monitors the labels on the pull request. HeuDiConv automation can add entries to the changelog, cut releases, and push new images to dockerhub.

The following pull request labels are respected:

  • major: Increment the major version when merged

  • minot: Increment the minot version when merged

  • patch: Increment the patch version when merged

  • skip-release: Preserve the current version when merged

  • release: Create a release when this pr is merged

  • internal: Changes only affect the internal API

  • documentation: Changes only affect the documentation

  • tests: Add or improve existing tests

  • dependencies: Update one or more dependencies version

  • performance: Improve performance of an existing feature

Development environment

We support Python 3 only (>= 3.7).

Dependencies which you will need are listed in the repository. Note that you will likely have these will already be available on your system if you used a package manager (e.g. Debian’s apt-get, Gentoo’s emerge, or simply PIP) to install the software.

Development work might require live access to the copy of HeuDiConv which is being developed. If a system-wide release of HeuDiConv is already installed, or likely to be, it is best to keep development work sandboxed inside a dedicated virtual environment. This is best accomplished via:

cd /path/to/your/clone/of/heudiconv
mkdir -p venvs/dev
python -m venv venvs/dev
source venvs/dev/bin/activate
pip install -e .[all]

Documentation

To contribute to the documentation, we recommend building the docs locally prior to submitting a patch.

To build the docs locally:

  1. From the root of the heudiconv repository, pip install -r docs/requirements.txt

  2. From the docs/ directory, run make html

Additional Hints

It is recommended to check that your contribution complies with the following rules before submitting a pull request:

  • All public functions (i.e. functions whose name does not start with an underscore) should have informative docstrings with sample usage presented as doctests when appropriate.

  • Docstrings are formatted in NumPy style.

  • Lines are no longer than 120 characters.

  • All tests still pass:

    cd /path/to/your/clone/of/heudiconv
    pytest -vvs .
    
  • New code should be accompanied by new tests.

Contents