validation — warped-ROI validation

Schema: ValidationConfig in src/thesis/core/config/validators.py. Controls automatic post-warp QC for the hcp and meta-pipeline workflows.

Field	Type	Default	Constraints	Description
check_rois	bool	False	—	Run automated validation on warped ROI masks after ANTs transformation.
min_voxels	int	10	≥ 1	Minimum non-zero voxels in a warped ROI mask. Fewer voxels raises PipelineError.
singularity_threshold	float	1e-6	> 0	Minimum absolute determinant of the affine 3×3 rotation/scale block. Below this the ROI is rejected as degenerate (prevents probtrackx2 from crashing on a collapsed mask).
volume_ratio_min	float	0.5	0.0 < x ≤ 1.0	Lower bound for the warped-vs-original voxel-count ratio. Below this a warning is emitted.
volume_ratio_max	float	1.5	≥ 1.0	Upper bound for the warped-vs-original voxel-count ratio. Above this a warning is emitted.

Example

validation:
  check_rois: true
  min_voxels: 10
  singularity_threshold: 1.0e-6
  volume_ratio_min: 0.5
  volume_ratio_max: 1.5

Per-patient overrides are useful when a specific subject has unusually small anatomy:

# config/patients/SMALL_ROI_PATIENT.yaml
validation:
  min_voxels: 5
  volume_ratio_min: 0.3

Notes

• The validator runs after the ANTs warp and before tractography, so a failure aborts the patient early with a clear error message rather than producing zero streamlines.

• volume_ratio_min and volume_ratio_max only emit warnings — they don’t fail the run.