habit.precision: repeatability screen

Precision analysis: which voxel features deserve to define habitats.

Voxel-wise radiomics is noisy; clustering features that do not survive a simulated re-acquisition produces habitats nobody can reproduce. This package implements the precision screen of Prior et al. (Radiol Artif Intell 2024;6(2):e230118) as composable domain components:

• ImagePerturbation implementations (noise, translation, rotation, optional MONAI bspline_deform) and the PerturbationChain composing one simulated retest;

• precision_panel() / aggregate_panels() computing per-subject and cohort-level ICC tables on voxel feature fields;

• identify_precise_features() applying the LCL screen across experiments and returning the serialisable PreciseFeatureSet;

• habitat_stability() scoring habitat maps under perturbation;

• align_habitat_map() remapping independently clustered labels of the same voxels onto a reference (overlap Hungarian);

• align_habitat_maps_to_prototypes() naming habitats across subjects by iterative matching to shared (or frozen) prototypes.

User guide: Habitat Guide Precise voxel features · Matching habitat labels across subjects. Recipe wrapper: identify_precise_voxel_features().

Simulated-retest perturbations and the ICC intersection that decides which extracted voxel columns may define habitats (Prior et al., Radiol Artif Intell 2024;6(2):e230118). Label matching lives here too: align_habitat_map (voxel overlap) for two maps of the same voxels and align_habitat_maps_to_prototypes for different subjects, including naming a new cohort with frozen prototypes. Method choice, algorithm, and literature: Matching habitat labels across fits and subjects.

Classes

ImagePerturbation	Turn one subject into a perturbed copy of itself: a simulated re-acquisition.
GaussianNoisePerturbation	Add zero-mean Gaussian noise to every image of a subject.
TranslationPerturbation	Translate image content by a (random) sub-voxel shift.
RotationPerturbation	Rotate image content by a small fixed angle about the image centre.
RigidPerturbation	Sub-voxel translation and small-angle rotation in ONE resample.
BSplineDeformPerturbation	MONAI elastic / B-spline free-form warp of every image and ROI.
MorphologicalPerturbation	Uniformly grow or shrink every ROI (MIRP perturbation_roi_adapt_size).
GradientWeightedPerturbation	Locally grow/shrink ROI boundaries where image gradient is low.
SliceExtentPerturbation	Add or remove whole axial slices at the superior/inferior ROI ends.
PerturbationChain	Apply several image perturbations in sequence to one subject.
PreciseFeatureSet	Voxel features that passed the precision screen, with the evidence.
ImagePerturbationRegistry	Name-to-implementation registry for image perturbations.
HabitatPrototypeAlignment	Cohort habitat maps renamed onto shared prototypes.

Functions

perturb_image	Return a same-grid perturbed copy of one image.
prior2024_retest_perturbation	Simulated-retest chain of Prior et al. 2024 / MIRP 1.2.0 Appendix S2.
precision_panel	Compute the per-feature ICC panel of ONE subject under ONE experiment.
aggregate_panels	Aggregate per-subject panels into the cohort-level panel.
identify_precise_features	Select the features that clear the LCL threshold in EVERY experiment.
align_habitat_map	Remap moving habitat ids onto the reference id space.
align_habitat_maps_to_prototypes	Give every subject's habitats one shared set of names (cohort matching).
habitat_stability	Score habitat stability between a reference map and perturbed maps.