kwneuro.build_template
======================

.. py:module:: kwneuro.build_template


Functions
---------

.. autoapisummary::

   kwneuro.build_template.average_volumes
   kwneuro.build_template.build_template
   kwneuro.build_template.build_multi_metric_template


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

.. py:function:: average_volumes(volume_list: collections.abc.Sequence[kwneuro.resource.VolumeResource], normalize: bool = True) -> kwneuro.resource.InMemoryVolumeResource

   Calculates the simple arithmetic average (mean) of a list of 3D scalar volumes.

   Input volumes are automatically resampled to the largest image space in the list.
   However, no registration is performed so all volumes should be in the same physical coordinate space to begin with.
   This is a simplified version of ANTs `average_images`. All volumes are treated with equal weight (1/N).

   :param volume_list: A list of 3D scalar VolumeResource objects. Volumes do not need
                       to share the same shape/resolution but must be physically aligned.

   :returns: A VolumeResource object containing the element-wise arithmetic mean of all input volumes in the largest image space.


.. py:function:: build_template(volume_list: collections.abc.Sequence[kwneuro.resource.VolumeResource], initial_template: kwneuro.resource.VolumeResource | None = None, iterations: int = 3) -> kwneuro.resource.InMemoryVolumeResource

   Constructs an unbiased mean shape template from a list of 3D scalar volumes using
   an iterative group-wise registration approach based on ANTs.

   The process follows the standard iterative unbiased approach:
   1. Register all images to the current template (using SyN and Affine transforms).
   2. Average the warped images to create a new template estimate.
   3. Average the resulting transformations (warp and affine) to calculate the mean shift.
   4. Apply the inverse of the mean shift to the template to correct bias toward the true mean.
   5. Sharpen the template to enhance edge definition.

   :param volume_list: A list of input 3D scalar volumes (VolumeResource objects).
                       If an initial template is not provided, the input volumes should all be rigidly aligned to
                       create a plausible initial average image.
   :param initial_template: An optional starting template volume. If None, the
                            initial template is the simple average of all input volumes.
   :param iterations: The number of iterations for the template refinement process.

   :returns: A VolumeResource object representing the final group-wise mean template.


.. py:function:: build_multi_metric_template(subject_list: collections.abc.Sequence[collections.abc.Mapping[str, kwneuro.resource.VolumeResource]], initial_template: collections.abc.Mapping[str, kwneuro.resource.VolumeResource] | None = None, weights: collections.abc.Mapping[str, numpy.floating] | None = None, iterations: int = 3) -> collections.abc.Mapping[str, kwneuro.resource.InMemoryVolumeResource]

   Constructs an unbiased mean shape template from a list of input volumes using
   an iterative group-wise registration approach based on ANTs, utilizing
   multiple image modalities simultaneously. See 'build_template' for more details.

   NOTE: The current implementation assumes input images are roughly pre-aligned.

   :param subject_list: A list of dictionaries where each subject maps modality names to their corresponding 3D scalar volumes (VolumeResource objects).
                        It is assumed that all volumes for a given subject are already co-registered.
   :param initial_template: An optional starting template volume. If None, the
                            initial template is the simple average of all input volumes.
   :param weights: The weight given to each volume type (modality) during the multivariate registration step.
                   The first entry is treated as the reference modality; all subsequent weights are normalized relative to
                   this first value before being passed to ANTs. If None, equal weights are assumed.
                   The dictionary length must match the number of modalities provided in subject_list.
   :param iterations: The number of iterations for the template refinement process.

   :returns: A VolumeResource object representing the final group-wise mean template (per modality)