.. _sphx_glr_auto_examples_02_stages:

2. Each stage
=============

**Background.** A two-step habitat analysis is a chain of stages:
extract voxel features, preprocess them, partition each tumour into
supervoxels, pool the cohort, fit one habitat model, assign labels.

**Purpose.** Each page runs one stage on demo data so you can see its
input, its output, and the parameters that matter.

These pages open the stage list of the
:doc:`complete analysis </auto_examples/00_full_pipeline/plot_01_full_pipeline>`.
``Stage``'s first argument is a label. ``Spec`` names the component.

* **extract** — :doc:`/auto_examples/02_stages/plot_06_voxel_intensities`,
  :doc:`/auto_examples/02_stages/plot_01_feature_routes`,
  :doc:`/auto_examples/02_stages/plot_02_expression`,
  :doc:`/auto_examples/02_stages/plot_02_custom_features`,
  :doc:`/auto_examples/02_stages/plot_03_voxel_texture`,
  :doc:`/auto_examples/02_stages/plot_07_voxel_texture`,
  :doc:`/auto_examples/02_stages/plot_08_derived_map`,
  :doc:`/auto_examples/02_stages/plot_09_texture_habitats`.
* **preprocess** — :doc:`/auto_examples/02_stages/plot_04_feature_preprocessing`,
  :doc:`/auto_examples/02_stages/plot_10_preprocess_features`,
  :doc:`/auto_examples/02_stages/plot_11_preprocess_compare`,
  :doc:`/auto_examples/02_stages/plot_06_texture_preprocessing`.
* **partition** — :doc:`/auto_examples/02_stages/plot_12_supervoxels`,
  :doc:`/auto_examples/02_stages/plot_05_supervoxel_features`.
* **fit** — :doc:`/auto_examples/02_stages/plot_13_fit_model`.
* **assign** — :doc:`/auto_examples/02_stages/plot_14_assign_labels`.


.. 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. The extract stage decides which numbers describe each voxel; habitats can only separate what those columns show. The simplest choice is the image intensities themselves.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_01_feature_routes_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_01_feature_routes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Voxel features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Built-in extractors cover intensities and texture. When your study needs its own voxel formula (here, liver DCE enhancement and wash-out), you write a small extractor class, register it under a name, and use that name in a Spec like any built-in one.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_02_custom_features_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_02_custom_features`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Clinicians often read DCE images as ratios (how much a voxel enhances, how fast it washes out) rather than raw signal. An expression extractor computes such ratios per voxel from a formula string, without writing a class.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_02_expression_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_02_expression`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Expression voxel features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Intensity alone cannot tell a smooth region from a mottled one of the same brightness. Voxel texture computes a radiomics feature in a small cube around every ROI voxel, giving one texture map per feature that clustering can use as a column.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_03_voxel_texture_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_03_voxel_texture`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Voxel texture and GPU</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. k-means groups rows by distance, so a column with large numbers (or a few extreme voxels) can decide the habitats on its own. Preprocessing rescales or clips the feature columns first; HABIT lets you do this at three points of the two-step analysis.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_04_feature_preprocessing_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_04_feature_preprocessing`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Feature preprocessing</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. The cohort model clusters supervoxels, not voxels, so each supervoxel needs its own row of numbers. That row can be a simple summary of its voxels (mean, median, SD) or radiomics texture computed on the supervoxel as a small ROI.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_05_supervoxel_features_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_05_supervoxel_features`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Supervoxel feature extraction and acceleration</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Texture columns have very different ranges, so the preprocess stage matters even more for texture than for intensity. Where the scaling state is learned (inside each subject, or once on the pooled cohort) also changes what the habitats mean.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_06_texture_preprocessing_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_06_texture_preprocessing`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Preprocessing voxel texture before clustering</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Habitat analysis clusters voxels by what they look like across the input images. The first stage, extract, turns each voxel inside the ROI into a row of numbers that later stages can cluster.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_06_voxel_intensities_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_06_voxel_intensities`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extracting voxel intensities</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. A voxel texture value describes how grey levels vary in a small cube around each ROI voxel, which intensity alone does not show. Here it is computed with one function call on an image and a mask.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_07_voxel_texture_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_07_voxel_texture`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extracting a voxel texture</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Habitats follow whatever columns the extract stage produces. Clustering derived DCE maps (enhancement and wash-out ratios) instead of raw intensities groups voxels by their enhancement pattern (contrast uptake and wash-out) rather than by absolute signal.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_08_derived_map_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_08_derived_map`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Clustering habitats from a derived map</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Texture maps can be clustered like intensities: each ROI voxel becomes one row of texture values, and k-means groups voxels with similar local patterns into habitats.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_09_texture_habitats_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_09_texture_habitats`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Clustering habitats from a texture field</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Raw intensities differ in range between phases and contain a few extreme voxels. The preprocess stage rescales the feature columns before clustering so that no single column dominates the distance.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_10_preprocess_features_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_10_preprocess_features`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Preprocessing features before clustering</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Preprocessing changes the distances k-means sees, so it can change the habitats. To see by how much, fit the same design twice, once with and once without preprocessing, and compare the two maps.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_11_preprocess_compare_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_11_preprocess_compare`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Comparing habitat maps with and without preprocessing</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. A tumour has tens of thousands of voxels. The two-step design first groups them, inside each subject, into small patches of similar voxels, so the cohort model later clusters a few rows per subject instead of every voxel.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_12_supervoxels_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_12_supervoxels`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Partitioning a ROI into supervoxels</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. After every subject is cut into supervoxels, fit learns one habitat definition from all of them together. Because the same model labels every patient, habitat 2 means the same feature profile in each subject.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_13_fit_model_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_13_fit_model`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fitting a cohort habitat model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. A fitted model only stores centroids. assign turns that into a picture: every supervoxel of a subject gets the id of its nearest centroid, and every voxel inherits the id of its supervoxel.">

.. only:: html

  .. image:: /auto_examples/02_stages/images/thumb/sphx_glr_plot_14_assign_labels_thumb.png
    :alt:

  :doc:`/auto_examples/02_stages/plot_14_assign_labels`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Assigning habitat labels</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /auto_examples/02_stages/plot_01_feature_routes
   /auto_examples/02_stages/plot_02_custom_features
   /auto_examples/02_stages/plot_02_expression
   /auto_examples/02_stages/plot_03_voxel_texture
   /auto_examples/02_stages/plot_04_feature_preprocessing
   /auto_examples/02_stages/plot_05_supervoxel_features
   /auto_examples/02_stages/plot_06_texture_preprocessing
   /auto_examples/02_stages/plot_06_voxel_intensities
   /auto_examples/02_stages/plot_07_voxel_texture
   /auto_examples/02_stages/plot_08_derived_map
   /auto_examples/02_stages/plot_09_texture_habitats
   /auto_examples/02_stages/plot_10_preprocess_features
   /auto_examples/02_stages/plot_11_preprocess_compare
   /auto_examples/02_stages/plot_12_supervoxels
   /auto_examples/02_stages/plot_13_fit_model
   /auto_examples/02_stages/plot_14_assign_labels