{"id":13812696,"url":"https://github.com/nipy/heudiconv","last_synced_at":"2025-10-21T20:03:46.349Z","repository":{"id":1378655,"uuid":"42650211","full_name":"nipy/heudiconv","owner":"nipy","description":"Flexible DICOM conversion into structured directory layouts","archived":false,"fork":false,"pushed_at":"2025-05-13T18:30:14.000Z","size":11980,"stargazers_count":253,"open_issues_count":205,"forks_count":131,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-13T19:42:51.036Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://heudiconv.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nipy.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":".zenodo.json"}},"created_at":"2015-09-17T10:34:11.000Z","updated_at":"2025-05-13T18:30:18.000Z","dependencies_parsed_at":"2024-01-04T19:41:47.346Z","dependency_job_id":"0db62621-4dd9-4e57-a102-99b617cda1d3","html_url":"https://github.com/nipy/heudiconv","commit_stats":{"total_commits":1177,"total_committers":56,"mean_commits":"21.017857142857142","dds":0.6355140186915889,"last_synced_commit":"502bf49d9532d82546283fe31a5f1398ba3acc66"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipy%2Fheudiconv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipy%2Fheudiconv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipy%2Fheudiconv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipy%2Fheudiconv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nipy","download_url":"https://codeload.github.com/nipy/heudiconv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254239481,"owners_count":22037714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T04:00:54.588Z","updated_at":"2025-10-21T20:03:46.337Z","avatar_url":"https://github.com/nipy.png","language":"Python","funding_links":[],"categories":["Data Conversion and Standards","Libraries"],"sub_categories":["Python"],"readme":"=============\n**HeuDiConv**\n=============\n\n`a heuristic-centric DICOM converter`\n\n.. image:: https://joss.theoj.org/papers/10.21105/joss.05839/status.svg\n   :target: https://doi.org/10.21105/joss.05839\n   :alt: JOSS Paper\n\n.. image:: https://img.shields.io/badge/docker-nipy/heudiconv:latest-brightgreen.svg?logo=docker\u0026style=flat\n  :target: https://hub.docker.com/r/nipy/heudiconv/tags/\n  :alt: Our Docker image\n\n.. image:: https://github.com/nipy/heudiconv/actions/workflows/test.yml/badge.svg?event=push\n  :target: https://github.com/nipy/heudiconv/actions/workflows/test.yml\n  :alt: GitHub Actions (test)\n\n.. image:: https://codecov.io/gh/nipy/heudiconv/branch/master/graph/badge.svg\n  :target: https://codecov.io/gh/nipy/heudiconv\n  :alt: CodeCoverage\n\n.. image:: https://readthedocs.org/projects/heudiconv/badge/?version=latest\n  :target: http://heudiconv.readthedocs.io/en/latest/?badge=latest\n  :alt: Readthedocs\n\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1012598.svg\n  :target: https://doi.org/10.5281/zenodo.1012598\n  :alt: Zenodo (latest)\n\n.. image:: https://repology.org/badge/version-for-repo/debian_unstable/heudiconv.svg?header=Debian%20Unstable\n   :target: https://repology.org/project/heudiconv/versions\n   :alt: Debian Unstable\n\n.. image:: https://repology.org/badge/version-for-repo/gentoo_ovl_science/python:heudiconv.svg?header=Gentoo%20%28%3A%3Ascience%29\n   :target: https://repology.org/project/python:heudiconv/versions\n   :alt: Gentoo (::science)\n\n.. image:: https://repology.org/badge/version-for-repo/pypi/python:heudiconv.svg?header=PyPI\n   :target: https://repology.org/project/python:heudiconv/versions\n   :alt: PyPI\n\n.. image:: https://img.shields.io/badge/RRID-SCR__017427-blue\n   :target: https://identifiers.org/RRID:SCR_017427\n   :alt: RRID\n\nAbout\n-----\n\n``heudiconv`` is a flexible DICOM converter for organizing brain imaging data\ninto structured directory layouts.\n\n- It allows flexible directory layouts and naming schemes through customizable heuristics implementations.\n- It only converts the necessary DICOMs and ignores everything else in a directory.\n- You can keep links to DICOM files in the participant layout.\n- Using `dcm2niix \u003chttps://github.com/rordenlab/dcm2niix/\u003e`_ under the hood, it's fast.\n- It can track the provenance of the conversion from DICOM to NIfTI in W3C PROV format.\n- It provides assistance in converting to `BIDS \u003chttp://bids.neuroimaging.io/\u003e`_.\n- It integrates with `DataLad \u003chttps://www.datalad.org/\u003e`_ to place converted and original data under git/git-annex\n  version control while automatically annotating files with sensitive information (e.g., non-defaced anatomicals, etc).\n\nHeudiconv can be inserted into your workflow to provide automatic conversion as part of a data acquisition pipeline, as seen in the figure below:\n\n.. image:: figs/environment.png\n\nInstallation\n------------\n\nSee our `installation page \u003chttps://heudiconv.readthedocs.io/en/latest/installation.html\u003e`_\non heudiconv.readthedocs.io .\n\nHOWTO 101\n---------\n\nIn 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.\nThe 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.\nYou 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`:\n\n.. image:: figs/workflow.png\n\n\n``heudiconv`` comes with `existing heuristics \u003chttps://github.com/nipy/heudiconv/tree/master/heudiconv/heuristics\u003e`_ which can be used as is, or as examples.\nFor instance, the Heuristic `convertall \u003chttps://github.com/nipy/heudiconv/blob/master/heudiconv/heuristics/convertall.py\u003e`_ extracts standard metadata from all matching DICOMs.\n``heudiconv`` creates mapping files, ``\u003csomething\u003e.edit.text`` which lets researchers simply establish their own conversion mapping.\n\nIn most use-cases of retrospective study data conversion, you would need to create your custom heuristic following the examples and the `\"Heuristic\" section \u003chttps://heudiconv.readthedocs.io/en/latest/heuristics.html\u003e`_ in the documentation.\n**Note** that `ReproIn heuristic \u003chttps://github.com/nipy/heudiconv/blob/master/heudiconv/heuristics/reproin.py\u003e`_ is\ngeneric and powerful enough to be adopted virtually for *any* study: For prospective studies, you would just need\nto name your sequences following the `ReproIn convention \u003chttps://github.com/nipy/heudiconv/blob/master/heudiconv/heuristics/reproin.py#L26\u003e`_, and for\nretrospective conversions, you often would be able to create a new versatile heuristic by simply providing\nremappings into ReproIn as shown in `this issue (documentation is coming) \u003chttps://github.com/ReproNim/reproin/issues/18#issuecomment-834598084\u003e`_.\n\nHaving decided on a heuristic, you could use the command line::\n\n    heudiconv -f HEURISTIC-FILE-OR-NAME -o OUTPUT-PATH --files INPUT-PATHs\n\nwith various additional options (see ``heudiconv --help`` or\n`\"CLI Reference\" in documentation \u003chttps://heudiconv.readthedocs.io/en/latest/commandline.html\u003e`__) to tune its behavior to\nconvert your data.\n\nFor detailed examples and guides, please check out `ReproIn conversion invocation examples \u003chttps://github.com/ReproNim/reproin/#conversion\u003e`_\nand the `user tutorials \u003chttps://heudiconv.readthedocs.io/en/latest/tutorials.html\u003e`_ in the documentation.\n\n\nHow to cite\n-----------\n\nPlease use `Zenodo record \u003chttps://doi.org/10.5281/zenodo.1012598\u003e`_ for\nyour specific version of HeuDiConv.  We also support gathering\nall relevant citations via `DueCredit \u003chttp://duecredit.org\u003e`_.\n\n\nHow to contribute\n-----------------\n\nFor a detailed into, see our `contributing guide \u003cCONTRIBUTING.rst\u003e`_.\n\nOur releases are packaged using Intuit auto, with the corresponding workflow including\nDocker image preparation being found in ``.github/workflows/release.yml``.\n\n\n3-rd party heuristics\n---------------------\n\n- https://github.com/courtois-neuromod/ds_prep/blob/main/mri/convert/heuristics_unf.py\n\n\nSupport\n-------\n\nAll bugs, concerns and enhancement requests for this software can be submitted here:\nhttps://github.com/nipy/heudiconv/issues.\n\nIf you have a problem or would like to ask a question about how to use ``heudiconv``,\nplease submit a question to `NeuroStars.org \u003chttp://neurostars.org/tags/heudiconv\u003e`_ with a ``heudiconv`` tag.\nNeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.\n\nAll previous ``heudiconv`` questions are available here:\nhttp://neurostars.org/tags/heudiconv/ .\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnipy%2Fheudiconv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnipy%2Fheudiconv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnipy%2Fheudiconv/lists"}