HEUDICONV(1)

👑 HEUDICONV — the heudiconv(1) manual page, bestie edition 💅

okay so. welcome to HEUDICONV(1), section 1 of the User Commands manual. this is the DICOM converter that takes your chaotic pile of brain imaging data and turns it into a structured directory layout. it's giving organization. it's giving main character energy. let's get into it 🧚✨

---

✨ NAME ✨

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

---

🦋 DESCRIPTION 🦋

usage, bestie:

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]

and here's a lil example so you can see her in action, periodt:

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

---

💖 options: (the whole menu, no skips)

• -h, --help — show this help message and exit. the classic. the icon. 🫶
• --version — show program's version number and exit. she'll tell you who she is.
• -d DICOM_DIR_TEMPLATE, --dicom_dir_template DICOM_DIR_TEMPLATE — where your dicomdir lives, and you can index it with subject id {subject} and session {session}. tarballs are supported too, not just directories — and yes, they can be compressed, we love a zipped queen. all matching tarballs for a subject get extracted and their content processed in a single pass. if multiple tarballs turn up, each one is assumed to be a separate session, and the --ses argument gets ignored. ngl, you might need to wrap the value in quotes so your shell doesn't try to interpret the {...} — she's nosy like that 😭
• --files [FILES ...] — files (tarballs, dicoms) or directories containing files to process. you literally cannot provide this if you're using --dicom_dir_template. pick a lane bestie.
• -s [SUBJS ...], --subjects [SUBJS ...] — list of subjects — required for dicom template. if you don't hand it over, the DICOMS get "sorted" first and subject IDs are deduced by the heuristic. it's giving detective work 🔍
• -c {dcm2niix,none}, --converter {dcm2niix,none} — the tool used for DICOM conversion. setting it to none disables the actual conversion step — which is lowkey the whole point but highkey useful for testing your heuristics ✨
• -o OUTDIR, --outdir OUTDIR — output directory for conversion setup (for further customization and future reference, iykyk). this directory will refer to non-anonymized subject IDs. note that.
• -l LOCATOR, --locator LOCATOR — study path under outdir. if you provide it, it overloads whatever value the heuristic gave. if --datalad is enabled, every directory within the locator becomes a super-dataset, thus establishing a hierarchy, very demure, very mindful. setting it to "unknown" will skip that dataset entirely.
• -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 into anonymized IDs. such command must take a single argument and return a single anonymized ID. also see --conv-outdir. one in, one out, no drama.
• -f HEURISTIC, --heuristic HEURISTIC — name of a known heuristic, or the path to the Python script containing the heuristic. your moment to shine, bestie.
• -p, --with-prov — store additional provenance information. requires python-rdflib. no rdflib, no provenance, sorry babes 🎀
• -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 option is notop, which skips creation of top-level BIDS files. this is useful when running in batch mode to prevent possible race conditions. protect your peace, skip the top-level files.
• --overwrite — overwrite existing converted files. ruthless. iconic.
• --datalad — store the entire collection as DataLad dataset(s). small files get committed directly to git, while large ones go 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. mortals stay unbothered 🦋
• --dbg — do not catch exceptions and show exception traceback. raw, unfiltered, no filter. we love transparency 😭
• --command {heuristics,heuristic-info,ls,populate-templates,sanitize-jsons,treat-jsons,populate-intended-for} — custom action to be performed on the provided files instead of regular operation. side quest unlocked 🔥
• -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. minimal. clean. no clutter ✨
• --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. go forth and parallelize, queen 👑
• --queue-args QUEUE_ARGS — additional queue arguments passed as a single string of space-separated Argument=Value pairs.

---

💀 reminder bestie: --files and -d/--dicom_dir_template are mutually exclusive, -s/--subjects is required for the dicom template, and -p/--with-prov needs python-rdflib installed. read the room, read the flags.

---

that's the whole page, no cap. this was heudiconv 1.3.2, brought to you in November 2024 🌸 mwah, go convert something beautiful 💖🫶✨