Advanced usage¶

CPU usage and threading¶

Most of DELTA-SVD runs single-threaded. The only multi-core step is the within-subject template construction, which runs for longitudinal input (more than one timepoint); there the timepoints are registered to the template in parallel.

--threads sets how many physical CPU cores that step may use:

Value	Behaviour
`auto` (default)	Detect the physical cores available to the run. On a cluster this honours the cores your scheduler assigned, so a correctly sized job needs no setting.
`N`	Cap usage at `N` cores.
`1`	Run the whole pipeline single-threaded.

Timepoints are spread across the available cores automatically: with more cores than timepoints, each registration also gets extra threads; with fewer, the registrations share the budget. You don't need to tune this by hand.

Note

Only physical cores are counted; hyperthreads are ignored, because registration gains little from them. To use them anyway, pass an explicit --threads value.

Choosing a value¶

Single subject on a workstation — leave the default, or set --threads to the number of cores you want to devote to the run.
Many subjects in parallel on a cluster — give each subject its own core budget and run them side by side. --threads 1 per subject keeps CPU load even and lets you pack as many subjects as you have cores; if your scheduler allocates several cores per subject, the default auto uses exactly those.
Limited memory — rarely a concern: at standard diffusion resolutions a run fits comfortably in memory even with several timepoints, and it only becomes relevant for very high-resolution images. If needed, cap the number of registrations run in parallel with the expert --para option (not shown in --help); --para 1 processes one timepoint at a time while still using the whole core budget — the lowest-memory setting.

Important

For longitudinal input, the effective core count has a small effect on the results: the multi-threaded template registration sums intermediate values in a thread-count-dependent order, so a different core count shifts the output metrics slightly. The differences are negligible for interpretation, but if you need exactly reproducible numbers across machines, pin --threads to a fixed value rather than relying on auto (which depends on the machine).

Running under Docker¶

The image runs as a non-root user (nonroot, uid 999). Under Docker the process therefore writes files owned by 999:999 on the host. To get output owned by your host user, run the container as yourself:

docker run --rm --user "$(id -u):$(id -g)" \
  -v /path/to/data:/data \
  delta-svd:<version> --dwi /data/sub-01_dwi.nii.gz --id sub-01

If a step complains about an unset HOME, add -e HOME=/tmp. To run the aggregator under Docker, override the entry point:

docker run --rm -v /path/to/data:/data \
  --entrypoint delta-svd_aggregate_results.py \
  delta-svd:<version> /data -o /data/study_aggregated.csv

Apptainer and rootless Podman map your host identity into the container, so they need none of this — output is owned by you automatically.

Other options¶

Option	Description
`--reprocess [name]`	Allow reprocessing over existing output (otherwise a run refuses to overwrite). Optionally give an alternative results-CSV base name to preserve the previous `delta-svd_results.csv`.
`--debug`	Keep the `delta-svd_temp/` folder of intermediate files instead of deleting it.
`--bRange LO HI`	b-value range used for tensor fitting (default `800 1200`).
`--skeletonMask <NIfTI>`	Use an alternative skeleton mask instead of the validated default.
`--para <n>`	Expert override (not shown in `--help`): number of ANTs registration jobs run in parallel during template construction, independent of `--threads`. `--para 1` serialises registration while each job still uses the full core budget — the lowest-memory setting for a longitudinal run.