Usage¶
heudiconv
processes DICOM files and converts the output into user defined
paths.
CommandLine Arguments¶
- Example:
- heudiconv -d ‘rawdata/{subject}’ -o . -f heuristic.py -s s1 s2 s3
usage: heudiconv [-h] [--version]
[-d DICOM_DIR_TEMPLATE | --files [FILES [FILES ...]]]
[-s [SUBJS [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}]
[-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 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. |
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/
Batch jobs¶
heudiconv
can natively handle multi-subject, multi-session conversions,
although it will process these linearly. To speed this up, multiple heudiconv
processes can be spawned concurrently, each converting a different subject and/or
session.
The following example uses SLURM and Singularity to submit every subjects’
DICOMs as an independent heudiconv
execution.
The first script aggregates the DICOM directories and submits them to
run_heudiconv.sh
with SLURM as a job array.
If using bids, the notop
bids option suppresses creation of
top-level files in the bids directory (e.g.,
dataset_description.json
) to avoid possible race conditions.
These files may be generated later with populate_templates.sh
below (except for participants.tsv
, which must be create
manually).
#!/bin/bash
set -eu
# where the DICOMs are located
DCMROOT=/dicom/storage/voice
# where we want to output the data
OUTPUT=/converted/data/voice
# find all DICOM directories that start with "voice"
DCMDIRS=(`find ${DCMROOT} -maxdepth 1 -name voice* -type d`)
# submit to another script as a job array on SLURM
sbatch --array=0-`expr ${#DCMDIRS[@]} - 1` run_heudiconv.sh ${OUTPUT} ${DCMDIRS[@]}
The second script processes a DICOM directory with heudiconv
using the built-in
reproin heuristic.
#!/bin/bash
set -eu
OUTDIR=${1}
# receive all directories, and index them per job array
DCMDIRS=(${@:2})
DCMDIR=${DCMDIRS[${SLURM_ARRAY_TASK_ID}]}
echo Submitted directory: ${DCMDIR}
IMG="/singularity-images/heudiconv-0.10.0-dev.sif"
CMD="singularity run -B ${DCMDIR}:/dicoms:ro -B ${OUTDIR}:/output -e ${IMG} --files /dicoms/ -o /output -f reproin -c dcm2niix -b notop --minmeta -l ."
printf "Command:\n${CMD}\n"
${CMD}
echo "Successful process"
This script creates the top-level bids files (e.g.,
dataset_description.json
)
- ..code:: shell
#!/bin/bash set -eu
OUTDIR=${1} IMG=”/singularity-images/heudiconv-0.10.0-dev.sif” CMD=”singularity run -B ${OUTDIR}:/output -e ${IMG} –files /output -f reproin –command populate-templates”
printf “Command:n${CMD}n” ${CMD} echo “Successful process”