goatpy.batch_correction
=======================

.. py:module:: goatpy.batch_correction

.. autoapi-nested-parse::

   batch_correction.py
   ===================

   Batch correction for MALDI SpatialData objects.

   Supports two methods:

   * Harmony
       Operates on a PCA embedding.
       Corrected embeddings are stored in:

           adata.obsm["X_pca_harmony"]

       The raw intensity matrix (adata.X) is NOT modified.

   * ComBat
       Operates directly on adata.X.
       Corrected intensities overwrite:

           adata.X


   ---------------------------------------------------------------------------
   .. important::

      This function assumes the data has already been normalised
      (e.g. TIC or RMS normalisation).
      
      Applying batch correction to raw counts will produce misleading results.

   ---------------------------------------------------------------------------
   USAGE
   ---------------------------------------------------------------------------

   # Option 1 — merge inside batch_correction
   merged = batch_correction(
       sdatas=[sdata1, sdata2],
       batch_names=["A", "B"],
       method="harmony",
   )

   # Option 2 — use an already merged object
   merged = batch_correction(
       pre_merged=merged_sdata,
       method="combat",
   )



Functions
---------

.. autoapisummary::

   goatpy.batch_correction.batch_correction


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

.. py:function:: batch_correction(sdatas: Optional[list[spatialdata.SpatialData]] = None, batch_names: Optional[list[str]] = None, pre_merged: Optional[spatialdata.SpatialData] = None, method: Literal['harmony', 'combat'] = 'harmony', pcs: int = 30, covariates: Optional[list[str]] = None, table_name: str = 'maldi_adata', batch_col: str = 'batch', feature_join: str = 'inner', random_state: int = 42) -> spatialdata.SpatialData

   Merge SpatialData objects and apply batch correction.

   :param sdatas: SpatialData objects to merge.
   :param batch_names: Batch labels corresponding to sdatas.
   :param pre_merged: Already merged SpatialData object.
                      If provided, merge_spatialdata is skipped.
   :param method: "harmony" or "combat"
   :param pcs: Number of PCs for Harmony.
   :param covariates: Covariates to preserve during ComBat.
   :param table_name: AnnData table name.
   :param batch_col: obs column containing batch labels.
   :param feature_join: "inner" or "outer"
   :param random_state: Random seed for Harmony.

   :rtype: SpatialData