align_habitat_map

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_map(reference: HabitatMap, moving: HabitatMap, *, force: bool = False) → HabitatMap[source]

Remap moving habitat ids onto the reference id space.

For two maps of the same voxels (retest, perturbation, another preprocessing chain, another reader): independently clustered maps permute integer ids, so ids are paired by maximal voxel overlap (Hungarian on the overlap counts, the Prior 2024 munkres step) and moving is rewritten into the reference ids. Maps that already share a model_id (the apply-saved-model path) are returned unchanged: those ids are already the same definition.

To name habitats of different subjects use align_habitat_maps_to_prototypes(); overlap between two patients’ voxels has no meaning.

habitat_stability() uses the same pairing, so the compare figure and the Dice table share one correspondence. Do not feed an already-aligned map back into habitat_stability; it pairs the original maps itself.

Parameters:

  • reference – Habitat map whose ids are the target space.

  • moving – Independently labelled map of the same voxel grid.

  • force – If True, align even when model_id already matches. Independent one_step / fit_predict runs on the same subject share a model_id (spec + subject-id digest, not image content) and need force=True.

Returns:

A new map with remapped labels. model_id is taken from reference. habitat_ids starts with the reference ids and appends leftover moving habitats (rewritten to unused ids after max(reference ids)) when the moving map had more clusters. The input moving map is returned as-is when the model ids already match and force is False.

Raises:

HABITAPIError – If the grids differ.

Examples using habit.precision.align_habitat_map

Why habitat ids must be matched

Why habitat ids must be matched

Matching maps of the same voxels by overlap

Matching maps of the same voxels by overlap

Precise voxel features

Precise voxel features