MaldiAMRKit 0.22.0__tar.gz → 0.22.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.22.0
+Version: 0.22.1
 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
@@ -143,7 +144,7 @@ pip install -e .[dev]
 - **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
 - **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
@@ -162,7 +163,7 @@ pip install -e .[dev]
 
 ### 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
@@ -246,7 +247,7 @@ pipe = Pipeline([
     ("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}")
 ```

{maldiamrkit-0.22.0 → maldiamrkit-0.22.1}/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.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.22.0
+Version: 0.22.1
 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
@@ -143,7 +144,7 @@ pip install -e .[dev]
 - **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
 - **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
@@ -162,7 +163,7 @@ pip install -e .[dev]
 
 ### 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
@@ -246,7 +247,7 @@ pipe = Pipeline([
     ("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}")
 ```

{maldiamrkit-0.22.0 → maldiamrkit-0.22.1}/README.md

@@ -82,7 +82,7 @@ pip install -e .[dev]
 - **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
 - **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
@@ -101,7 +101,7 @@ pip install -e .[dev]
 
 ### 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
@@ -185,7 +185,7 @@ pipe = Pipeline([
     ("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}")
 ```

{maldiamrkit-0.22.0 → maldiamrkit-0.22.1}/maldiamrkit/__init__.py

@@ -27,7 +27,7 @@ Examples
 from .dataset import MaldiSet
 from .spectrum import MaldiSpectrum
 
-__version__ = "0.22.0"
+__version__ = "0.22.1"
 __author__ = "Ettore Rocchi"
 
 __all__ = [

maldiamrkit-0.22.1/maldiamrkit/alignment/_dtw.py

@@ -0,0 +1,82 @@
+"""Banded Sakoe-Chiba DTW path, computed on the band only.
+
+The path is the one :func:`tslearn.metrics.dtw_path` returns for two series
+of equal length with ``global_constraint="sakoe_chiba"``: same float64 cost,
+same tie order when walking back. Memory is ``O(n * (2 * radius + 1))``
+instead of tslearn's ``O(n ** 2)``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+
+
+@njit(cache=True, nogil=True)
+def _banded_path(s1, s2, radius):
+    """Forward DTW path ``(path_i, path_j)`` of two float64 series of length n."""
+    n = s1.shape[0]
+    r = min(radius, n - 1)
+    w = 2 * r + 1
+    # cost[i, k] is the accumulated cost of cell (i, j) with j = i - r + k.
+    cost = np.full((n, w), np.inf)
+    for i in range(n):
+        lo = max(0, i - r)
+        hi = min(n - 1, i + r)
+        for j in range(lo, hi + 1):
+            k = j - i + r
+            if i == 0 and j == 0:
+                best = 0.0
+            else:
+                up = cost[i - 1, k + 1] if i > 0 and k + 1 < w else np.inf
+                left = cost[i, k - 1] if j > 0 and k > 0 else np.inf
+                diag = cost[i - 1, k] if i > 0 and j > 0 else np.inf
+                best = min(up, left, diag)
+            diff = s1[i] - s2[j]
+            dist = diff * diff
+            cost[i, k] = dist + best
+
+    path_i = np.empty(2 * n, dtype=np.int64)
+    path_j = np.empty(2 * n, dtype=np.int64)
+    i = n - 1
+    j = n - 1
+    m = 0
+    path_i[0] = i
+    path_j[0] = j
+    while i != 0 or j != 0:
+        if i == 0:
+            j -= 1
+        elif j == 0:
+            i -= 1
+        else:
+            # Same order as tslearn: diagonal, then up, then left.
+            k = j - i + r
+            diag = cost[i - 1, k] if 0 <= k < w else np.inf
+            up = cost[i - 1, k + 1] if 0 <= k + 1 < w else np.inf
+            left = cost[i, k - 1] if 0 <= k - 1 < w else np.inf
+            if diag <= up and diag <= left:
+                i -= 1
+                j -= 1
+            elif up <= left:
+                i -= 1
+            else:
+                j -= 1
+        m += 1
+        path_i[m] = i
+        path_j[m] = j
+    return path_i[: m + 1][::-1].copy(), path_j[: m + 1][::-1].copy()
+
+
+def _dtw_path(
+    query: np.ndarray, reference: np.ndarray, radius: int
+) -> tuple[np.ndarray, np.ndarray]:
+    """Banded DTW path of two series of equal length.
+
+    Both series are cast to contiguous float64 (as tslearn does), so the
+    kernel is compiled once whatever the input dtype.
+    """
+    return _banded_path(
+        np.ascontiguousarray(query, dtype=np.float64),
+        np.ascontiguousarray(reference, dtype=np.float64),
+        int(radius),
+    )

maldiamrkit-0.22.1/maldiamrkit/alignment/_versioning.py

@@ -0,0 +1,87 @@
+"""Version stamp for pickled aligners.
+
+A pickled :class:`~maldiamrkit.alignment.Warping` or
+:class:`~maldiamrkit.alignment.RawWarping` records the maldiamrkit version it
+was saved with. An aligner fitted with maldiamrkit 0.21 or earlier lacks the
+parameters added in 0.22 and aligns differently, so it is refused instead of
+being completed with defaults (which would align new spectra differently
+from the training data).
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+
+_PARAMS_SINCE_0_22 = (
+    "shift_estimator",
+    "min_gain",
+    "min_support",
+    "n_peaks",
+    "prealign",
+    "renormalize",
+)
+
+
+def _current_version() -> str:
+    import maldiamrkit
+
+    return maldiamrkit.__version__
+
+
+def _version_tuple(text: object) -> tuple[int, int, int] | None:
+    """Integers of the first three dotted fields of a version, or None."""
+    if not isinstance(text, str):
+        return None
+    match = re.match(r"\s*(\d+)\.(\d+)(?:\.(\d+))?", text)
+    if match is None:
+        return None
+    return tuple(int(part or 0) for part in match.groups())
+
+
+def _versioned_state(state: dict) -> dict:
+    """Stamp the pickled state with the running maldiamrkit version."""
+    return dict(state, _maldiamrkit_version=_current_version())
+
+
+def _checked_state(name: str, state: dict) -> dict:
+    """Return the state to restore, warning when it comes from an older release."""
+    state = dict(state)
+    version = state.pop("_maldiamrkit_version", None)
+    current = _current_version()
+    if any(param not in state for param in _PARAMS_SINCE_0_22):
+        message = (
+            f"This {name} was fitted with maldiamrkit 0.21 or earlier, whose "
+            f"alignment differs from maldiamrkit {current}: it must be refitted "
+            "(fit, transform and get_alignment_quality raise), or used with "
+            "maldiamrkit < 0.22."
+        )
+    elif version is None:
+        message = (
+            f"This {name} was pickled with maldiamrkit 0.22.0 or earlier, which "
+            f"did not record its version; it is loaded with maldiamrkit "
+            f"{current} and can still be used."
+        )
+    else:
+        saved, running = _version_tuple(version), _version_tuple(current)
+        if saved is not None and (running is None or saved >= running):
+            return state
+        message = (
+            f"This {name} was pickled with maldiamrkit {version} and is loaded "
+            f"with maldiamrkit {current}."
+        )
+    warnings.warn(message, UserWarning, stacklevel=3)
+    return state
+
+
+def _check_supported(estimator: object) -> None:
+    """Raise when ``estimator`` holds the state of maldiamrkit 0.21 or earlier."""
+    if all(hasattr(estimator, param) for param in _PARAMS_SINCE_0_22):
+        return
+    name = type(estimator).__name__
+    raise RuntimeError(
+        f"This {name} was fitted with maldiamrkit 0.21 or earlier, whose "
+        "alignment differs from maldiamrkit 0.22: create and fit a new "
+        f"{name} with the current version (or keep maldiamrkit < 0.22 to use "
+        "this one)."
+    )

{maldiamrkit-0.22.0 → maldiamrkit-0.22.1}/maldiamrkit/alignment/peak_align.py

@@ -62,7 +62,10 @@ def align_peaks(
     peaks : PeakSet
         Peak set to align.
     ref_peaks_mz : array-like
-        Reference peak m/z positions to align to.
+        Reference peak m/z positions to align to. Estimate them on the
+        training spectra only (for example ``RawWarping(...).fit(X_train)``
+        and its ``ref_peaks_mz_``), so that test peak sets do not shape
+        their own reference.
     method : {"shift", "linear", "piecewise", "quadratic", "cubic", "lowess"}, default="shift"
         Warping strategy. ``"dtw"`` is unsupported for peak sets because it
         resamples onto a dense grid and would destroy the set structure.
@@ -82,7 +85,8 @@ def align_peaks(
     Returns
     -------
     PeakSet
-        A new peak set with warped m/z and unchanged intensities.
+        A new peak set with warped m/z and unchanged intensities and
+        scores.
 
     Raises
     ------
@@ -110,9 +114,10 @@ def align_peaks(
             "'cubic', or 'lowess'."
         )
 
+    score = None if peaks.score is None else peaks.score.copy()
     ref_peaks_mz = np.asarray(ref_peaks_mz, dtype=float).ravel()
     if peaks.n_peaks == 0 or ref_peaks_mz.size == 0:
-        return PeakSet(peaks.mz.copy(), peaks.intensity.copy())
+        return PeakSet(peaks.mz.copy(), peaks.intensity.copy(), score=score)
 
     strategy = _build_strategy(
         method, max_shift_da, n_segments, smooth_sigma, lowess_frac, lowess_it
@@ -125,4 +130,4 @@ def align_peaks(
         ref_peaks_mz,
         np.ones_like(ref_peaks_mz),
     )
-    return PeakSet(np.asarray(new_mz, dtype=float), peaks.intensity.copy())
+    return PeakSet(np.asarray(new_mz, dtype=float), peaks.intensity.copy(), score=score)

{maldiamrkit-0.22.0 → maldiamrkit-0.22.1}/maldiamrkit/alignment/raw_warping.py

@@ -13,9 +13,20 @@ from sklearn.base import BaseEstimator, TransformerMixin
 from ..data.duplicates import DuplicateStrategy, apply_index_strategy
 from ..detection.peak_detector import MaldiPeakDetector
 from ..io.readers import read_spectrum
-from ..preprocessing.binning import BinningMethod, bin_spectrum
+from ..preprocessing.binning import (
+    _BINNING_REGISTRY,
+    BinningMethod,
+    _bin_on_edges,
+    bin_spectrum,
+)
 from ..preprocessing.pipeline import preprocess
 from ..preprocessing.preprocessing_pipeline import PreprocessingPipeline
+from ._versioning import (
+    _PARAMS_SINCE_0_22,
+    _check_supported,
+    _checked_state,
+    _versioned_state,
+)
 from .strategies import (
     _ALIGNMENT_REGISTRY,
     _SHIFT_ESTIMATORS,
@@ -56,10 +67,15 @@ def create_raw_input(
         * ``"first"``: keep the first occurrence (default).
         * ``"last"``: keep the last occurrence.
         * ``"drop"``: remove all duplicates.
-        * ``"keep_all"``: keep every replicate with ``_repN`` suffixes.
+        * ``"keep_all"``: keep every replicate, adding ``_repN`` to the
+          duplicated IDs (unique IDs stay unchanged).
         * ``"average"``: keep all replicates and add an
           ``_original_id`` column so that
-          :meth:`RawWarping.transform` can group and average them.
+          :meth:`RawWarping.transform` can group and average them (the
+          output then has one row per sample, so it cannot be used inside
+          ``Pipeline.fit``, which needs one row per input row; when
+          splitting rows, keep the replicates of a sample together with
+          ``groups=``).
 
     Returns
     -------
@@ -136,6 +152,8 @@ class RawWarping(BaseEstimator, TransformerMixin):
         Width of output bins in Daltons.
     bin_method : str, default="uniform"
         Binning method. One of 'uniform', 'proportional', 'adaptive', 'custom'.
+        With 'adaptive', the edges are learned from the reference spectrum in
+        :meth:`fit` and used for every transformed spectrum.
     bin_kwargs : dict, optional
         Additional keyword arguments for binning.
     max_shift_da : float, default=10.0
@@ -145,10 +163,8 @@ class RawWarping(BaseEstimator, TransformerMixin):
     n_segments : int, default=5
         Number of segments for piecewise warping.
     dtw_radius : int, default=10
-        Radius constraint for DTW. DTW memory grows with the square of the
-        number of reference points (about 10 GB per spectrum for a 0.5 Da
-        grid over 2-20 kDa), so a coarser ``interp_step`` is needed to run
-        it on full-resolution spectra.
+        Radius constraint for DTW (Sakoe-Chiba band, in points of the
+        reference grid).
     smooth_sigma : float, default=2.0
         Gaussian smoothing for piecewise transitions.
     lowess_frac : float, default=0.3
@@ -263,6 +279,10 @@ class RawWarping(BaseEstimator, TransformerMixin):
     aligns each spectrum on its own (replicates of one sample are averaged
     after alignment), so its result does not depend on the other spectra
     transformed with it.
+
+    A pickled aligner records the maldiamrkit version it was saved with; one
+    fitted with maldiamrkit 0.21 or earlier cannot be used and must be
+    refitted.
     """
 
     def __init__(
@@ -407,6 +427,32 @@ class RawWarping(BaseEstimator, TransformerMixin):
 
         return ref_mz, ref_intensity, ref_peaks_mz
 
+    def __getstate__(self):
+        return _versioned_state(super().__getstate__())
+
+    def __setstate__(self, state):
+        super().__setstate__(_checked_state(type(self).__name__, state))
+        # Aligners pickled with 0.22.0 binned adaptively spectrum by spectrum:
+        # learn the edges from their reference, as fit does now.
+        if (
+            "_adaptive_edges_" not in self.__dict__
+            and hasattr(self, "ref_mz_")
+            and all(param in self.__dict__ for param in _PARAMS_SINCE_0_22)
+        ):
+            self._adaptive_edges_ = self._learn_adaptive_edges()
+            if self._adaptive_edges_ is not None and not self._output_columns().equals(
+                self.output_columns_
+            ):
+                self._adaptive_edges_ = None
+                self._stale_bins_ = True
+                warnings.warn(
+                    "This RawWarping was pickled with maldiamrkit 0.22.0 and its "
+                    "adaptive bins cannot be rebuilt exactly from its reference: "
+                    "refit it before transforming.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
     def fit(self, X: pd.DataFrame, y=None):
         """
         Fit by computing the reference spectrum from raw data.
@@ -427,10 +473,14 @@ class RawWarping(BaseEstimator, TransformerMixin):
 
         Raises
         ------
+        RuntimeError
+            If the transformer was fitted with maldiamrkit 0.21 or earlier
+            (loaded from an old pickle).
         ValueError
             If the input DataFrame is empty, lacks a 'path' column,
             or uses an unknown warping method.
         """
+        _check_supported(self)
         if X.empty:
             raise ValueError("Input DataFrame X is empty")
 
@@ -454,6 +504,8 @@ class RawWarping(BaseEstimator, TransformerMixin):
 
         # Store preprocessing config
         self.pipeline_ = self.pipeline or PreprocessingPipeline.default()
+        self._adaptive_edges_ = None
+        self.__dict__.pop("_stale_bins_", None)
 
         # Get paths from DataFrame
         paths = X["path"].tolist()
@@ -484,12 +536,50 @@ class RawWarping(BaseEstimator, TransformerMixin):
                 stacklevel=2,
             )
 
+        # Adaptive bins are learned once, from the reference, so that every
+        # transformed spectrum gets the same columns.
+        self._adaptive_edges_ = self._learn_adaptive_edges()
+
         # Determine output columns by binning a sample spectrum
-        sample_binned = self._bin_warped(self.ref_mz_, self.ref_intensity_)
-        self.output_columns_ = sample_binned.set_index("mass").index.astype(str)
+        self.output_columns_ = self._output_columns()
 
         return self
 
+    def _learn_adaptive_edges(self) -> np.ndarray | None:
+        """Adaptive bin edges of the reference, or None for other methods.
+
+        The reference is binned with :func:`bin_spectrum`, which also checks
+        ``bin_kwargs``.
+        """
+        if _BINNING_REGISTRY.resolve_key(self.bin_method, BinningMethod) != "adaptive":
+            return None
+        mz_min, mz_max = self.pipeline_.mz_range
+        _, metadata = bin_spectrum(
+            pd.DataFrame({"mass": self.ref_mz_, "intensity": self.ref_intensity_}),
+            mz_min=mz_min,
+            mz_max=mz_max,
+            bin_width=self.bin_width,
+            method=self.bin_method,
+            **(self.bin_kwargs or {}),
+        )
+        return np.append(
+            metadata["bin_start"].to_numpy(dtype=float),
+            float(metadata["bin_end"].iloc[-1]),
+        )
+
+    def _output_columns(self) -> pd.Index:
+        """Column labels of the binned output, from the reference."""
+        binned = self._bin_warped(self.ref_mz_, self.ref_intensity_)
+        return binned.set_index("mass").index.astype(str)
+
+    def _check_bins(self) -> None:
+        """Raise when the adaptive bins of a 0.22.0 pickle could not be rebuilt."""
+        if getattr(self, "_stale_bins_", False):
+            raise RuntimeError(
+                "This RawWarping was pickled with maldiamrkit 0.22.0 and its "
+                "adaptive bins cannot be rebuilt exactly: refit it."
+            )
+
     def _get_strategy(self):
         """Build strategy instance from current parameters."""
         cls = _ALIGNMENT_REGISTRY[self.method]
@@ -554,6 +644,10 @@ class RawWarping(BaseEstimator, TransformerMixin):
     def _bin_warped(self, mz: np.ndarray, intensity: np.ndarray) -> pd.DataFrame:
         """Bin warped raw spectrum to output grid."""
         warped_df = pd.DataFrame({"mass": mz, "intensity": intensity})
+        adaptive_edges = getattr(self, "_adaptive_edges_", None)
+        if adaptive_edges is not None:
+            binned, _ = _bin_on_edges(warped_df, adaptive_edges)
+            return binned
         bin_kwargs = self.bin_kwargs or {}
         mz_min, mz_max = self.pipeline_.mz_range
         binned, _ = bin_spectrum(
@@ -612,15 +706,21 @@ class RawWarping(BaseEstimator, TransformerMixin):
         -------
         X_aligned : pd.DataFrame
             Aligned and binned spectra with sample IDs as index and
-            m/z bin centers as columns.
+            m/z bin centers as columns. With an ``_original_id`` column
+            (see :func:`create_raw_input`), replicates are averaged into
+            one row per sample, in order of first appearance.
 
         Raises
         ------
         RuntimeError
-            If the transformer has not been fitted.
+            If the transformer has not been fitted, was fitted with
+            maldiamrkit 0.21 or earlier, or was pickled with 0.22.0 with
+            adaptive bins that cannot be rebuilt.
         ValueError
             If the input DataFrame lacks a 'path' column.
         """
+        _check_supported(self)
+        self._check_bins()
         if not hasattr(self, "ref_mz_"):
             raise RuntimeError("RawWarping must be fitted before transform")
 
@@ -648,7 +748,7 @@ class RawWarping(BaseEstimator, TransformerMixin):
         if "_original_id" in X.columns:
             original_ids = X["_original_id"]
             result["_original_id"] = original_ids.values
-            averaged = result.groupby("_original_id").mean()
+            averaged = result.groupby("_original_id", sort=False).mean()
             averaged.index.name = None
             result = averaged
 
@@ -678,8 +778,12 @@ class RawWarping(BaseEstimator, TransformerMixin):
         Raises
         ------
         RuntimeError
-            If the transformer has not been fitted.
+            If the transformer has not been fitted, was fitted with
+            maldiamrkit 0.21 or earlier, or was pickled with 0.22.0 with
+            adaptive bins that cannot be rebuilt.
         """
+        _check_supported(self)
+        self._check_bins()
         if not hasattr(self, "ref_mz_"):
             raise RuntimeError("RawWarping must be fitted first")