Data

Tools

Indexes

Applications

Experiments

Open Source Science

HeuDiConv — flexible DICOM conversion into structured directory layouts

HeuDiConv — flexible DICOM conversion into structured directory layouts - Published in JOSS (2024)

https://github.com/nipy/heudiconv

Science Score: 95.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 9 DOI reference(s) in README and JOSS metadata
  • ✓
    Academic publication links
    Links to: joss.theoj.org, zenodo.org
  • ✓
    Committers with academic emails
    14 of 50 committers (28.0%) from academic institutions
  • ○
    Institutional organization owner
  • ✓
    JOSS paper metadata
    Published in Journal of Open Source Software

Keywords from Contributors

bids closember data-storage git-annex usable neuroimaging eeg magnetoencephalography electroencephalography neuroscience

Scientific Fields

Biology Life Sciences - 40% confidence
Last synced: 4 months ago · JSON representation

Repository

Flexible DICOM conversion into structured directory layouts

Basic Info
Statistics
  • Stars: 264
  • Watchers: 18
  • Forks: 134
  • Open Issues: 206
  • Releases: 37
Created over 10 years ago · Last pushed 4 months ago
Metadata Files
Readme Changelog Contributing License Zenodo

README.rst 

=============
**HeuDiConv**
=============

`a heuristic-centric DICOM converter`

.. image:: https://joss.theoj.org/papers/10.21105/joss.05839/status.svg
   :target: https://doi.org/10.21105/joss.05839
   :alt: JOSS Paper

.. image:: https://img.shields.io/badge/docker-nipy/heudiconv:latest-brightgreen.svg?logo=docker&style=flat
  :target: https://hub.docker.com/r/nipy/heudiconv/tags/
  :alt: Our Docker image

.. image:: https://github.com/nipy/heudiconv/actions/workflows/test.yml/badge.svg?event=push
  :target: https://github.com/nipy/heudiconv/actions/workflows/test.yml
  :alt: GitHub Actions (test)

.. image:: https://codecov.io/gh/nipy/heudiconv/branch/master/graph/badge.svg
  :target: https://codecov.io/gh/nipy/heudiconv
  :alt: CodeCoverage

.. image:: https://readthedocs.org/projects/heudiconv/badge/?version=latest
  :target: http://heudiconv.readthedocs.io/en/latest/?badge=latest
  :alt: Readthedocs

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1012598.svg
  :target: https://doi.org/10.5281/zenodo.1012598
  :alt: Zenodo (latest)

.. image:: https://repology.org/badge/version-for-repo/debian_unstable/heudiconv.svg?header=Debian%20Unstable
   :target: https://repology.org/project/heudiconv/versions
   :alt: Debian Unstable

.. image:: https://repology.org/badge/version-for-repo/gentoo_ovl_science/python:heudiconv.svg?header=Gentoo%20%28%3A%3Ascience%29
   :target: https://repology.org/project/python:heudiconv/versions
   :alt: Gentoo (::science)

.. image:: https://repology.org/badge/version-for-repo/pypi/python:heudiconv.svg?header=PyPI
   :target: https://repology.org/project/python:heudiconv/versions
   :alt: PyPI

.. image:: https://img.shields.io/badge/RRID-SCR__017427-blue
   :target: https://identifiers.org/RRID:SCR_017427
   :alt: 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:

.. image:: 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`:

.. image:: 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, ``.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
---------------------

- https://github.com/courtois-neuromod/ds_prep/blob/main/mri/convert/heuristics_unf.py


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/ .

Owner

  • Name: NIPY developers
  • Login: nipy
  • Kind: organization

JOSS Publication

HeuDiConv — flexible DICOM conversion into structured directory layouts
Published
July 03, 2024
DOI
Volume 9, Issue 99, Page 5839
Authors
Yaroslav O. Halchenko ORCID
Center for Open Neuroscience, Department of Psychological and Brain Sciences, Dartmouth College, Hanover, NH, USA
Mathias Goncalves ORCID
Department of Psychology, Stanford University, CA, USA
Satrajit Ghosh ORCID
McGovern Institute, Massachusetts Institute of Technology, Cambridge, MA, USA
Pablo Velasco ORCID
Flywheel Exchange LLC, Minneapolis, MN, USA
Matteo Visconti di Oleggio Castello ORCID
University of California, Berkeley, Berkeley, CA, USA
Taylor Salo ORCID
Perelman School of Medicine, University of Pennsylvania, Philadelphia, PA, USA
John T. Wodder
Center for Open Neuroscience, Department of Psychological and Brain Sciences, Dartmouth College, Hanover, NH, USA
Michael Hanke ORCID
Institute of Neuroscience and Medicine, Brain & Behaviour (INM-7), Research Center Jülich, Jülich, Germany, Institute of Systems Neuroscience, Medical Faculty, Heinrich Heine University Düsseldorf, Düsseldorf, Germany
Patrick Sadil ORCID
Department of Biostatistics, Johns Hopkins Bloomberg School of Public Health, Baltimore, MD, USA
Krzysztof Jacek Gorgolewski ORCID
Emeritus of Department of Psychology, Stanford University, CA, USA
Horea-Ioan Ioanas ORCID
Center for Open Neuroscience, Department of Psychological and Brain Sciences, Dartmouth College, Hanover, NH, USA
Chris Rorden ORCID
Department of Psychology, University of South Carolina, Columbia, SC, USA
Timothy J. Hendrickson ORCID
Masonic Institute for the Developing Brain, University of Minnesota, Minneapolis, MN, USA, Minnesota Supercomputing Institute, University of Minnesota, Minneapolis, MN, USA
Michael Dayan ORCID
Human Neuroscience Platform, Fondation Campus Biotech Geneva, Geneva, Switzerland
Sean Dae Houlihan ORCID
Center for Open Neuroscience, Department of Psychological and Brain Sciences, Dartmouth College, Hanover, NH, USA, Department of Brain and Cognitive Sciences, Massachusetts Institute of Technology, Cambridge, MA, USA
James Kent ORCID
Department of Psychology, University of Texas at Austin, Austin, TX, USA
Ted Strauss ORCID
McConnell Brain Imaging Centre, McGill University, Montreal, QC, Canada
John Lee ORCID
Data Science and Sharing Team, National Institute of Mental Health, Bethesda, MD, USA
Isaac To ORCID
Center for Open Neuroscience, Department of Psychological and Brain Sciences, Dartmouth College, Hanover, NH, USA
Christopher J. Markiewicz ORCID
Department of Psychology, Stanford University, CA, USA
Darren Lukas ORCID
Institute for Glycomics, Griffith University, QLD, Australia
Ellyn R. Butler ORCID
Department of Psychology, Northwestern University, Evanston, IL, USA
Todd Thompson
Department of Brain and Cognitive Sciences, Massachusetts Institute of Technology, Cambridge, MA, USA
Maite Termenon ORCID
Biomedical Engineering Department, Faculty of Engineering, Mondragon University, Mondragon, Spain, BCBL, Basque center on Cognition, Brain and Language, San Sebastian, Spain
David V. Smith ORCID
Department of Psychology and Neuroscience, Temple University, Philadelphia, PA, USA
Austin Macdonald ORCID
Center for Open Neuroscience, Department of Psychological and Brain Sciences, Dartmouth College, Hanover, NH, USA
David N. Kennedy ORCID
Departments of Psychiatry and Radiology, University of Massachusetts Chan Medical School, Worcester, MA, USA
Editor
Britta Westner ORCID
Tags
neuroscience standardization DICOM BIDS open science FOSS
View PDF Review Thread Software Archive

GitHub Events

Total
  • Create event: 13
  • Release event: 3
  • Issues event: 18
  • Watch event: 25
  • Delete event: 6
  • Member event: 1
  • Issue comment event: 94
  • Push event: 20
  • Pull request review event: 25
  • Pull request review comment event: 25
  • Pull request event: 35
  • Fork event: 7
Last Year
  • Create event: 13
  • Release event: 3
  • Issues event: 18
  • Watch event: 25
  • Delete event: 6
  • Member event: 1
  • Issue comment event: 94
  • Push event: 20
  • Pull request review event: 26
  • Pull request review comment event: 26
  • Pull request event: 35
  • Fork event: 7

Committers

Last synced: 5 months ago

All Time
  • Total Commits: 1,396
  • Total Committers: 50
  • Avg Commits per committer: 27.92
  • Development Distribution Score (DDS): 0.622
Past Year
  • Commits: 50
  • Committers: 7
  • Avg Commits per committer: 7.143
  • Development Distribution Score (DDS): 0.44
Top Committers
Name Email Commits
Yaroslav Halchenko d****n@o****m 528
Mathias Goncalves g****s@g****m 221
Pablo Velasco p****o@n****u 98
Matteo Visconti di Oleggio Castello m****r@d****u 87
Taylor Salo t****6@f****u 66
John T. Wodder II g****t@v****g 57
Satrajit Ghosh s****h@g****m 38
DBIC BIDS Team b****s@d****u 31
Michael Hanke m****e@g****m 31
auto a****o@n****l 27
Basile Pinsard b****d@g****m 25
Austin Macdonald a****n@d****u 24
Horea Christian c****r@c****u 21
Patrick Sadil p****l@g****m 14
Michael Dayan m****n@f****h 13
Dae Houlihan d****a@m****u 12
Steven Tilley s****e@s****m 10
James Kent j****t@u****u 8
Isaac To c****k@g****m 7
Alan Kuurstra a****a@g****m 7
Jörg Stadler j****r@l****e 6
Matthew Brett m****t@g****m 5
dependabot[bot] 4****] 5
Kasbohm i****n@g****m 5
Christopher J. Markiewicz m****z@s****u 4
Darren Lukas d****s@t****u 4
Keith Callenberg k****g@g****m 3
Michael Krause k****e@m****e 3
Sin Kim A****o 3
Jakub Kaczmarzyk j****k@m****u 3
and 20 more...
Committer Domains (Top 20 + Academic)
dartmouth.edu: 2 mit.edu: 2 onerussian.com: 1 nyu.edu: 1 fiu.edu: 1 varonathe.org: 1 dbic.dartmouth.edu: 1 chymera.eu: 1 fcbg.ch: 1 steventilley.com: 1 uiowa.edu: 1 lin-magdeburg.de: 1 stanford.edu: 1 tri.edu.au: 1 mpib-berlin.mpg.de: 1 niwa.co.nz: 1 umn.edu: 1 idor.org: 1 bdi.ox.ac.uk: 1 charite.de: 1 umassmed.edu: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time
  • Total issues: 105
  • Total pull requests: 176
  • Average time to close issues: about 1 year
  • Average time to close pull requests: 2 months
  • Total issue authors: 55
  • Total pull request authors: 28
  • Average comments per issue: 2.64
  • Average comments per pull request: 3.16
  • Merged pull requests: 132
  • Bot issues: 0
  • Bot pull requests: 6
Past Year
  • Issues: 21
  • Pull requests: 47
  • Average time to close issues: 3 days
  • Average time to close pull requests: 8 days
  • Issue authors: 16
  • Pull request authors: 5
  • Average comments per issue: 1.14
  • Average comments per pull request: 2.13
  • Merged pull requests: 30
  • Bot issues: 0
  • Bot pull requests: 3
View more stats
Top Authors
Issue Authors
  • yarikoptic (29)
  • bpinsard (6)
  • neurorepro (5)
  • asmacdo (4)
  • TheChymera (3)
  • psadil (2)
  • andrew-yian-sun (2)
  • ChristianNSchmitz (2)
  • WilliamFCB (2)
  • s-madhavan (2)
  • levchenkoegor (2)
  • askieslinger (2)
  • mih (2)
  • anbai106 (1)
  • anthonyromyn (1)
Pull Request Authors
  • yarikoptic (69)
  • bpinsard (23)
  • jwodder (14)
  • asmacdo (11)
  • octomike (7)
  • dependabot[bot] (6)
  • tsalo (4)
  • candleindark (4)
  • mgxd (4)
  • jennan (4)
  • TheChymera (4)
  • xuanxu (3)
  • chaselgrove (2)
  • pvelasco (2)
  • mslw (2)
Top Labels
Issue Labels
released (10) documentation (4) enhancement (4) easy (2) question (2) answered (2) doc (2) bug (2) help-wanted (2) tests (1) good-first-issue (1) DX (1) UX (1) BIDS (1) patch (1) release (1)
Pull Request Labels
released (78) internal (36) release (28) documentation (27) patch (21) minor (13) tests (7) enhancement (3) dependencies (2) skip-release (2) UX (2) BIDS (2) great-for-hackathon (1) bug (1) major (1)

Packages

  • Total packages: 1
  • Total downloads: unknown
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 12
conda-forge.org: heudiconv

Convert DICOM dirs based on heuristic info - HeuDiConv uses the dcmstack package and dcm2niix tool to convert DICOM directories or tarballs into collections of NIfTI files following pre-defined heuristic(s).

  • Versions: 12
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Forks count: 16.6%
Stargazers count: 25.2%
Average: 31.7%
Dependent repos count: 34.0%
Dependent packages count: 51.2%
Last synced: 4 months ago

Dependencies

.github/workflows/docker.yml actions
  • actions/checkout v3 composite
.github/workflows/release.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
.github/workflows/test.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • codecov/codecov-action v3 composite
Dockerfile docker
  • neurodebian bullseye build
dev-requirements.txt pypi
  • inotify * development
  • tinydb * development
docs/requirements.txt pypi
  • sphinx-argparse *
  • sphinxcontrib-napoleon *
.github/workflows/codespell.yml actions
  • actions/checkout v3 composite
  • codespell-project/actions-codespell v1 composite
.github/workflows/lint.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
.github/workflows/typing.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
pyproject.toml pypi
requirements.txt pypi
setup.py pypi