a heuristic-centric DICOM converter
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, not everything 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).
In a nutshell -- heudiconv operates using a heuristic which, given metadata from DICOMs, would decide how to name resultant (from conversion using dcm2niix) files. Heuristic convertall <https://github .com/nipy/heudiconv/blob/master/heudiconv/heuristics/convertall.py> could also be used to actually have no real heuristic and simply establish your own conversion mapping by editing produced mapping files. In most use-cases of retrospecive study data conversion you would need to create your custom heuristic following existing heuristics as examples and/or referring to "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 very versatile heuristic by simply providing remappings into ReproIn as shown in this issue (documentation is coming).
Having decided on heuristic you could use command line:
heudiconv -f HEURISTIC-FILE-OR-NAME -o OUTPUT-PATH --files INPUT-PATHswith various additional options (see heudiconv --help or "Usage" in documentation) to tune its behavior, to convert your data. See e.g. ReproIn conversion invocation examples.
Please also see user tutorials in documentation.
Please use Zenodo record for your specific version of HeuDiConv. We also support gathering all relevant citations via DueCredit.
HeuDiConv sources are managed with Git on GitHub. Please file issues and suggest changes via Pull Requests.
HeuDiConv requires installation of dcm2niix and optionally DataLad.
For development you will need a non-shallow clone (so there is a recent released tag) of the aforementioned repository. You can then install all necessary development requirements using pip install -r dev-requirements.txt. Testing is done using pytest. Releases are packaged using Intuit auto. Workflow for releases and preparation of Docker images is in .github/workflows/release.yml.