kwneuro.structural
==================

.. py:module:: kwneuro.structural


Classes
-------

.. autoapisummary::

   kwneuro.structural.StructuralImage


Module Contents
---------------

.. py:class:: StructuralImage

   A structural (e.g. T1-weighted) MRI image.


   .. py:attribute:: volume
      :type:  kwneuro.resource.VolumeResource

      The structural MRI volume. Expected to be a 3D volume.


   .. py:method:: load() -> StructuralImage

      Load any on-disk resources into memory and return a StructuralImage with all resources loaded.



   .. py:method:: save(path: kwneuro.util.PathLike, basename: str) -> StructuralImage

      Save the volume to disk and return a StructuralImage with an on-disk resource.

      :param path: The desired save directory.
      :param basename: The desired file basename (without extension).

      Returns: A StructuralImage with its internal resource being on-disk.



   .. py:method:: correct_bias() -> StructuralImage

      Apply N4 bias field correction using ANTsPy.

      Returns: A new StructuralImage with the bias-corrected volume.



   .. py:method:: extract_brain() -> kwneuro.resource.InMemoryVolumeResource

      Extract a brain mask using HD-BET.

      This is meant to be convenient rather than efficient.
      Using this in a loop could result in unnecessary repetition of file I/O operations.
      For efficiency, see :func:`kwneuro.masks.brain_extract_structural_batch`.



   .. py:method:: segment_tissues(mask: kwneuro.resource.VolumeResource | None = None, method: str = 'atropos') -> kwneuro.resource.InMemoryVolumeResource

      Segment brain tissues into labeled classes.

      :param mask: Optional brain mask. Used only with ``method="atropos"``; when omitted
                   a mask is generated automatically via :func:`ants.get_mask`.
                   Ignored for ``method="deep_atropos"``, which handles preprocessing internally.
      :param method: Segmentation method. One of:

                     - ``"atropos"`` *(default)*: Classical ANTsPy k-means Atropos.
                       Returns a 3-class labeled volume (1=CSF, 2=GM, 3=WM).
                       No extra installation required.
                     - ``"deep_atropos"``: Deep-learning segmentation via ANTsPyNet.
                       Returns a 6-class labeled volume (1=CSF, 2=GM, 3=WM, 4=deep GM,
                       5=cerebellum, 6=brainstem). Requires ``pip install kwneuro[antspynet]``.

      Returns: A labeled segmentation volume.



   .. py:method:: parcellate(method: str = 'dkt') -> kwneuro.resource.InMemoryVolumeResource

      Cortical parcellation.

      :param method: Parcellation method. Currently only ``"dkt"`` is supported:
                     Desikan-Killiany-Tourville (DKT) cortical labeling via ANTsPyNet
                     (~84 regions). Requires ``pip install kwneuro[antspynet]``.

      Returns: A DKT-labeled parcellation volume.