align_habitat_maps_to_prototypes
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.
- align_habitat_maps_to_prototypes(habitat_maps: Sequence[HabitatMap], *, models: Sequence[Any] | None = None, features: Sequence[Any] | None = None, centroids: Sequence[ndarray] | None = None, metric: Literal['sqeuclidean', 'manhattan', 'cosine', 'correlation'] = 'sqeuclidean', reduction: Literal['mean', 'median'] = 'mean', max_distance: float | None = None, standardize: Literal['none', 'zscore'] = 'none', max_iter: int = 100, prototypes: HabitatPrototypeAlignment | None = None) HabitatPrototypeAlignment[source]
Give every subject’s habitats one shared set of names (cohort matching).
For per-subject (
one_step) habitats each subject numbers its habitats in arbitrary order. Pairwise matching to one reference subject makes the names depend on who the reference is, and chains of pairwise matches need not agree (A→B→C versus A→C). This operator names all subjects at once againstKshared prototypes:start from one subject’s habitat summaries as prototypes;
match every subject one-to-one onto the prototypes (Hungarian on the
metriccost; two habitats of one tumour never share a name);move each prototype to the centre of its matched summaries (mean, median for
"manhattan", mean direction for cosine / correlation);repeat until nothing changes. Every subject with
Khabitats is tried as the start and the tightest result is kept.
This is the relabelling algorithm of Stephens (2000) for label switching, equivalently k-means with a cannot-link constraint inside each subject (Wagstaff et al. 2001). Prototype ids are sorted by the first feature (then the second, …), so they do not depend on input order. With two subjects and the default metric the grouping equals pairwise Hungarian on squared Euclidean distance.
Kis the largest subject habitat count. Every habitat of every subject gets its own prototype id: no subject loses, gains, or merges a habitat. A subject with fewer habitats simply lacks some ids (zero volume in cohort tables).max_distanceis off by default; when set, a habitat farther than that from every free prototype is left unnamed (prototype_idNA, subject-local id aboveK).What describes a habitat (pass exactly one):
models(default use) – the fitted per-subject models;HabitatModel.centroidsare the clustering centroids, rowiishabitat_ids[i]. Names therefore follow the same features that defined the habitats.features– one voxel feature source per map: aVoxelFeatureField(rows atvoxel_index), or a volume /ImageVolumeon the map grid with an optional trailing feature axis. Each habitat is summarised by thereductionof its voxels.centroids– caller-built(n_habitats, n_features)matrices, rows inhabitat_idsorder.
Values are compared as given, so they must be comparable across subjects: same features, computed so that values mean the same thing in every patient (for example relative enhancement, or a validated intensity normalisation).
one_stepmodels cluster raw voxel values by default, and raw MRI signal is not comparable across scanners or patients.standardize="zscore"rescales every column once on the pooled cohort summaries (unit balance when features have different units; it does not make incomparable signal comparable).Metric choice.
"sqeuclidean"(default) and"manhattan"(robust to one outlying habitat) compare feature values."cosine"compares only the direction of the feature vector, so a weakly and a strongly enhancing habitat with the same ratio look identical; with one feature of constant sign every habitat looks the same."correlation"compares only the shape of the feature profile; with two features every centred profile is one of two directions, and with one feature it is undefined (an error). No error is raised for few features otherwise: choose cosine / correlation only when many features describe a habitat and their shape, not their level, is the habitat definition.max_distanceanddistanceare in the metric’s units (Euclidean, L1,1 - cos,1 - r).Frozen prototypes. Pass a previous result as
prototypes=to name a validation cohort or a new patient with a trained definition: the habitats are assigned once to the stored prototypes, nothing is refitted, and the aligned maps get the storedmodel_id. The source feature names,metric,standardizeandreductionmust equal the stored ones, and a z-score reuses the storedlocation/scale. A subject with more habitats than stored prototypes keeps the extra ones unnamed.Maps that already share one cohort model (two-step, direct pooling, apply-saved-model) are already named consistently and do not need this step.
- Parameters:
habitat_maps – One map per subject (any grids; no voxel is compared across subjects).
models – Fitted per-subject models, one per map. Their
feature_namesmust agree.features – Voxel feature fields or volumes, one per map. Feature names (when present) must agree.
centroids – Caller-supplied summary matrices, one per map.
metric –
"sqeuclidean"(default),"manhattan","cosine", or"correlation".reduction –
"mean"(default, the quantity a k-means centroid stores) or"median"; used only withfeatures.max_distance – Optional distance above which a habitat is left unnamed instead of being forced onto a prototype.
None(default) names every habitat.standardize –
"none"(default) or"zscore"on pooled rows.max_iter – Upper bound on assign / update rounds per start.
prototypes – Optional earlier result whose prototypes are reused without refitting.
- Returns:
A
HabitatPrototypeAlignment. Aligned maps share onemodel_idderived from the prototypes and the parameters (the stored one for frozen runs).- Raises:
HABITAPIError – If no source or more than one is given, sources do not line up with the maps, feature definitions differ, frozen settings disagree, or a cosine / correlation summary has zero length.
