tract_similarity_sweep — cohort threshold grid search

Schema: TractSimilaritySweepConfig in src/thesis/core/config/validators.py. Drives the cohort-level tract_similarity_sweep workflow (scope="cohort"), which grid-searches the subject and atlas binarisation thresholds and reports the cell maximising mean (or median) Dice across the cohort.

The sweep operates in "fraction" mode — both grids must lie in (0, 1).

Top-level fields

Field	Type	Default	Constraints	Description
subject_threshold_grid	ThresholdGridConfig	start=0.05, stop=0.50, step=0.025	—	Grid over subject_threshold.value.
atlas_threshold_grid	ThresholdGridConfig	start=0.05, stop=0.50, step=0.025	—	Grid over atlas_threshold.value.
aggregation	"mean" | "median"	"mean"	—	Cohort aggregation used to pick the best grid cell.
output_subdir	str	"tract_similarity_sweep"	—	Output subdirectory under the cohort output root.
emit_heatmap	bool	True	—	Emit a matplotlib heatmap PNG of the aggregated grid.

ThresholdGridConfig

Provide either start/stop/step or an explicit values list (mutually exclusive).

Field	Type	Default	Constraints	Description
start	float | None	0.05	0.0 < x < 1.0	Grid start (inclusive).
stop	float | None	0.50	0.0 < x < 1.0; > start	Grid stop (inclusive within float tolerance).
step	float | None	0.025	> 0.0	Grid step.
values	List[float] | None	None	each in (0, 1); non-empty	Explicit values (mutually exclusive with start/stop/step).

A model_validator enforces the mutual-exclusion rule and that stop > start when using the range form.

Example

tract_similarity_sweep:
  subject_threshold_grid:
    start: 0.02
    stop: 0.30
    step: 0.02
  atlas_threshold_grid:
    values: [0.05, 0.10, 0.20, 0.40]
  aggregation: median
  output_subdir: tract_similarity_sweep
  emit_heatmap: true

Notes

• The sweep reuses TractSimilarityConfig for everything else (atlas/FDT paths, NMI bins, output layout) — it only overrides the two threshold values per grid cell.

• Output layout: <cohort_output_root>/<output_subdir>/heatmap.png + a CSV/JSON of per-cell aggregates.

• For the per-patient metric definitions, see tract_similarity.