identify_precise_voxel_features

Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

identify_precise_voxel_features(cohort: Cohort, *, extractor_factory: Callable[[int, float], VoxelFeatureExtractor] | None = None, kernel_radii: Sequence[int] = (1, 3), bin_widths: Sequence[float] = (12, 25), base_kernel_radius: int = 3, base_bin_width: float = 12, perturbation: ImagePerturbation | None = None, lcl_threshold: float = 0.5, include: Sequence[str] = (), exclude: Sequence[str] = (), alpha: float = 0.05, min_voxels: int = 10, seed: int = 0, show_progress: bool = True) → PreciseFeatureSet[source]

Identify the voxel features precise enough to define habitats.

Per subject, up to three experiments are run:

  • repeatability – ICC(3A,1) between the base-setting feature maps of the original and of one perturbed (simulated retest) image;

  • reproducibility_kernel_radius – ICC(3C,1) between the feature maps at kernel_radii with the bin width fixed at base_bin_width (skipped when fewer than two radii are given);

  • reproducibility_bin_width – ICC(3C,1) between the feature maps at bin_widths with the radius fixed at base_kernel_radius (skipped when fewer than two widths are given).

Per-feature per-subject ICCs are aggregated by the cohort median (the paper’s aggregation), and a feature is precise when its median LCL reaches lcl_threshold in EVERY experiment, subject to the include / exclude expert overrides (the paper used include for NGTDM Coarseness).

Parameters:

  • cohort – Subjects to screen on; their ROIs define the voxel pools.

  • extractor_factory – (kernel_radius, bin_width) -> extractor; None selects voxel_radiomics_factory() (the bundled CT preset). Custom extractors need a factory mapping the grid point onto their own settings.

  • kernel_radii – Reproducibility grid of neighbourhood radii; the paper contrasts R1 with R3.

  • bin_widths – Reproducibility grid of bin widths; the paper contrasts B12 with B25.

  • base_kernel_radius – Radius of the base (repeatability) setting.

  • base_bin_width – Bin width of the base (repeatability) setting.

  • perturbation – Simulated-retest perturbation; None selects the paper’s chain (Chang-estimated Gaussian noise, sub-voxel translation, 0.5-degree in-plane rotation, original ROI kept).

  • lcl_threshold – Lower-confidence-limit cutoff; 0.5 is the paper’s “at least good” boundary.

  • include – Expert overrides added regardless of the criteria.

  • exclude – Features removed regardless of the criteria.

  • alpha – Two-sided significance level of the confidence limits.

  • min_voxels – Minimum paired-voxel count per subject; below it a subject’s feature is unmeasurable and does not veto the median.

  • seed – Master seed; each subject’s perturbation draws from its own spawned child sequence, so the screen is fully reproducible.

  • show_progress – Show a progress bar over the cohort.

Returns:

The precise feature set with the cohort-level evidence panels.

Raises:

HABITAPIError – If the cohort is empty.