MaldiAMRKit 0.22.0__tar.gz → 0.22.2__tar.gz

{maldiamrkit-0.22.0 → maldiamrkit-0.22.2/MaldiAMRKit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.22.0
+Version: 0.22.2
 Summary: A comprehensive toolkit for MALDI-TOF mass spectrometry data preprocessing for antimicrobial resistance (AMR) prediction purposes
 Author-email: Ettore Rocchi <ettore.rocchi3@unibo.it>
 License-Expression: MIT
@@ -31,6 +31,7 @@ Requires-Dist: seaborn>=0.11.0
 Requires-Dist: pybaselines>=1.0.0
 Requires-Dist: gudhi>=3.5.0
 Requires-Dist: tslearn>=0.6.0
+Requires-Dist: numba>=0.55
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pyarrow>=14.0.0
 Requires-Dist: typer>=0.9.0
@@ -70,13 +71,20 @@ Dynamic: license-file
 [![License](https://img.shields.io/github/license/EttoreRocchi/MaldiAMRKit)](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/LICENSE)
 
 <p align="center">
-  <img src="docs/maldiamrkit.png" alt="MaldiAMRKit" width="320"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EttoreRocchi/MaldiAMRKit/main/docs/maldiamrkit_dark.png">
+    <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiAMRKit/main/docs/maldiamrkit.png" alt="MaldiAMRKit" width="320"/>
+  </picture>
 </p>
 
 <p align="center">
   <strong>A comprehensive toolkit for MALDI-TOF mass spectrometry data preprocessing for antimicrobial resistance (AMR) prediction purposes</strong>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiAMRKit/main/docs/preprocessing_pipeline.svg" alt="Animated MaldiAMRKit pipeline: a raw MALDI-TOF spectrum is smoothed, baseline-corrected, peak-detected and binned into a feature vector that predicts antimicrobial resistance (R/S)" width="720"/>
+</p>
+
 <p align="center">
   <a href="#installation">Installation</a> •
   <a href="#features">Features</a> •
@@ -105,13 +113,13 @@ pip install maldisuite
 
 Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSuite/>.
 
-### Optional: Batch Correction & UMAP
+### Optional: UMAP & combatlearn
 
 ```bash
 pip install maldiamrkit[batch]
 ```
 
-Installs [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) for ComBat-based batch effect correction and `umap-learn` for UMAP exploratory plots.
+MaldiAMRKit has no batch corrector of its own. This extra adds `umap-learn` for UMAP exploratory plots, and [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) to use ComBat directly on a feature matrix. For batch correction built for MALDI-TOF spectra, see [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit).
 
 ### Optional: extended mzML/mzXML support
 
@@ -121,7 +129,7 @@ pip install maldiamrkit[formats]
 
 `.mzML` and `.mzXML` files are read out of the box (zlib-compressed or uncompressed arrays). This extra installs [`pyteomics`](https://pyteomics.readthedocs.io/) with `lxml`, `psims`, and `pynumpress`, which additionally handle numpress-compressed arrays. `pynumpress` ships no wheels for Python 3.10, so numpress arrays need Python 3.11 or newer.
 
-### Development Installation
+### Development installation
 
 ```bash
 git clone https://github.com/EttoreRocchi/MaldiAMRKit.git
@@ -132,18 +140,18 @@ pip install -e .[dev]
 ## Features
 
 ### Preprocessing
-- **Composable Pipeline**: Build custom `PreprocessingPipeline` from individual transformers (smoothing, baseline correction, normalization, trimming), serializable to JSON/YAML
+- **Composable Pipeline**: Build custom `PreprocessingPipeline` from individual transformers (smoothing, baseline correction, normalisation, trimming), serialisable to JSON/YAML
 - **Smoothing**: Savitzky-Golay and moving-average filters
 - **Baseline Correction**: SNIP, morphological top-hat, lower-convex-hull, and iterative rolling-median baselines
 - **Multiple Binning Strategies**: Uniform, proportional, adaptive, and custom bin edges
 - **Quality Metrics**: SNR estimation, MAD-based noise estimation, comprehensive quality reports, and alignment assessment
 - **Replicate Merging**: Mean/median/weighted merging with correlation-based outlier detection
 
-### Alignment & Detection
-- **Spectral Alignment**: Shift, linear, piecewise, DTW, quadratic, cubic, and LOWESS warping for both binned and raw full-resolution spectra. Spectra are first shifted and then aligned to the reference of the shifted spectra, a non-rigid warp is kept only when the matched peaks support it, and resampling preserves the total intensity; spectra of several species are best aligned one species at a time
+### Alignment & detection
+- **Spectral Alignment**: Shift, linear, piecewise, DTW, quadratic, cubic, and LOWESS warping for both binned and raw full-resolution spectra. Spectra are first shifted and then aligned to the reference of the shifted spectra, a non-rigid warp is kept only when the matched peaks support it, and resampling preserves the total intensity (neither applies to DTW); spectra of several species are best aligned one species at a time
 - **Peak Detection**: Local maxima and persistent homology methods
 - **Peak Sets**: `PeakSet` / `PeakList` represent each spectrum as a variable-length `(m/z, intensity)` set for peak-set models, via `MaldiPeakDetector.transform_peaklist()` on binned spectra or `create_peakset_input()` at full m/z resolution; extraction is stateless per spectrum, so results are cacheable without leakage
-- **Fit-Free Peak Alignment**: `align_peaks()` warps a peak set onto caller-supplied reference peaks, so the reference stays fitted on the training split
+- **Fit-Free Peak Alignment**: `align_peaks()` warps a peak set onto caller-supplied reference peaks, which the caller estimates on the training split (for example `RawWarping(...).fit(X_train).ref_peaks_mz_`; a reference built with test spectra leaks)
 
 ### Extensibility
 - **Component Registries**: Plug your own components into the name-dispatched machinery - `register_spectral_metric()` for distance metrics (usable in `spectral_distance`, `pairwise_distances`, and `DriftMonitor`), `register_transformer()` to make `PreprocessingPipeline` configs holding custom transformers round-trip through JSON/YAML, and `register_binning_method()` for custom bin edges
@@ -157,19 +165,23 @@ pip install -e .[dev]
 
 ### Susceptibility (MIC encoding & breakpoints)
 - **`MICEncoder`**: Convert raw MIC strings into `log2(MIC)` regression targets plus S/I/R categories and ATU flags in a single pass
-- **`BreakpointTable`**: Clinical breakpoint tables (EUCAST v1.0-v16.0 bundled) loaded by version, year, latest, or custom YAML
+- **`BreakpointTable`**: Clinical breakpoint tables (19 EUCAST versions between v1.0 and v16.0 bundled) loaded by version, year, latest, or custom YAML
 - **`LabelEncoder`**: Map R/I/S to binary with configurable intermediate handling (moved from `maldiamrkit.evaluation` in v0.15)
 
-### Differential Analysis
+### Differential analysis
 - **`DifferentialAnalysis`**: Per-bin statistical testing (Mann-Whitney U, Welch's t-test) between resistant and susceptible groups, with multiple-testing correction, log2 fold change, and Cohen's d effect size
-- **Peak Selection**: `top_peaks()` by adjusted p-value, `significant_peaks()` with fold-change and p-value thresholds, `compare_drugs()` for multi-drug boolean significance matrices
+- **Peak Ranking**: `top_peaks()` by adjusted p-value, `significant_peaks()` with fold-change and p-value thresholds, `compare_drugs()` for multi-drug boolean significance matrices (to select features for a classifier, rank peaks inside each training fold)
 - **AMR-Aware Plots**: `plot_volcano()`, `plot_manhattan()` along the m/z axis, and `plot_drug_comparison()` with binary heatmap or UpSet-style intersection view
 
-### Drift Monitoring
+### Drift monitoring
 - **`DriftMonitor`**: Anchor a baseline on early timestamps (default: first 20%) and track temporal drift via three complementary views - reference similarity of per-window median spectra, PCA centroid trajectory in a baseline-fitted PCA space, and Jaccard stability of top-k differential peaks over time
 - **Trajectory Plots**: `plot_reference_drift`, `plot_pca_drift`, `plot_peak_stability`, `plot_effect_size_drift`
 
-### Data Management
+### Spectral similarity
+- **Distances & Clustering**: `spectral_distance` and `pairwise_distances` with built-in or registered metrics, `cluster_spectra` with hierarchical, HDBSCAN, and k-medoids methods, silhouette scores, and metadata concordance
+- **Plots**: `plot_distance_heatmap` and `plot_dendrogram`
+
+### Data management
 - **Dataset Building & Loading**: `DatasetBuilder` and `DatasetLoader` with pluggable layout adapters (`FlatLayout`, `BrukerTreeLayout`, `DRIAMSLayout`, `MARISMaLayout`)
 - **Replicate Collapsing**: `DRIAMSLayout(collapse_replicates=True)` merges technical replicates (`_MALDI<N>`) to one row per isolate at load time via the active `duplicate_strategy`
 - **Bruker Format Support**: Read Bruker flexAnalysis binary data (fid/1r + acqus) natively via `read_spectrum()` on directories
@@ -178,9 +190,9 @@ pip install -e .[dev]
 - **Composable Filters**: `SpeciesFilter`, `DrugFilter`, `QualityFilter`, `MetadataFilter` combinable with `&`/`|`/`~` operators
 - **Spectrum Export**: Save spectra to CSV, TXT, or mzML via `MaldiSpectrum.save()` and `MaldiSet.save_spectra()`
 
-### Visualization & Tools
-- **Exploratory Plots**: PCA, t-SNE, and UMAP scatter plots colored by species, resistance phenotype, or any metadata column
-- **Batch Effect Correction**: Multi-site/multi-instrument correction via [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) (`pip install maldiamrkit[batch]`)
+### Visualisation & tools
+- **Exploratory Plots**: PCA, t-SNE, and UMAP scatter plots coloured by species, resistance phenotype, or any metadata column
+- **Batch Effect Correction**: Not part of this package. Use [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) directly (`pip install maldiamrkit[batch]`) or [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit)
 - **CLI**: `maldiamrkit preprocess`, `maldiamrkit quality`, and `maldiamrkit build` for batch processing
 - **Parallel Processing**: Multi-core support via `n_jobs` parameter
 - **ML-Ready**: Direct integration with scikit-learn pipelines
@@ -189,9 +201,9 @@ pip install -e .[dev]
 
 Full documentation is available at [maldiamrkit.readthedocs.io](https://maldiamrkit.readthedocs.io/).
 
-## Quick Start
+## Quick start
 
-### Load and Preprocess a Single Spectrum
+### Load and preprocess a single spectrum
 
 ```python
 from maldiamrkit import MaldiSpectrum
@@ -210,7 +222,7 @@ from maldiamrkit.visualization import plot_spectrum
 plot_spectrum(spec, stage="binned")
 ```
 
-### Build a Dataset from Multiple Spectra
+### Build a dataset from multiple spectra
 
 ```python
 from maldiamrkit import MaldiSet
@@ -228,7 +240,7 @@ X = data.X  # Feature matrix
 y = data.get_y_single("Drug")  # Target labels
 ```
 
-### Machine Learning Pipeline
+### Machine learning pipeline
 
 ```python
 from sklearn.pipeline import Pipeline
@@ -240,13 +252,13 @@ from maldiamrkit.detection import MaldiPeakDetector
 
 # Create ML pipeline
 pipe = Pipeline([
-    ("peaks", MaldiPeakDetector(binary=False, prominence=0.05)),
+    ("peaks", MaldiPeakDetector(binary=False, prominence=1e-4)),
     ("warp", Warping(method="shift")),
     ("scaler", StandardScaler()),
     ("clf", RandomForestClassifier(n_estimators=100, random_state=42))
 ])
 
-# Cross-validation
+# Cross-validation (with replicates, use StratifiedGroupKFold and groups=data.groups)
 scores = cross_val_score(pipe, X, y, cv=5, scoring="accuracy")
 print(f"CV Accuracy: {scores.mean():.3f} +/- {scores.std():.3f}")
 ```
@@ -259,32 +271,32 @@ For more examples covering alignment, filtering, evaluation, CLI usage, and more
 
 For more detailed examples, see the notebooks:
 
-- [Quick Start](notebooks/01_quick_start.ipynb) - Loading, preprocessing, binning, and quality assessment
-- [Peak Detection](notebooks/02_peak_detection.ipynb) - Local maxima and persistent homology methods
-- [Alignment](notebooks/03_alignment.ipynb) - Warping methods and alignment quality
-- [Evaluation](notebooks/04_evaluation.ipynb) - AMR metrics, label encoding, and stratified splitting
-- [Exploration](notebooks/05_exploration.ipynb) - PCA, t-SNE, UMAP visualizations and batch correction
-- [Differential Analysis](notebooks/06_differential_analysis.ipynb) - R vs. S peak testing, volcano/Manhattan plots, and multi-drug comparison
-- [Drift Monitoring](notebooks/07_drift_monitoring.ipynb) - Baseline-anchored drift detection: reference similarity, PCA trajectory, peak stability, and effect-size drift
-- [Susceptibility](notebooks/08_susceptibility.ipynb) - `MICEncoder` + `BreakpointTable` for log2(MIC) regression targets, S/I/R categorisation with ATU, and `mic_regression_report` evaluation
-- [Peak Sets](notebooks/09_peak_sets.ipynb) - `PeakSet` / `PeakList` extraction, ranking and padding, caching, and fit-free peak alignment
-- [Custom Components](notebooks/10_custom_components.ipynb) - registering a custom distance metric and a custom transformer end-to-end
+- [Quick Start](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/01_quick_start.ipynb) - Loading, preprocessing, binning, and quality assessment
+- [Peak Detection](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/02_peak_detection.ipynb) - Local maxima and persistent homology methods
+- [Alignment](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/03_alignment.ipynb) - Warping methods and alignment quality
+- [Evaluation](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/04_evaluation.ipynb) - AMR metrics, label encoding, and stratified splitting
+- [Exploration](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/05_exploration.ipynb) - PCA, t-SNE, and UMAP visualisations, spectral similarity, and clustering
+- [Differential Analysis](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/06_differential_analysis.ipynb) - R vs. S peak testing, volcano/Manhattan plots, and multi-drug comparison
+- [Drift Monitoring](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/07_drift_monitoring.ipynb) - Baseline-anchored drift detection: reference similarity, PCA trajectory, peak stability, and effect-size drift
+- [Susceptibility](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/08_susceptibility.ipynb) - `MICEncoder` + `BreakpointTable` for log2(MIC) regression targets, S/I/R categorisation with ATU, and `mic_regression_report` evaluation
+- [Peak Sets](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/09_peak_sets.ipynb) - `PeakSet` / `PeakList` extraction, ranking and padding, caching, and fit-free peak alignment
+- [Custom Components](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/10_custom_components.ipynb) - registering a custom distance metric and a custom transformer end-to-end
 
-Notebooks `01`-`03` and `08`-`10` run on the small example dataset bundled under [`data/`](data/) or are fully self-contained. Notebooks `04`-`07` need more samples and pull the real **MALDI-Kleb-AI** archive (Rocchi *et al.*, 2026; [Zenodo DOI 10.5281/zenodo.17405072](https://zenodo.org/records/17405072)) via the [`demo`](notebooks/_demo.py) helper. By default the helper restricts the dataset to the **Rome sub-cohort** (~470 spectra, single acquisition centre, no batch correction required); the 370 MB tarball is cached under `~/.cache/maldiamrkit/` on first use.
+Notebooks `01`-`03` and `08`-`10` run on the small example dataset bundled under [`data/`](https://github.com/EttoreRocchi/MaldiAMRKit/tree/main/data) or are fully self-contained. Notebooks `04`-`07` need more samples and pull the real **MALDI-Kleb-AI** archive (Rocchi *et al.*, 2026; [Zenodo DOI 10.5281/zenodo.17405072](https://zenodo.org/records/17405072)) via the [`demo`](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/_demo.py) helper. By default the helper restricts the dataset to the **Rome sub-cohort** (~470 spectra, single acquisition centre, no batch correction required); the 370 MB tarball is cached under `~/.cache/maldiamrkit/` on first use.
 
-## MaldiSuite Ecosystem
+## MaldiSuite ecosystem
 
-MaldiAMRKit is the data-model and preprocessing package of the **MaldiSuite** ecosystem:
+MaldiAMRKit is one of the three packages of the **MaldiSuite** ecosystem:
 
 - **MaldiAMRKit** (this package) - data model (`MaldiSpectrum`, `MaldiSet`), preprocessing, alignment, peak detection, differential analysis, and AMR-aware evaluation.
 - **[MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit)** - 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/>).
 
 ## Contributing
 
-Pull requests, bug reports, and feature ideas are welcome. See the [Contributing Guide](CONTRIBUTING.md) for how to get started.
+Pull requests, bug reports, and feature ideas are welcome. See the [Contributing Guide](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/CONTRIBUTING.md) for how to get started.
 
 ## Citing
 
@@ -296,7 +308,7 @@ See the [full publications list](https://maldiamrkit.readthedocs.io/en/latest/pa
 
 ## License
 
-This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the **MIT License**. See the [LICENSE](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/LICENSE) file for details.
 
 ## Acknowledgements
 

{maldiamrkit-0.22.0 → maldiamrkit-0.22.2}/MaldiAMRKit.egg-info/SOURCES.txt

@@ -21,11 +21,14 @@ maldiamrkit/filters.py
 maldiamrkit/py.typed
 maldiamrkit/spectrum.py
 maldiamrkit/alignment/__init__.py
+maldiamrkit/alignment/_dtw.py
+maldiamrkit/alignment/_versioning.py
 maldiamrkit/alignment/peak_align.py
 maldiamrkit/alignment/raw_warping.py
 maldiamrkit/alignment/strategies.py
 maldiamrkit/alignment/warping.py
 maldiamrkit/data/__init__.py
+maldiamrkit/data/_metadata.py
 maldiamrkit/data/builder.py
 maldiamrkit/data/dataset_layouts.py
 maldiamrkit/data/duplicates.py

{maldiamrkit-0.22.0 → maldiamrkit-0.22.2}/MaldiAMRKit.egg-info/requires.txt

@@ -7,6 +7,7 @@ seaborn>=0.11.0
 pybaselines>=1.0.0
 gudhi>=3.5.0
 tslearn>=0.6.0
+numba>=0.55
 pyyaml>=6.0
 pyarrow>=14.0.0
 typer>=0.9.0

{maldiamrkit-0.22.0/MaldiAMRKit.egg-info → maldiamrkit-0.22.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.22.0
+Version: 0.22.2
 Summary: A comprehensive toolkit for MALDI-TOF mass spectrometry data preprocessing for antimicrobial resistance (AMR) prediction purposes
 Author-email: Ettore Rocchi <ettore.rocchi3@unibo.it>
 License-Expression: MIT
@@ -31,6 +31,7 @@ Requires-Dist: seaborn>=0.11.0
 Requires-Dist: pybaselines>=1.0.0
 Requires-Dist: gudhi>=3.5.0
 Requires-Dist: tslearn>=0.6.0
+Requires-Dist: numba>=0.55
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pyarrow>=14.0.0
 Requires-Dist: typer>=0.9.0
@@ -70,13 +71,20 @@ Dynamic: license-file
 [![License](https://img.shields.io/github/license/EttoreRocchi/MaldiAMRKit)](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/LICENSE)
 
 <p align="center">
-  <img src="docs/maldiamrkit.png" alt="MaldiAMRKit" width="320"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EttoreRocchi/MaldiAMRKit/main/docs/maldiamrkit_dark.png">
+    <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiAMRKit/main/docs/maldiamrkit.png" alt="MaldiAMRKit" width="320"/>
+  </picture>
 </p>
 
 <p align="center">
   <strong>A comprehensive toolkit for MALDI-TOF mass spectrometry data preprocessing for antimicrobial resistance (AMR) prediction purposes</strong>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EttoreRocchi/MaldiAMRKit/main/docs/preprocessing_pipeline.svg" alt="Animated MaldiAMRKit pipeline: a raw MALDI-TOF spectrum is smoothed, baseline-corrected, peak-detected and binned into a feature vector that predicts antimicrobial resistance (R/S)" width="720"/>
+</p>
+
 <p align="center">
   <a href="#installation">Installation</a> •
   <a href="#features">Features</a> •
@@ -105,13 +113,13 @@ pip install maldisuite
 
 Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSuite/>.
 
-### Optional: Batch Correction & UMAP
+### Optional: UMAP & combatlearn
 
 ```bash
 pip install maldiamrkit[batch]
 ```
 
-Installs [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) for ComBat-based batch effect correction and `umap-learn` for UMAP exploratory plots.
+MaldiAMRKit has no batch corrector of its own. This extra adds `umap-learn` for UMAP exploratory plots, and [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) to use ComBat directly on a feature matrix. For batch correction built for MALDI-TOF spectra, see [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit).
 
 ### Optional: extended mzML/mzXML support
 
@@ -121,7 +129,7 @@ pip install maldiamrkit[formats]
 
 `.mzML` and `.mzXML` files are read out of the box (zlib-compressed or uncompressed arrays). This extra installs [`pyteomics`](https://pyteomics.readthedocs.io/) with `lxml`, `psims`, and `pynumpress`, which additionally handle numpress-compressed arrays. `pynumpress` ships no wheels for Python 3.10, so numpress arrays need Python 3.11 or newer.
 
-### Development Installation
+### Development installation
 
 ```bash
 git clone https://github.com/EttoreRocchi/MaldiAMRKit.git
@@ -132,18 +140,18 @@ pip install -e .[dev]
 ## Features
 
 ### Preprocessing
-- **Composable Pipeline**: Build custom `PreprocessingPipeline` from individual transformers (smoothing, baseline correction, normalization, trimming), serializable to JSON/YAML
+- **Composable Pipeline**: Build custom `PreprocessingPipeline` from individual transformers (smoothing, baseline correction, normalisation, trimming), serialisable to JSON/YAML
 - **Smoothing**: Savitzky-Golay and moving-average filters
 - **Baseline Correction**: SNIP, morphological top-hat, lower-convex-hull, and iterative rolling-median baselines
 - **Multiple Binning Strategies**: Uniform, proportional, adaptive, and custom bin edges
 - **Quality Metrics**: SNR estimation, MAD-based noise estimation, comprehensive quality reports, and alignment assessment
 - **Replicate Merging**: Mean/median/weighted merging with correlation-based outlier detection
 
-### Alignment & Detection
-- **Spectral Alignment**: Shift, linear, piecewise, DTW, quadratic, cubic, and LOWESS warping for both binned and raw full-resolution spectra. Spectra are first shifted and then aligned to the reference of the shifted spectra, a non-rigid warp is kept only when the matched peaks support it, and resampling preserves the total intensity; spectra of several species are best aligned one species at a time
+### Alignment & detection
+- **Spectral Alignment**: Shift, linear, piecewise, DTW, quadratic, cubic, and LOWESS warping for both binned and raw full-resolution spectra. Spectra are first shifted and then aligned to the reference of the shifted spectra, a non-rigid warp is kept only when the matched peaks support it, and resampling preserves the total intensity (neither applies to DTW); spectra of several species are best aligned one species at a time
 - **Peak Detection**: Local maxima and persistent homology methods
 - **Peak Sets**: `PeakSet` / `PeakList` represent each spectrum as a variable-length `(m/z, intensity)` set for peak-set models, via `MaldiPeakDetector.transform_peaklist()` on binned spectra or `create_peakset_input()` at full m/z resolution; extraction is stateless per spectrum, so results are cacheable without leakage
-- **Fit-Free Peak Alignment**: `align_peaks()` warps a peak set onto caller-supplied reference peaks, so the reference stays fitted on the training split
+- **Fit-Free Peak Alignment**: `align_peaks()` warps a peak set onto caller-supplied reference peaks, which the caller estimates on the training split (for example `RawWarping(...).fit(X_train).ref_peaks_mz_`; a reference built with test spectra leaks)
 
 ### Extensibility
 - **Component Registries**: Plug your own components into the name-dispatched machinery - `register_spectral_metric()` for distance metrics (usable in `spectral_distance`, `pairwise_distances`, and `DriftMonitor`), `register_transformer()` to make `PreprocessingPipeline` configs holding custom transformers round-trip through JSON/YAML, and `register_binning_method()` for custom bin edges
@@ -157,19 +165,23 @@ pip install -e .[dev]
 
 ### Susceptibility (MIC encoding & breakpoints)
 - **`MICEncoder`**: Convert raw MIC strings into `log2(MIC)` regression targets plus S/I/R categories and ATU flags in a single pass
-- **`BreakpointTable`**: Clinical breakpoint tables (EUCAST v1.0-v16.0 bundled) loaded by version, year, latest, or custom YAML
+- **`BreakpointTable`**: Clinical breakpoint tables (19 EUCAST versions between v1.0 and v16.0 bundled) loaded by version, year, latest, or custom YAML
 - **`LabelEncoder`**: Map R/I/S to binary with configurable intermediate handling (moved from `maldiamrkit.evaluation` in v0.15)
 
-### Differential Analysis
+### Differential analysis
 - **`DifferentialAnalysis`**: Per-bin statistical testing (Mann-Whitney U, Welch's t-test) between resistant and susceptible groups, with multiple-testing correction, log2 fold change, and Cohen's d effect size
-- **Peak Selection**: `top_peaks()` by adjusted p-value, `significant_peaks()` with fold-change and p-value thresholds, `compare_drugs()` for multi-drug boolean significance matrices
+- **Peak Ranking**: `top_peaks()` by adjusted p-value, `significant_peaks()` with fold-change and p-value thresholds, `compare_drugs()` for multi-drug boolean significance matrices (to select features for a classifier, rank peaks inside each training fold)
 - **AMR-Aware Plots**: `plot_volcano()`, `plot_manhattan()` along the m/z axis, and `plot_drug_comparison()` with binary heatmap or UpSet-style intersection view
 
-### Drift Monitoring
+### Drift monitoring
 - **`DriftMonitor`**: Anchor a baseline on early timestamps (default: first 20%) and track temporal drift via three complementary views - reference similarity of per-window median spectra, PCA centroid trajectory in a baseline-fitted PCA space, and Jaccard stability of top-k differential peaks over time
 - **Trajectory Plots**: `plot_reference_drift`, `plot_pca_drift`, `plot_peak_stability`, `plot_effect_size_drift`
 
-### Data Management
+### Spectral similarity
+- **Distances & Clustering**: `spectral_distance` and `pairwise_distances` with built-in or registered metrics, `cluster_spectra` with hierarchical, HDBSCAN, and k-medoids methods, silhouette scores, and metadata concordance
+- **Plots**: `plot_distance_heatmap` and `plot_dendrogram`
+
+### Data management
 - **Dataset Building & Loading**: `DatasetBuilder` and `DatasetLoader` with pluggable layout adapters (`FlatLayout`, `BrukerTreeLayout`, `DRIAMSLayout`, `MARISMaLayout`)
 - **Replicate Collapsing**: `DRIAMSLayout(collapse_replicates=True)` merges technical replicates (`_MALDI<N>`) to one row per isolate at load time via the active `duplicate_strategy`
 - **Bruker Format Support**: Read Bruker flexAnalysis binary data (fid/1r + acqus) natively via `read_spectrum()` on directories
@@ -178,9 +190,9 @@ pip install -e .[dev]
 - **Composable Filters**: `SpeciesFilter`, `DrugFilter`, `QualityFilter`, `MetadataFilter` combinable with `&`/`|`/`~` operators
 - **Spectrum Export**: Save spectra to CSV, TXT, or mzML via `MaldiSpectrum.save()` and `MaldiSet.save_spectra()`
 
-### Visualization & Tools
-- **Exploratory Plots**: PCA, t-SNE, and UMAP scatter plots colored by species, resistance phenotype, or any metadata column
-- **Batch Effect Correction**: Multi-site/multi-instrument correction via [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) (`pip install maldiamrkit[batch]`)
+### Visualisation & tools
+- **Exploratory Plots**: PCA, t-SNE, and UMAP scatter plots coloured by species, resistance phenotype, or any metadata column
+- **Batch Effect Correction**: Not part of this package. Use [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) directly (`pip install maldiamrkit[batch]`) or [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit)
 - **CLI**: `maldiamrkit preprocess`, `maldiamrkit quality`, and `maldiamrkit build` for batch processing
 - **Parallel Processing**: Multi-core support via `n_jobs` parameter
 - **ML-Ready**: Direct integration with scikit-learn pipelines
@@ -189,9 +201,9 @@ pip install -e .[dev]
 
 Full documentation is available at [maldiamrkit.readthedocs.io](https://maldiamrkit.readthedocs.io/).
 
-## Quick Start
+## Quick start
 
-### Load and Preprocess a Single Spectrum
+### Load and preprocess a single spectrum
 
 ```python
 from maldiamrkit import MaldiSpectrum
@@ -210,7 +222,7 @@ from maldiamrkit.visualization import plot_spectrum
 plot_spectrum(spec, stage="binned")
 ```
 
-### Build a Dataset from Multiple Spectra
+### Build a dataset from multiple spectra
 
 ```python
 from maldiamrkit import MaldiSet
@@ -228,7 +240,7 @@ X = data.X  # Feature matrix
 y = data.get_y_single("Drug")  # Target labels
 ```
 
-### Machine Learning Pipeline
+### Machine learning pipeline
 
 ```python
 from sklearn.pipeline import Pipeline
@@ -240,13 +252,13 @@ from maldiamrkit.detection import MaldiPeakDetector
 
 # Create ML pipeline
 pipe = Pipeline([
-    ("peaks", MaldiPeakDetector(binary=False, prominence=0.05)),
+    ("peaks", MaldiPeakDetector(binary=False, prominence=1e-4)),
     ("warp", Warping(method="shift")),
     ("scaler", StandardScaler()),
     ("clf", RandomForestClassifier(n_estimators=100, random_state=42))
 ])
 
-# Cross-validation
+# Cross-validation (with replicates, use StratifiedGroupKFold and groups=data.groups)
 scores = cross_val_score(pipe, X, y, cv=5, scoring="accuracy")
 print(f"CV Accuracy: {scores.mean():.3f} +/- {scores.std():.3f}")
 ```
@@ -259,32 +271,32 @@ For more examples covering alignment, filtering, evaluation, CLI usage, and more
 
 For more detailed examples, see the notebooks:
 
-- [Quick Start](notebooks/01_quick_start.ipynb) - Loading, preprocessing, binning, and quality assessment
-- [Peak Detection](notebooks/02_peak_detection.ipynb) - Local maxima and persistent homology methods
-- [Alignment](notebooks/03_alignment.ipynb) - Warping methods and alignment quality
-- [Evaluation](notebooks/04_evaluation.ipynb) - AMR metrics, label encoding, and stratified splitting
-- [Exploration](notebooks/05_exploration.ipynb) - PCA, t-SNE, UMAP visualizations and batch correction
-- [Differential Analysis](notebooks/06_differential_analysis.ipynb) - R vs. S peak testing, volcano/Manhattan plots, and multi-drug comparison
-- [Drift Monitoring](notebooks/07_drift_monitoring.ipynb) - Baseline-anchored drift detection: reference similarity, PCA trajectory, peak stability, and effect-size drift
-- [Susceptibility](notebooks/08_susceptibility.ipynb) - `MICEncoder` + `BreakpointTable` for log2(MIC) regression targets, S/I/R categorisation with ATU, and `mic_regression_report` evaluation
-- [Peak Sets](notebooks/09_peak_sets.ipynb) - `PeakSet` / `PeakList` extraction, ranking and padding, caching, and fit-free peak alignment
-- [Custom Components](notebooks/10_custom_components.ipynb) - registering a custom distance metric and a custom transformer end-to-end
+- [Quick Start](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/01_quick_start.ipynb) - Loading, preprocessing, binning, and quality assessment
+- [Peak Detection](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/02_peak_detection.ipynb) - Local maxima and persistent homology methods
+- [Alignment](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/03_alignment.ipynb) - Warping methods and alignment quality
+- [Evaluation](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/04_evaluation.ipynb) - AMR metrics, label encoding, and stratified splitting
+- [Exploration](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/05_exploration.ipynb) - PCA, t-SNE, and UMAP visualisations, spectral similarity, and clustering
+- [Differential Analysis](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/06_differential_analysis.ipynb) - R vs. S peak testing, volcano/Manhattan plots, and multi-drug comparison
+- [Drift Monitoring](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/07_drift_monitoring.ipynb) - Baseline-anchored drift detection: reference similarity, PCA trajectory, peak stability, and effect-size drift
+- [Susceptibility](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/08_susceptibility.ipynb) - `MICEncoder` + `BreakpointTable` for log2(MIC) regression targets, S/I/R categorisation with ATU, and `mic_regression_report` evaluation
+- [Peak Sets](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/09_peak_sets.ipynb) - `PeakSet` / `PeakList` extraction, ranking and padding, caching, and fit-free peak alignment
+- [Custom Components](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/10_custom_components.ipynb) - registering a custom distance metric and a custom transformer end-to-end
 
-Notebooks `01`-`03` and `08`-`10` run on the small example dataset bundled under [`data/`](data/) or are fully self-contained. Notebooks `04`-`07` need more samples and pull the real **MALDI-Kleb-AI** archive (Rocchi *et al.*, 2026; [Zenodo DOI 10.5281/zenodo.17405072](https://zenodo.org/records/17405072)) via the [`demo`](notebooks/_demo.py) helper. By default the helper restricts the dataset to the **Rome sub-cohort** (~470 spectra, single acquisition centre, no batch correction required); the 370 MB tarball is cached under `~/.cache/maldiamrkit/` on first use.
+Notebooks `01`-`03` and `08`-`10` run on the small example dataset bundled under [`data/`](https://github.com/EttoreRocchi/MaldiAMRKit/tree/main/data) or are fully self-contained. Notebooks `04`-`07` need more samples and pull the real **MALDI-Kleb-AI** archive (Rocchi *et al.*, 2026; [Zenodo DOI 10.5281/zenodo.17405072](https://zenodo.org/records/17405072)) via the [`demo`](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/notebooks/_demo.py) helper. By default the helper restricts the dataset to the **Rome sub-cohort** (~470 spectra, single acquisition centre, no batch correction required); the 370 MB tarball is cached under `~/.cache/maldiamrkit/` on first use.
 
-## MaldiSuite Ecosystem
+## MaldiSuite ecosystem
 
-MaldiAMRKit is the data-model and preprocessing package of the **MaldiSuite** ecosystem:
+MaldiAMRKit is one of the three packages of the **MaldiSuite** ecosystem:
 
 - **MaldiAMRKit** (this package) - data model (`MaldiSpectrum`, `MaldiSet`), preprocessing, alignment, peak detection, differential analysis, and AMR-aware evaluation.
 - **[MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit)** - 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/>).
 
 ## Contributing
 
-Pull requests, bug reports, and feature ideas are welcome. See the [Contributing Guide](CONTRIBUTING.md) for how to get started.
+Pull requests, bug reports, and feature ideas are welcome. See the [Contributing Guide](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/CONTRIBUTING.md) for how to get started.
 
 ## Citing
 
@@ -296,7 +308,7 @@ See the [full publications list](https://maldiamrkit.readthedocs.io/en/latest/pa
 
 ## License
 
-This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the **MIT License**. See the [LICENSE](https://github.com/EttoreRocchi/MaldiAMRKit/blob/main/LICENSE) file for details.
 
 ## Acknowledgements