kwneuro.harmonize
=================

.. py:module:: kwneuro.harmonize

.. autoapi-nested-parse::

   ComBat harmonization for multi-site scalar brain volumes.



Classes
-------

.. autoapisummary::

   kwneuro.harmonize.CombatEstimates


Functions
---------

.. autoapisummary::

   kwneuro.harmonize.harmonize_volumes


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

.. py:class:: CombatEstimates

   ComBat parameter estimates from a harmonization run.

   These estimates can be used to inspect the fitted model or, in the future,
   to harmonize new data using the same model via ``neuroCombatFromTraining``.


   .. py:attribute:: estimates
      :type:  dict[str, Any]

      Empirical Bayes estimates of batch effects (gamma/delta parameters,
      pooled variance, etc.).


   .. py:attribute:: info
      :type:  dict[str, Any]

      Metadata about the harmonization (batch levels, sample counts,
      design matrix, etc.).


.. py:function:: harmonize_volumes(volumes: collections.abc.Sequence[kwneuro.resource.VolumeResource], covars: pandas.DataFrame, batch_col: str, mask: kwneuro.resource.VolumeResource, *, categorical_cols: list[str] | None = None, continuous_cols: list[str] | None = None, eb: bool = True, parametric: bool = True, mean_only: bool = False, ref_batch: str | None = None, preserve_out_of_mask: bool = False) -> tuple[list[kwneuro.resource.InMemoryVolumeResource], CombatEstimates]

   Harmonize 3D scalar brain volumes across scanner sites using ComBat.

   All volumes must be in the same voxel space (same shape). A mask selects
   which voxels to harmonize; out-of-mask voxels are zeroed by default or
   preserved from the original volumes if ``preserve_out_of_mask`` is True.

   :param volumes: Sequence of 3D scalar VolumeResource objects, one per
                   subject/scan. Must all have identical shape.
   :param covars: A pandas DataFrame with one row per volume. Must contain at
                  least the batch column. Row order must correspond to ``volumes``.
   :param batch_col: Column name in ``covars`` identifying the scanner/site.
   :param mask: A 3D VolumeResource. Voxels where mask > 0 are included in
                harmonization. Must have the same shape as the input volumes.
   :param categorical_cols: Column names in ``covars`` for categorical covariates
                            to preserve (e.g. ``["sex"]``).
   :param continuous_cols: Column names in ``covars`` for continuous covariates
                           to preserve (e.g. ``["age"]``).
   :param eb: Whether to use Empirical Bayes estimation. Default True.
   :param parametric: Whether to use parametric adjustments. Default True.
   :param mean_only: Whether to only adjust batch means (not variances).
   :param ref_batch: Optional reference batch whose data is preserved as-is.
   :param preserve_out_of_mask: If True, voxels outside the mask retain their
                                original values. If False (default), they are set to zero.

   :returns: A tuple of (harmonized_volumes, combat_estimates). The first element
             is a list of harmonized InMemoryVolumeResources in the same order as
             the input. The second is a CombatEstimates object containing the
             fitted model parameters.

   :raises ValueError: If inputs are invalid (shape mismatch, missing columns,
       fewer than 2 batches, empty mask, etc.).