atlas_qc — cohort atlas QC

Schema: AtlasQCConfig in src/thesis/core/config/validators.py. Optional post-atlas quality-control outputs for the cohort atlas workflow.

When atlas_qc.enabled: true, the atlas workflow writes additional outputs into <output_dir>/atlas_qc/ after generating the atlas.

Field	Type	Default	Constraints	Description
enabled	bool	False	—	Enable atlas QC generation.
generate_group_plots	bool	True	—	Generate cohort-level atlas summary plots. (Reserved for future expansion of plot artefacts.)
generate_patient_reports	bool	False	—	Generate per-patient atlas QC outputs. (Reserved for future per-subject artefacts.)
outlier_sd_threshold	float	2.0	> 0.0	SD threshold for atlas outlier detection.
subject_density_threshold	float	0.01	0.0 ≤ x ≤ 1.0	Minimum normalised streamline density for a subject voxel to count as present. Drives the cohort-occupancy map.
group_core_threshold	float	0.5	0.0 ≤ x ≤ 1.0	Proportion of subjects required for a voxel to be part of the cohort core mask.
leave_one_out	bool	False	—	Compute leave-one-out group-consistency Dice summaries per subject.
leave_one_out_min_subjects	int	3	≥ 2	Minimum number of subjects required to run leave-one-out validation.
compute_cv	bool	True	—	Compute Coefficient-of-Variation maps.
cv_mean_threshold	float	0.01	0.0 ≤ x ≤ 1.0	Fraction of atlas-mean maximum required to compute CV (suppresses CV in low-signal voxels).
compute_log_stats	bool	True	—	Compute statistics in log space (add to qc_summary.json).
log_offset	float	1e-6	> 0.0	Positive offset added before log-transforming subject maps.
output_subdir	str	"atlas_qc"	—	Subdirectory under the cohort output directory where atlas QC artefacts are written. Override per backend (e.g. atlas_qc_mrtrix3) to coexist with another backend’s QC under the same outputs/ tree.

Output layout

<output_dir>/atlas/
├── atlas_mean.nii.gz
├── atlas_std.nii.gz
└── atlas_cov.nii.gz

<output_dir>/atlas_qc/                       # only when atlas_qc.enabled
├── cohort_occupancy.nii.gz                  # fraction of subjects per voxel
├── cohort_core_mask.nii.gz                  # occupancy ≥ group_core_threshold
├── cohort_cv.nii.gz                         # when compute_cv: true
└── qc_summary.json                          # Dice, CV, log-space summaries

Example

atlas:
  presence_value: 0.10
  cov_mean_threshold_pct: 0.01

atlas_qc:
  enabled: true
  subject_density_threshold: 0.01
  group_core_threshold: 0.5
  leave_one_out: true
  leave_one_out_min_subjects: 3
  compute_cv: true
  cv_mean_threshold: 0.01
  compute_log_stats: true
  log_offset: 1.0e-6

thesis run -w atlas -c default

Notes

• subject_density_threshold is what counts a voxel as “present” in a subject. group_core_threshold is what fraction of subjects must agree for the voxel to belong to the cohort core. These are the two main knobs when interpreting CV blow-ups at tract edges.

• outlier_sd_threshold, generate_group_plots, and generate_patient_reports are reserved for future expansion.