MaldiAMRKit 0.18.0__tar.gz → 0.20.0__tar.gz

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0/MaldiAMRKit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.18.0
+Version: 0.20.0
 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
@@ -39,7 +39,6 @@ Requires-Dist: tqdm>=4.60.0
 Provides-Extra: docs
 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: sphinxcontrib-typer>=0.5.0; extra == "docs"
 Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
@@ -53,6 +52,11 @@ Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Provides-Extra: batch
 Requires-Dist: umap-learn>=0.5; extra == "batch"
 Requires-Dist: combatlearn>=1.3; extra == "batch"
+Provides-Extra: formats
+Requires-Dist: pyteomics>=4.0; extra == "formats"
+Requires-Dist: lxml>=4.0; extra == "formats"
+Requires-Dist: psims>=1.0; extra == "formats"
+Requires-Dist: pynumpress>=0.1.5; python_version >= "3.11" and extra == "formats"
 Dynamic: license-file
 
 # MaldiAMRKit
@@ -109,6 +113,14 @@ pip install maldiamrkit[batch]
 
 Installs [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) for ComBat-based batch effect correction and `umap-learn` for UMAP exploratory plots.
 
+### Optional: extended mzML/mzXML support
+
+```bash
+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
 
 ```bash
@@ -130,6 +142,12 @@ pip install -e .[dev]
 ### Alignment & Detection
 - **Spectral Alignment**: Shift, linear, piecewise, DTW, quadratic, cubic, and LOWESS warping for both binned and raw full-resolution spectra
 - **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
+
+### 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
+- **Discovery & Safety**: `list_spectral_metrics()`, `list_transformers()`, `list_binning_methods()` report what is registered; built-ins are replaced only with an explicit `override=True`, and unregistering an overridden built-in restores the default
 
 ### Evaluation
 - **AMR Metrics**: VME, ME, sensitivity, specificity, categorical agreement, and `amr_classification_report` following EUCAST conventions
@@ -155,9 +173,10 @@ pip install -e .[dev]
 - **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
+- **Open Formats**: Read `.mzML` and `.mzXML` files (optionally gzipped) via `read_spectrum()`, `MaldiSpectrum`, and `FlatLayout(spectrum_ext=".mzML")`; `pip install maldiamrkit[formats]` adds `pyteomics` for numpress-compressed arrays
 - **MIC Parsing**: `parse_mic_column()` for parsing MIC strings with qualifiers and European decimals
 - **Composable Filters**: `SpeciesFilter`, `DrugFilter`, `QualityFilter`, `MetadataFilter` combinable with `&`/`|`/`~` operators
-- **Spectrum Export**: Save spectra to CSV or TXT via `MaldiSpectrum.save()` and `MaldiSet.save_spectra()`
+- **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
@@ -248,8 +267,10 @@ For more detailed examples, see the notebooks:
 - [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
 
-Notebooks `01`-`03` and `08` 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/`](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.
 
 ## MaldiSuite Ecosystem
 

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/MaldiAMRKit.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 requirements-batch.txt
 requirements-dev.txt
 requirements-docs.txt
+requirements-formats.txt
 requirements.txt
 MaldiAMRKit.egg-info/PKG-INFO
 MaldiAMRKit.egg-info/SOURCES.txt
@@ -13,6 +14,7 @@ MaldiAMRKit.egg-info/requires.txt
 MaldiAMRKit.egg-info/top_level.txt
 maldiamrkit/__init__.py
 maldiamrkit/_compat.py
+maldiamrkit/_registry.py
 maldiamrkit/cli.py
 maldiamrkit/dataset.py
 maldiamrkit/filters.py
@@ -71,6 +73,7 @@ maldiamrkit/evaluation/splitting.py
 maldiamrkit/io/__init__.py
 maldiamrkit/io/mic.py
 maldiamrkit/io/readers.py
+maldiamrkit/io/writers.py
 maldiamrkit/preprocessing/__init__.py
 maldiamrkit/preprocessing/binning.py
 maldiamrkit/preprocessing/merging.py

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/MaldiAMRKit.egg-info/requires.txt

@@ -27,8 +27,15 @@ hypothesis>=6.0.0
 [docs]
 sphinx>=7.0.0
 pydata-sphinx-theme>=0.15.0
-sphinx-autodoc-typehints>=2.0.0
 sphinx-design>=0.6.0
 sphinxcontrib-typer>=0.5.0
 nbsphinx>=0.9.0
 ipykernel>=6.0.0
+
+[formats]
+pyteomics>=4.0
+lxml>=4.0
+psims>=1.0
+
+[formats:python_version >= "3.11"]
+pynumpress>=0.1.5

{maldiamrkit-0.18.0/MaldiAMRKit.egg-info → maldiamrkit-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.18.0
+Version: 0.20.0
 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
@@ -39,7 +39,6 @@ Requires-Dist: tqdm>=4.60.0
 Provides-Extra: docs
 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: sphinxcontrib-typer>=0.5.0; extra == "docs"
 Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
@@ -53,6 +52,11 @@ Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Provides-Extra: batch
 Requires-Dist: umap-learn>=0.5; extra == "batch"
 Requires-Dist: combatlearn>=1.3; extra == "batch"
+Provides-Extra: formats
+Requires-Dist: pyteomics>=4.0; extra == "formats"
+Requires-Dist: lxml>=4.0; extra == "formats"
+Requires-Dist: psims>=1.0; extra == "formats"
+Requires-Dist: pynumpress>=0.1.5; python_version >= "3.11" and extra == "formats"
 Dynamic: license-file
 
 # MaldiAMRKit
@@ -109,6 +113,14 @@ pip install maldiamrkit[batch]
 
 Installs [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) for ComBat-based batch effect correction and `umap-learn` for UMAP exploratory plots.
 
+### Optional: extended mzML/mzXML support
+
+```bash
+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
 
 ```bash
@@ -130,6 +142,12 @@ pip install -e .[dev]
 ### Alignment & Detection
 - **Spectral Alignment**: Shift, linear, piecewise, DTW, quadratic, cubic, and LOWESS warping for both binned and raw full-resolution spectra
 - **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
+
+### 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
+- **Discovery & Safety**: `list_spectral_metrics()`, `list_transformers()`, `list_binning_methods()` report what is registered; built-ins are replaced only with an explicit `override=True`, and unregistering an overridden built-in restores the default
 
 ### Evaluation
 - **AMR Metrics**: VME, ME, sensitivity, specificity, categorical agreement, and `amr_classification_report` following EUCAST conventions
@@ -155,9 +173,10 @@ pip install -e .[dev]
 - **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
+- **Open Formats**: Read `.mzML` and `.mzXML` files (optionally gzipped) via `read_spectrum()`, `MaldiSpectrum`, and `FlatLayout(spectrum_ext=".mzML")`; `pip install maldiamrkit[formats]` adds `pyteomics` for numpress-compressed arrays
 - **MIC Parsing**: `parse_mic_column()` for parsing MIC strings with qualifiers and European decimals
 - **Composable Filters**: `SpeciesFilter`, `DrugFilter`, `QualityFilter`, `MetadataFilter` combinable with `&`/`|`/`~` operators
-- **Spectrum Export**: Save spectra to CSV or TXT via `MaldiSpectrum.save()` and `MaldiSet.save_spectra()`
+- **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
@@ -248,8 +267,10 @@ For more detailed examples, see the notebooks:
 - [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
 
-Notebooks `01`-`03` and `08` 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/`](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.
 
 ## MaldiSuite Ecosystem
 

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/README.md

@@ -52,6 +52,14 @@ pip install maldiamrkit[batch]
 
 Installs [`combatlearn`](https://github.com/EttoreRocchi/combatlearn) for ComBat-based batch effect correction and `umap-learn` for UMAP exploratory plots.
 
+### Optional: extended mzML/mzXML support
+
+```bash
+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
 
 ```bash
@@ -73,6 +81,12 @@ pip install -e .[dev]
 ### Alignment & Detection
 - **Spectral Alignment**: Shift, linear, piecewise, DTW, quadratic, cubic, and LOWESS warping for both binned and raw full-resolution spectra
 - **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
+
+### 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
+- **Discovery & Safety**: `list_spectral_metrics()`, `list_transformers()`, `list_binning_methods()` report what is registered; built-ins are replaced only with an explicit `override=True`, and unregistering an overridden built-in restores the default
 
 ### Evaluation
 - **AMR Metrics**: VME, ME, sensitivity, specificity, categorical agreement, and `amr_classification_report` following EUCAST conventions
@@ -98,9 +112,10 @@ pip install -e .[dev]
 - **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
+- **Open Formats**: Read `.mzML` and `.mzXML` files (optionally gzipped) via `read_spectrum()`, `MaldiSpectrum`, and `FlatLayout(spectrum_ext=".mzML")`; `pip install maldiamrkit[formats]` adds `pyteomics` for numpress-compressed arrays
 - **MIC Parsing**: `parse_mic_column()` for parsing MIC strings with qualifiers and European decimals
 - **Composable Filters**: `SpeciesFilter`, `DrugFilter`, `QualityFilter`, `MetadataFilter` combinable with `&`/`|`/`~` operators
-- **Spectrum Export**: Save spectra to CSV or TXT via `MaldiSpectrum.save()` and `MaldiSet.save_spectra()`
+- **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
@@ -191,8 +206,10 @@ For more detailed examples, see the notebooks:
 - [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
 
-Notebooks `01`-`03` and `08` 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/`](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.
 
 ## MaldiSuite Ecosystem
 

maldiamrkit-0.20.0/maldiamrkit/__init__.py

@@ -0,0 +1,38 @@
+"""MaldiAMRKit: MALDI-TOF preprocessing toolkit for AMR prediction.
+
+Subpackage guide
+----------------
+- ``maldiamrkit.data``: DatasetBuilder, DatasetLoader, InputLayout, DatasetLayout
+- ``maldiamrkit.filters``: SpeciesFilter, DrugFilter, QualityFilter, MetadataFilter
+- ``maldiamrkit.preprocessing``: PreprocessingPipeline, transformers, binning, quality, merging
+- ``maldiamrkit.alignment``: Warping, RawWarping, create_raw_input, align_peaks, AlignmentStrategy, AlignmentMethod
+- ``maldiamrkit.detection``: MaldiPeakDetector, PeakSet, PeakList, create_peakset_input
+- ``maldiamrkit.evaluation``: AMR metrics (binary + mic_regression_report), splitting (LabelEncoder moved to susceptibility)
+- ``maldiamrkit.susceptibility``: MICEncoder, BreakpointTable, BreakpointResult, LabelEncoder
+- ``maldiamrkit.similarity``: spectral_distance, pairwise_distances, clustering, plots
+- ``maldiamrkit.differential``: DifferentialAnalysis, plot_volcano, plot_manhattan, plot_drug_comparison
+- ``maldiamrkit.drift``: DriftMonitor, plot_reference_drift, plot_pca_drift, plot_peak_stability, plot_effect_size_drift
+- ``maldiamrkit.visualization``: plot_spectrum, plot_pseudogel, plot_peaks, plot_alignment, plot_pca, plot_tsne, plot_umap
+- ``maldiamrkit.io``: read_spectrum, parse_mic_column
+
+Examples
+--------
+>>> from maldiamrkit import MaldiSpectrum, MaldiSet
+>>> from maldiamrkit.preprocessing import PreprocessingPipeline
+>>> from maldiamrkit.alignment import Warping
+>>> from maldiamrkit.data import DatasetBuilder, DatasetLoader, FlatLayout, DRIAMSLayout
+>>> from maldiamrkit.susceptibility import MICEncoder, BreakpointTable
+"""
+
+from .dataset import MaldiSet
+from .spectrum import MaldiSpectrum
+
+__version__ = "0.20.0"
+__author__ = "Ettore Rocchi"
+
+__all__ = [
+    "MaldiSet",
+    "MaldiSpectrum",
+    "__version__",
+    "__author__",
+]

maldiamrkit-0.20.0/maldiamrkit/_registry.py

@@ -0,0 +1,124 @@
+"""Shared machinery for the package's name-dispatched component registries.
+
+The public registration APIs (``register_spectral_metric``,
+``register_transformer``, ``register_binning_method`` and their
+``unregister_*`` / ``list_*`` companions) are thin wrappers around one
+:class:`_ComponentRegistry` instance per component kind, so the three
+registries share a single implementation of the built-in protection,
+override, restore, and name-resolution semantics.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Callable
+
+
+class _ComponentRegistry(dict):
+    """A ``name -> component`` mapping whose built-in entries are protected.
+
+    Behaves as a plain dict for lookups, while the mutation methods enforce
+    the registry contract:
+
+    - registering a new name is always allowed (re-registering a custom name
+      replaces it silently);
+    - replacing a built-in requires ``override=True``;
+    - unregistering an overridden built-in restores the default component;
+    - unregistering a pristine built-in is refused.
+
+    Parameters
+    ----------
+    kind : str
+        Full component noun used in error messages, e.g. ``"spectral
+        metric"``.
+    short : str
+        Short noun used where the messages already say the kind, e.g.
+        ``"metric"``.
+    register_fn : str
+        Name of the public registration function to point users at.
+    entries : dict
+        The built-in components. A copy is kept as the immutable set of
+        defaults that :meth:`unregister` can restore.
+    validate : callable, optional
+        Called with the candidate component before registration; should
+        raise ``TypeError`` for unacceptable components.
+    """
+
+    def __init__(
+        self,
+        kind: str,
+        short: str,
+        register_fn: str,
+        entries: dict[str, Any],
+        validate: Callable[[Any], None] | None = None,
+    ) -> None:
+        super().__init__(entries)
+        self._kind = kind
+        self._short = short
+        self._register_fn = register_fn
+        self._validate = validate
+        self._defaults: dict[str, Any] = dict(entries)
+
+    @property
+    def defaults(self) -> dict[str, Any]:
+        """The built-in components (``name -> component``), never mutated."""
+        return self._defaults
+
+    def register(self, name: str, component: Any, *, override: bool = False) -> None:
+        if self._validate is not None:
+            self._validate(component)
+        if name in self._defaults and not override:
+            raise ValueError(
+                f"{name!r} is a built-in {self._kind}. "
+                "Pass override=True to replace it."
+            )
+        self[name] = component
+
+    def unregister(self, name: str) -> None:
+        if name in self._defaults:
+            default = self._defaults[name]
+            if self.get(name) is default:
+                raise ValueError(
+                    f"Cannot unregister built-in {self._kind} {name!r}. "
+                    f"Built-in {self._short}s are {sorted(self._defaults)}."
+                )
+            self[name] = default
+            return
+        try:
+            del self[name]
+        except KeyError:
+            raise KeyError(f"No {self._kind} named {name!r} is registered.") from None
+
+    def names(self) -> list[str]:
+        return sorted(self)
+
+    def resolve_key(
+        self,
+        value: Any,
+        enum_cls: type[Enum] | None = None,
+        *,
+        not_a: str = "valid",
+    ) -> str:
+        """Return the registry key for *value*, an enum member or a name.
+
+        Raises
+        ------
+        ValueError
+            If *value* names no registered component. The message lists the
+            registered names and points at the registration function.
+        """
+        if enum_cls is not None and isinstance(value, enum_cls):
+            key = value.value
+        else:
+            key = value
+        try:
+            known = key in self
+        except TypeError:
+            known = False
+        if not known:
+            raise ValueError(
+                f"{value!r} is not a {not_a} {self._kind}. Use one of "
+                f"{self.names()} or register a custom {self._short} with "
+                f"{self._register_fn}()."
+            )
+        return key

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/maldiamrkit/alignment/raw_warping.py

@@ -45,11 +45,11 @@ def create_raw_input(
         How to handle duplicate sample IDs (e.g. the same sample
         appearing in multiple year subdirectories):
 
-        * ``"first"``  -- keep the first occurrence (default).
-        * ``"last"``   -- keep the last occurrence.
-        * ``"drop"``   -- remove all duplicates.
-        * ``"keep_all"`` -- keep every replicate with ``_repN`` suffixes.
-        * ``"average"`` -- keep all replicates and add an
+        * ``"first"``: keep the first occurrence (default).
+        * ``"last"``: keep the last occurrence.
+        * ``"drop"``: remove all duplicates.
+        * ``"keep_all"``: keep every replicate with ``_repN`` suffixes.
+        * ``"average"``: keep all replicates and add an
           ``_original_id`` column so that
           :meth:`RawWarping.transform` can group and average them.
 

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/maldiamrkit/data/__init__.py

@@ -2,11 +2,11 @@
 
 Submodules
 ----------
-- ``input_layouts`` -- :class:`InputLayout` adapters for :class:`DatasetBuilder`
-- ``dataset_layouts`` -- :class:`DatasetLayout` adapters for :class:`DatasetLoader`
-- ``builder`` -- :class:`DatasetBuilder`, :class:`ProcessingHandler`, :class:`BuildReport`
-- ``loader`` -- :class:`DatasetLoader`
-- ``site_info`` -- :class:`SiteInfo`, :class:`BuildInfo`, ``read_site_info``,
+- ``input_layouts``: :class:`InputLayout` adapters for :class:`DatasetBuilder`
+- ``dataset_layouts``: :class:`DatasetLayout` adapters for :class:`DatasetLoader`
+- ``builder``: :class:`DatasetBuilder`, :class:`ProcessingHandler`, :class:`BuildReport`
+- ``loader``: :class:`DatasetLoader`
+- ``site_info``: :class:`SiteInfo`, :class:`BuildInfo`, ``read_site_info``,
   ``write_site_info`` (self-describing dataset manifest written at build time
   and consulted by :class:`DRIAMSLayout` at load time)
 """

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/maldiamrkit/data/breakpoints/example.yaml

@@ -1,4 +1,4 @@
-# Synthetic example breakpoint table -- NOT FOR CLINICAL USE.
+# Synthetic example breakpoint table: NOT FOR CLINICAL USE.
 #
 # Used by tests, docs, and notebooks for shape demonstration only. The
 # values below are illustrative and have been deliberately simplified;

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/maldiamrkit/data/dataset_layouts.py

@@ -169,25 +169,28 @@ class DRIAMSLayout(DatasetLayout):
         The column is renamed to ``'Species'`` for downstream use.
     year : str, int, or None
         Restrict to a single year.
-    metadata_dir : str, default="id"
-        Subdirectory name containing metadata CSV files.
-    metadata_suffix : str, default="_clean.csv"
-        Filename suffix for metadata CSV files.
-    spectrum_ext : str, default=".txt"
-        File extension for spectrum files (including the dot).
+    metadata_dir : str, optional
+        Subdirectory name containing metadata CSV files. Taken from
+        ``site_info.json`` when the dataset has one, else ``"id"``.
+    metadata_suffix : str, optional
+        Filename suffix for metadata CSV files. Taken from
+        ``site_info.json`` when the dataset has one, else ``"_clean.csv"``.
+    spectrum_ext : str, optional
+        File extension for spectrum files (including the dot). Taken from
+        ``site_info.json`` when the dataset has one, else ``".txt"``.
     duplicate_strategy : str or DuplicateStrategy, default ``"first"``
         How to handle duplicate spectrum IDs (e.g. the same sample
         appearing in multiple year subdirectories):
 
-        * ``"first"``  -- keep the first occurrence (default).
-        * ``"last"``   -- keep the last occurrence.
-        * ``"drop"``   -- remove all duplicates.
-        * ``"keep_all"`` -- keep every replicate with ``_repN`` suffixes.
-        * ``"average"`` -- tag replicates for downstream averaging.
+        * ``"first"``: keep the first occurrence (default).
+        * ``"last"``: keep the last occurrence.
+        * ``"drop"``: remove all duplicates.
+        * ``"keep_all"``: keep every replicate with ``_repN`` suffixes.
+        * ``"average"``: tag replicates for downstream averaging.
     id_transform : callable, optional
         Function mapping raw ``ID`` strings to a canonical *sample*
         identifier. When set, duplicates are detected on the
-        transformed identifier rather than the raw one -- so
+        transformed identifier rather than the raw one, so
         technical-replicate files that share an underlying sample
         (e.g. DRIAMS ``UUID_MALDI1`` / ``UUID_MALDI2``) are
         recognized as duplicates by ``duplicate_strategy``. The raw
@@ -212,11 +215,15 @@ class DRIAMSLayout(DatasetLayout):
         collapse DRIAMS technical replicates (``_MALDI<N>``) to one row per
         underlying isolate via the active ``duplicate_strategy``. Ignored when
         an explicit ``id_transform`` is given (that always takes precedence).
-    mz_min : float, default=2000.0
+    mz_min : float, optional
         Lower m/z edge to assign to bin index 0 when a ``binned_N/`` stage
-        is loaded.  Only consulted by :meth:`postprocess_spectrum`.
-    mz_max : float, default=19997.0
-        Upper m/z edge assigned to bin index ``N-1``.
+        is loaded.  Only consulted by :meth:`postprocess_spectrum`. Taken
+        from the ``mz_range`` in ``site_info.json`` when the dataset has one,
+        else ``2000.0``.
+    mz_max : float, optional
+        Upper m/z edge assigned to bin index ``N-1``. Taken from the
+        ``mz_range`` in ``site_info.json`` when the dataset has one, else
+        ``19997.0``.
     normalize_tic : bool, default=False
         When ``True``, re-apply a TIC normalization
         (``intensity <- intensity / sum(intensity)``) to every loaded
@@ -224,7 +231,7 @@ class DRIAMSLayout(DatasetLayout):
         published DRIAMS / MS-UMG ``binned_6000/`` files do not sum
         to 1.0 on disk (empirically ~1.29 and ~1.36 respectively),
         despite the DRIAMS preprocessing script calling
-        ``calibrateIntensity(method="TIC")`` before trimming -- the
+        ``calibrateIntensity(method="TIC")`` before trimming; the
         cause is somewhere in the upstream pipeline (MALDIquant version
         or an implicit scaling step) and has not been reproduced here.
         Enabling this kwarg gives sum=1.0 per spectrum, aligning DRIAMS
@@ -531,13 +538,13 @@ class MARISMaLayout(DatasetLayout):
         How to handle duplicate specimen identifiers (e.g. the same
         sample measured at multiple MALDI target positions):
 
-        * ``"first"``  -- keep the first occurrence (default).
-        * ``"last"``   -- keep the last occurrence.
-        * ``"drop"``   -- remove all duplicates.
-        * ``"keep_all"`` -- keep every replicate, appending the
+        * ``"first"``: keep the first occurrence (default).
+        * ``"last"``: keep the last occurrence.
+        * ``"drop"``: remove all duplicates.
+        * ``"keep_all"``: keep every replicate, appending the
           target-position value to the ID
           (``{identifier}_{target_position}``).
-        * ``"average"`` -- tag replicates for downstream averaging
+        * ``"average"``: tag replicates for downstream averaging
           (adds ``_original_id`` column).
     id_transform : callable, optional
         Function mapping raw ``ID`` strings to a canonical *sample*

{maldiamrkit-0.18.0 → maldiamrkit-0.20.0}/maldiamrkit/data/input_layouts.py

@@ -80,6 +80,10 @@ class FlatLayout(InputLayout):
         ``spectra_dir`` is itself flat but the years are known from another
         source. Takes precedence over the inferred subfolder year,
         but not over ``year_column``.
+    spectrum_ext : str, default=".txt"
+        File extension of the spectrum files.  Any format understood by
+        :func:`~maldiamrkit.io.read_spectrum` works, e.g. ``".mzML"`` or
+        ``".mzXML"`` for open-format exports.
     """
 
     def __init__(
@@ -90,30 +94,39 @@ class FlatLayout(InputLayout):
         id_column: str = "ID",
         year_column: str | None = None,
         year_overrides: dict[str, str] | None = None,
+        spectrum_ext: str = ".txt",
     ) -> None:
         self.spectra_dir = Path(spectra_dir)
         self.metadata_csv = Path(metadata_csv)
         self.id_column = id_column
         self.year_column = year_column
         self.year_overrides = year_overrides
+        self.spectrum_ext = (
+            spectrum_ext if spectrum_ext.startswith(".") else f".{spectrum_ext}"
+        )
         self._year_map: dict[str, str] | None = None
         self._folder_year_map: dict[str, str] = {}
 
     def discover_spectra(self) -> list[Path]:
-        """Find ``.txt`` files, whether flat or in (possibly nested) subfolders.
+        """Find spectrum files, whether flat or in (possibly nested) subfolders.
+
+        The extension is ``spectrum_ext`` (``.txt`` by default).
 
         Files are searched flat first, then one level down, then
         recursively. Whenever a spectrum sits under a four-digit-year
         folder, that year is recorded so it can serve as a fallback when
         no ``year_column`` is supplied (see :meth:`get_year`).
         """
-        files = sorted(self.spectra_dir.glob("*.txt"))
+        pattern = f"*{self.spectrum_ext}"
+        files = sorted(self.spectra_dir.glob(pattern))
         if not files:
-            files = sorted(self.spectra_dir.glob("*/*.txt"))
+            files = sorted(self.spectra_dir.glob(f"*/{pattern}"))
         if not files:
-            files = sorted(self.spectra_dir.rglob("*.txt"))
+            files = sorted(self.spectra_dir.rglob(pattern))
         if not files:
-            raise ValueError(f"No .txt spectrum files found in {self.spectra_dir}")
+            raise ValueError(
+                f"No {self.spectrum_ext} spectrum files found in {self.spectra_dir}"
+            )
 
         self._folder_year_map = {}
         for f in files:
@@ -214,13 +227,13 @@ class BrukerTreeLayout(InputLayout):
         How to handle duplicate specimen identifiers (e.g. the same
         sample measured at multiple MALDI target positions):
 
-        * ``"first"``  -- keep the first occurrence (default).
-        * ``"last"``   -- keep the last occurrence.
-        * ``"drop"``   -- remove all duplicates.
-        * ``"keep_all"`` -- keep every replicate, appending the
+        * ``"first"``: keep the first occurrence (default).
+        * ``"last"``: keep the last occurrence.
+        * ``"drop"``: remove all duplicates.
+        * ``"keep_all"``: keep every replicate, appending the
           target-position value to the ID
           (``{identifier}_{target_position}``).
-        * ``"average"`` -- tag replicates for downstream averaging
+        * ``"average"``: tag replicates for downstream averaging
           (adds ``_original_id`` column).
     validate : bool, default=True
         If ``True``, skip empty spectra (all-zero ``fid``) and warn