.. _sphx_glr_auto_examples_01_data_in:

1. Data In
==========

**Background.** Every habitat analysis starts by telling HABIT which images
and which tumour mask belong to which patient. **Purpose.** Each page turns
files or arrays you already have into a :class:`~habit.contracts.Cohort`;
terms are defined on :doc:`/auto_examples/01_data_in/plot_01_directory`.

The :doc:`complete analysis </auto_examples/00_full_pipeline/plot_01_full_pipeline>`
starts from a :class:`~habit.contracts.Cohort`. Every route on this
section ends in one. Each page shows
two assemblies: ``Cohort([one_subject])`` and ``Cohort([several_subjects])``.
Pass that cohort to ``fit`` / ``fit_predict``. A Python list is not a cohort.

Pick the page that matches the files you already have.

* **HABIT directory** — ``images/<subject>/<series>/<one file>`` and
  ``masks/<subject>/<roi>/<one file>``. One series or several. The mask
  folder name can differ from the series name.
  :doc:`/auto_examples/01_data_in/plot_01_directory`.
* **Loose NIfTI, NRRD, or MetaImage** — one pair or many. You choose the
  series name and the ROI name. Image and mask grids may differ.
  :doc:`/auto_examples/01_data_in/plot_04_nifti_files`.
* **SimpleITK images already in memory** —
  :doc:`/auto_examples/01_data_in/plot_02_simpleitk`.
* **NumPy arrays or deep-learning tensors** — axis order ``(z, y, x)``,
  integer mask, ``0`` = background.
  :doc:`/auto_examples/01_data_in/plot_03_numpy_arrays`.

DICOM, and series that still need resampling or bias correction, are not a
load route. Preprocess them first (:doc:`/how_to/preprocess`), then use the
directory page. The official demo pack is already preprocessed.

``read_image`` / ``read_mask`` accept what SimpleITK reads
(``.nii``, ``.nii.gz``, ``.nrrd``, ``.mha``, ``.mhd``).


.. 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. Before any habitat can be found, HABIT needs to know which images and which tumour mask belong to each patient. The simplest way is a fixed folder layout that HABIT reads in one call.">

.. only:: html

  .. image:: /auto_examples/01_data_in/images/thumb/sphx_glr_plot_01_directory_thumb.png
    :alt:

  :doc:`/auto_examples/01_data_in/plot_01_directory`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Load from directory</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Many imaging scripts already hold images as SimpleITK objects. HABIT can wrap those objects directly, keeping their spacing, origin and direction, so no files have to be rearranged.">

.. only:: html

  .. image:: /auto_examples/01_data_in/images/thumb/sphx_glr_plot_02_simpleitk_thumb.png
    :alt:

  :doc:`/auto_examples/01_data_in/plot_02_simpleitk`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Load from SimpleITK</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="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 Geometry that records spacing, origin and direction.">

.. only:: html

  .. image:: /auto_examples/01_data_in/images/thumb/sphx_glr_plot_03_numpy_arrays_thumb.png
    :alt:

  :doc:`/auto_examples/01_data_in/plot_03_numpy_arrays`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Load from NumPy arrays</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background. Images and masks often sit as loose files (NIfTI, NRRD, MetaImage) rather than in the HABIT folder layout. HABIT can point at each file directly and reads the voxels only when a stage needs them.">

.. only:: html

  .. image:: /auto_examples/01_data_in/images/thumb/sphx_glr_plot_04_nifti_files_thumb.png
    :alt:

  :doc:`/auto_examples/01_data_in/plot_04_nifti_files`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Load from NIfTI files</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /auto_examples/01_data_in/plot_01_directory
   /auto_examples/01_data_in/plot_02_simpleitk
   /auto_examples/01_data_in/plot_03_numpy_arrays
   /auto_examples/01_data_in/plot_04_nifti_files