combatlearn 0.2.1__tar.gz → 1.0.0__tar.gz

{combatlearn-0.2.1 → combatlearn-1.0.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: combatlearn
-Version: 0.2.1
+Version: 1.0.0
 Summary: Batch-effect harmonization for machine learning frameworks.
 Author-email: Ettore Rocchi <ettoreroc@gmail.com>
-License-Expression: MIT
+License: MIT
 Keywords: machine-learning,harmonization,combat,preprocessing
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
@@ -19,13 +19,23 @@ Requires-Dist: matplotlib>=3.4
 Requires-Dist: plotly>=5.0
 Requires-Dist: nbformat>=4.2
 Requires-Dist: umap-learn>=0.5
-Requires-Dist: pytest>=7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
 Dynamic: license-file
 
 # **combatlearn**
 
 [![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)
+[![Documentation](https://readthedocs.org/projects/combatlearn/badge/?version=latest)](https://combatlearn.readthedocs.io)
 [![PyPI Downloads](https://static.pepy.tech/badge/combatlearn)](https://pepy.tech/projects/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)
@@ -95,6 +105,17 @@ 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/docs/demo/combatlearn_demo.ipynb)
 
+## Documentation
+
+**Full documentation is available at [combatlearn.readthedocs.io](https://combatlearn.readthedocs.io)**
+
+The documentation includes:
+- [Installation Guide](https://combatlearn.readthedocs.io/en/latest/installation/)
+- [Quick Start Tutorial](https://combatlearn.readthedocs.io/en/latest/quickstart/)
+- [User Guide](https://combatlearn.readthedocs.io/en/latest/user-guide/overview/)
+- [API Reference](https://combatlearn.readthedocs.io/en/latest/api/)
+- [Examples](https://combatlearn.readthedocs.io/en/latest/examples/basic-usage/)
+
 ## `ComBat` parameters
 
 The following section provides a detailed explanation of all parameters available in the scikit-learn-compatible `ComBat` class.

{combatlearn-0.2.1 → combatlearn-1.0.0}/README.md

@@ -2,6 +2,7 @@
 
 [![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)
+[![Documentation](https://readthedocs.org/projects/combatlearn/badge/?version=latest)](https://combatlearn.readthedocs.io)
 [![PyPI Downloads](https://static.pepy.tech/badge/combatlearn)](https://pepy.tech/projects/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)
@@ -71,6 +72,17 @@ 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/docs/demo/combatlearn_demo.ipynb)
 
+## Documentation
+
+**Full documentation is available at [combatlearn.readthedocs.io](https://combatlearn.readthedocs.io)**
+
+The documentation includes:
+- [Installation Guide](https://combatlearn.readthedocs.io/en/latest/installation/)
+- [Quick Start Tutorial](https://combatlearn.readthedocs.io/en/latest/quickstart/)
+- [User Guide](https://combatlearn.readthedocs.io/en/latest/user-guide/overview/)
+- [API Reference](https://combatlearn.readthedocs.io/en/latest/api/)
+- [Examples](https://combatlearn.readthedocs.io/en/latest/examples/basic-usage/)
+
 ## `ComBat` parameters
 
 The following section provides a detailed explanation of all parameters available in the scikit-learn-compatible `ComBat` class.

combatlearn-1.0.0/combatlearn/__init__.py

@@ -0,0 +1,5 @@
+from .combat import ComBat
+
+__all__ = ["ComBat"]
+__version__ = "1.0.0"
+__author__ = "Ettore Rocchi"

{combatlearn-0.2.1 → combatlearn-1.0.0}/combatlearn/combat.py

@@ -14,28 +14,17 @@ import numpy as np
 import numpy.linalg as la
 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
 import matplotlib.pyplot as plt
-from typing import Literal, Optional, Union, Dict, Tuple, Any, cast
+import matplotlib.colors as mcolors
+from typing import Literal, Optional, Union, Dict, Tuple, Any
 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"
+import umap
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
 
 ArrayLike = Union[pd.DataFrame, pd.Series, npt.NDArray[Any]]
 FloatArray = npt.NDArray[np.float64]
@@ -57,8 +46,9 @@ class ComBatModel:
         ignoring the variance (`delta_star`).
     reference_batch : str, optional
         If specified, the batch level to use as reference.
-    covbat_cov_thresh : float, default=0.9
-        CovBat: cumulative explained variance threshold for PCA.
+    covbat_cov_thresh : float or int, default=0.9
+        CovBat: cumulative variance threshold (0, 1] to retain PCs, or
+        integer >= 1 specifying the number of components directly.
     eps : float, default=1e-8
         Numerical jitter to avoid division-by-zero.
     """
@@ -66,19 +56,19 @@ class ComBatModel:
     def __init__(
         self,
         *,
-        method: Literal["johnson", "fortin", "chen"] = "johnson", 
+        method: Literal["johnson", "fortin", "chen"] = "johnson",
         parametric: bool = True,
         mean_only: bool = False,
         reference_batch: Optional[str] = None,
         eps: float = 1e-8,
-        covbat_cov_thresh: float = 0.9,
+        covbat_cov_thresh: Union[float, int] = 0.9,
     ) -> None:
         self.method: str = method
         self.parametric: bool = parametric
         self.mean_only: bool = bool(mean_only)
         self.reference_batch: Optional[str] = reference_batch
         self.eps: float = float(eps)
-        self.covbat_cov_thresh: float = float(covbat_cov_thresh)
+        self.covbat_cov_thresh: Union[float, int] = covbat_cov_thresh
 
         self._batch_levels: pd.Index
         self._grand_mean: pd.Series
@@ -95,9 +85,16 @@ class ComBatModel:
         self._batch_levels_pc: pd.Index
         self._pc_gamma_star: FloatArray
         self._pc_delta_star: FloatArray
-        
-        if not (0.0 < self.covbat_cov_thresh <= 1.0):
-            raise ValueError("covbat_cov_thresh must be in (0, 1].")
+
+        # Validate covbat_cov_thresh
+        if isinstance(self.covbat_cov_thresh, float):
+            if not (0.0 < self.covbat_cov_thresh <= 1.0):
+                raise ValueError("covbat_cov_thresh must be in (0, 1] when float.")
+        elif isinstance(self.covbat_cov_thresh, int):
+            if self.covbat_cov_thresh < 1:
+                raise ValueError("covbat_cov_thresh must be >= 1 when int.")
+        else:
+            raise TypeError("covbat_cov_thresh must be float or int.")
 
     @staticmethod
     def _as_series(
@@ -335,8 +332,14 @@ class ComBatModel:
         X_meanvar_adj = self._transform_fortin(X, batch, disc, cont)
         X_centered = X_meanvar_adj - X_meanvar_adj.mean(axis=0)
         pca = PCA(svd_solver="full", whiten=False).fit(X_centered)
-        cumulative = np.cumsum(pca.explained_variance_ratio_)
-        n_pc = int(np.searchsorted(cumulative, self.covbat_cov_thresh) + 1)
+
+        # Determine number of components based on threshold type
+        if isinstance(self.covbat_cov_thresh, int):
+            n_pc = min(self.covbat_cov_thresh, len(pca.explained_variance_ratio_))
+        else:
+            cumulative = np.cumsum(pca.explained_variance_ratio_)
+            n_pc = int(np.searchsorted(cumulative, self.covbat_cov_thresh) + 1)
+
         self._covbat_pca = pca
         self._covbat_n_pc = n_pc
 
@@ -487,7 +490,8 @@ class ComBatModel:
         continuous_covariates: Optional[ArrayLike] = None,
     ) -> pd.DataFrame:
         """Transform the data using fitted ComBat parameters."""
-        check_is_fitted(self, ["_gamma_star"])
+        if not hasattr(self, "_gamma_star"):
+            raise ValueError("This ComBatModel instance is not fitted yet. Call 'fit' before 'transform'.")
         if not isinstance(X, pd.DataFrame):
             X = pd.DataFrame(X)
         idx = X.index
@@ -599,7 +603,7 @@ class ComBatModel:
         """Chen transform implementation."""
         X_meanvar_adj = self._transform_fortin(X, batch, disc, cont)
         X_centered = X_meanvar_adj - self._covbat_pca.mean_
-        scores = self._covbat_pca.transform(X_centered.values)
+        scores = self._covbat_pca.transform(X_centered)
         n_pc = self._covbat_n_pc
         scores_adj = scores.copy()
 
@@ -638,7 +642,7 @@ class ComBat(BaseEstimator, TransformerMixin):
         mean_only: bool = False,
         reference_batch: Optional[str] = None,
         eps: float = 1e-8,
-        covbat_cov_thresh: float = 0.9,
+        covbat_cov_thresh: Union[float, int] = 0.9,
     ) -> None:
         self.batch = batch
         self.discrete_covariates = discrete_covariates
@@ -758,7 +762,8 @@ class ComBat(BaseEstimator, TransformerMixin):
             - `'original'`: embedding of original data
             - `'transformed'`: embedding of ComBat-transformed data
         """
-        check_is_fitted(self._model, ["_gamma_star"])
+        if not hasattr(self._model, "_gamma_star"):
+            raise ValueError("This ComBat instance is not fitted yet. Call 'fit' before 'plot_transformation'.")
 
         if n_components not in [2, 3]:
             raise ValueError(f"n_components must be 2 or 3, got {n_components}")
@@ -767,11 +772,6 @@ class ComBat(BaseEstimator, TransformerMixin):
         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)
 
@@ -796,8 +796,8 @@ class ComBat(BaseEstimator, TransformerMixin):
         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)
+            reducer_orig = umap.UMAP(n_components=n_components, **umap_params)
+            reducer_trans = umap.UMAP(n_components=n_components, **umap_params)
 
         X_embedded_orig = reducer_orig.fit_transform(X_np)
         X_embedded_trans = reducer_trans.fit_transform(X_trans_np)
@@ -811,7 +811,7 @@ class ComBat(BaseEstimator, TransformerMixin):
         else:
             fig = self._create_interactive_plot(
                 X_embedded_orig, X_embedded_trans, batch_vec,
-                reduction_method, n_components, title, show_legend
+                reduction_method, n_components, cmap, title, show_legend
             )
 
         if return_embeddings:
@@ -844,9 +844,9 @@ class ComBat(BaseEstimator, TransformerMixin):
         n_batches = len(unique_batches)
 
         if n_batches <= 10:
-            colors = plt.cm.get_cmap(cmap)(np.linspace(0, 1, n_batches))
+            colors = matplotlib.colormaps.get_cmap(cmap)(np.linspace(0, 1, n_batches))
         else:
-            colors = plt.cm.get_cmap('tab20')(np.linspace(0, 1, n_batches))
+            colors = matplotlib.colormaps.get_cmap('tab20')(np.linspace(0, 1, n_batches))
 
         if n_components == 2:
             ax1 = plt.subplot(1, 2, 1)
@@ -930,6 +930,7 @@ class ComBat(BaseEstimator, TransformerMixin):
             batch_labels: pd.Series,
             method: str,
             n_components: int,
+            cmap: str,
             title: Optional[str],
             show_legend: bool) -> Any:
         """Create interactive plots using plotly."""
@@ -953,43 +954,69 @@ class ComBat(BaseEstimator, TransformerMixin):
 
         unique_batches = batch_labels.drop_duplicates()
 
+        n_batches = len(unique_batches)
+        cmap_func = matplotlib.colormaps.get_cmap(cmap)
+        color_list = [mcolors.to_hex(cmap_func(i / max(n_batches - 1, 1))) for i in range(n_batches)]
+
+        batch_to_color = dict(zip(unique_batches, color_list))
+
         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),
+                    go.Scatter(
+                        x=X_orig[mask, 0], y=X_orig[mask, 1],
+                        mode='markers',
+                        name=f'Batch {batch}',
+                        marker=dict(
+                            size=8,
+                            color=batch_to_color[batch],
+                            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),
+                    go.Scatter(
+                        x=X_trans[mask, 0], y=X_trans[mask, 1],
+                        mode='markers',
+                        name=f'Batch {batch}',
+                        marker=dict(
+                            size=8,
+                            color=batch_to_color[batch],
+                            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),
+                    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,
+                            color=batch_to_color[batch],
+                            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),
+                    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,
+                            color=batch_to_color[batch],
+                            line=dict(width=0.5, color='black')
+                        ),
+                        showlegend=show_legend),
                     row=1, col=2
                 )
 

{combatlearn-0.2.1 → combatlearn-1.0.0}/combatlearn.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: combatlearn
-Version: 0.2.1
+Version: 1.0.0
 Summary: Batch-effect harmonization for machine learning frameworks.
 Author-email: Ettore Rocchi <ettoreroc@gmail.com>
-License-Expression: MIT
+License: MIT
 Keywords: machine-learning,harmonization,combat,preprocessing
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
@@ -19,13 +19,23 @@ Requires-Dist: matplotlib>=3.4
 Requires-Dist: plotly>=5.0
 Requires-Dist: nbformat>=4.2
 Requires-Dist: umap-learn>=0.5
-Requires-Dist: pytest>=7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
 Dynamic: license-file
 
 # **combatlearn**
 
 [![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)
+[![Documentation](https://readthedocs.org/projects/combatlearn/badge/?version=latest)](https://combatlearn.readthedocs.io)
 [![PyPI Downloads](https://static.pepy.tech/badge/combatlearn)](https://pepy.tech/projects/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)
@@ -95,6 +105,17 @@ 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/docs/demo/combatlearn_demo.ipynb)
 
+## Documentation
+
+**Full documentation is available at [combatlearn.readthedocs.io](https://combatlearn.readthedocs.io)**
+
+The documentation includes:
+- [Installation Guide](https://combatlearn.readthedocs.io/en/latest/installation/)
+- [Quick Start Tutorial](https://combatlearn.readthedocs.io/en/latest/quickstart/)
+- [User Guide](https://combatlearn.readthedocs.io/en/latest/user-guide/overview/)
+- [API Reference](https://combatlearn.readthedocs.io/en/latest/api/)
+- [Examples](https://combatlearn.readthedocs.io/en/latest/examples/basic-usage/)
+
 ## `ComBat` parameters
 
 The following section provides a detailed explanation of all parameters available in the scikit-learn-compatible `ComBat` class.

{combatlearn-0.2.1 → combatlearn-1.0.0}/combatlearn.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE
 README.md
 pyproject.toml
+requirements.txt
 combatlearn/__init__.py
 combatlearn/combat.py
 combatlearn.egg-info/PKG-INFO

combatlearn-1.0.0/combatlearn.egg-info/requires.txt

@@ -0,0 +1,19 @@
+pandas>=1.3
+numpy>=1.21
+scikit-learn>=1.2
+matplotlib>=3.4
+plotly>=5.0
+nbformat>=4.2
+umap-learn>=0.5
+
+[dev]
+pytest>=7
+pytest-cov>=4.0
+ruff>=0.1
+mypy>=1.0
+
+[docs]
+mkdocs>=1.5.0
+mkdocs-material>=9.0.0
+mkdocstrings[python]>=0.24.0
+pymdown-extensions>=10.0

{combatlearn-0.2.1 → combatlearn-1.0.0}/pyproject.toml

@@ -4,21 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "combatlearn"
-version = "0.2.1"
+dynamic = ["version", "dependencies"]
 description = "Batch-effect harmonization for machine learning frameworks."
 authors = [{name="Ettore Rocchi", email="ettoreroc@gmail.com"}]
 requires-python = ">=3.10"
-dependencies = [
-    "pandas>=1.3",
-    "numpy>=1.21",
-    "scikit-learn>=1.2",
-    "matplotlib>=3.4",
-    "plotly>=5.0",
-    "nbformat>=4.2",
-    "umap-learn>=0.5",
-    "pytest>=7"
-]
-license = "MIT"
+license = {text = "MIT"}
 readme = {file="README.md", content-type="text/markdown"}
 keywords = [
     "machine-learning",
@@ -33,6 +23,24 @@ classifiers = [
     "Programming Language :: Python :: 3",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+docs = [
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.0.0",
+    "mkdocstrings[python]>=0.24.0",
+    "pymdown-extensions>=10.0",
+]
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["combatlearn*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "combatlearn.__version__"}
+dependencies = {file = ["requirements.txt"]}

combatlearn-0.2.1/combatlearn.egg-info/requires.txt → combatlearn-1.0.0/requirements.txt

@@ -4,5 +4,4 @@ scikit-learn>=1.2
 matplotlib>=3.4
 plotly>=5.0
 nbformat>=4.2
-umap-learn>=0.5
-pytest>=7
+umap-learn>=0.5

combatlearn-1.0.0/tests/test_combat.py

@@ -0,0 +1,379 @@
+import numpy as np
+import pandas as pd
+import pytest
+from sklearn.pipeline import Pipeline
+from sklearn.base import clone
+from sklearn.preprocessing import StandardScaler
+from combatlearn import ComBat
+from combatlearn.combat import ComBatModel
+from utils import simulate_data, simulate_covariate_data
+
+
+def test_transform_without_fit_raises():
+    """
+    Test that `transform` raises a `ValueError` if not fitted.
+    """
+    X, batch = simulate_data()
+    model = ComBatModel()
+    with pytest.raises(ValueError, match="not fitted"):
+        model.transform(X, batch=batch)
+
+
+def test_unseen_batch_raises_value_error():
+    """
+    Test that unseen batch raises a `ValueError`.
+    """
+    X, batch = simulate_data()
+    model = ComBatModel().fit(X, batch=batch)
+    new_batch = pd.Series(["Z"] * len(batch), index=batch.index)
+    with pytest.raises(ValueError):
+        model.transform(X, batch=new_batch)
+
+
+def test_single_sample_batch_error():
+    """
+    Test that a single sample batch raises a `ValueError`.
+    """
+    X, batch = simulate_data()
+    batch.iloc[0] = "single"
+    with pytest.raises(ValueError):
+        ComBatModel().fit(X, batch=batch)
+
+
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_dtypes_preserved(method):
+    """All output columns must remain floating dtypes after correction."""
+    if method == "johnson":
+        X, batch = simulate_data()
+        extra = {}
+    else:                                  # fortin  or  chen
+        X, batch, disc, cont = simulate_covariate_data()
+        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
+
+    X_corr = ComBat(batch=batch, method=method, **extra).fit_transform(X)
+    assert all(np.issubdtype(dt, np.floating) for dt in X_corr.dtypes)
+
+def test_wrapper_clone_and_pipeline():
+    """
+    Test `ComBat` wrapper can be cloned and used in a `Pipeline`.
+    """
+    X, batch = simulate_data()
+    wrapper = ComBat(batch=batch, parametric=True)
+    pipe = Pipeline([
+        ("scaler", StandardScaler()),
+        ("combat", wrapper),
+    ])
+    X_corr = pipe.fit_transform(X)
+    pipe_clone: Pipeline = clone(pipe)
+    X_corr2 = pipe_clone.fit_transform(X)
+    np.testing.assert_allclose(X_corr, X_corr2, rtol=1e-5, atol=1e-5)
+
+
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_no_nan_or_inf_in_output(method):
+    """`ComBat` must not introduce NaN or Inf values, for any backend."""
+    if method == "johnson":
+        X, batch = simulate_data()
+        extra = {}
+    else:                                  # fortin  or  chen
+        X, batch, disc, cont = simulate_covariate_data()
+        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
+
+    X_corr = ComBat(batch=batch, method=method, **extra).fit_transform(X)
+    assert not np.isnan(X_corr.values).any()
+    assert not np.isinf(X_corr.values).any()
+
+
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_shape_preserved(method):
+    """The (n_samples, n_features) shape must be identical pre- and post-ComBat."""
+    if method == "johnson":
+        X, batch = simulate_data()
+        combat = ComBat(batch=batch, method=method).fit(X)
+    elif method in ["fortin", "chen"]:
+        X, batch, disc, cont = simulate_covariate_data()
+        combat = ComBat(
+            batch=batch,
+            discrete_covariates=disc,
+            continuous_covariates=cont,
+            method=method,
+        ).fit(X)
+
+    X_corr = combat.transform(X)
+    assert X_corr.shape == X.shape
+
+
+def test_johnson_print_warning():
+    """
+    Test that a warning is printed when using the Johnson method.
+    """
+    X, batch, disc, cont = simulate_covariate_data()
+    with pytest.warns(Warning, match="Covariates are ignored when using method='johnson'."):
+        _ = ComBat(
+            batch=batch,
+            discrete_covariates=disc,
+            continuous_covariates=cont,
+            method="johnson",
+        ).fit(X)
+
+
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_reference_batch_samples_unchanged(method):
+    """
+    Samples belonging to the reference batch must come out *numerically identical*
+    (within floating-point jitter) after correction.
+    """
+    if method == "johnson":
+        X, batch = simulate_data()
+        extra = {}
+    elif method in ["fortin", "chen"]:
+        X, batch, disc, cont = simulate_covariate_data()
+        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
+
+    ref_batch = batch.iloc[0]
+    combat = ComBat(batch=batch, method=method,
+                    reference_batch=ref_batch, **extra).fit(X)
+    X_corr = combat.transform(X)
+
+    mask = batch == ref_batch
+    np.testing.assert_allclose(X_corr.loc[mask].values,
+                               X.loc[mask].values,
+                               rtol=0, atol=1e-10)
+
+
+def test_reference_batch_missing_raises():
+    """
+    Asking for a reference batch that doesn't exist should fail.
+    """
+    X, batch = simulate_data()
+    with pytest.raises(ValueError, match="not present"):
+        ComBat(batch=batch, reference_batch="DOES_NOT_EXIST").fit(X)
+
+
+@pytest.mark.parametrize("parametric", [True, False])
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_parametric_vs_nonparametric(parametric, method):
+    """
+    Test both parametric and non-parametric modes work without errors.
+    """
+    if method == "johnson":
+        X, batch = simulate_data()
+        extra = {}
+    else:
+        X, batch, disc, cont = simulate_covariate_data()
+        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
+
+    combat = ComBat(batch=batch, method=method, parametric=parametric, **extra)
+    X_corr = combat.fit_transform(X)
+    assert X_corr.shape == X.shape
+    assert not np.isnan(X_corr.values).any()
+
+
+@pytest.mark.parametrize("mean_only", [True, False])
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_mean_only_mode(mean_only, method):
+    """
+    Test mean_only mode works for all methods.
+    """
+    if method == "johnson":
+        X, batch = simulate_data()
+        extra = {}
+    else:
+        X, batch, disc, cont = simulate_covariate_data()
+        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
+
+    combat = ComBat(batch=batch, method=method, mean_only=mean_only, **extra)
+    X_corr = combat.fit_transform(X)
+    assert X_corr.shape == X.shape
+    assert not np.isnan(X_corr.values).any()
+
+
+def test_covbat_cov_thresh_as_float():
+    """
+    Test CovBat with covbat_cov_thresh as float (cumulative variance threshold).
+    """
+    X, batch, disc, cont = simulate_covariate_data()
+    combat = ComBat(
+        batch=batch,
+        discrete_covariates=disc,
+        continuous_covariates=cont,
+        method="chen",
+        covbat_cov_thresh=0.95,
+    )
+    X_corr = combat.fit_transform(X)
+    assert X_corr.shape == X.shape
+    assert not np.isnan(X_corr.values).any()
+
+
+def test_covbat_cov_thresh_as_int():
+    """
+    Test CovBat with covbat_cov_thresh as int (number of components).
+    """
+    X, batch, disc, cont = simulate_covariate_data()
+    n_components = 10
+    combat = ComBat(
+        batch=batch,
+        discrete_covariates=disc,
+        continuous_covariates=cont,
+        method="chen",
+        covbat_cov_thresh=n_components,
+    )
+    X_corr = combat.fit_transform(X)
+    assert X_corr.shape == X.shape
+    assert not np.isnan(X_corr.values).any()
+    assert combat._model._covbat_n_pc == n_components
+
+
+def test_covbat_cov_thresh_invalid_float_raises():
+    """
+    Test that invalid float values for covbat_cov_thresh raise ValueError.
+    """
+    with pytest.raises(ValueError, match="must be in \\(0, 1\\]"):
+        ComBatModel(covbat_cov_thresh=1.5)
+
+    with pytest.raises(ValueError, match="must be in \\(0, 1\\]"):
+        ComBatModel(covbat_cov_thresh=0.0)
+
+
+def test_covbat_cov_thresh_invalid_int_raises():
+    """
+    Test that invalid int values for covbat_cov_thresh raise ValueError.
+    """
+    with pytest.raises(ValueError, match="must be >= 1"):
+        ComBatModel(covbat_cov_thresh=0)
+
+
+def test_covbat_cov_thresh_invalid_type_raises():
+    """
+    Test that invalid types for covbat_cov_thresh raise TypeError.
+    """
+    with pytest.raises(TypeError, match="must be float or int"):
+        ComBatModel(covbat_cov_thresh="invalid")
+
+
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_index_preserved(method):
+    """
+    Test that the index is preserved after transformation.
+    """
+    if method == "johnson":
+        X, batch = simulate_data()
+        extra = {}
+    else:
+        X, batch, disc, cont = simulate_covariate_data()
+        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
+
+    custom_index = pd.Index([f"sample_{i}" for i in range(len(X))])
+    X.index = custom_index
+    batch.index = custom_index
+    if method != "johnson":
+        disc.index = custom_index
+        cont.index = custom_index
+
+    combat = ComBat(batch=batch, method=method, **extra)
+    X_corr = combat.fit_transform(X)
+    assert X_corr.index.equals(custom_index)
+
+
+@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
+def test_column_names_preserved(method):
+    """
+    Test that column names are preserved after transformation.
+    """
+    if method == "johnson":
+        X, batch = simulate_data()
+        extra = {}
+    else:
+        X, batch, disc, cont = simulate_covariate_data()
+        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
+
+    custom_columns = [f"feature_{i}" for i in range(X.shape[1])]
+    X.columns = custom_columns
+
+    combat = ComBat(batch=batch, method=method, **extra)
+    X_corr = combat.fit_transform(X)
+    assert list(X_corr.columns) == custom_columns
+
+
+def test_plot_transformation_static_2d():
+    """
+    Test plot_transformation with static 2D PCA visualization.
+    """
+    X, batch = simulate_data(n_samples=100, n_features=20)
+    combat = ComBat(batch=batch, method="johnson").fit(X)
+
+    fig = combat.plot_transformation(
+        X,
+        reduction_method='pca',
+        n_components=2,
+        plot_type='static'
+    )
+    assert fig is not None
+
+
+def test_plot_transformation_static_3d():
+    """
+    Test plot_transformation with static 3D PCA visualization.
+    """
+    X, batch = simulate_data(n_samples=100, n_features=20)
+    combat = ComBat(batch=batch, method="johnson").fit(X)
+
+    fig = combat.plot_transformation(
+        X,
+        reduction_method='pca',
+        n_components=3,
+        plot_type='static'
+    )
+    assert fig is not None
+
+
+def test_plot_transformation_return_embeddings():
+    """
+    Test that plot_transformation can return embeddings.
+    """
+    X, batch = simulate_data(n_samples=100, n_features=20)
+    combat = ComBat(batch=batch, method="johnson").fit(X)
+
+    fig, embeddings = combat.plot_transformation(
+        X,
+        reduction_method='pca',
+        n_components=2,
+        plot_type='static',
+        return_embeddings=True
+    )
+    assert fig is not None
+    assert 'original' in embeddings
+    assert 'transformed' in embeddings
+    assert embeddings['original'].shape == (100, 2)
+    assert embeddings['transformed'].shape == (100, 2)
+
+
+def test_plot_transformation_invalid_method_raises():
+    """
+    Test that invalid reduction_method raises ValueError.
+    """
+    X, batch = simulate_data(n_samples=100, n_features=20)
+    combat = ComBat(batch=batch, method="johnson").fit(X)
+
+    with pytest.raises(ValueError, match="reduction_method must be"):
+        combat.plot_transformation(X, reduction_method='invalid')
+
+
+def test_plot_transformation_invalid_n_components_raises():
+    """
+    Test that invalid n_components raises ValueError.
+    """
+    X, batch = simulate_data(n_samples=100, n_features=20)
+    combat = ComBat(batch=batch, method="johnson").fit(X)
+
+    with pytest.raises(ValueError, match="n_components must be 2 or 3"):
+        combat.plot_transformation(X, n_components=4)
+
+
+def test_invalid_method_raises():
+    """
+    Test that an invalid method raises ValueError.
+    """
+    X, batch = simulate_data()
+    with pytest.raises(ValueError, match="method must be"):
+        ComBatModel(method="invalid").fit(X, batch=batch)

combatlearn-0.2.1/combatlearn/__init__.py

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

combatlearn-0.2.1/tests/test_combat.py

@@ -1,150 +0,0 @@
-import numpy as np
-import pandas as pd
-import pytest
-from sklearn.pipeline import Pipeline
-from sklearn.base import clone
-from sklearn.preprocessing import StandardScaler
-from sklearn.exceptions import NotFittedError
-from combatlearn import ComBatModel, ComBat
-from utils import simulate_data, simulate_covariate_data
-
-
-def test_transform_without_fit_raises():
-    """
-    Test that `transform` raises a `NotFittedError` if not fitted.
-    """
-    X, batch = simulate_data()
-    model = ComBatModel()
-    with pytest.raises(NotFittedError):
-        model.transform(X, batch=batch)
-
-
-def test_unseen_batch_raises_value_error():
-    """
-    Test that unseen batch raises a `ValueError`.
-    """
-    X, batch = simulate_data()
-    model = ComBatModel().fit(X, batch=batch)
-    new_batch = pd.Series(["Z"] * len(batch), index=batch.index)
-    with pytest.raises(ValueError):
-        model.transform(X, batch=new_batch)
-
-
-def test_single_sample_batch_error():
-    """
-    Test that a single sample batch raises a `ValueError`.
-    """
-    X, batch = simulate_data()
-    batch.iloc[0] = "single"
-    with pytest.raises(ValueError):
-        ComBatModel().fit(X, batch=batch)
-
-
-@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
-def test_dtypes_preserved(method):
-    """All output columns must remain floating dtypes after correction."""
-    if method == "johnson":
-        X, batch = simulate_data()
-        extra = {}
-    else:                                  # fortin  or  chen
-        X, batch, disc, cont = simulate_covariate_data()
-        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
-
-    X_corr = ComBat(batch=batch, method=method, **extra).fit_transform(X)
-    assert all(np.issubdtype(dt, np.floating) for dt in X_corr.dtypes)
-
-def test_wrapper_clone_and_pipeline():
-    """
-    Test `ComBat` wrapper can be cloned and used in a `Pipeline`.
-    """
-    X, batch = simulate_data()
-    wrapper = ComBat(batch=batch, parametric=True)
-    pipe = Pipeline([
-        ("scaler", StandardScaler()),
-        ("combat", wrapper),
-    ])
-    X_corr = pipe.fit_transform(X)
-    pipe_clone: Pipeline = clone(pipe)
-    X_corr2 = pipe_clone.fit_transform(X)
-    np.testing.assert_allclose(X_corr, X_corr2, rtol=1e-5, atol=1e-5)
-
-
-@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
-def test_no_nan_or_inf_in_output(method):
-    """`ComBat` must not introduce NaN or Inf values, for any backend."""
-    if method == "johnson":
-        X, batch = simulate_data()
-        extra = {}
-    else:                                  # fortin  or  chen
-        X, batch, disc, cont = simulate_covariate_data()
-        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
-
-    X_corr = ComBat(batch=batch, method=method, **extra).fit_transform(X)
-    assert not np.isnan(X_corr.values).any()
-    assert not np.isinf(X_corr.values).any()
-
-
-@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
-def test_shape_preserved(method):
-    """The (n_samples, n_features) shape must be identical pre- and post-ComBat."""
-    if method == "johnson":
-        X, batch = simulate_data()
-        combat = ComBat(batch=batch, method=method).fit(X)
-    elif method in ["fortin", "chen"]:
-        X, batch, disc, cont = simulate_covariate_data()
-        combat = ComBat(
-            batch=batch,
-            discrete_covariates=disc,
-            continuous_covariates=cont,
-            method=method,
-        ).fit(X)
-
-    X_corr = combat.transform(X)
-    assert X_corr.shape == X.shape
-
-
-def test_johnson_print_warning():
-    """
-    Test that a warning is printed when using the Johnson method.
-    """
-    X, batch, disc, cont = simulate_covariate_data()
-    with pytest.warns(Warning, match="Covariates are ignored when using method='johnson'."):
-        _ = ComBat(
-            batch=batch,
-            discrete_covariates=disc,
-            continuous_covariates=cont,
-            method="johnson",
-        ).fit(X)
-
-
-@pytest.mark.parametrize("method", ["johnson", "fortin", "chen"])
-def test_reference_batch_samples_unchanged(method):
-    """
-    Samples belonging to the reference batch must come out *numerically identical*
-    (within floating-point jitter) after correction.
-    """
-    if method == "johnson":
-        X, batch = simulate_data()
-        extra = {}
-    elif method in ["fortin", "chen"]:
-        X, batch, disc, cont = simulate_covariate_data()
-        extra = dict(discrete_covariates=disc, continuous_covariates=cont)
-
-    ref_batch = batch.iloc[0]
-    combat = ComBat(batch=batch, method=method,
-                    reference_batch=ref_batch, **extra).fit(X)
-    X_corr = combat.transform(X)
-
-    mask = batch == ref_batch
-    np.testing.assert_allclose(X_corr.loc[mask].values,
-                               X.loc[mask].values,
-                               rtol=0, atol=1e-10)
-
-
-def test_reference_batch_missing_raises():
-    """
-    Asking for a reference batch that doesn't exist should fail.
-    """
-    X, batch = simulate_data()
-    with pytest.raises(ValueError, match="not present"):
-        ComBat(batch=batch, reference_batch="DOES_NOT_EXIST").fit(X)