CLI Reference¶
heudiconv
processes DICOM files and converts the output into user defined
paths.
- Example:
heudiconv -d ‘rawdata/{subject}’ -o . -f heuristic.py -s s1 s2 s3
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]
Named Arguments¶
- --version
show program’s version number and exit
- -d, --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 (tarballs, dicoms) or directories containing files to process. Cannot be provided if using –dicom_dir_template.
- -s, --subjects
List of subjects - required for dicom template. If not provided, DICOMS would first be “sorted” and subject IDs deduced by the heuristic.
- -c, --converter
Possible choices: dcm2niix, none
Tool to use for DICOM conversion. Setting to “none” disables the actual conversion step – useful for testing heuristics.
- -o, --outdir
Output directory for conversion setup (for further customization and future reference. This directory will refer to non-anonymized subject IDs.
- -l, --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
Output directory for converted files. By default this is identical to –outdir. This option is most useful in combination with –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
Name of a known heuristic or path to the Python script containing heuristic.
- -p, --with-prov
Store additional provenance information. Requires python-rdflib.
- -ss, --ses
Session for longitudinal study_sessions. Default is None.
- -b, --bids
Possible choices: notop
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
Possible choices: 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, --grouping
Possible choices: studyUID, accession_number, all, custom
How to group dicoms (default: by studyUID).
- --minmeta
Exclude dcmstack meta information in sidecar jsons.
- --random-seed
Random seed to initialize RNG.
- --dcmconfig
JSON file for additional dcm2niix configuration.
Conversion submission options¶
- -q, --queue
Possible choices: SLURM, None
Batch system to submit jobs in parallel.
- --queue-args
Additional queue arguments passed as a single string of space-separated Argument=Value pairs.