.. _sphx_glr_auto_examples_06_matching:

6. Matching Habitat Labels
==========================

**Background.** A clustering run numbers its habitats in arbitrary order,
so the same tissue can be habitat 1 in one run or patient and habitat 3 in
another (**label switching**). **Purpose.** These pages show how HABIT
matches the ids so that Dice, volume fractions and cohort tables compare
like with like.

Calling it on a fitted study:
:doc:`/auto_examples/06_matching/plot_07_match_labels`.
The pages below show why ids switch and how each matcher works.

Habitat ids from independent clusterings are arbitrary: habitat 1 of one
fit can be habitat 3 of another. Anything that compares habitats by id
(Dice, volume fractions, a cohort feature table) must match the ids
first. HABIT has two matchers, chosen by what the two sides share:

* **Voxel overlap** -- the maps label the *same voxels* (a restart,
  another ``k``, another feature set, a perturbed image, a second reader).
  Hungarian assignment on the voxel-overlap table.
  :func:`~habit.precision.align_habitat_map`,
  :func:`~habit.precision.habitat_stability`.
* **Shared prototypes** -- the maps label *different subjects*. Each
  subject's habitat summaries are matched one-to-one onto ``K`` shared
  prototypes, iterated until stable; prototypes can be frozen to name a
  new cohort. :func:`~habit.precision.align_habitat_maps_to_prototypes`.

A shared cohort model (two-step, direct pooling, an applied saved model)
already uses one id space and needs neither. Formulas, proofs, and
literature: :doc:`/reference/habitat_matching`.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Clustering algorithms such as k-means number their clusters in arbitrary order, so two fits of the same tumour can give the same region different habitat ids. Any comparison by id (Dice, volume per habitat, a cohort table) needs the ids matched first.">

.. only:: html

  .. image:: /auto_examples/06_matching/images/thumb/sphx_glr_plot_01_label_switching_thumb.png
    :alt:

  :doc:`/auto_examples/06_matching/plot_01_label_switching`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Why habitat ids must be matched</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. When two habitat maps cover the same voxels, their ids can be matched by counting shared voxels alone, even if the two fits used a different number of habitats or different features.">

.. only:: html

  .. image:: /auto_examples/06_matching/images/thumb/sphx_glr_plot_02_overlap_cases_thumb.png
    :alt:

  :doc:`/auto_examples/06_matching/plot_02_overlap_cases`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Matching maps of the same voxels by overlap</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Two patients share no voxels, so their habitats cannot be matched by overlap. Instead each habitat is described by a summary row and all subjects are named against one shared set of reference rows.">

.. only:: html

  .. image:: /auto_examples/06_matching/images/thumb/sphx_glr_plot_03_prototype_steps_thumb.png
    :alt:

  :doc:`/auto_examples/06_matching/plot_03_prototype_steps`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Prototype matching step by step</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Prototype matching needs a rule for how far a habitat is from a prototype. The default compares feature values; the alternatives trade that for robustness to outliers or for comparing curve shape only.">

.. only:: html

  .. image:: /auto_examples/06_matching/images/thumb/sphx_glr_plot_04_prototype_metrics_thumb.png
    :alt:

  :doc:`/auto_examples/06_matching/plot_04_prototype_metrics`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Choosing the distance for prototype matching</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Once prototypes are learned on a training cohort, they define what each habitat id means. New patients should be named against those fixed prototypes rather than refitting them.">

.. only:: html

  .. image:: /auto_examples/06_matching/images/thumb/sphx_glr_plot_05_frozen_prototypes_thumb.png
    :alt:

  :doc:`/auto_examples/06_matching/plot_05_frozen_prototypes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Naming a new cohort with frozen prototypes</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Habitat features are usually analysed as a table with one row per patient and one column per habitat. That only works if a column refers to the same kind of habitat in every patient.">

.. only:: html

  .. image:: /auto_examples/06_matching/images/thumb/sphx_glr_plot_06_downstream_tables_thumb.png
    :alt:

  :doc:`/auto_examples/06_matching/plot_06_downstream_tables`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">What matching changes in a cohort feature table</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. In a one_step study each patient is clustered on its own, so habitat ids are not comparable between patients until they are matched onto shared prototypes.">

.. only:: html

  .. image:: /auto_examples/06_matching/images/thumb/sphx_glr_plot_07_match_labels_thumb.png
    :alt:

  :doc:`/auto_examples/06_matching/plot_07_match_labels`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Matching habitat labels across subjects</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /auto_examples/06_matching/plot_01_label_switching
   /auto_examples/06_matching/plot_02_overlap_cases
   /auto_examples/06_matching/plot_03_prototype_steps
   /auto_examples/06_matching/plot_04_prototype_metrics
   /auto_examples/06_matching/plot_05_frozen_prototypes
   /auto_examples/06_matching/plot_06_downstream_tables
   /auto_examples/06_matching/plot_07_match_labels