MaldiBatchKit 0.2.0__tar.gz → 0.2.2__tar.gz

{maldibatchkit-0.2.0 → maldibatchkit-0.2.2/MaldiBatchKit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiBatchKit
-Version: 0.2.0
+Version: 0.2.2
 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,7 +27,7 @@ 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.15.0
 Requires-Dist: typer>=0.9.0
@@ -42,7 +42,7 @@ Requires-Dist: sphinx>=7.0.0; extra == "docs"
 Requires-Dist: pydata-sphinx-theme>=0.15.0; extra == "docs"
 Requires-Dist: sphinx-autodoc-typehints>=2.0.0; extra == "docs"
 Requires-Dist: sphinx-design>=0.6.0; extra == "docs"
-Requires-Dist: sphinx-click>=5.0.0; extra == "docs"
+Requires-Dist: sphinxcontrib-typer>=0.5.0; extra == "docs"
 Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
 Requires-Dist: ipykernel>=6.0.0; extra == "docs"
 Requires-Dist: ipywidgets>=8.0.0; extra == "docs"
@@ -62,13 +62,20 @@ Dynamic: license-file
 [![License](https://img.shields.io/github/license/EttoreRocchi/MaldiBatchKit)](https://github.com/EttoreRocchi/MaldiBatchKit/blob/main/LICENSE)
 
 <p align="center">
-  <img src="docs/maldibatchkit_logo.png" alt="MaldiBatchKit" width="320"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/docs/maldibatchkit_logo_dark.png">
+    <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/docs/maldibatchkit_logo.png" alt="MaldiBatchKit" width="320"/>
+  </picture>
 </p>
 
 <p align="center">
   <strong>Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows</strong>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/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> •
@@ -79,7 +86,7 @@ Dynamic: license-file
   <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 corrects the inter-batch and inter-site shifts of multi-centre MALDI-TOF studies. It is part of the **MaldiSuite** ecosystem: it can be used on its own, or together with [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiDeepKit](https://github.com/EttoreRocchi/MaldiDeepKit).
 
 ## Installation
 
@@ -120,8 +127,8 @@ Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSu
   - `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.
+- **Diagnostic benchmark**: `BatchCorrectionBenchmark` runs a fixed set of metrics across multiple correctors with intervals from stratified subsamples and a tidy `(method, metric, value, ci_lo, ci_hi)` summary, ready for paper-figure comparisons.
+- **Visualisation**: 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 ...`.
 
@@ -172,6 +179,8 @@ corrected_ds.X      # harmonised feature matrix
 corrected_ds.y      # AMR labels, unchanged
 ```
 
+The `*_column` arguments name columns of the metadata behind `ds.meta`; a missing column raises `KeyError`. A corrector uses only what it accepts: `quality_column` has no effect with `SpeciesAwareComBat`.
+
 ### CLI
 
 The CLI is organised as `maldibatchkit correct <method>` + `maldibatchkit diagnose`. Every method has its own subcommand with only the flags it actually uses:
@@ -212,7 +221,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
 
@@ -220,7 +229,7 @@ Run `maldibatchkit correct <method> --help` for the full flag list of any correc
 |--------------------------------|---------------------------|----------------------|------------------|
 | 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              |
@@ -246,7 +255,7 @@ from sklearn.pipeline import Pipeline
 from maldibatchkit import AutoCorrector
 
 pipe = Pipeline([
-    ("correct", AutoCorrector(batch=batch, discrete_covariates=species)),
+    ("correct", AutoCorrector(batch=batch, discrete_covariates=species, quality=snr)),
     ("clf", LogisticRegression(max_iter=1000)),
 ])
 grid = GridSearchCV(
@@ -343,26 +352,24 @@ 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`.
+Most metrics take `(X, batch)`; `per_batch_spectrum_count` takes only `batch`. `diagnostic_report(before, after, batch)` composes them into a tidy DataFrame suitable for `plot_diagnostic_summary`.
 
-## MaldiSuite Ecosystem
+## MaldiSuite ecosystem
 
-MaldiBatchKit is the harmonisation package of the **MaldiSuite** ecosystem:
+MaldiBatchKit is one of the three packages 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/>).
+The three packages share the `MaldiSet` data model. Each can be used on its own, or combined with the others. Install the full suite with `pip install maldisuite`. Landing page: [MaldiSuite](<https://ettorerocchi.github.io/MaldiSuite/>).
 
 ## Citation
 
-If you use MaldiBatchKit in academic work please cite:
-
-> _Citation will be available soon._
+MaldiBatchKit is part of MaldiSuite, which is described in an Application Note currently under review at *Bioinformatics*. The full citation will be added here once the article is published.
 
-along with the upstream references for whichever methods you apply (Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
+Please also cite the upstream references for whichever methods you apply (Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/EttoreRocchi/MaldiBatchKit/blob/main/LICENSE).

{maldibatchkit-0.2.0 → maldibatchkit-0.2.2}/MaldiBatchKit.egg-info/requires.txt

@@ -3,7 +3,7 @@ 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.15.0
 typer>=0.9.0
@@ -20,7 +20,7 @@ sphinx>=7.0.0
 pydata-sphinx-theme>=0.15.0
 sphinx-autodoc-typehints>=2.0.0
 sphinx-design>=0.6.0
-sphinx-click>=5.0.0
+sphinxcontrib-typer>=0.5.0
 nbsphinx>=0.9.0
 ipykernel>=6.0.0
 ipywidgets>=8.0.0

{maldibatchkit-0.2.0/MaldiBatchKit.egg-info → maldibatchkit-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiBatchKit
-Version: 0.2.0
+Version: 0.2.2
 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,7 +27,7 @@ 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.15.0
 Requires-Dist: typer>=0.9.0
@@ -42,7 +42,7 @@ Requires-Dist: sphinx>=7.0.0; extra == "docs"
 Requires-Dist: pydata-sphinx-theme>=0.15.0; extra == "docs"
 Requires-Dist: sphinx-autodoc-typehints>=2.0.0; extra == "docs"
 Requires-Dist: sphinx-design>=0.6.0; extra == "docs"
-Requires-Dist: sphinx-click>=5.0.0; extra == "docs"
+Requires-Dist: sphinxcontrib-typer>=0.5.0; extra == "docs"
 Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
 Requires-Dist: ipykernel>=6.0.0; extra == "docs"
 Requires-Dist: ipywidgets>=8.0.0; extra == "docs"
@@ -62,13 +62,20 @@ Dynamic: license-file
 [![License](https://img.shields.io/github/license/EttoreRocchi/MaldiBatchKit)](https://github.com/EttoreRocchi/MaldiBatchKit/blob/main/LICENSE)
 
 <p align="center">
-  <img src="docs/maldibatchkit_logo.png" alt="MaldiBatchKit" width="320"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/docs/maldibatchkit_logo_dark.png">
+    <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/docs/maldibatchkit_logo.png" alt="MaldiBatchKit" width="320"/>
+  </picture>
 </p>
 
 <p align="center">
   <strong>Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows</strong>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/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> •
@@ -79,7 +86,7 @@ Dynamic: license-file
   <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 corrects the inter-batch and inter-site shifts of multi-centre MALDI-TOF studies. It is part of the **MaldiSuite** ecosystem: it can be used on its own, or together with [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiDeepKit](https://github.com/EttoreRocchi/MaldiDeepKit).
 
 ## Installation
 
@@ -120,8 +127,8 @@ Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSu
   - `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.
+- **Diagnostic benchmark**: `BatchCorrectionBenchmark` runs a fixed set of metrics across multiple correctors with intervals from stratified subsamples and a tidy `(method, metric, value, ci_lo, ci_hi)` summary, ready for paper-figure comparisons.
+- **Visualisation**: 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 ...`.
 
@@ -172,6 +179,8 @@ corrected_ds.X      # harmonised feature matrix
 corrected_ds.y      # AMR labels, unchanged
 ```
 
+The `*_column` arguments name columns of the metadata behind `ds.meta`; a missing column raises `KeyError`. A corrector uses only what it accepts: `quality_column` has no effect with `SpeciesAwareComBat`.
+
 ### CLI
 
 The CLI is organised as `maldibatchkit correct <method>` + `maldibatchkit diagnose`. Every method has its own subcommand with only the flags it actually uses:
@@ -212,7 +221,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
 
@@ -220,7 +229,7 @@ Run `maldibatchkit correct <method> --help` for the full flag list of any correc
 |--------------------------------|---------------------------|----------------------|------------------|
 | 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              |
@@ -246,7 +255,7 @@ from sklearn.pipeline import Pipeline
 from maldibatchkit import AutoCorrector
 
 pipe = Pipeline([
-    ("correct", AutoCorrector(batch=batch, discrete_covariates=species)),
+    ("correct", AutoCorrector(batch=batch, discrete_covariates=species, quality=snr)),
     ("clf", LogisticRegression(max_iter=1000)),
 ])
 grid = GridSearchCV(
@@ -343,26 +352,24 @@ 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`.
+Most metrics take `(X, batch)`; `per_batch_spectrum_count` takes only `batch`. `diagnostic_report(before, after, batch)` composes them into a tidy DataFrame suitable for `plot_diagnostic_summary`.
 
-## MaldiSuite Ecosystem
+## MaldiSuite ecosystem
 
-MaldiBatchKit is the harmonisation package of the **MaldiSuite** ecosystem:
+MaldiBatchKit is one of the three packages 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/>).
+The three packages share the `MaldiSet` data model. Each can be used on its own, or combined with the others. Install the full suite with `pip install maldisuite`. Landing page: [MaldiSuite](<https://ettorerocchi.github.io/MaldiSuite/>).
 
 ## Citation
 
-If you use MaldiBatchKit in academic work please cite:
-
-> _Citation will be available soon._
+MaldiBatchKit is part of MaldiSuite, which is described in an Application Note currently under review at *Bioinformatics*. The full citation will be added here once the article is published.
 
-along with the upstream references for whichever methods you apply (Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
+Please also cite the upstream references for whichever methods you apply (Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/EttoreRocchi/MaldiBatchKit/blob/main/LICENSE).

{maldibatchkit-0.2.0 → maldibatchkit-0.2.2}/README.md

@@ -9,13 +9,20 @@
 [![License](https://img.shields.io/github/license/EttoreRocchi/MaldiBatchKit)](https://github.com/EttoreRocchi/MaldiBatchKit/blob/main/LICENSE)
 
 <p align="center">
-  <img src="docs/maldibatchkit_logo.png" alt="MaldiBatchKit" width="320"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/docs/maldibatchkit_logo_dark.png">
+    <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/docs/maldibatchkit_logo.png" alt="MaldiBatchKit" width="320"/>
+  </picture>
 </p>
 
 <p align="center">
   <strong>Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows</strong>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiBatchKit/main/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> •
@@ -26,7 +33,7 @@
   <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 corrects the inter-batch and inter-site shifts of multi-centre MALDI-TOF studies. It is part of the **MaldiSuite** ecosystem: it can be used on its own, or together with [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiDeepKit](https://github.com/EttoreRocchi/MaldiDeepKit).
 
 ## Installation
 
@@ -67,8 +74,8 @@ Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSu
   - `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.
+- **Diagnostic benchmark**: `BatchCorrectionBenchmark` runs a fixed set of metrics across multiple correctors with intervals from stratified subsamples and a tidy `(method, metric, value, ci_lo, ci_hi)` summary, ready for paper-figure comparisons.
+- **Visualisation**: 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 ...`.
 
@@ -119,6 +126,8 @@ corrected_ds.X      # harmonised feature matrix
 corrected_ds.y      # AMR labels, unchanged
 ```
 
+The `*_column` arguments name columns of the metadata behind `ds.meta`; a missing column raises `KeyError`. A corrector uses only what it accepts: `quality_column` has no effect with `SpeciesAwareComBat`.
+
 ### CLI
 
 The CLI is organised as `maldibatchkit correct <method>` + `maldibatchkit diagnose`. Every method has its own subcommand with only the flags it actually uses:
@@ -159,7 +168,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
 
@@ -167,7 +176,7 @@ Run `maldibatchkit correct <method> --help` for the full flag list of any correc
 |--------------------------------|---------------------------|----------------------|------------------|
 | 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              |
@@ -193,7 +202,7 @@ from sklearn.pipeline import Pipeline
 from maldibatchkit import AutoCorrector
 
 pipe = Pipeline([
-    ("correct", AutoCorrector(batch=batch, discrete_covariates=species)),
+    ("correct", AutoCorrector(batch=batch, discrete_covariates=species, quality=snr)),
     ("clf", LogisticRegression(max_iter=1000)),
 ])
 grid = GridSearchCV(
@@ -290,26 +299,24 @@ 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`.
+Most metrics take `(X, batch)`; `per_batch_spectrum_count` takes only `batch`. `diagnostic_report(before, after, batch)` composes them into a tidy DataFrame suitable for `plot_diagnostic_summary`.
 
-## MaldiSuite Ecosystem
+## MaldiSuite ecosystem
 
-MaldiBatchKit is the harmonisation package of the **MaldiSuite** ecosystem:
+MaldiBatchKit is one of the three packages 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/>).
+The three packages share the `MaldiSet` data model. Each can be used on its own, or combined with the others. Install the full suite with `pip install maldisuite`. Landing page: [MaldiSuite](<https://ettorerocchi.github.io/MaldiSuite/>).
 
 ## Citation
 
-If you use MaldiBatchKit in academic work please cite:
-
-> _Citation will be available soon._
+MaldiBatchKit is part of MaldiSuite, which is described in an Application Note currently under review at *Bioinformatics*. The full citation will be added here once the article is published.
 
-along with the upstream references for whichever methods you apply (Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
+Please also cite the upstream references for whichever methods you apply (Johnson 2007, Fortin 2018, Chen 2022, Ritchie 2015, Korsunsky 2019).
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/EttoreRocchi/MaldiBatchKit/blob/main/LICENSE).

{maldibatchkit-0.2.0 → maldibatchkit-0.2.2}/maldibatchkit/__init__.py

@@ -58,7 +58,7 @@ from .metrics import (
     make_batch_scorer,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 __author__ = "Ettore Rocchi"
 
 __all__ = [

{maldibatchkit-0.2.0 → maldibatchkit-0.2.2}/maldibatchkit/_base.py

@@ -27,7 +27,14 @@ import pandas as pd
 from sklearn.base import BaseEstimator, TransformerMixin
 from sklearn.utils.validation import check_array, check_is_fitted
 
-from ._utils import ArrayLike, _ensure_index, _subset
+from ._utils import (
+    ArrayLike,
+    _check_label_values,
+    _check_positional_alignment,
+    _check_unique_ids,
+    _ensure_index,
+    _subset,
+)
 
 
 def _check_array_finite(X: Any) -> None:
@@ -65,6 +72,8 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
     :meth:`get_params` / :meth:`set_params` work.
     """
 
+    _sample_aligned_params: tuple[str, ...] = ("batch",)
+
     def __init__(self, batch: ArrayLike) -> None:
         self.batch = batch
 
@@ -72,6 +81,13 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
         """Validate the feature matrix."""
         _check_array_finite(X)
 
+    def _check_sample_alignment(self, X: ArrayLike) -> None:
+        """Reject pandas per-sample inputs that an ndarray ``X`` cannot match."""
+        if isinstance(X, pd.DataFrame | pd.Series):
+            return
+        for name in self._sample_aligned_params:
+            _check_positional_alignment(getattr(self, name, None), len(X), name)
+
     def _prepare_fit(
         self, X: ArrayLike
     ) -> tuple[pd.DataFrame, npt.NDArray[Any], pd.Index]:
@@ -87,7 +103,10 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
             The shared index used by ``X`` and ``batch``.
         """
         self._validate_X(X)
+        self._check_sample_alignment(X)
         idx = _ensure_index(X)
+        _check_unique_ids(idx, "X")
+        self._fitted_on_frame_ = isinstance(X, pd.DataFrame)
         if isinstance(X, pd.DataFrame):
             self.feature_names_in_ = np.asarray(X.columns, dtype=object)
             X_df = X
@@ -104,11 +123,7 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
                 raise ValueError(f"`batch` must be 1-D; got shape {batch_vec.shape}.")
             batch_vec = batch_vec.iloc[:, 0]
         batch_ser = pd.Series(batch_vec, index=idx)
-        if batch_ser.isna().any():
-            raise ValueError(
-                f"batch contains {int(batch_ser.isna().sum())} NaN value(s); "
-                f"all batch labels must be non-null."
-            )
+        _check_label_values(batch_ser, "batch")
         return X_df, batch_ser.to_numpy(), idx
 
     def _prepare_transform(
@@ -117,13 +132,32 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
         """Run common ``transform``-time bookkeeping."""
         check_is_fitted(self)
         self._validate_X(X)
+        self._check_sample_alignment(X)
         idx = _ensure_index(X)
+        _check_unique_ids(idx, "X")
         was_df = isinstance(X, pd.DataFrame)
         X_df = X if was_df else pd.DataFrame(np.asarray(X), index=idx)
+        if X_df.shape[1] != self.n_features_in_:
+            raise ValueError(
+                f"X has {X_df.shape[1]} features, but {type(self).__name__} "
+                f"is expecting {self.n_features_in_} features as input."
+            )
+        if (
+            was_df
+            and getattr(self, "_fitted_on_frame_", False)
+            and not np.array_equal(
+                np.asarray(X.columns, dtype=object), self.feature_names_in_
+            )
+        ):
+            raise ValueError(
+                "The feature names should match those that were passed during "
+                "fit, in the same order."
+            )
         batch_vec = _subset(self.batch, idx)
         if isinstance(batch_vec, pd.DataFrame):
             batch_vec = batch_vec.iloc[:, 0]
         batch_ser = pd.Series(batch_vec, index=idx)
+        _check_label_values(batch_ser, "batch")
         return X_df, batch_ser.to_numpy(), idx, was_df
 
     def _fit_impl(