Usage¶

DELTA-SVD runs as a container. The container's entry point is the main pipeline script delta-svd.py, so the arguments you pass after the image name are the pipeline's arguments.

apptainer run delta-svd.sif --dwi <image> --id <subject> [options]

Under Apptainer (recommended) or rootless Podman, output files come out owned by you. Under Docker you must bind-mount your data (-v) and take an extra step to get output owned by your host user; see Advanced usage.

Inputs¶

A run processes one subject, given one diffusion-weighted image per timepoint.

For --bval, --bvec and --bmask, you may give one value (applied to all timepoints) or one per timepoint. When your files follow the naming convention above, you can omit them entirely.

Cross-sectional (single timepoint)¶

Run from the folder holding sub-01_dwi.nii.gz, sub-01_dwi.bval, sub-01_dwi.bvec and sub-01_dwi_brainmask.nii.gz; everything but the DWI is then inferred:

apptainer run delta-svd.sif \
  --dwi sub-01_dwi.nii.gz \
  --id sub-01

Longitudinal (multiple timepoints)¶

List all the timepoints' images after a single --dwi (one image per timepoint). DELTA-SVD builds a within-subject template with ANTs and derives the skeleton on it, so metrics are directly comparable across timepoints:

apptainer run delta-svd.sif \
  --dwi ses-1_dwi.nii.gz ses-2_dwi.nii.gz \
  --tp  ses-1 ses-2 \
  --id  sub-01

Restricting the analysis with masks¶

All masks are optional. Per-timepoint masks are given in DWI space (one per timepoint, in the same order as --dwi; write NA to skip a timepoint) and are merged in template space.

Output¶

Written to the output folder:

• delta-svd_results.csv — the results table. Endpoint metric rows contain the validated endpoints MSMD (mean skeletonised MD), PSMD (peak width of skeletonised MD) and MSFW (mean skeletonised free water), reported per timepoint and per region. The table also contains QC bookkeeping rows describing the analysed voxel sets; these have metric=NA and value=NaN.
• delta-svd_qc.html — a quality-control report (skeleton and masks overlaid on the data). It also records the DELTA-SVD version and all command-line arguments used for the run, including values containing spaces or quotes, so results remain traceable. Control it with --qc: 1 (default) writes the HTML, 2 also keeps the underlying NIfTI images in a delta-svd_qc/ folder, 0 skips both.
• delta-svd_run_manifest.json — a machine-readable record written after the requested processing steps and final cleanup succeed. It uses the versioned schema below and records the same command information as the QC report.

The run manifest is completion and provenance information; it is not required by the aggregation script, which continues to aggregate any matching results CSV.

Run manifest schema¶

manifest_schema_version is currently 1. The remaining fields are:

The results table has the following columns:

Region values¶

The region column uses these values:

Rows with metric=NA and value=NaN are QC-bookkeeping rows rather than endpoint metrics.

Intermediate files are written under delta-svd_temp/ and deleted on success; pass --debug to keep them.

Aggregating across subjects¶

delta-svd_aggregate_results.py collects the per-subject delta-svd_results.csv tables into one. It is a second script in the image, so run it with apptainer exec. Run from the directory that holds your per-subject output folders and point it at the current directory (.):

apptainer exec delta-svd.sif \
  delta-svd_aggregate_results.py . -o study_aggregated.csv

It searches the given directory recursively for delta-svd_results.csv and concatenates the matches. Useful options: