combatlearn 1.4.0__tar.gz → 2.0.0__tar.gz

{combatlearn-1.4.0 → combatlearn-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: combatlearn
-Version: 1.4.0
+Version: 2.0.0
 Summary: Batch-effect harmonization for machine learning frameworks.
 Author-email: Ettore Rocchi <ettoreroc@gmail.com>
 License: MIT

{combatlearn-1.4.0 → combatlearn-2.0.0}/combatlearn/__init__.py

@@ -1,5 +1,5 @@
 from .sklearn_api import ComBat
 
 __all__ = ["ComBat"]
-__version__ = "1.4.0"
+__version__ = "2.0.0"
 __author__ = "Ettore Rocchi"

combatlearn-2.0.0/combatlearn/_utils.py

@@ -0,0 +1,21 @@
+"""Internal utilities shared across combatlearn modules."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .core import ArrayLike
+
+
+def _subset(obj: ArrayLike | None, idx: pd.Index) -> pd.DataFrame | pd.Series | None:
+    """Subset array-like object by index."""
+    if obj is None:
+        return None
+    if isinstance(obj, pd.Series | pd.DataFrame):
+        return obj.loc[idx]
+    else:
+        if isinstance(obj, np.ndarray) and obj.ndim == 1:
+            return pd.Series(obj, index=idx)
+        else:
+            return pd.DataFrame(obj, index=idx)

combatlearn-2.0.0/combatlearn/inspection.py

@@ -0,0 +1,194 @@
+"""Standalone inspection functions for fitted ComBat models."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    from .sklearn_api import ComBat
+
+
+def feature_batch_diagnostics(
+    combat: ComBat,
+    mode: Literal["magnitude", "distribution"] = "magnitude",
+    weighted: bool = True,
+) -> pd.DataFrame:
+    """Compute per-feature batch effect magnitude.
+
+    Returns a DataFrame with columns ``location``, ``scale``, and
+    ``combined``. Location is the (weighted) RMS of gamma across batches
+    (standardized mean shifts). Scale is the (weighted) RMS of log-delta
+    across batches (log-fold variance change). Combined is the Euclidean
+    norm sqrt(location**2 + scale**2). Using RMS provides L2-consistent
+    aggregation; using log(delta) ensures symmetry.
+
+    Parameters
+    ----------
+    combat : ComBat
+        A fitted ``ComBat`` instance.
+    mode : {'magnitude', 'distribution'}, default='magnitude'
+        - 'magnitude': Returns L2-consistent absolute batch effect magnitudes.
+          Suitable for ranking, thresholding, and cross-dataset comparison.
+        - 'distribution': Returns column-wise normalized proportions (each column
+          sums to 1, values in range [0, 1]), representing the relative contribution
+          of each feature to the total location, scale, or combined batch effect.
+          Note: normalization is applied independently to each column, so the
+          Euclidean relationship (combined**2 = location**2 + scale**2) no longer holds.
+    weighted : bool, default=True
+        If True, compute a weighted RMS where each batch is weighted by its
+        sample size. This gives more influence to larger batches, producing
+        a more statistically representative summary. If False, all batches
+        contribute equally regardless of size.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with index=feature names, columns=['location', 'scale', 'combined'],
+        sorted by 'combined' descending.
+
+    Raises
+    ------
+    ValueError
+        If the model is not fitted or if mode is invalid.
+    """
+    if not hasattr(combat, "_model") or not hasattr(combat._model, "_gamma_star"):
+        raise ValueError(
+            "This ComBat instance is not fitted yet. Call 'fit' before 'feature_batch_diagnostics'."
+        )
+
+    if mode not in ["magnitude", "distribution"]:
+        raise ValueError(f"mode must be 'magnitude' or 'distribution', got '{mode}'")
+
+    feature_names = combat._model._grand_mean.index
+    gamma_star = combat._model._gamma_star
+    delta_star = combat._model._delta_star
+
+    if weighted:
+        # Batch sample sizes as weights, normalized to sum to 1
+        n_per_batch = combat._model._n_per_batch
+        weights = np.array(
+            [n_per_batch[str(lvl)] for lvl in combat._model._batch_levels], dtype=np.float64
+        )
+        weights = weights / weights.sum()
+
+        # Location effect: weighted RMS of gamma across batches
+        location = np.sqrt((weights[:, np.newaxis] * gamma_star**2).sum(axis=0))
+
+        # Scale effect: weighted RMS of log(delta) across batches
+        if not combat.mean_only:
+            scale = np.sqrt((weights[:, np.newaxis] * np.log(delta_star) ** 2).sum(axis=0))
+        else:
+            scale = np.zeros_like(location)
+    else:
+        # Location effect: unweighted RMS of gamma across batches
+        location = np.sqrt((gamma_star**2).mean(axis=0))
+
+        # Scale effect: unweighted RMS of log(delta) across batches
+        if not combat.mean_only:
+            scale = np.sqrt((np.log(delta_star) ** 2).mean(axis=0))
+        else:
+            scale = np.zeros_like(location)
+
+    # Euclidean to treat location and scale as orthogonal dimensions
+    combined = np.sqrt(location**2 + scale**2)
+
+    if mode == "distribution":
+        # Normalize each column independently to sum to 1
+        location_sum = location.sum()
+        scale_sum = scale.sum()
+        combined_sum = combined.sum()
+
+        location = location / location_sum if location_sum > 0 else location
+        scale = scale / scale_sum if scale_sum > 0 else scale
+        combined = combined / combined_sum if combined_sum > 0 else combined
+
+    return pd.DataFrame(
+        {
+            "location": location,
+            "scale": scale,
+            "combined": combined,
+        },
+        index=feature_names,
+    ).sort_values("combined", ascending=False)
+
+
+def summary(combat: ComBat) -> str:
+    """Return a human-readable diagnostic report after fitting.
+
+    Parameters
+    ----------
+    combat : ComBat
+        A fitted ``ComBat`` instance.
+
+    Returns
+    -------
+    str
+        Multi-line summary string.
+
+    Raises
+    ------
+    ValueError
+        If the model is not fitted.
+    """
+    if not hasattr(combat, "_model") or not hasattr(combat._model, "_gamma_star"):
+        raise ValueError("This ComBat instance is not fitted yet. Call 'fit' before 'summary'.")
+
+    lines: list[str] = []
+    lines.append("ComBat Summary")
+    lines.append("=" * 40)
+    lines.append(f"Method:          {combat.method}")
+    lines.append(f"Parametric:      {combat.parametric}")
+    lines.append(f"Mean only:       {combat.mean_only}")
+    lines.append(f"Reference batch: {combat.reference_batch or 'None'}")
+
+    batch_levels = combat._model._batch_levels
+    n_per_batch = combat._model._n_per_batch
+    lines.append(f"Number of batches: {len(batch_levels)}")
+    lines.append("Samples per batch:")
+    for lvl in batch_levels:
+        lines.append(f"  {lvl}: {n_per_batch[str(lvl)]}")
+
+    n_features = len(combat._model._grand_mean)
+    lines.append(f"Number of features: {n_features}")
+
+    lines.append("")
+    lines.append("Top 5 features by batch effect (combined):")
+    importance = feature_batch_diagnostics(combat)
+    top5 = importance.head(5)
+    for feat, row in top5.iterrows():
+        lines.append(f"  {feat}: {row['combined']:.4f}")
+
+    # Diagnostics table
+    lines.append("")
+    lines.append("Diagnostics")
+    lines.append("=" * 40)
+    col_w = 34
+    lines.append(f"{'Metric':<{col_w}}Value")
+    lines.append(f"{'------':<{col_w}}-----")
+
+    if hasattr(combat, "_batch_var_before_"):
+        lines.append(f"{'Batch var. explained (before)':<{col_w}}{combat._batch_var_before_:.1%}")
+    if hasattr(combat, "_batch_var_after_"):
+        lines.append(f"{'Batch var. explained (after)':<{col_w}}{combat._batch_var_after_:.1%}")
+
+    design_cond = getattr(combat._model, "_design_cond", None)
+    if design_cond is not None:
+        lines.append(f"{'Design matrix condition number':<{col_w}}{design_cond:.1f}")
+
+    conv_info = getattr(combat._model, "_convergence_info", [])
+    if conv_info:
+        eb_type = "parametric" if combat.parametric else "non-parametric"
+        lines.append(f"EB convergence ({eb_type}):")
+        for info in conv_info:
+            batch_name = info["batch"]
+            if info["converged"]:
+                status = f"converged ({info['iterations']} iter)"
+            else:
+                max_change = max(info["final_gamma_change"], info["final_delta_change"])
+                status = f"NOT CONVERGED ({info['iterations']} iter, \u0394={max_change:.2e})"
+            lines.append(f"  {batch_name!s:<{col_w - 2}}{status}")
+
+    return "\n".join(lines)

{combatlearn-1.4.0 → combatlearn-2.0.0}/combatlearn/metrics.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 import numpy.typing as npt
@@ -13,8 +13,12 @@ from sklearn.decomposition import PCA
 from sklearn.metrics import davies_bouldin_score, silhouette_score
 from sklearn.neighbors import NearestNeighbors
 
+from ._utils import _subset
 from .core import ArrayLike
 
+if TYPE_CHECKING:
+    from .sklearn_api import ComBat
+
 
 def _compute_pca_embedding(
     X_before: npt.NDArray[Any],
@@ -623,225 +627,134 @@ def _compute_alignment_metrics(
     }
 
 
-class ComBatMetricsMixin:
-    """Mixin providing batch effect metrics for the ComBat wrapper."""
-
-    @property
-    def metrics_(self) -> dict[str, Any] | None:
-        """Return cached metrics from last fit_transform with compute_metrics=True.
-
-        Returns
-        -------
-        dict or None
-            Cached metrics dictionary, or None if no metrics have been computed.
-        """
-        return getattr(self, "_metrics_cache", None)
-
-    def compute_batch_metrics(
-        self,
-        X: ArrayLike,
-        batch: ArrayLike | None = None,
-        *,
-        pca_components: int | None = None,
-        k_neighbors: list[int] | None = None,
-        kbet_k0: int | None = None,
-        lisi_perplexity: int = 30,
-        n_jobs: int = 1,
-        nn_algorithm: str = "auto",
-    ) -> dict[str, Any]:
-        """
-        Compute batch effect metrics before and after ComBat correction.
-
-        Parameters
-        ----------
-        X : array-like of shape (n_samples, n_features)
-            Input data to evaluate.
-        batch : array-like of shape (n_samples,), optional
-            Batch labels. If None, uses the batch stored at construction.
-        pca_components : int, optional
-            Number of PCA components for dimensionality reduction before
-            computing metrics. If None (default), metrics are computed in
-            the original feature space. Must be less than min(n_samples, n_features).
-        k_neighbors : list of int, default=[5, 10, 50]
-            Values of k for k-NN preservation metric.
-        kbet_k0 : int, optional
-            Neighborhood size for kBET. Default is 10% of samples.
-        lisi_perplexity : int, default=30
-            Perplexity for LISI computation.
-        n_jobs : int, default=1
-            Number of parallel jobs for neighbor computations.
-        nn_algorithm : {'auto', 'ball_tree', 'kd_tree', 'brute'}, default='auto'
-            Algorithm used for nearest neighbor computation. Passed to
-            ``sklearn.neighbors.NearestNeighbors``.
-
-        Returns
-        -------
-        dict
-            Dictionary with three main keys:
-
-            - ``batch_effect``: Silhouette, Davies-Bouldin, kBET, LISI, variance ratio
-              (each with 'before' and 'after' values)
-            - ``preservation``: k-NN preservation fractions, distance correlation
-            - ``alignment``: Centroid distance, Levene statistic (each with
-              'before' and 'after' values)
-
-        Raises
-        ------
-        ValueError
-            If the model is not fitted or if pca_components is invalid.
-        """
-        _valid_nn = {"auto", "ball_tree", "kd_tree", "brute"}
-        if nn_algorithm not in _valid_nn:
-            raise ValueError(f"nn_algorithm must be one of {_valid_nn}, got '{nn_algorithm}'")
-
-        if not hasattr(self, "_model") or not hasattr(self._model, "_gamma_star"):
-            raise ValueError(
-                "This ComBat instance is not fitted yet. Call 'fit' before 'compute_batch_metrics'."
-            )
+def compute_batch_metrics(
+    combat: ComBat,
+    X: ArrayLike,
+    batch: ArrayLike | None = None,
+    *,
+    pca_components: int | None = None,
+    k_neighbors: list[int] | None = None,
+    kbet_k0: int | None = None,
+    lisi_perplexity: int = 30,
+    n_jobs: int = 1,
+    nn_algorithm: str = "auto",
+) -> dict[str, Any]:
+    """
+    Compute batch effect metrics before and after ComBat correction.
 
-        if not isinstance(X, pd.DataFrame):
-            X = pd.DataFrame(X)
+    Parameters
+    ----------
+    combat : ComBat
+        A fitted ``ComBat`` instance.
+    X : array-like of shape (n_samples, n_features)
+        Input data to evaluate.
+    batch : array-like of shape (n_samples,), optional
+        Batch labels. If None, uses the batch stored at construction.
+    pca_components : int, optional
+        Number of PCA components for dimensionality reduction before
+        computing metrics. If None (default), metrics are computed in
+        the original feature space. Must be less than min(n_samples, n_features).
+    k_neighbors : list of int, default=[5, 10, 50]
+        Values of k for k-NN preservation metric.
+    kbet_k0 : int, optional
+        Neighborhood size for kBET. Default is 10% of samples.
+    lisi_perplexity : int, default=30
+        Perplexity for LISI computation.
+    n_jobs : int, default=1
+        Number of parallel jobs for neighbor computations.
+    nn_algorithm : {'auto', 'ball_tree', 'kd_tree', 'brute'}, default='auto'
+        Algorithm used for nearest neighbor computation. Passed to
+        ``sklearn.neighbors.NearestNeighbors``.
 
-        idx = X.index
+    Returns
+    -------
+    dict
+        Dictionary with three main keys:
+
+        - ``batch_effect``: Silhouette, Davies-Bouldin, kBET, LISI, variance ratio
+          (each with 'before' and 'after' values)
+        - ``preservation``: k-NN preservation fractions, distance correlation
+        - ``alignment``: Centroid distance, Levene statistic (each with
+          'before' and 'after' values)
+
+    Raises
+    ------
+    ValueError
+        If the model is not fitted or if pca_components is invalid.
+    """
+    _valid_nn = {"auto", "ball_tree", "kd_tree", "brute"}
+    if nn_algorithm not in _valid_nn:
+        raise ValueError(f"nn_algorithm must be one of {_valid_nn}, got '{nn_algorithm}'")
 
-        if batch is None:
-            batch_vec = self._subset(self.batch, idx)  # type: ignore[attr-defined]
-        else:
-            if isinstance(batch, pd.Series | pd.DataFrame):
-                batch_vec = batch.loc[idx] if hasattr(batch, "loc") else batch
-            elif isinstance(batch, np.ndarray):
-                batch_vec = pd.Series(batch, index=idx)
-            else:
-                batch_vec = pd.Series(batch, index=idx)
-
-        batch_labels = np.array(batch_vec)
-
-        X_before = X.values
-        X_after = self.transform(X).values  # type: ignore[attr-defined]
-
-        n_samples, n_features = X_before.shape
-        if kbet_k0 is None:
-            kbet_k0 = max(10, int(0.10 * n_samples))
-        if k_neighbors is None:
-            k_neighbors = [5, 10, 50]
-
-        # Validate and apply PCA if requested
-        if pca_components is not None:
-            max_components = min(n_samples, n_features)
-            if pca_components >= max_components:
-                raise ValueError(
-                    f"pca_components={pca_components} must be less than "
-                    f"min(n_samples, n_features)={max_components}."
-                )
-            X_before_pca, X_after_pca, _ = _compute_pca_embedding(X_before, X_after, pca_components)
-        else:
-            X_before_pca = X_before
-            X_after_pca = X_after
-
-        batch_effect = _compute_batch_effect_metrics(
-            X_before_pca,
-            X_after_pca,
-            batch_labels,
-            kbet_k0=kbet_k0,
-            lisi_perplexity=lisi_perplexity,
-            nn_algorithm=nn_algorithm,
-        )
-        preservation = _compute_preservation_metrics(
-            X_before_pca,
-            X_after_pca,
-            k_neighbors,
-            n_jobs,
-            nn_algorithm=nn_algorithm,
-        )
-        alignment = _compute_alignment_metrics(
-            X_before,
-            X_after,
-            X_before_pca,
-            X_after_pca,
-            batch_labels,
+    if not hasattr(combat, "_model") or not hasattr(combat._model, "_gamma_star"):
+        raise ValueError(
+            "This ComBat instance is not fitted yet. Call 'fit' before 'compute_batch_metrics'."
         )
 
-        return {
-            "batch_effect": batch_effect,
-            "preservation": preservation,
-            "alignment": alignment,
-        }
-
-    def feature_batch_importance(
-        self,
-        mode: Literal["magnitude", "distribution"] = "magnitude",
-    ) -> pd.DataFrame:
-        """Compute per-feature batch effect magnitude.
-
-        Returns a DataFrame with columns ``location``, ``scale``, and
-        ``combined``. Location is the RMS of gamma across batches
-        (standardized mean shifts). Scale is the RMS of log-delta across
-        batches (log-fold variance change). Combined is the Euclidean norm
-        sqrt(location**2 + scale**2). Using RMS provides L2-consistent
-        aggregation; using log(delta) ensures symmetry.
-
-        Parameters
-        ----------
-        mode : {'magnitude', 'distribution'}, default='magnitude'
-            - 'magnitude': Returns L2-consistent absolute batch effect magnitudes.
-              Suitable for ranking, thresholding, and cross-dataset comparison.
-            - 'distribution': Returns column-wise normalized proportions (each column
-              sums to 1, values in range [0, 1]), representing the relative contribution
-              of each feature to the total location, scale, or combined batch effect.
-              Note: normalization is applied independently to each column, so the
-              Euclidean relationship (combined**2 = location**2 + scale**2) no longer holds.
-
-        Returns
-        -------
-        pd.DataFrame
-            DataFrame with index=feature names, columns=['location', 'scale', 'combined'],
-            sorted by 'combined' descending.
-
-        Raises
-        ------
-        ValueError
-            If the model is not fitted or if mode is invalid.
-        """
-        if not hasattr(self, "_model") or not hasattr(self._model, "_gamma_star"):
-            raise ValueError(
-                "This ComBat instance is not fitted yet. "
-                "Call 'fit' before 'feature_batch_importance'."
-            )
+    if not isinstance(X, pd.DataFrame):
+        X = pd.DataFrame(X)
 
-        if mode not in ["magnitude", "distribution"]:
-            raise ValueError(f"mode must be 'magnitude' or 'distribution', got '{mode}'")
+    idx = X.index
 
-        feature_names = self._model._grand_mean.index
-        gamma_star = self._model._gamma_star
-        delta_star = self._model._delta_star
+    if batch is None:
+        batch_vec = _subset(combat.batch, idx)
+    else:
+        if isinstance(batch, pd.Series | pd.DataFrame):
+            batch_vec = batch.loc[idx] if hasattr(batch, "loc") else batch
+        elif isinstance(batch, np.ndarray):
+            batch_vec = pd.Series(batch, index=idx)
+        else:
+            batch_vec = pd.Series(batch, index=idx)
 
-        # Location effect: RMS of gamma across batches (L2 aggregation)
-        location = np.sqrt((gamma_star**2).mean(axis=0))
+    batch_labels = np.array(batch_vec)
 
-        # Scale effect: RMS of log(delta) across batches
-        if not self.mean_only:  # type: ignore[attr-defined]
-            scale = np.sqrt((np.log(delta_star) ** 2).mean(axis=0))
-        else:
-            scale = np.zeros_like(location)
-
-        # Euclidean to treat location and scale as orthogonal dimensions
-        combined = np.sqrt(location**2 + scale**2)
-
-        if mode == "distribution":
-            # Normalize each column independently to sum to 1
-            location_sum = location.sum()
-            scale_sum = scale.sum()
-            combined_sum = combined.sum()
-
-            location = location / location_sum if location_sum > 0 else location
-            scale = scale / scale_sum if scale_sum > 0 else scale
-            combined = combined / combined_sum if combined_sum > 0 else combined
-
-        return pd.DataFrame(
-            {
-                "location": location,
-                "scale": scale,
-                "combined": combined,
-            },
-            index=feature_names,
-        ).sort_values("combined", ascending=False)
+    X_before = X.values
+    X_after = combat.transform(X).values
+
+    n_samples, n_features = X_before.shape
+    if kbet_k0 is None:
+        kbet_k0 = max(10, int(0.10 * n_samples))
+    if k_neighbors is None:
+        k_neighbors = [5, 10, 50]
+
+    # Validate and apply PCA if requested
+    if pca_components is not None:
+        max_components = min(n_samples, n_features)
+        if pca_components >= max_components:
+            raise ValueError(
+                f"pca_components={pca_components} must be less than "
+                f"min(n_samples, n_features)={max_components}."
+            )
+        X_before_pca, X_after_pca, _ = _compute_pca_embedding(X_before, X_after, pca_components)
+    else:
+        X_before_pca = X_before
+        X_after_pca = X_after
+
+    batch_effect = _compute_batch_effect_metrics(
+        X_before_pca,
+        X_after_pca,
+        batch_labels,
+        kbet_k0=kbet_k0,
+        lisi_perplexity=lisi_perplexity,
+        nn_algorithm=nn_algorithm,
+    )
+    preservation = _compute_preservation_metrics(
+        X_before_pca,
+        X_after_pca,
+        k_neighbors,
+        n_jobs,
+        nn_algorithm=nn_algorithm,
+    )
+    alignment = _compute_alignment_metrics(
+        X_before,
+        X_after,
+        X_before_pca,
+        X_after_pca,
+        batch_labels,
+    )
+
+    return {
+        "batch_effect": batch_effect,
+        "preservation": preservation,
+        "alignment": alignment,
+    }