---
name: "heudiconv"
section: "1"
platform: "linux"
package: "heudiconv"
version: "1.3.2-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/heudiconv"
---

# heudiconv(1)

DICOM converter for organizing brain imaging data into structured directory layouts

## NAME

heudiconv - DICOM converter for organizing brain imaging data into structured directory layouts

## DESCRIPTION

usage: heudiconv \[-h\] \[--version\]

-

  \[-d DICOM\_DIR\_TEMPLATE \| **--files** \[FILES ...\]\] \[-s \[SUBJS ...\]\] \[-c {dcm2niix,none}\] \[-o OUTDIR\] \[-l LOCATOR\] \[-a CONV\_OUTDIR\] \[--anon-cmd ANON\_CMD\] \[-f HEURISTIC\] \[-p\] \[-ss SESSION\] \[-b \[BIDSOPTION1 \[BIDSOPTION2 ...\]\]\] \[--overwrite\] \[--datalad\] \[--dbg\] \[--command {heuristics,heuristic-info,ls,populate-templates,sanitize-jsons,treat-jsons,populate-intended-for}\] \[-g {studyUID,accession\_number,all,custom}\] \[--minmeta\] \[--random-seed RANDOM\_SEED\] \[--dcmconfig DCMCONFIG\] \[-q {SLURM,None}\] \[--queue-args QUEUE\_ARGS\]

Example: heudiconv **-d** 'rawdata/{subject}' **-o** . **-f** heuristic.py **-s** s1 s2 s3

### options:

- **-h**, **--help**

  show this help message and exit

- **--version**

  show program's version number and exit

- **-d** DICOM\_DIR\_TEMPLATE, **--dicom\_dir\_template** DICOM\_DIR\_TEMPLATE

  Location of dicomdir that can be indexed with subject id {subject} and session {session}. Tarballs (can be compressed) are supported in addition to directory. All matching tarballs for a subject are extracted and their content processed in a single pass. If multiple tarballs are found, each is assumed to be a separate session and the **--ses** argument is ignored. Note that you might need to surround the value with quotes to avoid {...} being considered by shell

- **--files** \[FILES ...\]

  Files (tarballs, dicoms) or directories containing files to process. Cannot be provided if using **--dicom\_dir\_template**.

- **-s** \[SUBJS ...\], **--subjects** \[SUBJS ...\]

  List of subjects - required for dicom template. If not provided, DICOMS would first be "sorted" and subject IDs deduced by the heuristic.

- **-c** {dcm2niix,none}, **--converter** {dcm2niix,none}

  Tool to use for DICOM conversion. Setting to "none" disables the actual conversion step **--** useful for testing heuristics.

- **-o** OUTDIR, **--outdir** OUTDIR

  Output directory for conversion setup (for further customization and future reference. This directory will refer to non-anonymized subject IDs.

- **-l** LOCATOR, **--locator** LOCATOR

  Study path under outdir. If provided, it overloads the value provided by the heuristic. If **--datalad** is enabled, every directory within locator becomes a super-dataset thus establishing a hierarchy. Setting to "unknown" will skip that dataset.

- **-a** CONV\_OUTDIR, **--conv-outdir** CONV\_OUTDIR

  Output directory for converted files. By default this is identical to **--outdir**. This option is most useful in combination with **--anon-cmd**.

- **--anon-cmd** ANON\_CMD

  Command to run to convert subject IDs used for DICOMs to anonymized IDs. Such command must take a single argument and return a single anonymized ID. Also see **--conv-outdir**.

- **-f** HEURISTIC, **--heuristic** HEURISTIC

  Name of a known heuristic or path to the Python script containing heuristic.

- **-p**, **--with-prov**

  Store additional provenance information. Requires python-rdflib.

- **-ss** SESSION, **--ses** SESSION

  Session for longitudinal study\_sessions. Default is None.

- **-b** \[BIDSOPTION1 \[BIDSOPTION2 ...\]\], **--bids** \[BIDSOPTION1 \[BIDSOPTION2 ...\]\]

  Flag for output into BIDS structure. Can also take BIDS-specific options, e.g., **--bids** notop. The only currently supported options is "notop", which skips creation of top-level BIDS files. This is useful when running in batch mode to prevent possible race conditions.

- **--overwrite**

  Overwrite existing converted files.

- **--datalad**

  Store the entire collection as DataLad dataset(s). Small files will be committed directly to git, while large to annex. New version (6) of annex repositories will be used in a "thin" mode so it would look to mortals as just any other regular directory (i.e. no symlinks to under .git/annex). For now just for BIDS mode.

- **--dbg**

  Do not catch exceptions and show exception traceback.

- **--command** {heuristics,heuristic-info,ls,populate-templates,sanitize-jsons,treat-jsons,populate-intended-for}

  Custom action to be performed on provided files instead of regular operation.

- **-g** {studyUID,accession\_number,all,custom}, **--grouping** {studyUID,accession\_number,all,custom}

  How to group dicoms (default: by studyUID).

- **--minmeta**

  Exclude dcmstack meta information in sidecar jsons.

- **--random-seed** RANDOM\_SEED

  Random seed to initialize RNG.

- **--dcmconfig** DCMCONFIG

  JSON file for additional dcm2niix configuration.

### Conversion submission options:

- **-q** {SLURM,None}, **--queue** {SLURM,None}

  Batch system to submit jobs in parallel.

- **--queue-args** QUEUE\_ARGS

  Additional queue arguments passed as a single string of space-separated Argument=Value pairs.