CLI Reference

CLI Reference

The CLI ships under three equivalent names: qr, qradiomics, qrdx. Everything is a Unix-style command — files in, files out, no server required.

qr --help
qr --version
qr info

Command map (by stage)

Command	Stage	Purpose
qr tcia download	data	Bulk-download a TCIA collection (multi-process + progress)
qr anonymize	data	Strip PHI from a DICOM tree (DICOM PS3.15 Annex E)
qr convert dicom-series	data/image	DICOM CT/MR → NRRD; PET auto-routes through SUV conversion
qr convert rtstruct	data/image	DICOM RTSTRUCT contour → label NRRD (case-insensitive ROI)
qr convert manifest-from-dir	data	Glob image+mask pairs into a manifest CSV
qr preprocess	image	bbox crop + isotropic resample per (image, mask) row
qr register	image	Rigid Mattes-MI/LBFGSB moving→fixed (mask transfer)
qr hu-correct	image	Histogram-match CBCT to a reference CT
qr extract	features	Multi-engine extraction (PyRadiomics/PySERA/rtools) → features.csv (manifest + pattern)
qr shape extract	features	AHSN + spiculation shape descriptors
qr delta	features	DeltaPair (A − B) + trend slope per patient across timepoints
qr results merge	features	features.csv + clinical.csv → analysis_ready.csv
qr analyze survival	modeling	Univariate Cox proportional hazards
qr analyze classify	modeling	Univariate logistic regression
qr analyze importance	modeling	Random-forest + permutation (+ optional SHAP)
qr ml train	modeling	CV Cox / logistic + leakage-safe corr/univariate selection
qr ml predict	modeling	Apply a trained model to new features
qr ml evaluate	modeling	Hold-out evaluation report (c-index / AUC)
qr bench	modeling	Multi-model classification benchmark (LR/SVM/ExtraTrees/RF/GBM/MLP/XGB/LGBM/FLAML/TPOT), nested CV + optional HPO/external test
qr workflow plan	assembly	Generate a multi-step plan from a template
qr workflow show	assembly	Inspect a plan's steps and variables
qr workflow scaffold	assembly	Render a plan as shell / nextflow / prefect
qr workflow run	assembly	Execute a plan (default executor: nextflow)
qr pattern list / search	meta	Browse bundled pattern templates
qr config get / set	meta	User preferences in ~/.qradiomics/config.yaml

DICOM conversion

# CT/PET/MR DICOM series → single NRRD volume
qr convert dicom-series -i <root>/<patient>/<study>/CT/ -o <out>/<patient>_CT.nrrd

# RTSTRUCT contour → binary label NRRD (same geometry as the reference CT)
qr convert rtstruct -d <root>/<patient>/<study>/CT/ \
   -r <root>/<patient>/<study>/RTSeries/RS.<uid>.dcm --roi GTV \
   -o <out>/<patient>_GTV-label.nrrd

# Build a manifest by globbing image/mask pairs
qr convert manifest-from-dir -d <out>/ \
   --image-glob '*_CT.nrrd' --mask-glob '*-label.nrrd' -o manifest.csv

RTSTRUCT conversion uses rt-utils (pip install qradiomics[rtstruct]). ROI lookup is case-insensitive (--roi Heart matches heart). The mask is auto-reshaped to CT geometry with a ±1-slice z-trim/pad.

Extraction & analysis

qr extract       -m manifest.csv -p nsclc-survival -o features.csv
qr results merge -f features.csv -c clinical.csv -o analysis_ready.csv
qr analyze survival -i analysis_ready.csv --outcome OS_months --event OS_event -o cox.csv
qr analyze classify -i analysis_ready.csv --target response_label
qr analyze importance -i analysis_ready.csv --target outcome --method shap

qr extract runs one or more extraction engines in a single pass via --engine <pyradiomics,pysera,rtools|all> (comma-separated, default pyradiomics):

qr extract -m manifest.csv -p nsclc-survival -o features.csv --engine pyradiomics,pysera,rtools
qr extract -m manifest.csv -p nsclc-survival -o features.csv --engine all

The results merge join key is PatientID / patient_id; header variants like Survival.time + deadstatus.event auto-rename.

Multi-model benchmarking

qr bench runs nested cross-validation across multiple classifiers and reports OOF ROC-AUC, average precision, and Brier score, with optional hyperparameter search and external-test evaluation:

qr bench -i features.csv --outcome event --models LR,RF,XGB,LGBM,FLAML --cv 10
qr bench -i features.csv --outcome event --all-models --hpo optuna
qr bench -i features.csv --outcome event --external-test ext.csv

• Models: LR, SVM, ExtraTrees, RF, GBM, MLP, XGB, LGBM by default; --all-models adds FLAML AutoML. TPOT is opt-in only (--models TPOT) — it is materially more expensive and its genetic-programming search is not reproducible run-to-run, so --tpot-repeats (default 5) refits it independently and reports mean ± std.
• --cv/--inner-cv (default 10×5) control the nested CV; --hpo grid|optuna picks the search strategy (--optuna-trials, default 30).
• --external-test ext.csv refits each CV-selected model on the full training set and scores it on a held-out CSV; --calibrate-threshold picks a Youden's-J decision threshold from out-of-fold training probabilities instead of the hardcoded 0.5.
• Writes bench_cv_results.csv, bench_external_results.csv (if --external-test), and an HTML report to --output-dir (default results/bench).
• qr ml benchmark is the canonical, recommended entry point on the same engine (adds a correlation pre-filter); qr bench remains a permanent backward-compatible alias.

Machine learning (survival / classification)

qr ml train fits a leakage-safe CV model (Cox or logistic) with correlation + univariate feature selection inside each fold:

qr ml train -i analysis_ready.csv --task classify --outcome response_label \
  --group-col patient_id --folds 5 --model model.pkl --metrics metrics.json

• --task classify auto-detects multiclass outcomes (more than two labels) and switches to a multiclass-appropriate metric/prediction path automatically — no separate flag needed.
• --group-col (default patient_id) uses grouped CV (GroupKFold-style) so same-patient rows never split across train/test folds; omit only if rows are already one-per-patient.

Bundled pattern templates

pattern_id	Description
ct-default	Plain CT, single timepoint, multi image-type baseline
standard-radiomics	Multi-modality generic radiomics
survival-analysis	Cox + RSF + KM, time-to-event task
nsclc-survival	NSCLC CT GTV, LoG+Wavelet+Square/Sqrt/Log image types (~1130 features)

Drop a new *.yaml into qradiomics/data/templates/ to add a study; qr pattern list picks it up automatically.

Workflow assembly

Template	Stages	When
nrrd_survival	data → features → modeling	cohort already in NRRD
dicom_survival	data → image → features → modeling	cohort ships as DICOM + RTSTRUCT
dicom_to_ml	data → image → features → modeling (ML)	full end-to-end DICOM → trained model + CV + held-out eval

qr workflow plan -t dicom_to_ml -d /data/cohort -c clinical.csv --roi GTV --pattern nsclc-survival -o plan.json
qr workflow scaffold -p plan.json -e nextflow -o pipeline.nf   # optional inspection
qr workflow run plan.json                                      # nextflow (default)
qr workflow run plan.json --executor inline                    # small/interactive
qr workflow run plan.json --executor prefect                   # Prefect-orchestrated

The plan is plain JSON/YAML — agents can read, mutate (add a stage, swap a pattern, change executor), and re-run without re-templating. Per-patient steps are fanned out automatically by the Nextflow / Prefect scaffolders.

See Python API for the library layer beneath every command.