Workflow Usage Guide#

The framework currently ships 17 self-registering workflows. List them at any time with:

thesis list-workflows

Workflows fall into five groups. All are launched via thesis run -w <name> (see the CLI reference for shared flags).

Tractography backends#

`hcp`#

Probabilistic tractography on HCP-style inputs using FSL ProbTrackX2. Default protocol: hcp. Reuses BedpostX outputs, applies optional atlas ROI extraction, ANTs ROI transforms, ROI validation, and streamline warping back to template space. GPU-aware (probtrackx2_gpu / probtrackx2_gpu11.0) when hardware.gpu_enabled: true.

Requires HCP-layout inputs (including T1w/Diffusion.bedpostX/) already on disk — run preprocess first if you only have raw vendor data. This is the first row of the Choosing a workflow table.

thesis run -w hcp -p 114823 -c default

`tract_synthseg`#

Meta-workflow: SynthSeg → tractography. Generates a patient-specific segmentation at runtime (via mri_synthseg) and feeds it to the tractography graph. Best when no precomputed segmentation exists. The tractography backend is selected by config.tractography.method:

"probtrackx2" (default) — runs the FSL ProbTrackX2 / HCP tractography graph and writes tractography/probtrackx2/.
"mrtrix3" — runs MRtrix3 tckgen with SynthSeg-derived avoid/stop masks and writes tractography/mrtrix3/.

Default protocol: tract_synthseg.

thesis run -w tract_synthseg -p 114823 -c tract_synthseg            # ProbTrackX2 backend
thesis run -w tract_synthseg -p 114823 -c tract_synthseg_mrtrix3    # MRtrix3 backend

`mrtrix3`#

MRtrix3 tractography pipeline: 5ttgen → dwi2response dhollander → dwi2fod msmt_csd → mtnormalise → tckgen (ACT) → tcksift2 → tckmap. Reuses the HCP ROI-extraction pipeline unchanged. Patient-level intermediates (5TT, GMWMI, response functions, FODs) live under <output>/tractography/mrtrix3/_shared/; per-hemisphere products under <output>/tractography/mrtrix3/<hemi>/. Density filename matches ProbTrackX2 (fdt_paths.nii.gz) so tract_similarity consumes both via tract_similarity.probtrackx_relpath. Default protocol: mrtrix3.

Gotcha: 5ttgen fsl returns zero brainstem and silently produces 0 streamlines for brainstem seeds. Set tractography.fivett_algorithm: freesurfer (or hsvs) when seeding brainstem ROIs. SIFT2’s mu coefficient is captured automatically via tcksift2 -out_mu (needed for cross-subject comparable Fibre Bundle Capacity).

thesis run -w mrtrix3 -p 114823 -c mrtrix3

End-to-end meta-pipelines#

`full_pipeline`#

Single Nipype graph chaining preprocess → registration → (tract_synthseg || atlas_to_patient) → tract_similarity. The backend is selected by config.tractography.method:

"probtrackx2" (default) — wires tract_synthseg (ProbTrackX2 backend) and BedpostX.
"mrtrix3" — wires tract_synthseg (MRtrix3 backend); BedpostX is structurally disabled.

Default protocol: full_pipeline. The CLI surfaces headline tract_similarity metrics (Dice, Pearson, Hausdorff-95, NMI) in the run summary.

thesis run -w full_pipeline -p 114823 -c full_pipeline                # ProbTrackX2 backend
thesis run -w full_pipeline -p 114823 -c full_pipeline_mrtrix3        # MRtrix3 backend

Preprocessing, registration, segmentation#

`preprocess`#

Converts raw *_T1.nii.gz, *_T2.nii.gz, *_dmri_AP.nii.gz, *_dmri_PA.nii.gz, .bval, .bvec inputs under patients/Unprocessed/<patient_id>/ (or the configured paths.inputs_dir) into an HCP-compatible output layout under data/processed/<patient_id>/T1w/. Wraps TOPUP, Eddy, DTIFit, BedpostX, N4 bias correction, SynthStrip/SynthSeg, and optional ANTs registration / template-label transform steps. Default protocol/config: preprocess.

thesis run -w preprocess -p DTI_LDF001 -c preprocess

`registration`#

Patient-to-template structural registration with ANTs or FireANTs backends and a swappable QC viewer (currently FSLeyes; html reserved). Resolves the moving image from registration.moving_image first, then hcp.t1_image or hcp.t2_image depending on registration.moving_modality. Outputs land under <output_dir>/registration/. FireANTs deformable runs export affine + composed warp as ANTs-compatible 5-D NIfTI (intent_code=1007).

thesis run -w registration -p 114823 -c default

`synthseg`#

Standalone mri_synthseg segmentation. Resolves the T1 from synthseg.t1_image, then hcp.t1_image. Runs on CPU or GPU depending on synthseg.cpu and hardware configuration.

thesis run -w synthseg -p 114823 -c default

Cohort, atlas, similarity#

`atlas` (cohort-level)#

Cohort-level statistical atlas (mean, std, std_error, CoV, prob_threshold) computed with pure NumPy from per-subject warped tractography. Scans the configured output base for <patient>/<tractography_relpath>/<run>/warped_streamlines/fdt_paths.nii.gz + waytotal. Set atlas.tractography_relpath: tractography/mrtrix3 for the MRtrix3 backend. Set atlas_qc.enabled: true to also generate cohort occupancy / core mask / CV outputs under <output_dir>/atlas_qc/.

thesis run -w atlas -c default

`atlas_to_patient`#

Warps cohort atlas maps into patient space using pre-computed template-to-patient ANTs transforms. Driven by transforms.jobs[] — each job specifies input files, direction, interpolation, and an output subdir.

thesis run -w atlas_to_patient -p 114823 -c default

`learned_atlas` (cohort-level)#

Learns a sharp conditional deformable tract-density template instead of voxel-averaging warped tracts (VoxelMorph/AtlasMorph paradigm applied to TDI). A diffeomorphic registration U-Net emits only deformation fields (scaling-and-squaring integration; positive-Jacobian verified), so it never invents density — no hallucination. It emits the same five maps as atlas (atlas_mean/std/std_error/cov/prob_threshold) byte-compatible with the averaging atlas, so atlas_to_patient and tract_similarity keep working unchanged. The model runs only at atlas-build time on the cohort; patients consume the produced atlas via the existing atlas_to_patient path. Requires the optional ml extra (pip install -e '.[ml]') — torch is lazy-imported only inside the training node, so the CLI/import path works without it. Key config knobs under learned_atlas: training_space (template_native is the drop-in, runnable default; affine_native is opt-in, needs affine_native_relpath, and is rejected by verify_requirements as NOT drop-in for template-space atlas_to_patient), device, dtype, min_subjects (default 5), and optimizer.{lr, epochs, batch_size} (defaults 1e-4/50/2).

thesis run -w learned_atlas -c default --protocol hcp

`tract_similarity`#

Per-patient comparison between native-space tractography density and the warped cohort mean atlas. Four metric families: overlap (Dice/Jaccard/volume), correlation (Pearson/Spearman/cosine), spatial distance (Hausdorff-95/mean-surface/centroid), distribution similarity (NMI/symmetric KL/Bhattacharyya). Auto-detects hemisphere-split vs single-run layout. Default protocol: hcp. See configuration/tract_similarity.md.

`tract_similarity_cohort` (cohort-level)#

Cohort aggregation of per-patient tract_similarity outputs. Emits summary.csv, per_patient.csv, and outliers.json.

`tract_similarity_hcp_loo` (cohort-level)#

Per-HCP-subject leave-one-out tract similarity against the cohort atlas: for each subject the atlas is recomputed with that subject held out, then compared to the subject’s own density. Emits a metrics.json per subject (plus optional NIfTI). Default protocol: hcp.

thesis run -w tract_similarity_hcp_loo -c hcp

`tract_similarity_sweep` (cohort-level)#

Grid search over the subject and atlas binarisation thresholds (both in fraction mode). Reports the (subject, atlas) cell maximising mean/median Dice across the cohort; optionally writes a matplotlib heatmap. See configuration/tract_similarity_sweep.md.

`transform`#

Generic apply-transforms workflow driven by transforms.jobs[]. Each job specifies input files, direction (template_to_patient / patient_to_template), interpolation, and an output subdirectory. Per-job reference_image overrides are supported (useful for resampling onto a different grid like DWI space).

QC and examples#

`qc`#

QC visualisation and statistics workflow. Generates ROI overlays, track-density figures, tractography statistics (waytotal, voxel counts, NCS), batch outlier detection, SynthSeg QC parsing, warp Jacobian inspection, and per-target connectivity maps. Outputs land under <output_dir>/qc/. Can run standalone after a tractography workflow, or automatically post-workflow when qc.generate_overlays: true.

thesis run -w qc -p 114823 -c default

`minimal`#

Example/demo workflow showing the registration pattern. Useful as a template when adding a new workflow.

Common usage patterns#

Inspect what’s configured#

thesis list-workflows
thesis list-configs
thesis list-configs --subdir protocols
thesis show-config default

Build the workflow graph without running it#

thesis run -w hcp -p 114823 -c default --dry-run --graph
# writes <output>/workflow_graphs/workflow.png

Batch with retries and parallelism#

thesis run -w hcp --all -c default -j 4 -r 2

Re-export tractography statistics#

thesis stats collect -o data/processed/
thesis stats collect -o data/processed/ --tractography-relpath tractography/mrtrix3

Hemisphere selection#

thesis run -w hcp -p 114823 -c default --hemisphere left
thesis run -w hcp -p 114823 -c default --hemisphere both-separately  # two independent runs

Output expectations#

Normal mode shows errors, warnings, and key milestones ([OK]/[FAIL] labels), plus the end-of-run summary.
Verbose mode (-v) shows all events and the full underlying log stream — useful for debugging.
Quiet mode (-q) keeps only errors and the final result line.
Batch runs also print a per-batch tractography statistics table when ≥1 patient succeeded, and write JSON to <output_dir>/batch_stats/.
Cohort-level workflows ignore -p/--patient-id and --all; they run a single Nipype workflow against the configured output directory.

Choosing a workflow#

Goal	Workflow
HCP-preprocessed inputs already on disk	`hcp`
Need SynthSeg at runtime, then ProbTrackX2 tractography	`tract_synthseg` (`-c tract_synthseg`)
MRtrix3 tractography (multi-shell + ACT + SIFT2)	`mrtrix3`
Need SynthSeg at runtime, then MRtrix3 tractography	`tract_synthseg` (`-c tract_synthseg_mrtrix3`)
Raw vendor data → HCP layout	`preprocess`
Just patient-to-template registration	`registration`
Just SynthSeg segmentation	`synthseg`
End-to-end pipeline (preprocess → tractography → similarity), ProbTrackX2	`full_pipeline` (default config)
End-to-end pipeline, MRtrix3	`full_pipeline` with `-c full_pipeline_mrtrix3`
Build a statistical cohort atlas	`atlas`
Build a learned deformable cohort atlas (sharp template)	`learned_atlas`
Warp the atlas back into patient space	`atlas_to_patient`
Per-patient comparison vs the atlas	`tract_similarity`
Aggregate similarity across cohort	`tract_similarity_cohort`
Leave-one-out similarity per HCP subject	`tract_similarity_hcp_loo`
Sweep binarisation thresholds	`tract_similarity_sweep`
Apply arbitrary ANTs transforms	`transform`
Generate QC figures and stats	`qc`

Workflow Usage Guide#

Tractography backends#

hcp#

tract_synthseg#

mrtrix3#

End-to-end meta-pipelines#

full_pipeline#

Preprocessing, registration, segmentation#

preprocess#

registration#

synthseg#