MaldiBatchKit 0.1.0__tar.gz → 0.2.1__tar.gz

{maldibatchkit-0.1.0 → maldibatchkit-0.2.1/MaldiBatchKit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiBatchKit
-Version: 0.1.0
+Version: 0.2.1
 Summary: Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows
 Author-email: Ettore Rocchi <ettore.rocchi3@unibo.it>
 License-Expression: MIT
@@ -27,9 +27,9 @@ Requires-Dist: pandas>=1.3.0
 Requires-Dist: scipy>=1.13.0
 Requires-Dist: scikit-learn>=1.6.0
 Requires-Dist: matplotlib>=3.4.0
-Requires-Dist: combatlearn>=2.0.0
+Requires-Dist: combatlearn>=2.4.0
 Requires-Dist: harmonypy<2,>=0.2.0
-Requires-Dist: maldiamrkit>=0.12.0
+Requires-Dist: maldiamrkit>=0.15.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
@@ -55,8 +55,10 @@ Dynamic: license-file
 
 [![CI](https://github.com/EttoreRocchi/MaldiBatchKit/actions/workflows/ci.yml/badge.svg)](https://github.com/EttoreRocchi/MaldiBatchKit/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/github/EttoreRocchi/MaldiBatchKit/branch/main/graph/badge.svg)](https://codecov.io/github/EttoreRocchi/MaldiBatchKit)
-[![Docs](https://readthedocs.org/projects/maldibatchkit/badge/?version=latest)](https://maldibatchkit.readthedocs.io/en/latest/)
-[![Python](https://img.shields.io/badge/python-3.10--3.13-blue)](https://pypi.org/project/maldibatchkit/)
+[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://maldibatchkit.readthedocs.io/)
+
+[![PyPI Version](https://img.shields.io/pypi/v/maldibatchkit)](https://pypi.org/project/maldibatchkit/)
+[![Python](https://img.shields.io/pypi/pyversions/maldibatchkit)](https://pypi.org/project/maldibatchkit/)
 [![License](https://img.shields.io/github/license/EttoreRocchi/MaldiBatchKit)](https://github.com/EttoreRocchi/MaldiBatchKit/blob/main/LICENSE)
 
 <p align="center">
@@ -67,21 +69,21 @@ Dynamic: license-file
   <strong>Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows</strong>
 </p>
 
+<p align="center">
+  <img src="docs/batch_correction.svg" alt="Animated scatter plot: before correction MALDI-TOF samples cluster by acquisition site; after MaldiBatchKit the site effect is removed and samples cluster by species" width="720"/>
+</p>
+
 <p align="center">
   <a href="#installation">Installation</a> •
   <a href="#features">Features</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#algorithms">Algorithms</a> •
   <a href="#diagnostics">Diagnostics</a> •
+  <a href="#maldisuite-ecosystem">MaldiSuite</a> •
   <a href="#citation">Citation</a>
 </p>
 
-MaldiBatchKit is part of the **MaldiSuite** ecosystem and complements
-[MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit): where
-MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation,
-MaldiBatchKit focuses on the *harmonization* step, removing the
-inter-batch / inter-site shifts that plague multi-centre MALDI-TOF
-studies.
+MaldiBatchKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit): where MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation, MaldiBatchKit focuses on the *harmonization* step, removing the inter-batch / inter-site shifts that plague multi-centre MALDI-TOF studies.
 
 ## Installation
 
@@ -97,40 +99,34 @@ pip install maldibatchkit[dev]      # testing + linting
 pip install maldibatchkit[docs]     # sphinx
 ```
 
-`maldiamrkit` is a core dependency - installing MaldiBatchKit pulls
-it in automatically. `BatchAwareWarping` reuses
-`maldiamrkit.alignment.Warping` under the hood, and the
-`MaldiSetAdapter` bridges to `maldiamrkit.MaldiSet` for end-to-end
-AMR workflows.
+`maldiamrkit` is a core dependency - installing MaldiBatchKit pulls it in automatically. `BatchAwareWarping` reuses `maldiamrkit.alignment.Warping` under the hood, and the `MaldiSetAdapter` bridges to `maldiamrkit.MaldiSet` for end-to-end AMR workflows.
+
+### Install the full MaldiSuite
+
+To install MaldiBatchKit together with [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiDeepKit](https://github.com/EttoreRocchi/MaldiDeepKit) at compatible versions, install the [`maldisuite`](https://pypi.org/project/maldisuite/) meta-package:
+
+```bash
+pip install maldisuite
+```
+
+Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSuite/>.
 
 ## Features
 
-- **Unified sklearn API** (`BaseEstimator` + `TransformerMixin`) for
-  every correction method. `batch` and covariates are passed at
-  construction time and aligned to `X.index` at `fit` / `transform`,
-  so the same object works inside `Pipeline` / cross-validation
-  without data leakage.
-- **ComBat variants** (Johnson 2007, Fortin 2018, Chen 2022 CovBat)
-  re-exported from [combatlearn](https://github.com/EttoreRocchi/combatlearn).
+- **Unified sklearn API** (`BaseEstimator` + `TransformerMixin`) for every correction method. `batch` and covariates are passed at construction time and aligned to `X.index` at `fit` / `transform`, so the same object works inside `Pipeline` / cross-validation without data leakage.
+- **ComBat variants** (Johnson 2007, Fortin 2018, Chen 2022 CovBat) re-exported from [combatlearn](https://github.com/EttoreRocchi/combatlearn).
 - **Limma `removeBatchEffect`** (Ritchie et al. 2015).
 - **Harmony** (Korsunsky et al. 2019) via [harmonypy](https://github.com/slowkow/harmonypy), with a **mandatory, frozen PCA preprocessing stage** so it behaves sensibly on high-dimensional MALDI-TOF intensity matrices (tune with the `n_components=` argument).
-- **Simple baselines**: median centering, z-score per batch,
-  reference scaling.
+- **Simple baselines**: median centering, z-score per batch, reference scaling.
 - **MALDI-specific corrections**:
-  - `BatchAwareWarping` - per-batch m/z warping sharing a global
-    reference (wraps `maldiamrkit.alignment.Warping`).
-  - `QualityWeightedComBat` - weighted empirical-Bayes ComBat
-    variant where low-SNR spectra contribute less to the shrinkage
-    prior.
-  - `SpeciesAwareComBat` - convenience preset for ComBat-Fortin with
-    `species` as the protected biological covariate.
-- **Diagnostics**: kBET, LISI, silhouette-by-batch, per-batch peak
-  drift, per-batch TIC coefficient of variation, per-batch spectrum
-  count, plus a combined `diagnostic_report` DataFrame summary.
-- **Visualization**: UMAP before/after, per-batch peak-shape overlays,
-  before/after bar charts.
-- **Integration adapter**: `MaldiSetAdapter` turns a
-  `maldiamrkit.MaldiSet` into a corrected `MaldiSet` in one call.
+  - `BatchAwareWarping` - per-batch m/z warping sharing a global reference (wraps `maldiamrkit.alignment.Warping`).
+  - `QualityWeightedComBat` - weighted empirical-Bayes ComBat variant where low-SNR spectra contribute less to the shrinkage prior.
+  - `SpeciesAwareComBat` - convenience preset for ComBat-Fortin with `species` as the protected biological covariate.
+- **Diagnostics**: kBET, LISI, silhouette-by-batch, per-batch peak drift, per-batch TIC coefficient of variation, per-batch spectrum count, plus a combined `diagnostic_report` DataFrame summary.
+- **Method selection**: `AutoCorrector` exposes `method` as a settable hyperparameter so `GridSearchCV` can sweep across corrector families and let the downstream classifier metric (AUROC) decide. Ships with a `NoOpCorrector` so "do nothing" can sit on the candidate list as an honest baseline.
+- **Diagnostic benchmark**: `BatchCorrectionBenchmark` runs a fixed set of metrics across multiple correctors with stratified bootstrap CIs and a tidy `(method, metric, value, ci_lo, ci_hi)` summary, ready for paper-figure comparisons.
+- **Visualization**: UMAP before/after, per-batch peak-shape overlays, before/after bar charts.
+- **Integration adapter**: `MaldiSetAdapter` turns a `maldiamrkit.MaldiSet` into a corrected `MaldiSet` in one call.
 - **CLI**: `maldibatchkit correct ...` and `maldibatchkit diagnose ...`.
 
 ## Quick start
@@ -160,8 +156,7 @@ X_train_c = corrector.transform(X_train)
 X_test_c  = corrector.transform(X_test)   # same parameters applied to test
 ```
 
-`batch` is indexed by the same sample IDs that X uses, so the
-corrector picks the right subset on each call.
+`batch` is indexed by the same sample IDs that X uses, so the corrector picks the right subset on each call.
 
 ### MaldiSet integration
 
@@ -183,9 +178,7 @@ corrected_ds.y      # AMR labels, unchanged
 
 ### CLI
 
-The CLI is organised as `maldibatchkit correct <method>` +
-`maldibatchkit diagnose`. Every method has its own subcommand with
-only the flags it actually uses:
+The CLI is organised as `maldibatchkit correct <method>` + `maldibatchkit diagnose`. Every method has its own subcommand with only the flags it actually uses:
 
 ```bash
 # Vanilla Johnson ComBat
@@ -214,8 +207,7 @@ maldibatchkit diagnose \
     --batch-csv batch.csv --mz-csv mz.csv -o report.csv
 ```
 
-NPZ inputs bundle X, index, columns, and batch labels in one file, so
-the same commands work without sidecar CSVs:
+NPZ inputs bundle X, index, columns, and batch labels in one file, so the same commands work without sidecar CSVs:
 
 ```bash
 maldibatchkit correct combat-fortin \
@@ -224,11 +216,7 @@ maldibatchkit correct combat-fortin \
     -o corrected.npz
 ```
 
-Run `maldibatchkit correct <method> --help` for the full flag list of
-any corrector. `combat-fortin` / `combat-chen` refuse to run without
-covariates (they would silently reduce to Johnson ComBat);
-`species-combat` / `quality-combat` require their dedicated
-`--species-csv` / `--quality-csv` inputs.
+Run `maldibatchkit correct <method> --help` for the full flag list of any corrector. `combat-fortin` refuses to run without covariates (it would silently reduce to Johnson ComBat); `combat-chen` without covariates is plain CovBat (Johnson ComBat plus the covariance correction); `species-combat` / `quality-combat` require their dedicated `--species-csv` / `--quality-csv` inputs.
 
 ## Algorithms
 
@@ -236,34 +224,72 @@ covariates (they would silently reduce to Johnson ComBat);
 |--------------------------------|---------------------------|----------------------|------------------|
 | ComBat (Johnson, Fortin, Chen) | `ComBat`                  | Fortin / Chen        | yes              |
 | Limma                          | `Limma`                   | via `design=`        | yes              |
-| Harmony                        | `Harmony`                 | via `covariates=`    | yes              |
+| Harmony                        | `Harmony`                 | no (removes them)    | yes              |
 | Median centering               | `MedianCentering`         | no                   | yes              |
 | Z-score per batch              | `ZScorePerBatch`          | no                   | yes              |
 | Reference scaling              | `ReferenceScaling`        | no                   | yes              |
 | Batch-aware warping            | `BatchAwareWarping`       | no                   | yes              |
 | Quality-weighted ComBat        | `QualityWeightedComBat`   | no                   | yes              |
 | Species-aware ComBat           | `SpeciesAwareComBat`      | species              | yes              |
+| Identity / no-op               | `NoOpCorrector`           | n/a                  | yes              |
+| Meta-corrector                 | `AutoCorrector`           | inherits inner       | yes              |
+
+See the `QualityWeightedComBat` docstring for the mathematical formulation of the weighted empirical-Bayes update.
+
+### Choosing a corrector
+
+Picking among the methods above usually means asking one of two
+questions: *"which corrector gives the best AMR classifier?"* or
+*"which corrector mixes batches best while keeping species apart?"*.
+MaldiBatchKit ships one tool for each:
+
+```python
+from sklearn.linear_model import LogisticRegression
+from sklearn.model_selection import GridSearchCV
+from sklearn.pipeline import Pipeline
+from maldibatchkit import AutoCorrector
+
+pipe = Pipeline([
+    ("correct", AutoCorrector(batch=batch, discrete_covariates=species)),
+    ("clf", LogisticRegression(max_iter=1000)),
+])
+grid = GridSearchCV(
+    pipe,
+    param_grid={"correct__method": ["noop", "combat-fortin", "harmony", "qw-combat"]},
+    scoring="roc_auc",
+)
+grid.fit(X, y)
+```
 
-See the `QualityWeightedComBat` docstring for the mathematical
-formulation of the weighted empirical-Bayes update.
+```python
+from maldibatchkit import ComBat, NoOpCorrector
+from maldibatchkit.diagnostics import BatchCorrectionBenchmark
+
+bench = BatchCorrectionBenchmark(
+    correctors={
+        "none":   NoOpCorrector(batch=batch),
+        "fortin": ComBat(batch=batch, method="fortin", discrete_covariates=species),
+    },
+    metrics=("kbet", "lisi_normalized", "species_preservation"),
+    n_bootstrap=500,
+    random_state=0,
+).fit(X, batch=batch, species=species)
+bench.rank(by="species_preservation")
+```
+
+See [docs / Choosing a corrector](https://maldibatchkit.readthedocs.io/en/latest/choosing.html) for the full recipe.
 
 ## Extending MaldiBatchKit
 
-Every corrector in this package inherits from `BaseBatchCorrector`,
-which is re-exported at the top level. Subclass it, implement
-`_fit_impl` and `_transform_impl`, and you get a scikit-learn compatible,
-train/test-safe corrector for free - the base class handles index
-alignment between `X` and the stored `batch` labels, NaN / finite
-checks, DataFrame-vs-ndarray round-tripping, and the `feature_names_in_`
-/ `n_features_in_` / `get_feature_names_out` sklearn bookkeeping.
+Every corrector in this package inherits from `BaseBatchCorrector`, which is re-exported at the top level. Subclass it, implement `_fit_impl` and `_transform_impl`, and you get a scikit-learn compatible, train/test-safe corrector for free - the base class handles index alignment between `X` and the stored `batch` labels, NaN / finite checks, DataFrame-vs-ndarray round-tripping, and the `feature_names_in_` / `n_features_in_` / `get_feature_names_out` sklearn bookkeeping.
 
-Minimal custom corrector:
+Minimal custom corrector (toy example - not shipped with the package):
 
 ```python
 import pandas as pd
 from maldibatchkit import BaseBatchCorrector
 
-class MeanCentering(BaseBatchCorrector):
+class MyMeanCentering(BaseBatchCorrector):
     """Subtract per-batch means from each feature."""
 
     def _fit_impl(self, X_df, batch):
@@ -294,7 +320,7 @@ from sklearn.preprocessing import StandardScaler
 from sklearn.ensemble import RandomForestClassifier
 
 pipe = Pipeline([
-    ("mean", MeanCentering(batch=batch)),
+    ("mean", MyMeanCentering(batch=batch)),   # the class defined just above
     ("scaler", StandardScaler()),
     ("clf", RandomForestClassifier()),
 ])
@@ -307,14 +333,9 @@ Conventions (see `CONTRIBUTING.md`):
 - NumPy-style docstring on every public class.
 - Fitted attributes end in `_` (`self.batch_means_`, not `self.means`).
 - `transform` must be idempotent - no side effects outside `fit`.
-- Raise a clear `ImportError` (not a bare `ModuleNotFoundError`) when
-  an optional dependency is missing; see `Harmony._require_harmonypy`
-  for the reference pattern.
+- Raise a clear `ImportError` (not a bare `ModuleNotFoundError`) when an optional dependency is missing; see `Harmony._require_harmonypy` for the reference pattern.
 
-Look at `maldibatchkit/corrections/baselines.py` for the simplest
-end-to-end references (`MedianCentering`, `ZScorePerBatch`,
-`ReferenceScaling`), or at `quality_weighted.py` for a corrector with
-an iterative fit.
+Look at `maldibatchkit/corrections/baselines.py` for the simplest end-to-end references (`MedianCentering`, `ZScorePerBatch`, `ReferenceScaling`), or at `quality_weighted.py` for a corrector with an iterative fit.
 
 ## Diagnostics
 
@@ -326,9 +347,17 @@ from maldibatchkit.diagnostics import (
 )
 ```
 
-All metrics take the same `(X, batch)` signature. `diagnostic_report`
-composes them into a tidy DataFrame suitable for
-`plot_diagnostic_summary`.
+All metrics take the same `(X, batch)` signature. `diagnostic_report` composes them into a tidy DataFrame suitable for `plot_diagnostic_summary`.
+
+## MaldiSuite Ecosystem
+
+MaldiBatchKit is the harmonisation package of the **MaldiSuite** ecosystem:
+
+- **[MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit)** - data model (`MaldiSpectrum`, `MaldiSet`), preprocessing, alignment, peak detection, differential analysis, and AMR-aware evaluation.
+- **MaldiBatchKit** (this package) - batch-effect correction and harmonisation for multi-centre / multi-instrument MALDI-TOF spectra.
+- **[MaldiDeepKit](https://github.com/EttoreRocchi/MaldiDeepKit)** - sklearn-compatible deep learning classifiers (MLP, CNN, ResNet, Transformer).
+
+The three packages share the `MaldiSet` / `MaldiSpectrum` data model and are designed to compose in a single end-to-end pipeline. Install the full suite with `pip install maldisuite`. Landing page: [MaldiSuite](<https://ettorerocchi.github.io/MaldiSuite/>).
 
 ## Citation
 
@@ -336,8 +365,7 @@ If you use MaldiBatchKit in academic work please cite:
 
 > _Citation will be available soon._
 
-along with the upstream references for whichever methods you apply
-(Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
+along with the upstream references for whichever methods you apply (Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
 
 ## License
 

{maldibatchkit-0.1.0 → maldibatchkit-0.2.1}/MaldiBatchKit.egg-info/SOURCES.txt

@@ -16,15 +16,19 @@ maldibatchkit/_base.py
 maldibatchkit/_cli_io.py
 maldibatchkit/_utils.py
 maldibatchkit/cli.py
+maldibatchkit/metrics.py
 maldibatchkit/py.typed
 maldibatchkit/corrections/__init__.py
+maldibatchkit/corrections/auto.py
 maldibatchkit/corrections/baselines.py
 maldibatchkit/corrections/combat.py
 maldibatchkit/corrections/harmony.py
 maldibatchkit/corrections/limma.py
 maldibatchkit/corrections/maldi.py
+maldibatchkit/corrections/noop.py
 maldibatchkit/corrections/quality_weighted.py
 maldibatchkit/diagnostics/__init__.py
+maldibatchkit/diagnostics/benchmark.py
 maldibatchkit/diagnostics/generic.py
 maldibatchkit/diagnostics/maldi.py
 maldibatchkit/diagnostics/report.py
@@ -36,6 +40,7 @@ maldibatchkit/viz/summary.py
 maldibatchkit/viz/umap.py
 tests/test_cli.py
 tests/test_cli_io.py
+tests/test_metrics.py
 tests/test_mz_axis_resolution.py
 tests/test_no_data_leakage.py
 tests/test_package.py

{maldibatchkit-0.1.0 → maldibatchkit-0.2.1}/MaldiBatchKit.egg-info/requires.txt

@@ -3,9 +3,9 @@ pandas>=1.3.0
 scipy>=1.13.0
 scikit-learn>=1.6.0
 matplotlib>=3.4.0
-combatlearn>=2.0.0
+combatlearn>=2.4.0
 harmonypy<2,>=0.2.0
-maldiamrkit>=0.12.0
+maldiamrkit>=0.15.0
 typer>=0.9.0
 
 [dev]