Skip to main content

HeuDiConv

a heuristic-centric DICOM converter

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

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:

https://raw.githubusercontent.com/nipy/heudiconv/master/figs/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:

https://raw.githubusercontent.com/nipy/heudiconv/master/figs/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 “CLI Reference” 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/ .

Metadata

Release files for heudiconv 1.6.0

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

Source distribution (sdist)

Source distribution for heudiconv 1.6.0
File Size Uploaded Provenance Actions
heudiconv-1.6.0.tar.gz 9.2 MB Without provenance Details for heudiconv-1.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for heudiconv 1.6.0
File Interpreter ABI Platform Actions
heudiconv-1.6.0-py3-none-any.whl Python 3 none any Details for heudiconv-1.6.0-py3-none-any.whl

Total release size: 18.4 MB

Release files / heudiconv-1.6.0.tar.gz

Download URL heudiconv-1.6.0.tar.gz
Size 9.2 MB
Tags Source
SHA-256 checksum
How to use checksums
64b865c35d5b39212965fd7b5977249fcffd9f300492e46336118b60b224b3a9
BLAKE2b-256 checksum
How to use checksums
28aef645ec4e265571a3da4f7de3f7e94329a8dea9e853bf7003dd94dd5062a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / heudiconv-1.6.0-py3-none-any.whl

Download URL heudiconv-1.6.0-py3-none-any.whl
Size 9.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
39cac360273d7d35ff6efb524c806176623a3dfced2d38c77d475011a8c30051
BLAKE2b-256 checksum
How to use checksums
e72b9dc41b86d406ed4eef28c0b2be8d4de7becb3227dbaafac4af9babacd7eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Security for heudiconv 1.6.0

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.

Release history Release notifications | RSS feed

This release

1.6.0 This release

2 release files No provenance

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