tractography — tractography backends and parameters

Schema: TractographyConfig in src/thesis/core/config/validators.py. Drives the ProbTrackX2 (hcp) and MRtrix3 (mrtrix3) standalone workflows and the unified tract_synthseg meta-workflow (backend per method). Fields not relevant to the selected method are ignored.

General

Field	Type	Default	Constraints	Description
method	str	"probtrackx2"	one of probtrackx2 / tckgen / dsi_studio / mrtrix3	Tractography engine. tckgen is an alias used by some configs.
run_tractography	bool | None	None	—	Optional workflow-level toggle (interpreted by HCP-style workflows).
hemisphere	str	"both"	one of left / right / both / both-separately	Hemisphere selection. both merges ROIs; both-separately runs two independent tractography passes with separate outputs. CLI override: --hemisphere.
mem_gb_gpu	float	8.0	> 0	Nipype scheduler memory hint (GB) for GPU tractography nodes.
mem_gb_cpu	float	4.0	> 0	Nipype scheduler memory hint (GB) for CPU tractography nodes.
use_waypoints	bool	True	—	Whether to consume waypoint masks during tractography.

ROIs and waypoints

Field	Type	Default	Description
waypoint_files	Dict[str, Path] | None	None	Direct mapping of waypoint name → mask path (legacy single-atlas setup).
roi_files	List[Path] | None	None	Template-space ROI files to transform into patient space.
seed_roi	Path | None	None	Seed ROI path (patient- or template-space depending on workflow).
waypoint_masks	List[Path] | None	None	Pre-resolved waypoint mask files.
atlas_sources	List[AtlasSourceConfig] | None	None	Multi-atlas ROI configuration (recommended). Each source has name, roi_file, label_file, waypoint_labels, and an optional named transform from transforms.atlas_transforms.
roi_labels	Dict[str, Any] | None	None	Legacy single-atlas ROI configuration (label_file, roi_file, waypoint_labels).
synthseg_roi_labels	Dict[str, Any] | None	None	SynthSeg-sourced ROI configuration (waypoint_labels with label_values).

waypoint_labels entry

waypoint_labels is a mapping of ROI name → entry, used by atlas_sources, roi_labels, and synthseg_roi_labels. The entry dict is loosely typed (Dict[str, Any]); these are the keys the workflow reads (see src/thesis/workflows/hcp/operations/extraction.py):

Key	Type	Description
region_kind	str	Role of the ROI in tractography: one of seed, waypoint, stop, avoid, target. Entries with any other value are silently skipped.
label_name	str	A single label string matched (case-/text-exact) against the label_file CSV to resolve its integer value. Used by atlas_sources / roi_labels.
label_names	List[str]	Multiple label strings resolved via the CSV and merged into one mask (e.g. left + right).
label_values	List[int]	Explicit integer label values, used directly without a CSV lookup. This is the form synthseg_roi_labels uses (SynthSeg labels are known integers, so no label_file is needed).

Provide exactly one of label_values, label_names, or label_name per entry (checked in that precedence order). atlas_sources / roi_labels resolve names against their label_file; synthseg_roi_labels use label_values directly.

ProbTrackX2-specific (effective when method: probtrackx2)

Field	Type	Default	Constraints	ProbTrackX2 flag	Description
n_samples	int	5000	≥ 100	--nsamples	Streamlines per seed voxel.
n_steps	int	2000	≥ 100	--nsteps	Maximum steps per streamline.
step_length	float	0.5	0.1 ≤ x ≤ 2.0	--steplength	Step length in mm.
curvature_threshold	float	0.2	0.0 ≤ x ≤ 1.0	--cthr	Curvature threshold (lower = stricter).
loop_check	bool	True	—	--loopcheck	Detect and prune looping samples. Slower but allows lower curvature thresholds.
dist_thresh	float	0.0	≥ 0.0	--distthresh	Discard streamlines shorter than this (mm). 0.0 = no minimum.
fibst	int	1	≥ 1	--fibst	Starting fibre index. Only effective when rand_fib=0.
rand_fib	int	0	0–3	--randfib	Fibre sampling mode: 0 default, 1 random (f>thresh), 2 proportional (f>thresh), 3 all populations.
mod_euler	bool	False	—	--modeuler	Use modified Euler streamlining.
force_dir	bool	True	—	--forcedir	Force per-streamline directory creation.
opd	bool	True	—	--opd	Output path distribution.

MRtrix3-specific (effective when method: mrtrix3)

Field	Type	Default	Constraints	Description
tckgen_algorithm	str	"iFOD2"	—	tckgen tracking algorithm (iFOD2, iFOD1, SD_STREAM, Tensor_Det, …).
tckgen_select	int	5000	≥ 1	tckgen -select: target streamline count.
tckgen_seeds	int	5_000_000	≥ 1	tckgen -seeds: seed attempt cap (0 would mean unlimited; the schema forbids 0).
tckgen_minlength	float	30.0	≥ 0.0	tckgen -minlength (mm).
tckgen_maxlength	float	250.0	> 0.0	tckgen -maxlength (mm).
tckgen_backtrack	bool	True	—	tckgen -backtrack flag (recommended for ACT).
tckgen_crop_at_gmwmi	bool	True	—	tckgen -crop_at_gmwmi for precise endpoint placement.
tckgen_cutoff	float | None	None	≥ 0.0 if set	tckgen -cutoff FOD amplitude. None keeps MRtrix’s default.
response_algorithm	str	"dhollander"	one of dhollander / tournier / msmt_5tt / fa / manual	dwi2response algorithm.
fod_algorithm	str	"msmt_csd"	one of msmt_csd / csd	dwi2fod algorithm. msmt_csd for multi-shell, csd for single-shell.
use_mtnormalise	bool	True	—	Run mtnormalise after dwi2fod to correct intensity bias across tissues.
fivett_algorithm	str	"fsl"	one of fsl / freesurfer / hsvs	5ttgen backend. Use freesurfer or hsvs for brainstem seeds — 5ttgen fsl returns zero brainstem and silently produces 0 streamlines.
mask_source	str	"fsl_nodif"	one of fsl_nodif / dwi2mask	Brain-mask source. fsl_nodif reuses the HCP nodif_brain_mask; dwi2mask generates one from the DWI (note: dwi2mask legacy may over-erode deep WM).
mask_dilate_voxels	int	1	≥ 0	Brain-mask dilation passes (maskfilter ... dilate -npass N). MRtrix ACT recommends 1.
use_sift2	bool	True	—	Run tcksift2 to weight streamlines for tckmap. The workflow always captures mu via -out_mu (required for cross-subject comparable Fibre Bundle Capacity).
seed_strategy	str	"roi"	one of roi / gmwmi	tckgen seed source. roi seeds from the atlas/SynthSeg seed mask; gmwmi seeds from the GM-WM interface via -seed_gmwmi (requires ACT, always enabled here).
gmwmi_apply_roi_filters	bool	True	—	When seed_strategy: gmwmi, still apply any configured waypoint/avoid/stop/target masks as tckgen -include/-exclude/-mask filters. false forces pure whole-brain tracking. Ignored when seed_strategy: roi.

Example — ProbTrackX2 protocol

tractography:
  method: probtrackx2
  n_samples: 5000
  n_steps: 2000
  step_length: 0.5
  curvature_threshold: 0.2
  loop_check: true
  dist_thresh: 0.0
  rand_fib: 0
  mod_euler: false
  force_dir: true
  opd: true
  hemisphere: both
  mem_gb_gpu: 8.0
  mem_gb_cpu: 4.0

  atlas_sources:
    - name: main
      roi_file: data/masks/annotation_full.nii.gz
      label_file: data/masks/label_map.csv
      waypoint_labels:
        medulla-seed:
          region_kind: seed
          label_name: "pyramidal part of medulla oblongata"
        peduncle-waypoint:
          region_kind: waypoint
          label_name: "cerebral peduncle (crus cerebri)"

Example — MRtrix3 protocol

tractography:
  method: mrtrix3
  hemisphere: both-separately

  tckgen_algorithm: iFOD2
  tckgen_select: 2000000
  tckgen_seeds: 50000000
  tckgen_minlength: 30.0
  tckgen_maxlength: 250.0
  tckgen_backtrack: true
  tckgen_crop_at_gmwmi: true

  response_algorithm: dhollander
  fod_algorithm: msmt_csd
  use_mtnormalise: true

  fivett_algorithm: freesurfer    # brainstem seeds — see notes above
  mask_source: fsl_nodif
  mask_dilate_voxels: 1
  use_sift2: true

Notes

• mem_gb_gpu and mem_gb_cpu are scheduler hints — they don’t cap actual memory. Set them to reflect real peak usage so Nipype doesn’t over-schedule.

• For MRtrix3 cross-subject comparisons, SIFT2 weights are scaled by mu (captured automatically) to produce Fibre Bundle Capacity. Raw weight sums are not directly comparable across subjects.

• tract_similarity consumes both backends transparently — set tract_similarity.probtrackx_relpath: tractography/mrtrix3 (or atlas.tractography_relpath) when running atlas / similarity workflows over MRtrix3 outputs.