.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples\01_data_in\plot_03_numpy_arrays.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_01_data_in_plot_03_numpy_arrays.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_01_data_in_plot_03_numpy_arrays.py:


Load from NumPy arrays
======================

**Background.** Deep-learning and custom pipelines often hold images as
NumPy arrays (or tensors converted to NumPy). An array has no voxel size or
position, so HABIT pairs it with a :class:`~habit.contracts.Geometry` that
records spacing, origin and direction.

**Purpose.** You get a :class:`~habit.contracts.Cohort` built from arrays,
the first rows of its raw voxel-feature table, and a figure showing the
array become a plottable subject.

**When to use.** Use this when your data is already in memory as arrays;
skip it if you have files in the HABIT folder layout
(:doc:`/auto_examples/01_data_in/plot_01_directory`).

**Key terms.**

* **cohort / subject / ROI** -- see
  :doc:`/auto_examples/01_data_in/plot_01_directory`.
* **geometry** -- spacing, origin and direction that place an array in
  physical space; here the image and its mask share one geometry.
* **voxel feature** -- the numbers that describe one voxel (here, its LAP
  intensity); one column per feature.

Arrays use axis order ``(z, y, x)``. The mask is integer labels,
``0`` = background. One person and several people are each a
:class:`~habit.contracts.Cohort`.

.. GENERATED FROM PYTHON SOURCE LINES 33-34

One person. Change the two paths to your files, then keep the arrays.

.. GENERATED FROM PYTHON SOURCE LINES 34-71

.. code-block:: Python

    from pathlib import Path

    import matplotlib.pyplot as plt
    import numpy as np
    import SimpleITK as sitk

    from habit.contracts import ArrayImageRef, Cohort, Geometry, Subject
    from habit.datasets import fetch_demo
    from habit.viz import plot_numpy_ingest
    from habit.voxel_features import RawVoxelFeatures

    DATA = fetch_demo()
    IMAGE = DATA / "images" / "subj001" / "LAP" / "WATER__WATER__Ax_Dyn_LAVA_Flex+C_Series0009.nrrd"
    MASK = DATA / "masks" / "subj001" / "LAP" / "WATER__BH_Ax_LAVA_Flex_10min_Series0017_mask.nrrd"
    sitk_image = sitk.ReadImage(str(IMAGE))
    # GetArrayFromImage already returns (z, y, x); the mask must be integer labels.
    array = sitk.GetArrayFromImage(sitk_image)
    mask = np.asarray(sitk.GetArrayFromImage(sitk.ReadImage(str(MASK))), dtype=np.int32)
    # Arrays carry no physical metadata, so copy spacing / origin / direction here.
    geometry = Geometry.from_array(
        array.shape,
        spacing=tuple(sitk_image.GetSpacing()),
        origin=tuple(sitk_image.GetOrigin()),
        direction=tuple(sitk_image.GetDirection()),
    )
    np_subject = Subject(
        subject_id="subj001",
        images={"LAP": ArrayImageRef(array=array, geometry=geometry)},
        masks={"LAP": ArrayImageRef(array=mask, geometry=geometry)},
    )
    one = Cohort([np_subject], name="one")
    print(one)
    # Sanity check: the array-backed subject already feeds a HABIT extractor.
    field = RawVoxelFeatures(modalities=["LAP"])(np_subject)
    print(field.feature_frame().head())
    field.feature_frame().head()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    HABIT demo data (cached)
    DATA (preprocessed root): C:\Users\dongm\.habit_data\demo-data-v1\preprocessed

    On-disk inventory of this folder:
      subjects (5): subj001, subj002, subj003, subj004, subj005
      image series: LAP, PVP, delay_3min, pre_contrast
      mask keys:    LAP, PVP, delay_3min, pre_contrast
      example image: images/subj001/delay_3min/WATER__BH_Ax_LAVA_Flex_3min_Series0012.nrrd
      example mask:  masks/subj001/delay_3min/WATER__BH_Ax_LAVA_Flex_10min_Series0017_mask.nrrd

    Your own data must use the same folder tree (change IDs / series names):

      DATA/
        images/<subject_id>/<modality>/<one image file>
        masks/<subject_id>/<roi>/<one mask file>

    Then load it with the same call the demos use:

      cohort = cohort_from_directory(DATA, modalities=("LAP",), roi="LAP")

    Swap DATA / modalities / roi to match your tree. Mask key is often the
    same as one image series (here LAP).
    Cohort(1 subjects [subj001], name='one')
          LAP
    0  1020.0
    1  1018.0
    2  1077.0
    3  1073.0
    4  1033.0


.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>LAP</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>1020.0</td>
        </tr>
        <tr>
          <th>1</th>
          <td>1018.0</td>
        </tr>
        <tr>
          <th>2</th>
          <td>1077.0</td>
        </tr>
        <tr>
          <th>3</th>
          <td>1073.0</td>
        </tr>
        <tr>
          <th>4</th>
          <td>1033.0</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 72-74

Visual summary of this route: the array itself (left, as a colour matrix)
becomes a plottable Subject (right, zoomed to the ROI).

.. GENERATED FROM PYTHON SOURCE LINES 74-82

.. code-block:: Python

    Path("out").mkdir(exist_ok=True)
    fig = plot_numpy_ingest(
        np_subject.image("LAP"),
        roi_mask=np_subject.mask("LAP"),
    )
    fig.savefig("out/numpy_subject_ingest.png", dpi=150, bbox_inches="tight")
    plt.show()




.. image-sg:: /auto_examples/01_data_in/images/sphx_glr_plot_03_numpy_arrays_001.png
   :alt: From NumPy arrays to HABIT, Subject anatomy + ROI
   :srcset: /auto_examples/01_data_in/images/sphx_glr_plot_03_numpy_arrays_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 83-84

Several people. One Subject per person, then one cohort.

.. GENERATED FROM PYTHON SOURCE LINES 84-102

.. code-block:: Python

    IMAGE_2 = DATA / "images" / "subj002" / "LAP" / "012_WATERWATERAxDynLAVAFlexC.nrrd"
    MASK_2 = DATA / "masks" / "subj002" / "LAP" / "016_WATERWATERBHAxLAVAFlex5min_mask.nrrd"
    sitk_image_2 = sitk.ReadImage(str(IMAGE_2))
    array_2 = sitk.GetArrayFromImage(sitk_image_2)
    mask_2 = np.asarray(sitk.GetArrayFromImage(sitk.ReadImage(str(MASK_2))), dtype=np.int32)
    geometry_2 = Geometry.from_array(
        array_2.shape,
        spacing=tuple(sitk_image_2.GetSpacing()),
        origin=tuple(sitk_image_2.GetOrigin()),
        direction=tuple(sitk_image_2.GetDirection()),
    )
    subject_2 = Subject(
        subject_id="subj002",
        images={"LAP": ArrayImageRef(array=array_2, geometry=geometry_2)},
        masks={"LAP": ArrayImageRef(array=mask_2, geometry=geometry_2)},
    )
    many = Cohort([np_subject, subject_2], name="many")
    print(many)




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Cohort(2 subjects [subj001, subj002], name='many')





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 1.396 seconds)


.. _sphx_glr_download_auto_examples_01_data_in_plot_03_numpy_arrays.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_03_numpy_arrays.ipynb <plot_03_numpy_arrays.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_03_numpy_arrays.py <plot_03_numpy_arrays.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_03_numpy_arrays.zip <plot_03_numpy_arrays.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_