MaldiAMRKit 0.16.0__tar.gz → 0.17.0__tar.gz

{maldiamrkit-0.16.0 → maldiamrkit-0.17.0/MaldiAMRKit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.16.0
+Version: 0.17.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

{maldiamrkit-0.16.0 → maldiamrkit-0.17.0}/MaldiAMRKit.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ maldiamrkit/filters.py
 maldiamrkit/py.typed
 maldiamrkit/spectrum.py
 maldiamrkit/alignment/__init__.py
+maldiamrkit/alignment/peak_align.py
 maldiamrkit/alignment/raw_warping.py
 maldiamrkit/alignment/strategies.py
 maldiamrkit/alignment/warping.py
@@ -52,6 +53,7 @@ maldiamrkit/data/breakpoints/eucast/eucast_v8.1.yaml
 maldiamrkit/data/breakpoints/eucast/eucast_v9.0.yaml
 maldiamrkit/detection/__init__.py
 maldiamrkit/detection/peak_detector.py
+maldiamrkit/detection/peaklist.py
 maldiamrkit/differential/__init__.py
 maldiamrkit/differential/analysis.py
 maldiamrkit/differential/plots.py
@@ -94,4 +96,5 @@ maldiamrkit/visualization/peak_plots.py
 maldiamrkit/visualization/spectrum_plots.py
 tests/test_compat.py
 tests/test_numerical_edge_cases.py
-tests/test_peak_detector.py
+tests/test_peak_detector.py
+tests/test_peaklist.py

{maldiamrkit-0.16.0/MaldiAMRKit.egg-info → maldiamrkit-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiAMRKit
-Version: 0.16.0
+Version: 0.17.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

{maldiamrkit-0.16.0 → maldiamrkit-0.17.0}/maldiamrkit/__init__.py

@@ -5,8 +5,8 @@ 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, AlignmentStrategy, AlignmentMethod
-- ``maldiamrkit.detection``      -- MaldiPeakDetector
+- ``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
@@ -27,7 +27,7 @@ Examples
 from .dataset import MaldiSet
 from .spectrum import MaldiSpectrum
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"
 __author__ = "Ettore Rocchi"
 
 __all__ = [

{maldiamrkit-0.16.0 → maldiamrkit-0.17.0}/maldiamrkit/alignment/__init__.py

@@ -1,5 +1,6 @@
 """Spectral alignment and warping transformers."""
 
+from .peak_align import align_peaks
 from .raw_warping import RawWarping, create_raw_input
 from .strategies import AlignmentMethod, AlignmentStrategy
 from .warping import Warping
@@ -9,5 +10,6 @@ __all__ = [
     "AlignmentStrategy",
     "RawWarping",
     "Warping",
+    "align_peaks",
     "create_raw_input",
 ]

maldiamrkit-0.17.0/maldiamrkit/alignment/peak_align.py

@@ -0,0 +1,123 @@
+"""Fit-free peak-m/z alignment for peak sets.
+
+:func:`align_peaks` warps the m/z positions of a :class:`~maldiamrkit.detection.PeakSet`
+onto a reference peak list using the shared alignment strategies. It is
+**fit-free**: the reference peaks are supplied by the caller, which is expected
+to estimate them on the training split only (in the consumer's fold). The
+intensities are carried through unchanged.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..detection.peaklist import PeakSet
+from .strategies import ALIGNMENT_REGISTRY, AlignmentMethod, AlignmentStrategy
+
+
+def _build_strategy(
+    method: AlignmentMethod,
+    max_shift_da: float,
+    n_segments: int,
+    smooth_sigma: float,
+    lowess_frac: float,
+    lowess_it: int,
+) -> AlignmentStrategy:
+    """Instantiate the requested alignment strategy with its parameters."""
+    cls = ALIGNMENT_REGISTRY[method]
+    if method in (AlignmentMethod.shift, AlignmentMethod.linear):
+        return cls(max_shift=max_shift_da)
+    if method == AlignmentMethod.piecewise:
+        return cls(
+            n_segments=n_segments, smooth_sigma=smooth_sigma, max_shift=max_shift_da
+        )
+    if method == AlignmentMethod.quadratic:
+        return cls(max_shift=max_shift_da, degree=2)
+    if method == AlignmentMethod.cubic:
+        return cls(max_shift=max_shift_da, degree=3)
+    if method == AlignmentMethod.lowess:
+        return cls(max_shift=max_shift_da, frac=lowess_frac, it=lowess_it)
+    return cls()
+
+
+def align_peaks(
+    peaks: PeakSet,
+    ref_peaks_mz: np.ndarray,
+    *,
+    method: str | AlignmentMethod = "shift",
+    max_shift_da: float = 50.0,
+    n_segments: int = 5,
+    smooth_sigma: float = 2.0,
+    lowess_frac: float = 0.3,
+    lowess_it: int = 3,
+) -> PeakSet:
+    """Align a peak set's m/z positions to a reference peak list.
+
+    Fit-free: ``ref_peaks_mz`` is supplied by the caller. Builds the requested
+    warping transform from the matched (sample, reference) peak pairs and applies
+    it to the peak m/z; intensities are unchanged.
+
+    Parameters
+    ----------
+    peaks : PeakSet
+        Peak set to align.
+    ref_peaks_mz : array-like
+        Reference peak m/z positions to align to.
+    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.
+    max_shift_da : float, default=50.0
+        Maximum allowed shift in Daltons (used by the shift fallback and the
+        rigid/linear strategies).
+    n_segments : int, default=5
+        Number of segments for ``method="piecewise"``.
+    smooth_sigma : float, default=2.0
+        Gaussian smoothing (Da) for piecewise transitions.
+    lowess_frac : float, default=0.3
+        LOWESS bandwidth for ``method="lowess"``.
+    lowess_it : int, default=3
+        LOWESS robustness iterations for ``method="lowess"``.
+
+    Returns
+    -------
+    PeakSet
+        A new peak set with warped m/z and unchanged intensities.
+
+    Raises
+    ------
+    ValueError
+        If ``method="dtw"``.
+
+    Notes
+    -----
+    ``"shift"``, ``"linear"``, ``"quadratic"``, ``"cubic"`` and ``"lowess"``
+    operate directly on the matched peak m/z and are the well-behaved choices
+    for sparse peak sets. ``"piecewise"`` derives its Gaussian smoothing width
+    from the median spacing of the input points; on a sparse peak set that
+    spacing is large, so the smoothing is effectively inactive and the warp
+    reduces to an unsmoothed piecewise-linear transform.
+    """
+    method = AlignmentMethod(method)
+    if method == AlignmentMethod.dtw:
+        raise ValueError(
+            "method='dtw' is not supported for peak sets (it resamples onto a "
+            "dense grid). Use 'shift', 'linear', 'piecewise', 'quadratic', "
+            "'cubic', or 'lowess'."
+        )
+
+    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())
+
+    strategy = _build_strategy(
+        method, max_shift_da, n_segments, smooth_sigma, lowess_frac, lowess_it
+    )
+    new_mz, _ = strategy.align_raw(
+        peaks.mz,
+        peaks.intensity,
+        peaks.mz,
+        ref_peaks_mz,
+        ref_peaks_mz,
+        np.ones_like(ref_peaks_mz),
+    )
+    return PeakSet(np.asarray(new_mz, dtype=float), peaks.intensity.copy())

maldiamrkit-0.17.0/maldiamrkit/detection/__init__.py

@@ -0,0 +1,12 @@
+"""Peak detection algorithms and transformers."""
+
+from .peak_detector import MaldiPeakDetector, PeakMethod
+from .peaklist import PeakList, PeakSet, create_peakset_input
+
+__all__ = [
+    "MaldiPeakDetector",
+    "PeakMethod",
+    "PeakList",
+    "PeakSet",
+    "create_peakset_input",
+]

{maldiamrkit-0.16.0 → maldiamrkit-0.17.0}/maldiamrkit/detection/peak_detector.py

@@ -3,14 +3,25 @@
 from __future__ import annotations
 
 from enum import Enum
+from pathlib import Path
+from typing import Any
 
 import gudhi
 import numpy as np
 import pandas as pd
 from joblib import Parallel, delayed
-from scipy.signal import find_peaks
+from scipy.signal import find_peaks, peak_prominences
 from sklearn.base import BaseEstimator, TransformerMixin
 
+from .peaklist import (
+    RANK_BY,
+    PeakList,
+    PeakSet,
+    _array_hash,
+    _config_hash,
+    _PeakCache,
+)
+
 
 class PeakMethod(str, Enum):
     """Supported peak detection methods.
@@ -350,3 +361,262 @@ class MaldiPeakDetector(BaseEstimator, TransformerMixin):
             )
 
         return pd.DataFrame(stats, index=X.index)
+
+    def _detect_peaks_ph_scored(self, row: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        """Detect persistent-homology peaks and their persistence values.
+
+        Like :meth:`_detect_peaks_ph` but also returns the persistence
+        (death - birth) of each kept peak, index-ascending.
+
+        Parameters
+        ----------
+        row : np.ndarray
+            1D spectrum intensity array.
+
+        Returns
+        -------
+        indices : np.ndarray
+            Peak indices, ascending.
+        persistences : np.ndarray
+            Persistence of each peak, aligned with ``indices``.
+        """
+        row = np.asarray(row, dtype=float)
+        if np.allclose(row, row[0]):
+            return np.array([], dtype=int), np.array([], dtype=float)
+
+        signal = -row
+        signal = signal - signal.min()
+
+        cc = gudhi.CubicalComplex(top_dimensional_cells=signal[np.newaxis, :])
+        cc.persistence()
+        regular_pairs, essential_pairs = cc.cofaces_of_persistence_pairs()
+
+        regular = regular_pairs[0] if len(regular_pairs) else np.empty((0, 2), int)
+        essential = essential_pairs[0] if len(essential_pairs) else np.empty(0, int)
+        signal_max = float(np.max(signal))
+
+        idx_to_pers: dict[int, float] = {}
+        if regular.size:
+            births = signal[regular[:, 0]]
+            deaths = signal[regular[:, 1]]
+            persistences = deaths - births
+            keep = persistences >= self.persistence_threshold
+            for i, pers in zip(
+                regular[keep, 0].tolist(), persistences[keep].tolist(), strict=True
+            ):
+                idx_to_pers[int(i)] = max(idx_to_pers.get(int(i), 0.0), float(pers))
+        if essential.size:
+            essential_births = signal[essential]
+            persistences = signal_max - essential_births
+            keep = persistences >= self.persistence_threshold
+            for i, pers in zip(
+                essential[keep].tolist(), persistences[keep].tolist(), strict=True
+            ):
+                idx_to_pers[int(i)] = max(idx_to_pers.get(int(i), 0.0), float(pers))
+
+        if not idx_to_pers:
+            return np.array([], dtype=int), np.array([], dtype=float)
+        indices = np.array(sorted(idx_to_pers), dtype=int)
+        pers = np.array([idx_to_pers[int(i)] for i in indices], dtype=float)
+        return indices, pers
+
+    def _detect_scored(
+        self, row: np.ndarray, rank_by: str
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Return ``(peak_indices, ranking_scores)`` for one spectrum row.
+
+        Peak indices are ascending. ``rank_by="persistence"`` requires
+        ``method="ph"``; ``"intensity"`` and ``"prominence"`` work for either
+        detection method.
+        """
+        row = np.asarray(row, dtype=float)
+        if self.method == "local":
+            indices = self._detect_peaks_local(row)
+            persistences: np.ndarray | None = None
+        elif self.method == "ph":
+            indices, persistences = self._detect_peaks_ph_scored(row)
+        else:
+            raise ValueError(f"Unknown method: {self.method}")
+
+        indices = np.asarray(indices, dtype=int)
+        if indices.size == 0:
+            return indices, np.empty(0, dtype=float)
+
+        if rank_by == "intensity":
+            scores = row[indices]
+        elif rank_by == "prominence":
+            scores = peak_prominences(row, indices)[0]
+        elif rank_by == "persistence":
+            if persistences is None:
+                raise ValueError("rank_by='persistence' requires method='ph'.")
+            scores = persistences
+        else:
+            raise ValueError(f"Unknown rank_by={rank_by!r}; expected one of {RANK_BY}.")
+        return indices, np.asarray(scores, dtype=float)
+
+    def detect_peakset(
+        self,
+        mz: np.ndarray,
+        intensity: np.ndarray,
+        top_k: int | None = 200,
+        rank_by: str = "intensity",
+    ) -> PeakSet:
+        """Detect peaks in one spectrum and return a :class:`PeakSet`.
+
+        Stateless and per-spectrum: the result depends only on this spectrum,
+        so it is identical whether computed over a whole dataset or inside a
+        single fold.
+
+        Parameters
+        ----------
+        mz : array-like
+            m/z axis of the spectrum, shape ``(n_points,)``.
+        intensity : array-like
+            Intensity values aligned with ``mz``.
+        top_k : int or None, default=200
+            Keep at most this many peaks, ranked by ``rank_by``. ``None`` keeps
+            all detected peaks.
+        rank_by : {"intensity", "persistence", "prominence"}, default="intensity"
+            Ranking used to select the ``top_k`` peaks.
+
+        Returns
+        -------
+        PeakSet
+            The detected peaks (always carrying their true intensities,
+            regardless of the detector's ``binary`` setting).
+        """
+        mz = np.asarray(mz, dtype=float).ravel()
+        intensity = np.asarray(intensity, dtype=float).ravel()
+        if mz.shape != intensity.shape:
+            raise ValueError(
+                "mz and intensity must have the same shape; "
+                f"got {mz.shape} and {intensity.shape}."
+            )
+        indices, scores = self._detect_scored(intensity, rank_by)
+        if indices.size == 0:
+            return PeakSet(np.empty(0), np.empty(0))
+        if top_k is not None and indices.size > top_k:
+            keep = np.argsort(scores, kind="stable")[::-1][: int(top_k)]
+            indices = indices[keep]
+            scores = scores[keep]
+        peak_score = None if rank_by == "intensity" else scores
+        return PeakSet(mz[indices], intensity[indices], peak_score)
+
+    def _resolve_mz_index(
+        self, X: Any, mz: np.ndarray | None
+    ) -> tuple[np.ndarray, pd.Index]:
+        """Recover the m/z axis (from ``mz`` or numeric columns) and the index."""
+        if isinstance(X, pd.DataFrame):
+            index = X.index
+            columns: pd.Index | None = X.columns
+        else:
+            index = pd.RangeIndex(np.asarray(X).shape[0])
+            columns = None
+
+        if mz is not None:
+            return np.asarray(mz, dtype=float).ravel(), index
+        if columns is not None:
+            try:
+                return columns.to_numpy(dtype=float), index
+            except (ValueError, TypeError):
+                raise ValueError(
+                    "Could not recover an m/z axis from the DataFrame columns "
+                    f"({list(columns[:3])}...). Pass mz= explicitly (e.g. the bin "
+                    "centres from maldiamrkit.preprocessing.get_bin_metadata)."
+                ) from None
+        raise ValueError(
+            "X has no column labels to recover m/z from; pass mz= explicitly."
+        )
+
+    def transform_peaklist(
+        self,
+        X: Any,
+        top_k: int | None = 200,
+        rank_by: str = "intensity",
+        mz: np.ndarray | None = None,
+        cache_dir: str | Path | None = None,
+    ) -> PeakList:
+        """Extract a compact :class:`PeakList` from binned spectra.
+
+        Per-spectrum and stateless. The m/z axis is taken from ``mz`` if given,
+        otherwise recovered from the (numeric) DataFrame column labels.
+
+        Parameters
+        ----------
+        X : pd.DataFrame, pd.Series, or ndarray
+            Binned spectra of shape ``(n_samples, n_bins)``.
+        top_k : int or None, default=200
+            Maximum number of peaks kept per spectrum.
+        rank_by : {"intensity", "persistence", "prominence"}, default="intensity"
+            Ranking used to select the ``top_k`` peaks.
+        mz : array-like, optional
+            Explicit m/z axis of length ``n_bins``. Overrides column labels.
+        cache_dir : str, optional
+            If given, cache the resulting :class:`PeakList` keyed by a content +
+            config hash and reuse it on subsequent calls.
+
+        Returns
+        -------
+        PeakList
+            One :class:`PeakSet` per spectrum.
+        """
+        if rank_by not in RANK_BY:
+            raise ValueError(f"Unknown rank_by={rank_by!r}; expected one of {RANK_BY}.")
+        if isinstance(X, pd.Series):
+            X = X.to_frame().T
+
+        mz_axis, index = self._resolve_mz_index(X, mz)
+        values = X.to_numpy() if hasattr(X, "to_numpy") else np.asarray(X)
+        values = np.asarray(values, dtype=float)
+        if values.ndim == 1:
+            values = values.reshape(1, -1)
+        if values.shape[1] != mz_axis.shape[0]:
+            raise ValueError(
+                f"m/z axis length {mz_axis.shape[0]} does not match the "
+                f"{values.shape[1]} feature columns of X."
+            )
+
+        config = {
+            "source": "transform_peaklist",
+            "top_k": None if top_k is None else int(top_k),
+            "rank_by": rank_by,
+            "detector": self.get_params(),
+            "detector_kwargs": dict(self.kwargs),
+            "mz_axis": _array_hash(mz_axis),
+        }
+        config_hash = _config_hash(config)
+        content_hash = _array_hash(values)
+
+        cache = _PeakCache(cache_dir)
+        cached = cache.get(content_hash, config_hash)
+        if cached is not None:
+            return cached
+
+        rows = [values[i] for i in range(values.shape[0])]
+        if self.n_jobs == 1:
+            peaks = [
+                self.detect_peakset(mz_axis, row, top_k=top_k, rank_by=rank_by)
+                for row in rows
+            ]
+        else:
+            peaks = Parallel(n_jobs=self.n_jobs, prefer="processes")(
+                delayed(self.detect_peakset)(mz_axis, row, top_k, rank_by)
+                for row in rows
+            )
+
+        peaklist = PeakList(
+            peaks,
+            index=index,
+            meta={
+                "method": self.method.value,
+                "top_k": None if top_k is None else int(top_k),
+                "rank_by": rank_by,
+                "mz_range": [float(mz_axis.min()), float(mz_axis.max())],
+                "warped": False,
+                "content_hash": content_hash,
+                "config_hash": config_hash,
+                "source": "transform_peaklist",
+            },
+        )
+        cache.put(content_hash, config_hash, peaklist)
+        return peaklist