combatlearn 0.1.1__tar.gz → 0.2.0__tar.gz

{combatlearn-0.1.1/src/combatlearn.egg-info → combatlearn-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: combatlearn
-Version: 0.1.1
+Version: 0.2.0
 Summary: Batch-effect harmonization for machine learning frameworks.
 Author-email: Ettore Rocchi <ettoreroc@gmail.com>
 License: MIT License
@@ -37,15 +37,18 @@ License-File: LICENSE
 Requires-Dist: pandas>=1.3
 Requires-Dist: numpy>=1.21
 Requires-Dist: scikit-learn>=1.2
+Requires-Dist: plotly>=5.0
+Requires-Dist: nbformat>=4.2
+Requires-Dist: umap-learn>=0.5
 Requires-Dist: pytest>=7
 Dynamic: license-file
 
 # **combatlearn**
 
-[![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python)](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python)
+[![Python versions](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python)](https://www.python.org/)
 [![Test](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml/badge.svg)](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml)
 [![PyPI Downloads](https://static.pepy.tech/badge/combatlearn)](https://pepy.tech/projects/combatlearn)
-[![PyPI version](https://badge.fury.io/py/combatlearn.svg)](https://pypi.org/project/combatlearn/)
+[![PyPI Version](https://img.shields.io/pypi/v/combatlearn?cacheSeconds=300)](https://pypi.org/project/combatlearn/)
 [![License](https://img.shields.io/github/license/EttoreRocchi/combatlearn)](https://github.com/EttoreRocchi/combatlearn/blob/main/LICENSE)
 
 <div align="center">
@@ -56,7 +59,7 @@ Dynamic: license-file
 
 **Three methods**:
 - `method="johnson"` - classic ComBat (Johnson _et al._, 2007)
-- `method="fortin"` - covariate-aware ComBat (Fortin _et al._, 2018)
+- `method="fortin"` - neuroComBat (Fortin _et al._, 2018)
 - `method="chen"` - CovBat (Chen _et al._, 2022)
 
 ## Installation
@@ -111,7 +114,7 @@ print("Best parameters:", grid.best_params_)
 print(f"Best CV AUROC: {grid.best_score_:.3f}")
 ```
 
-For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/demo/combatlearn_demo.ipynb)
+For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/demo/combatlearn_demo.ipynb)
 
 ## `ComBat` parameters
 
@@ -136,6 +139,13 @@ The following section provides a detailed explanation of all parameters availabl
 | `covbat_cov_thresh` | float, int | `0.9` | For `"chen"` method only: Cumulative variance threshold $]0,1[$ to retain PCs in PCA space (e.g., 0.9 = retain 90% explained variance). If an integer is provided, it represents the number of principal components to use. |
 | `eps` | float | `1e-8` | Small jitter value added to variances to prevent divide-by-zero errors during standardization. |
 
+
+### Batch Effect Correction Visualization 
+
+The `plot_transformation` method allows to visualize the **ComBat** transformation effect using dimensionality reduction, showing the before/after comparison of data transformed by `ComBat` using PCA, t-SNE, or UMAP to reduce dimensions for visualization.
+
+For further details see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/demo/combatlearn_demo.ipynb).
+
 ## Contributing
 
 Pull requests, bug reports, and feature ideas are welcome: feel free to open a PR!
@@ -144,7 +154,7 @@ Pull requests, bug reports, and feature ideas are welcome: feel free to open a P
 
 [**Ettore Rocchi**](https://github.com/ettorerocchi) @ University of Bologna
 
-[Google Scholar](https://scholar.google.com/citations?user=MKHoGnQAAAAJ) $\cdot$ [Scopus](https://www.scopus.com/authid/detail.uri?authorId=57220152522)
+[Google Scholar](https://scholar.google.com/citations?user=MKHoGnQAAAAJ) | [Scopus](https://www.scopus.com/authid/detail.uri?authorId=57220152522)
 
 ## Acknowledgements
 

{combatlearn-0.1.1 → combatlearn-0.2.0}/README.md

@@ -1,9 +1,9 @@
 # **combatlearn**
 
-[![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python)](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python)
+[![Python versions](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python)](https://www.python.org/)
 [![Test](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml/badge.svg)](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml)
 [![PyPI Downloads](https://static.pepy.tech/badge/combatlearn)](https://pepy.tech/projects/combatlearn)
-[![PyPI version](https://badge.fury.io/py/combatlearn.svg)](https://pypi.org/project/combatlearn/)
+[![PyPI Version](https://img.shields.io/pypi/v/combatlearn?cacheSeconds=300)](https://pypi.org/project/combatlearn/)
 [![License](https://img.shields.io/github/license/EttoreRocchi/combatlearn)](https://github.com/EttoreRocchi/combatlearn/blob/main/LICENSE)
 
 <div align="center">
@@ -14,7 +14,7 @@
 
 **Three methods**:
 - `method="johnson"` - classic ComBat (Johnson _et al._, 2007)
-- `method="fortin"` - covariate-aware ComBat (Fortin _et al._, 2018)
+- `method="fortin"` - neuroComBat (Fortin _et al._, 2018)
 - `method="chen"` - CovBat (Chen _et al._, 2022)
 
 ## Installation
@@ -69,7 +69,7 @@ print("Best parameters:", grid.best_params_)
 print(f"Best CV AUROC: {grid.best_score_:.3f}")
 ```
 
-For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/demo/combatlearn_demo.ipynb)
+For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/demo/combatlearn_demo.ipynb)
 
 ## `ComBat` parameters
 
@@ -94,6 +94,13 @@ The following section provides a detailed explanation of all parameters availabl
 | `covbat_cov_thresh` | float, int | `0.9` | For `"chen"` method only: Cumulative variance threshold $]0,1[$ to retain PCs in PCA space (e.g., 0.9 = retain 90% explained variance). If an integer is provided, it represents the number of principal components to use. |
 | `eps` | float | `1e-8` | Small jitter value added to variances to prevent divide-by-zero errors during standardization. |
 
+
+### Batch Effect Correction Visualization 
+
+The `plot_transformation` method allows to visualize the **ComBat** transformation effect using dimensionality reduction, showing the before/after comparison of data transformed by `ComBat` using PCA, t-SNE, or UMAP to reduce dimensions for visualization.
+
+For further details see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/demo/combatlearn_demo.ipynb).
+
 ## Contributing
 
 Pull requests, bug reports, and feature ideas are welcome: feel free to open a PR!
@@ -102,7 +109,7 @@ Pull requests, bug reports, and feature ideas are welcome: feel free to open a P
 
 [**Ettore Rocchi**](https://github.com/ettorerocchi) @ University of Bologna
 
-[Google Scholar](https://scholar.google.com/citations?user=MKHoGnQAAAAJ) $\cdot$ [Scopus](https://www.scopus.com/authid/detail.uri?authorId=57220152522)
+[Google Scholar](https://scholar.google.com/citations?user=MKHoGnQAAAAJ) | [Scopus](https://www.scopus.com/authid/detail.uri?authorId=57220152522)
 
 ## Acknowledgements
 

{combatlearn-0.1.1/src → combatlearn-0.2.0}/combatlearn/__init__.py

@@ -1,4 +1,4 @@
 from .combat import ComBatModel, ComBat
 
 __all__ = ["ComBatModel", "ComBat"]
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{combatlearn-0.1.1/src → combatlearn-0.2.0}/combatlearn/combat.py

@@ -16,10 +16,25 @@ import pandas as pd
 from sklearn.base import BaseEstimator, TransformerMixin
 from sklearn.utils.validation import check_is_fitted
 from sklearn.decomposition import PCA
+from sklearn.manifold import TSNE
+import matplotlib.pyplot as plt
 from typing import Literal, Optional, Union, Dict, Tuple, Any, cast
 import numpy.typing as npt
 import warnings
 
+try:
+    import umap
+    UMAP_AVAILABLE = True
+except ImportError:
+    UMAP_AVAILABLE = False
+
+try:
+    import plotly.graph_objects as go
+    from plotly.subplots import make_subplots
+    PLOTLY_AVAILABLE = True
+except ImportError:
+    PLOTLY_AVAILABLE = False
+
 __author__ = "Ettore Rocchi"
 
 ArrayLike = Union[pd.DataFrame, pd.Series, npt.NDArray[Any]]
@@ -139,7 +154,7 @@ class ComBatModel:
 
         if self.reference_batch is not None and self.reference_batch not in batch.cat.categories:
             raise ValueError(
-                f"reference_batch={self.reference_batch!r} not present in the data batches "
+                f"reference_batch={self.reference_batch!r} not present in the data batches."
                 f"{list(batch.cat.categories)}"
             )
 
@@ -218,69 +233,94 @@ class ComBatModel:
         disc: Optional[pd.DataFrame],
         cont: Optional[pd.DataFrame],
     ) -> None:
-        """Fortin et al. (2018) ComBat."""
-        batch_levels = batch.cat.categories
-        n_batch = len(batch_levels)
+        """Fortin et al. (2018) neuroComBat."""
+        self._batch_levels = batch.cat.categories
+        n_batch = len(self._batch_levels)
         n_samples = len(X)
 
-        batch_dummies = pd.get_dummies(batch, drop_first=False)
+        batch_dummies = pd.get_dummies(batch, drop_first=False).astype(float)
+        if self.reference_batch is not None:
+            if self.reference_batch not in self._batch_levels:
+                raise ValueError(
+                    f"reference_batch={self.reference_batch!r} not present in batches."
+                    f"{list(self._batch_levels)}"
+                )
+            batch_dummies.loc[:, self.reference_batch] = 1.0
+
         parts: list[pd.DataFrame] = [batch_dummies]
         if disc is not None:
-            parts.append(pd.get_dummies(disc.astype("category"), drop_first=True))
+            parts.append(
+                pd.get_dummies(
+                    disc.astype("category"), drop_first=True
+                ).astype(float)
+            )
+
         if cont is not None:
-            parts.append(cont)
-        design = pd.concat(parts, axis=1).astype(float).values
+            parts.append(cont.astype(float))
+
+        design = pd.concat(parts, axis=1).values
         p_design = design.shape[1]
 
         X_np = X.values
         beta_hat = la.lstsq(design, X_np, rcond=None)[0]
 
-        gamma_hat = beta_hat[:n_batch]
+        beta_hat_batch = beta_hat[:n_batch]
         self._beta_hat_nonbatch = beta_hat[n_batch:]
 
-        n_per_batch_arr = batch.value_counts().sort_index().values
-        self._n_per_batch = dict(zip(batch_levels, n_per_batch_arr))
+        n_per_batch = batch.value_counts().sort_index().astype(int).values
+        self._n_per_batch = dict(zip(self._batch_levels, n_per_batch))
+
+        if self.reference_batch is not None:
+            ref_idx = list(self._batch_levels).index(self.reference_batch)
+            grand_mean = beta_hat_batch[ref_idx]
+        else:
+            grand_mean = (n_per_batch / n_samples) @ beta_hat_batch
+            ref_idx = None
 
-        grand_mean = (n_per_batch_arr / n_samples) @ gamma_hat
         self._grand_mean = pd.Series(grand_mean, index=X.columns)
 
-        resid = X_np - design @ beta_hat
-        var_pooled = (resid ** 2).sum(axis=0) / (n_samples - p_design) + self.eps
+        if self.reference_batch is not None:
+            ref_mask = (batch == self.reference_batch).values
+            resid = X_np[ref_mask] - design[ref_mask] @ beta_hat
+            denom = int(ref_mask.sum())
+        else:
+            resid = X_np - design @ beta_hat
+            denom = n_samples
+        var_pooled = (resid ** 2).sum(axis=0) / denom + self.eps
         self._pooled_var = pd.Series(var_pooled, index=X.columns)
 
         stand_mean = grand_mean + design[:, n_batch:] @ self._beta_hat_nonbatch
         Xs = (X_np - stand_mean) / np.sqrt(var_pooled)
 
-        delta_hat = np.empty_like(gamma_hat)
-        for i, lvl in enumerate(batch_levels):
-            idx = batch == lvl
-            delta_hat[i] = Xs[idx].var(axis=0, ddof=1) + self.eps
+        gamma_hat = np.vstack(
+            [Xs[batch == lvl].mean(axis=0) for lvl in self._batch_levels]
+        )
+        delta_hat = np.vstack(
+            [Xs[batch == lvl].var(axis=0, ddof=1) + self.eps
+             for lvl in self._batch_levels]
+        )
 
         if self.mean_only:
             gamma_star = self._shrink_gamma(
-                gamma_hat, delta_hat, n_per_batch_arr, parametric=self.parametric
+                gamma_hat, delta_hat, n_per_batch,
+                parametric = self.parametric
             )
             delta_star = np.ones_like(delta_hat)
         else:
             gamma_star, delta_star = self._shrink_gamma_delta(
-                gamma_hat, delta_hat, n_per_batch_arr, parametric=self.parametric
+                gamma_hat, delta_hat, n_per_batch,
+                parametric = self.parametric
             )
 
-        if self.reference_batch is not None:
-            ref_idx = list(batch_levels).index(self.reference_batch)
-            gamma_ref = gamma_star[ref_idx]
-            delta_ref = delta_star[ref_idx]
-            gamma_star = gamma_star - gamma_ref
+        if ref_idx is not None:
+            gamma_star[ref_idx] = 0.0
             if not self.mean_only:
-                delta_star = delta_star / delta_ref
-            self._reference_batch_idx = ref_idx
-        else:
-            self._reference_batch_idx = None
+                delta_star[ref_idx] = 1.0
+        self._reference_batch_idx = ref_idx
 
-        self._batch_levels = batch_levels
         self._gamma_star = gamma_star
         self._delta_star = delta_star
-        self._n_batch = n_batch
+        self._n_batch  = n_batch
         self._p_design = p_design
     
     def _fit_chen(
@@ -434,7 +474,7 @@ class ComBatModel:
         *,
         parametric: bool,
     ) -> FloatArray:
-        """Convenience wrapper that returns only γ⋆ (for *mean‑only* mode)."""
+        """Convenience wrapper that returns only γ⋆ (for *mean-only* mode)."""
         gamma, _ = self._shrink_gamma_delta(gamma_hat, delta_hat, n_per_batch, parametric=parametric)
         return gamma
 
@@ -454,7 +494,7 @@ class ComBatModel:
         batch = self._as_series(batch, idx, "batch")
         unseen = set(batch.cat.categories) - set(self._batch_levels)
         if unseen:
-            raise ValueError(f"Unseen batch levels during transform: {unseen}")
+            raise ValueError(f"Unseen batch levels during transform: {unseen}.")
         disc = self._to_df(discrete_covariates, idx, "discrete_covariates")
         cont = self._to_df(continuous_covariates, idx, "continuous_covariates")
 
@@ -466,7 +506,7 @@ class ComBatModel:
         elif method == "chen":
             return self._transform_chen(X, batch, disc, cont)
         else:
-            raise ValueError(f"Unknown method: {method}")
+            raise ValueError(f"Unknown method: {method}.")
 
     def _transform_johnson(
         self,
@@ -485,7 +525,7 @@ class ComBatModel:
             if not idx.any():
                 continue
             if self.reference_batch is not None and lvl == self.reference_batch:
-                X_adj.loc[idx] = X.loc[idx].values  # untouched
+                X_adj.loc[idx] = X.loc[idx].values
                 continue
 
             g = self._gamma_star[i]
@@ -505,18 +545,28 @@ class ComBatModel:
         cont: Optional[pd.DataFrame],
     ) -> pd.DataFrame:
         """Fortin transform implementation."""
-        batch_dummies = pd.get_dummies(batch, drop_first=False)[self._batch_levels]
-        parts: list[pd.DataFrame] = [batch_dummies]
+        batch_dummies = pd.get_dummies(batch, drop_first=False).astype(float)[self._batch_levels]
+        if self.reference_batch is not None:
+            batch_dummies.loc[:, self.reference_batch] = 1.0
+
+        parts = [batch_dummies]
         if disc is not None:
-            parts.append(pd.get_dummies(disc.astype("category"), drop_first=True))
+            parts.append(
+                pd.get_dummies(
+                    disc.astype("category"), drop_first=True
+                ).astype(float)
+            )
         if cont is not None:
-            parts.append(cont)
+            parts.append(cont.astype(float))
 
-        design = pd.concat(parts, axis=1).astype(float).values
+        design = pd.concat(parts, axis=1).values
 
         X_np = X.values
-        stand_mean = self._grand_mean.values + design[:, self._n_batch:] @ self._beta_hat_nonbatch
-        Xs = (X_np - stand_mean) / np.sqrt(self._pooled_var.values)
+        stand_mu = (
+            self._grand_mean.values +
+            design[:, self._n_batch:] @ self._beta_hat_nonbatch
+        )
+        Xs = (X_np - stand_mu) / np.sqrt(self._pooled_var.values)
 
         for i, lvl in enumerate(self._batch_levels):
             idx = batch == lvl
@@ -533,8 +583,11 @@ class ComBatModel:
             else:
                 Xs[idx] = (Xs[idx] - g) / np.sqrt(d)
 
-        X_adj = Xs * np.sqrt(self._pooled_var.values) + stand_mean
-        return pd.DataFrame(X_adj, index=X.index, columns=X.columns)
+        X_adj = (
+            Xs * np.sqrt(self._pooled_var.values) +
+            stand_mu
+        )
+        return pd.DataFrame(X_adj, index=X.index, columns=X.columns, dtype=float)
     
     def _transform_chen(
         self,
@@ -568,7 +621,7 @@ class ComBatModel:
 
 
 class ComBat(BaseEstimator, TransformerMixin):
-    """Pipeline‑friendly wrapper around `ComBatModel`.
+    """Pipeline-friendly wrapper around `ComBatModel`.
 
     Stores batch (and optional covariates) passed at construction and
     appropriately uses them for separate `fit` and `transform`.
@@ -621,6 +674,7 @@ class ComBat(BaseEstimator, TransformerMixin):
             discrete_covariates=disc,
             continuous_covariates=cont,
         )
+        self._fitted_batch = batch_vec
         return self
 
     def transform(self, X: ArrayLike) -> pd.DataFrame:
@@ -651,3 +705,315 @@ class ComBat(BaseEstimator, TransformerMixin):
                 return pd.Series(obj, index=idx)
             else:
                 return pd.DataFrame(obj, index=idx)
+
+    def plot_transformation(
+            self,
+            X: ArrayLike, *, 
+            reduction_method: Literal['pca', 'tsne', 'umap'] = 'pca', 
+            n_components: Literal[2, 3] = 2,
+            plot_type: Literal['static', 'interactive'] = 'static',
+            figsize: Tuple[int, int] = (12, 5),
+            alpha: float = 0.7,
+            point_size: int = 50,
+            cmap: str = 'Set1',
+            title: Optional[str] = None,
+            show_legend: bool = True,
+            return_embeddings: bool = False,
+            **reduction_kwargs) -> Union[Any, Tuple[Any, Dict[str, FloatArray]]]:
+        """
+        Visualize the ComBat transformation effect using dimensionality reduction.
+
+        It shows a before/after comparison of data transformed by `ComBat` using
+        PCA, t-SNE, or UMAP to reduce dimensions for visualization.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Input data to transform and visualize.
+
+        reduction_method : {`'pca'`, `'tsne'`, `'umap'`}, default=`'pca'`
+            Dimensionality reduction method.
+
+        n_components : {2, 3}, default=2
+            Number of components for dimensionality reduction.
+
+        plot_type : {`'static'`, `'interactive'`}, default=`'static'`
+            Visualization type:
+            - `'static'`: matplotlib plots (can be saved as images)
+            - `'interactive'`: plotly plots (explorable, requires plotly)
+
+        return_embeddings : bool, default=False
+            If `True`, return embeddings along with the plot.
+            
+        **reduction_kwargs : dict
+            Additional parameters for reduction methods.
+            
+        Returns
+        -------
+        fig : matplotlib.figure.Figure or plotly.graph_objects.Figure
+            The figure object containing the plots.
+            
+        embeddings : dict, optional
+            If `return_embeddings=True`, dictionary with:
+            - `'original'`: embedding of original data
+            - `'transformed'`: embedding of ComBat-transformed data
+        """
+        check_is_fitted(self._model, ["_gamma_star"])
+
+        if n_components not in [2, 3]:
+            raise ValueError(f"n_components must be 2 or 3, got {n_components}")
+        if reduction_method not in ['pca', 'tsne', 'umap']:
+            raise ValueError(f"reduction_method must be 'pca', 'tsne', or 'umap', got '{reduction_method}'")
+        if plot_type not in ['static', 'interactive']:
+            raise ValueError(f"plot_type must be 'static' or 'interactive', got '{plot_type}'")
+
+        if reduction_method == 'umap' and not UMAP_AVAILABLE:
+            raise ImportError("UMAP is not installed. Install with: pip install umap-learn")
+        if plot_type == 'interactive' and not PLOTLY_AVAILABLE:
+            raise ImportError("Plotly is not installed. Install with: pip install plotly")
+
+        if not isinstance(X, pd.DataFrame):
+            X = pd.DataFrame(X)
+
+        idx = X.index
+        batch_vec = self._subset(self.batch, idx)
+        if batch_vec is None:
+            raise ValueError("Batch information is required for visualization")
+
+        X_transformed = self.transform(X)
+
+        X_np = X.values
+        X_trans_np = X_transformed.values
+
+        if reduction_method == 'pca':
+            reducer_orig = PCA(n_components=n_components, **reduction_kwargs)
+            reducer_trans = PCA(n_components=n_components, **reduction_kwargs)
+        elif reduction_method == 'tsne':
+            tsne_params = {'perplexity': 30, 'max_iter': 1000, 'random_state': 42}
+            tsne_params.update(reduction_kwargs)
+            reducer_orig = TSNE(n_components=n_components, **tsne_params)
+            reducer_trans = TSNE(n_components=n_components, **tsne_params)
+        else:
+            umap_params = {'random_state': 42}
+            umap_params.update(reduction_kwargs)
+            reducer_orig = umap.UMAP(n_components=n_components, **reduction_kwargs)
+            reducer_trans = umap.UMAP(n_components=n_components, **reduction_kwargs)
+
+        X_embedded_orig = reducer_orig.fit_transform(X_np)
+        X_embedded_trans = reducer_trans.fit_transform(X_trans_np)
+
+        if plot_type == 'static':
+            fig = self._create_static_plot(
+                X_embedded_orig, X_embedded_trans, batch_vec, 
+                reduction_method, n_components, figsize, alpha, 
+                point_size, cmap, title, show_legend
+            )
+        else:
+            fig = self._create_interactive_plot(
+                X_embedded_orig, X_embedded_trans, batch_vec,
+                reduction_method, n_components, title, show_legend
+            )
+
+        if return_embeddings:
+            embeddings = {
+                'original': X_embedded_orig,
+                'transformed': X_embedded_trans
+            }
+            return fig, embeddings
+        else:
+            return fig
+
+    def _create_static_plot(
+            self,
+            X_orig: FloatArray,
+            X_trans: FloatArray, 
+            batch_labels: pd.Series,
+            method: str,
+            n_components: int,
+            figsize: Tuple[int, int],
+            alpha: float,
+            point_size: int, 
+            cmap: str,
+            title: Optional[str],
+            show_legend: bool) -> Any:
+        """Create static plots using matplotlib."""
+
+        fig = plt.figure(figsize=figsize)
+
+        unique_batches = batch_labels.drop_duplicates()
+        n_batches = len(unique_batches)
+
+        if n_batches <= 10:
+            colors = plt.cm.get_cmap(cmap)(np.linspace(0, 1, n_batches))
+        else:
+            colors = plt.cm.get_cmap('tab20')(np.linspace(0, 1, n_batches))
+
+        if n_components == 2:
+            ax1 = plt.subplot(1, 2, 1)
+            ax2 = plt.subplot(1, 2, 2)
+        else:
+            ax1 = fig.add_subplot(121, projection='3d')
+            ax2 = fig.add_subplot(122, projection='3d')
+
+        for i, batch in enumerate(unique_batches):
+            mask = batch_labels == batch
+            if n_components == 2:
+                ax1.scatter(
+                    X_orig[mask, 0], X_orig[mask, 1], 
+                    c=[colors[i]],
+                    s=point_size,
+                    alpha=alpha, 
+                    label=f'Batch {batch}',
+                    edgecolors='black',
+                    linewidth=0.5
+                )
+            else:
+                ax1.scatter(
+                    X_orig[mask, 0], X_orig[mask, 1], X_orig[mask, 2],
+                    c=[colors[i]],
+                    s=point_size,
+                    alpha=alpha, 
+                    label=f'Batch {batch}',
+                    edgecolors='black',
+                    linewidth=0.5
+                )
+
+        ax1.set_title(f'Before ComBat correction\n({method.upper()})')
+        ax1.set_xlabel(f'{method.upper()}1')
+        ax1.set_ylabel(f'{method.upper()}2')
+        if n_components == 3:
+            ax1.set_zlabel(f'{method.upper()}3')
+
+        for i, batch in enumerate(unique_batches):
+            mask = batch_labels == batch
+            if n_components == 2:
+                ax2.scatter(
+                    X_trans[mask, 0], X_trans[mask, 1], 
+                    c=[colors[i]],
+                    s=point_size,
+                    alpha=alpha, 
+                    label=f'Batch {batch}',
+                    edgecolors='black',
+                    linewidth=0.5
+                )
+            else:
+                ax2.scatter(
+                    X_trans[mask, 0], X_trans[mask, 1], X_trans[mask, 2],
+                    c=[colors[i]],
+                    s=point_size,
+                    alpha=alpha, 
+                    label=f'Batch {batch}',
+                    edgecolors='black',
+                    linewidth=0.5
+                )
+
+        ax2.set_title(f'After ComBat correction\n({method.upper()})')
+        ax2.set_xlabel(f'{method.upper()}1')
+        ax2.set_ylabel(f'{method.upper()}2')
+        if n_components == 3:
+            ax2.set_zlabel(f'{method.upper()}3')
+
+        if show_legend and n_batches <= 20:
+            ax2.legend(bbox_to_anchor=(1.05, 1), loc='upper left')
+
+        if title is None:
+            title = f'ComBat correction effect visualized with {method.upper()}'
+        fig.suptitle(title, fontsize=14, fontweight='bold')
+
+        plt.tight_layout()
+        return fig
+
+    def _create_interactive_plot(
+            self,
+            X_orig: FloatArray,
+            X_trans: FloatArray,
+            batch_labels: pd.Series,
+            method: str,
+            n_components: int,
+            title: Optional[str],
+            show_legend: bool) -> Any:
+        """Create interactive plots using plotly."""
+        if n_components == 2:
+            fig = make_subplots(
+                rows=1, cols=2,
+                subplot_titles=(
+                    f'Before ComBat correction ({method.upper()})',
+                    f'After ComBat correction ({method.upper()})'
+                )
+            )
+        else:
+            fig = make_subplots(
+                rows=1, cols=2,
+                specs=[[{'type': 'scatter3d'}, {'type': 'scatter3d'}]],
+                subplot_titles=(
+                    f'Before ComBat correction ({method.upper()})',
+                    f'After ComBat correction ({method.upper()})'
+                )
+            )
+
+        unique_batches = batch_labels.drop_duplicates()
+
+        for batch in unique_batches:
+            mask = batch_labels == batch
+
+            if n_components == 2:
+                fig.add_trace(
+                    go.Scatter(x=X_orig[mask, 0], y=X_orig[mask, 1],
+                              mode='markers',
+                              name=f'Batch {batch}',
+                              marker=dict(size=8, line=dict(width=1, color='black')),
+                              showlegend=False),
+                    row=1, col=1
+                )
+
+                fig.add_trace(
+                    go.Scatter(x=X_trans[mask, 0], y=X_trans[mask, 1],
+                              mode='markers',
+                              name=f'Batch {batch}',
+                              marker=dict(size=8, line=dict(width=1, color='black')),
+                              showlegend=show_legend),
+                    row=1, col=2
+                )
+            else:
+                fig.add_trace(
+                    go.Scatter3d(x=X_orig[mask, 0], y=X_orig[mask, 1], z=X_orig[mask, 2],
+                                mode='markers',
+                                name=f'Batch {batch}',
+                                marker=dict(size=5, line=dict(width=0.5, color='black')),
+                                showlegend=False),
+                    row=1, col=1
+                )
+
+                fig.add_trace(
+                    go.Scatter3d(x=X_trans[mask, 0], y=X_trans[mask, 1], z=X_trans[mask, 2],
+                                mode='markers',
+                                name=f'Batch {batch}',
+                                marker=dict(size=5, line=dict(width=0.5, color='black')),
+                                showlegend=show_legend),
+                    row=1, col=2
+                )
+
+        if title is None:
+            title = f'ComBat correction effect visualized with {method.upper()}'
+
+        fig.update_layout(
+            title=title,
+            title_font_size=16,
+            height=600,
+            showlegend=show_legend,
+            hovermode='closest'
+        )
+
+        axis_labels = [f'{method.upper()}{i+1}' for i in range(n_components)]
+
+        if n_components == 2:
+            fig.update_xaxes(title_text=axis_labels[0])
+            fig.update_yaxes(title_text=axis_labels[1])
+        else:
+            fig.update_scenes(
+                xaxis_title=axis_labels[0],
+                yaxis_title=axis_labels[1],
+                zaxis_title=axis_labels[2]
+            )
+
+        return fig

{combatlearn-0.1.1 → combatlearn-0.2.0/combatlearn.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: combatlearn
-Version: 0.1.1
+Version: 0.2.0
 Summary: Batch-effect harmonization for machine learning frameworks.
 Author-email: Ettore Rocchi <ettoreroc@gmail.com>
 License: MIT License
@@ -37,15 +37,18 @@ License-File: LICENSE
 Requires-Dist: pandas>=1.3
 Requires-Dist: numpy>=1.21
 Requires-Dist: scikit-learn>=1.2
+Requires-Dist: plotly>=5.0
+Requires-Dist: nbformat>=4.2
+Requires-Dist: umap-learn>=0.5
 Requires-Dist: pytest>=7
 Dynamic: license-file
 
 # **combatlearn**
 
-[![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python)](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python)
+[![Python versions](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python)](https://www.python.org/)
 [![Test](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml/badge.svg)](https://github.com/EttoreRocchi/combatlearn/actions/workflows/test.yaml)
 [![PyPI Downloads](https://static.pepy.tech/badge/combatlearn)](https://pepy.tech/projects/combatlearn)
-[![PyPI version](https://badge.fury.io/py/combatlearn.svg)](https://pypi.org/project/combatlearn/)
+[![PyPI Version](https://img.shields.io/pypi/v/combatlearn?cacheSeconds=300)](https://pypi.org/project/combatlearn/)
 [![License](https://img.shields.io/github/license/EttoreRocchi/combatlearn)](https://github.com/EttoreRocchi/combatlearn/blob/main/LICENSE)
 
 <div align="center">
@@ -56,7 +59,7 @@ Dynamic: license-file
 
 **Three methods**:
 - `method="johnson"` - classic ComBat (Johnson _et al._, 2007)
-- `method="fortin"` - covariate-aware ComBat (Fortin _et al._, 2018)
+- `method="fortin"` - neuroComBat (Fortin _et al._, 2018)
 - `method="chen"` - CovBat (Chen _et al._, 2022)
 
 ## Installation
@@ -111,7 +114,7 @@ print("Best parameters:", grid.best_params_)
 print(f"Best CV AUROC: {grid.best_score_:.3f}")
 ```
 
-For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/demo/combatlearn_demo.ipynb)
+For a full example of how to use **combatlearn** see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/demo/combatlearn_demo.ipynb)
 
 ## `ComBat` parameters
 
@@ -136,6 +139,13 @@ The following section provides a detailed explanation of all parameters availabl
 | `covbat_cov_thresh` | float, int | `0.9` | For `"chen"` method only: Cumulative variance threshold $]0,1[$ to retain PCs in PCA space (e.g., 0.9 = retain 90% explained variance). If an integer is provided, it represents the number of principal components to use. |
 | `eps` | float | `1e-8` | Small jitter value added to variances to prevent divide-by-zero errors during standardization. |
 
+
+### Batch Effect Correction Visualization 
+
+The `plot_transformation` method allows to visualize the **ComBat** transformation effect using dimensionality reduction, showing the before/after comparison of data transformed by `ComBat` using PCA, t-SNE, or UMAP to reduce dimensions for visualization.
+
+For further details see the [notebook demo](https://github.com/EttoreRocchi/combatlearn/blob/main/docs/demo/combatlearn_demo.ipynb).
+
 ## Contributing
 
 Pull requests, bug reports, and feature ideas are welcome: feel free to open a PR!
@@ -144,7 +154,7 @@ Pull requests, bug reports, and feature ideas are welcome: feel free to open a P
 
 [**Ettore Rocchi**](https://github.com/ettorerocchi) @ University of Bologna
 
-[Google Scholar](https://scholar.google.com/citations?user=MKHoGnQAAAAJ) $\cdot$ [Scopus](https://www.scopus.com/authid/detail.uri?authorId=57220152522)
+[Google Scholar](https://scholar.google.com/citations?user=MKHoGnQAAAAJ) | [Scopus](https://www.scopus.com/authid/detail.uri?authorId=57220152522)
 
 ## Acknowledgements
 

combatlearn-0.2.0/combatlearn.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+combatlearn/__init__.py
+combatlearn/combat.py
+combatlearn.egg-info/PKG-INFO
+combatlearn.egg-info/SOURCES.txt
+combatlearn.egg-info/dependency_links.txt
+combatlearn.egg-info/requires.txt
+combatlearn.egg-info/top_level.txt
+tests/test_combat.py

{combatlearn-0.1.1/src → combatlearn-0.2.0}/combatlearn.egg-info/requires.txt

@@ -1,4 +1,7 @@
 pandas>=1.3
 numpy>=1.21
 scikit-learn>=1.2
+plotly>=5.0
+nbformat>=4.2
+umap-learn>=0.5
 pytest>=7

{combatlearn-0.1.1 → combatlearn-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "combatlearn"
-version = "0.1.1"
+version = "0.2.0"
 description = "Batch-effect harmonization for machine learning frameworks."
 authors = [{name="Ettore Rocchi", email="ettoreroc@gmail.com"}]
 requires-python = ">=3.10"
@@ -12,6 +12,9 @@ dependencies = [
     "pandas>=1.3",
     "numpy>=1.21",
     "scikit-learn>=1.2",
+    "plotly>=5.0",
+    "nbformat>=4.2",
+    "umap-learn>=0.5",
     "pytest>=7"
 ]
 license = {file="LICENSE"}
@@ -31,5 +34,5 @@ classifiers = [
 ]
 
 [tool.setuptools.packages.find]
-where = ["src"]
+where = ["."]
 include = ["combatlearn*"]

combatlearn-0.1.1/src/combatlearn.egg-info/SOURCES.txt

@@ -1,11 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-src/combatlearn/__init__.py
-src/combatlearn/combat.py
-src/combatlearn.egg-info/PKG-INFO
-src/combatlearn.egg-info/SOURCES.txt
-src/combatlearn.egg-info/dependency_links.txt
-src/combatlearn.egg-info/requires.txt
-src/combatlearn.egg-info/top_level.txt
-tests/test_combat.py