quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/peak_multifit.py

@@ -0,0 +1,260 @@
+"""Simultaneous multi-peak + polynomial-background fit. Port of the
+``+bosonPlotter/peakAnalysis`` global fit (``onFitSimultaneous`` +
+``buildCompositeModel``/``compositeEval`` + ``computeArea``) and the exposed
+``+bosonPlotter/buildLinkedPacker``.
+
+Pure calc layer. Fits N peaks and a degree-``bg_degree`` polynomial background in
+one optimisation, optionally sharing FWHM (and η) across peaks and/or penalising
+center drift. The composite model approximates Split-Pearson-VII as a symmetric
+Pearson VII (m=1.5) and TCH-pV as an η=0.5 pseudo-Voigt — matching the MATLAB
+global fit (the per-peak fit in ``peak_fit`` uses the full forms).
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.optimize import minimize
+
+__all__ = ["build_linked_packer", "compute_peak_area", "fit_multi_peak"]
+
+_LN2 = math.log(2.0)
+_EPS = float(np.finfo(float).eps)
+_A_L = math.pi / 2.0
+_A_G = math.sqrt(math.pi) / (2.0 * math.sqrt(_LN2))
+
+ExpandFn = Callable[[NDArray[np.float64]], NDArray[np.float64]]
+
+
+def _composite_eval(
+    p: NDArray[np.float64], x: NDArray[np.float64], n_peaks: int, n_per_peak: int,
+    n_bg: int, model: str,
+) -> NDArray[np.float64]:
+    """Sum of ``n_peaks`` peaks + a polynomial background. Port of compositeEval."""
+    bg_coeffs = p[len(p) - n_bg :]  # [c0, c1, ..., cn]
+    y = np.polyval(bg_coeffs[::-1], x)
+    for k in range(n_peaks):
+        base = k * n_per_peak
+        height, x0 = p[base], p[base + 1]
+        fw = p[base + 2] if p[base + 2] != 0 else _EPS
+        u = (x - x0) / fw
+        if model == "Gaussian":
+            y = y + height * np.exp(-4.0 * _LN2 * u**2)
+        elif model == "Pseudo-Voigt":
+            eta = max(0.0, min(1.0, float(p[base + 3])))
+            y = y + eta * (height / (1.0 + 4.0 * u**2)) + (1.0 - eta) * (
+                height * np.exp(-4.0 * _LN2 * u**2)
+            )
+        elif model == "Split Pearson VII":
+            m = 1.5
+            y = y + height * (1.0 + 4.0 * (2.0 ** (1.0 / m) - 1.0) * u**2) ** (-m)
+        elif model == "TCH-pV":
+            y = y + 0.5 * (height / (1.0 + 4.0 * u**2)) + 0.5 * (
+                height * np.exp(-4.0 * _LN2 * u**2)
+            )
+        else:  # Lorentzian
+            y = y + height / (1.0 + 4.0 * u**2)
+    return np.asarray(y, dtype=float)
+
+
+def compute_peak_area(model: str, height: float, fwhm: float, eta: float) -> float:
+    """Integrated peak area from fitted params. Port of computeArea (SPVII/TCH use
+    the Lorentzian form, matching MATLAB's ``otherwise`` branch)."""
+    if model == "Gaussian":
+        return height * fwhm * math.sqrt(math.pi / _LN2) / 2.0
+    if model == "Pseudo-Voigt":
+        e = 0.5 if math.isnan(eta) else eta
+        return height * fwhm * (e * _A_L + (1.0 - e) * _A_G)
+    return height * fwhm * math.pi / 2.0
+
+
+def _build_composite_model(
+    x: NDArray[np.float64], y: NDArray[np.float64], peaks: list[dict[str, Any]],
+    model: str, bg_degree: int,
+) -> tuple[NDArray[np.float64], int, list[int], NDArray[np.float64]]:
+    """Initial super-parameter vector + layout. Port of buildCompositeModel."""
+    n_peaks = len(peaks)
+    x_span = float(np.max(x) - np.min(x))
+    is_pv = model == "Pseudo-Voigt"
+    n_per_peak = 4 if is_pv else 3
+    n_bg = bg_degree + 1
+    p0 = np.zeros(n_peaks * n_per_peak + n_bg)
+    center_indices: list[int] = []
+    seed_centers = np.zeros(n_peaks)
+    y_max = float(np.max(y))
+    for k in range(n_peaks):
+        pk = peaks[k]
+        base = k * n_per_peak
+        p0[base] = max(float(pk["height"]), y_max * 0.01)
+        p0[base + 1] = float(pk["center"])
+        p0[base + 2] = max(float(pk["fwhm"]), x_span * 0.005)
+        if is_pv:
+            eta0 = 0.5
+            pk_eta = pk.get("eta")
+            if pk_eta is not None and not (isinstance(pk_eta, float) and math.isnan(pk_eta)):
+                eta0 = float(pk_eta)
+            p0[base + 3] = eta0
+        center_indices.append(base + 1)
+        seed_centers[k] = float(pk["center"])
+    p0[len(p0) - n_bg] = float(np.min(y))  # c0 (intercept); c1.. default 0
+    return p0, n_per_peak, center_indices, seed_centers
+
+
+def build_linked_packer(
+    p0: ArrayLike, n_peaks: int, n_per_peak: int, link_mode: str, center_indices: Sequence[int]
+) -> tuple[NDArray[np.float64], ExpandFn, list[int]]:
+    """Reduce/expand machinery for shared peak parameters. Port of buildLinkedPacker.
+
+    Modes: ``None`` (identity), ``Shared FWHM`` (peak 0's FWHM is the master),
+    ``Shared FWHM + eta`` (FWHM and, for pseudo-Voigt, η are masters). Returns
+    ``(p_free0, expand_fn, free_center_idx)``; indices are 0-based.
+    """
+    p0a = np.asarray(p0, dtype=float)
+    m = p0a.size
+    if link_mode == "None" or n_peaks < 2:
+        return p0a.copy(), (lambda p: p), list(center_indices)
+
+    link_eta = link_mode == "Shared FWHM + eta" and n_per_peak == 4
+    drop: set[int] = set()
+    for k in range(1, n_peaks):
+        base = k * n_per_peak
+        drop.add(base + 2)  # slave FWHM
+        if link_eta:
+            drop.add(base + 3)  # slave eta
+    keep_idx = [i for i in range(m) if i not in drop]
+    p_free0 = p0a[keep_idx]
+
+    master_fwhm_free = keep_idx.index(2)  # peak 0 FWHM (0-based)
+    master_eta_free = keep_idx.index(3) if (link_eta and 3 in keep_idx) else -1
+
+    src_map = [0] * m
+    for pos, i in enumerate(keep_idx):
+        src_map[i] = pos + 1  # 1-based positive
+    for k in range(1, n_peaks):
+        base = k * n_per_peak
+        src_map[base + 2] = -1  # slave FWHM
+        if link_eta:
+            src_map[base + 3] = -2  # slave eta
+
+    def expand(p_free: NDArray[np.float64]) -> NDArray[np.float64]:
+        p_full = np.zeros(m)
+        for i in range(m):
+            s = src_map[i]
+            if s > 0:
+                p_full[i] = p_free[s - 1]
+            elif s == -1:
+                p_full[i] = p_free[master_fwhm_free]
+            elif s == -2:
+                p_full[i] = p_free[master_eta_free]
+        return p_full
+
+    free_center_idx = [keep_idx.index(ci) for ci in center_indices]
+    return p_free0, expand, free_center_idx
+
+
+def fit_multi_peak(
+    x: ArrayLike,
+    y: ArrayLike,
+    peaks: list[dict[str, Any]],
+    *,
+    model: str = "Lorentzian",
+    bg_degree: int = 1,
+    constrain: bool = False,
+    link_mode: str = "None",
+    max_fev: int | None = None,
+) -> dict[str, Any]:
+    """Fit ``peaks`` + a polynomial background simultaneously. Port of
+    ``peakAnalysis.onFitSimultaneous``.
+
+    ``model`` ∈ {Lorentzian, Gaussian, Pseudo-Voigt, Split Pearson VII, TCH-pV}.
+    ``bg_degree`` is the background polynomial degree. ``constrain=True`` adds a
+    soft center-drift penalty; ``link_mode`` shares FWHM/η across peaks. Returns a
+    dict with fitted ``peaks`` (center/fwhm/height/bg/eta/area/status), ``bgCoeffs``,
+    ``R2``, ``rmse``, ``params``, ``nPeaks``, ``model``.
+
+    Faithful-port note: MATLAB's ``onFitSimultaneous`` sets ``MaxIter`` to 30000
+    but leaves ``MaxFunEvals`` at fminsearch's default ``200·nFree`` — so the GUI
+    fit is *function-evaluation-limited*, often stopping before full convergence.
+    We replicate that budget by default (``max_fev=None`` → ``200·nFree``) so the
+    Python result matches the MATLAB GUI bit-for-bit (scipy and MATLAB share the
+    Lagarias simplex). Pass an explicit ``max_fev`` to let the fit converge further
+    (diverges from MATLAB parity — use only when you want the best fit, not parity).
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    n_peaks = len(peaks)
+    if n_peaks < 1:
+        raise ValueError("need at least one peak to fit")
+    x_span = float(np.max(xv) - np.min(xv))
+    is_pv = model == "Pseudo-Voigt"
+    n_bg = bg_degree + 1
+
+    p0, n_per_peak, center_indices, seed_centers = _build_composite_model(
+        xv, yv, peaks, model, bg_degree
+    )
+    p_free0, expand, free_center_idx = build_linked_packer(
+        p0, n_peaks, n_per_peak, link_mode, center_indices
+    )
+
+    def model_eval(pf: NDArray[np.float64]) -> NDArray[np.float64]:
+        return _composite_eval(expand(pf), xv, n_peaks, n_per_peak, n_bg, model)
+
+    if constrain and n_peaks > 1:
+        center_bnd = np.array(
+            [max(3.0 * abs(p0[k * n_per_peak + 2]), x_span * 0.02) for k in range(n_peaks)]
+        )
+        penalty_wt = float(np.sum((yv - np.mean(yv)) ** 2)) * 10.0
+        fci = np.asarray(free_center_idx, dtype=int)
+
+        def objective(pf: NDArray[np.float64]) -> float:
+            resid = model_eval(pf) - yv
+            pen = np.sum(np.maximum(0.0, ((pf[fci] - seed_centers) / center_bnd) ** 2 - 1.0))
+            return float(np.sum(resid**2) + penalty_wt * pen)
+    else:
+        def objective(pf: NDArray[np.float64]) -> float:
+            resid = model_eval(pf) - yv
+            return float(np.sum(resid**2))
+
+    n_free = int(np.asarray(p_free0).size)
+    fev = 200 * n_free if max_fev is None else max_fev
+    res = minimize(
+        objective, p_free0, method="Nelder-Mead",
+        options={"maxiter": 30000, "maxfev": fev, "xatol": 1e-10, "fatol": 1e-14},
+    )
+    p_fit = expand(np.asarray(res.x, dtype=float))
+
+    bg_coeffs = p_fit[len(p_fit) - n_bg :]
+    fitted: list[dict[str, Any]] = []
+    for k in range(n_peaks):
+        base = k * n_per_peak
+        height = float(p_fit[base])
+        x0 = float(p_fit[base + 1])
+        fw = abs(float(p_fit[base + 2]))
+        eta = max(0.0, min(1.0, float(p_fit[base + 3]))) if is_pv else float("nan")
+        fitted.append({
+            "center": x0,
+            "fwhm": fw,
+            "height": height,
+            "bg": float(np.polyval(bg_coeffs[::-1], x0)),
+            "eta": eta,
+            "area": compute_peak_area(model, height, fw, eta),
+            "status": "fitted(global)",
+            "model": model,
+        })
+
+    y_fit = _composite_eval(p_fit, xv, n_peaks, n_per_peak, n_bg, model)
+    ss_res = float(np.sum((yv - y_fit) ** 2))
+    ss_tot = float(np.sum((yv - np.mean(yv)) ** 2))
+    return {
+        "peaks": fitted,
+        "bgCoeffs": [float(c) for c in bg_coeffs],
+        "R2": 1.0 - ss_res / max(ss_tot, _EPS),
+        "rmse": math.sqrt(ss_res / xv.size),
+        "params": [float(v) for v in p_fit],
+        "nPeaks": n_peaks,
+        "model": model,
+    }

quantized/calc/peak_track.py

@@ -0,0 +1,134 @@
+"""Track a peak across a series of datasets. Port of fitting.trackPeak.
+
+Pure calc layer. Starting from a seed x-position, fits the nearest peak in each
+dataset within a search window; with ``follow=True`` the window recenters on each
+fitted position so a drifting peak (e.g. a Bragg reflection shifting with
+temperature) stays in view. Uses the bounded single-peak ``curve_fit`` (Gaussian
+or Lorentzian) and keeps a fit only when its R² exceeds 0.5.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+from .fitting import curve_fit
+
+__all__ = ["track_peak"]
+
+_FWHM_PER_SIGMA = 2.355  # MATLAB trackPeak uses the rounded constant, not 2*sqrt(2 ln 2)
+
+
+def _gaussian(x: NDArray[np.float64], p: NDArray[np.float64]) -> NDArray[np.float64]:
+    return np.asarray(p[0] * np.exp(-((x - p[1]) ** 2) / (2.0 * p[2] ** 2)), dtype=float)
+
+
+def _lorentzian(x: NDArray[np.float64], p: NDArray[np.float64]) -> NDArray[np.float64]:
+    return np.asarray(p[0] / (1.0 + ((x - p[1]) / p[2]) ** 2), dtype=float)
+
+
+def _extract_xy(
+    ds: DataStruct | tuple[Any, Any] | list[Any], channel: int
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Pull (x, y) from a DataStruct (time / values[:, channel]) or an (x, y) pair."""
+    if isinstance(ds, DataStruct):
+        x = np.asarray(ds.time, dtype=float).ravel()
+        values = np.asarray(ds.values, dtype=float)
+        ch = min(channel, values.shape[1] - 1) if values.ndim == 2 else 0
+        y = values[:, ch] if values.ndim == 2 else values.ravel()
+        return x, np.asarray(y, dtype=float).ravel()
+    if isinstance(ds, (tuple, list)) and len(ds) >= 2:
+        return (
+            np.asarray(ds[0], dtype=float).ravel(),
+            np.asarray(ds[1], dtype=float).ravel(),
+        )
+    return np.empty(0), np.empty(0)
+
+
+def track_peak(
+    datasets: list[Any],
+    seed_position: float,
+    *,
+    channel: int = 0,
+    window: float = 0.0,
+    shape: str = "gaussian",
+    min_height: float = 0.0,
+    follow: bool = True,
+) -> dict[str, Any]:
+    """Track a peak across ``datasets`` from ``seed_position``. Port of trackPeak.
+
+    Each dataset is a ``DataStruct`` or an ``(x, y)`` pair. ``window`` is the
+    search half-width in x-units (0 → auto, 5% of the x-range). ``shape`` is
+    ``"gaussian"`` or ``"lorentzian"``. Returns per-dataset ``center``/``height``/
+    ``fwhm``/``area``/``R2`` (NaN where no acceptable peak was found), ``found``
+    flags, and ``nDatasets``. ``channel`` is 0-based (MATLAB's is 1-based).
+    """
+    if shape not in ("gaussian", "lorentzian"):
+        raise ValueError(f'shape must be "gaussian" or "lorentzian", got "{shape}"')
+    n = len(datasets)
+    nan = float("nan")
+    center = [nan] * n
+    height = [nan] * n
+    fwhm = [nan] * n
+    area = [nan] * n
+    r2 = [nan] * n
+    found = [False] * n
+
+    current_pos = float(seed_position)
+    model = _gaussian if shape == "gaussian" else _lorentzian
+
+    for i in range(n):
+        x_data, y_data = _extract_xy(datasets[i], channel)
+        if x_data.size < 5:
+            continue
+
+        hw = window if window > 0 else 0.05 * (float(np.max(x_data)) - float(np.min(x_data)))
+        mask = (x_data >= current_pos - hw) & (x_data <= current_pos + hw)
+        x_seg, y_seg = x_data[mask], y_data[mask]
+        if x_seg.size < 5:
+            continue
+
+        peak_idx = int(np.argmax(y_seg))
+        peak_h, peak_x = float(y_seg[peak_idx]), float(x_seg[peak_idx])
+        if peak_h < min_height:
+            continue
+
+        p0 = [peak_h, peak_x, hw / 3.0]
+        lower = [0.0, current_pos - hw, 0.0]
+        upper = [math.inf, current_pos + hw, hw]
+        try:
+            r = curve_fit(x_seg, y_seg, model, p0, lower=lower, upper=upper, calc_errors=False)
+        except (ValueError, FloatingPointError, np.linalg.LinAlgError):
+            continue
+
+        if r["R2"] <= 0.5:
+            continue
+        params = r["params"]
+        center[i] = float(params[1])
+        height[i] = float(params[0])
+        w = abs(float(params[2]))
+        if shape == "gaussian":
+            fwhm[i] = _FWHM_PER_SIGMA * w
+            area[i] = float(params[0]) * w * math.sqrt(2.0 * math.pi)
+        else:
+            fwhm[i] = 2.0 * w
+            area[i] = float(params[0]) * math.pi * w
+        r2[i] = float(r["R2"])
+        found[i] = True
+        if follow:
+            current_pos = center[i]
+
+    return {
+        "center": center,
+        "height": height,
+        "fwhm": fwhm,
+        "area": area,
+        "R2": r2,
+        "found": found,
+        "nDatasets": n,
+    }

quantized/calc/peaks.py

@@ -0,0 +1,298 @@
+"""Robust peak detection. Port of utilities.findPeaksRobust.
+
+Pure calc layer (no Signal Toolbox equivalent — hand-rolled to match MATLAB).
+Detects local maxima on a background-subtracted residual, then filters by
+prominence, background slope, width (FWHM + points above half-max), local SNR,
+and a greedy minimum-separation rule. Returns ``(peaks, background)`` where
+``peaks`` is a list of dicts (one per peak).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .baseline import estimate_background
+from .processing import _matlab_gradient
+
+__all__ = ["find_peaks_robust"]
+
+_EPS = float(np.finfo(float).eps)
+
+
+def _matlab_round(x: float) -> int:
+    return int(math.copysign(math.floor(abs(x) + 0.5), x))
+
+
+def _estimate_noise(y: NDArray[np.float64]) -> float:
+    """Robust noise estimate from first differences (MAD/sqrt(2)), floored."""
+    diffs = np.diff(y)
+    sigma = 1.4826 * float(np.median(np.abs(diffs - np.median(diffs)))) / math.sqrt(2.0)
+    return max(sigma, float(np.max(y)) * 1e-6)
+
+
+def _prominence_bruteforce(
+    residual: NDArray[np.float64], max_idx: NDArray[np.intp]
+) -> NDArray[np.float64]:
+    """Reference O(M·walk) prominence: walk out each side until a higher sample.
+
+    Kept as the parity reference and the fallback for non-finite residuals
+    (NaN/Inf comparison semantics differ from the fast path)."""
+    n = residual.size
+    prom = np.zeros(max_idx.size)
+    for k in range(max_idx.size):
+        idx = int(max_idx[k])
+        pk_height = residual[idx]
+        left_min = pk_height
+        for j in range(idx - 1, -1, -1):
+            if residual[j] < left_min:
+                left_min = residual[j]
+            if residual[j] > pk_height:
+                break
+        right_min = pk_height
+        for j in range(idx + 1, n):
+            if residual[j] < right_min:
+                right_min = residual[j]
+            if residual[j] > pk_height:
+                break
+        prom[k] = pk_height - max(left_min, right_min)
+    return prom
+
+
+def _nearest_greater(a: NDArray[np.float64], *, forward: bool) -> NDArray[np.intp]:
+    """Index of the nearest strictly-greater element to each position.
+
+    ``forward=False`` scans left (previous-greater, sentinel -1); ``forward=True``
+    scans right (next-greater, sentinel n). O(n) via a monotonic stack."""
+    n = a.size
+    res = np.empty(n, dtype=np.intp)
+    rng = range(n) if not forward else range(n - 1, -1, -1)
+    sentinel = -1 if not forward else n
+    stack: list[int] = []
+    for i in rng:
+        ai = a[i]
+        while stack and a[stack[-1]] <= ai:
+            stack.pop()
+        res[i] = stack[-1] if stack else sentinel
+        stack.append(i)
+    return res
+
+
+class _RangeMin:
+    """Sparse table for static inclusive range-minimum (O(n log n) build, O(1) query)."""
+
+    def __init__(self, a: NDArray[np.float64]) -> None:
+        n = a.size
+        self.table: list[NDArray[np.float64]] = [np.asarray(a, dtype=float)]
+        j = 1
+        while (1 << j) <= n:
+            prev = self.table[j - 1]
+            span = 1 << (j - 1)
+            width = n - (1 << j) + 1
+            self.table.append(np.minimum(prev[:width], prev[span : span + width]))
+            j += 1
+
+    def query(self, lo: int, hi: int) -> float:
+        """Minimum over the inclusive range ``[lo, hi]``; ``+inf`` if empty (lo>hi)."""
+        if lo > hi:
+            return float("inf")
+        j = (hi - lo + 1).bit_length() - 1
+        return float(min(self.table[j][lo], self.table[j][hi - (1 << j) + 1]))
+
+
+def _compute_prominence(
+    residual: NDArray[np.float64], max_idx: NDArray[np.intp]
+) -> NDArray[np.float64]:
+    """Topographic prominence for each candidate maximum.
+
+    For a peak at ``idx`` the prominence is ``residual[idx] - max(left_min,
+    right_min)`` where each side-min is taken over the run from the nearest
+    strictly-greater sample up to the peak. Computing the nearest-greater indices
+    (monotonic stacks) and the run-minima (sparse table) is O(n log n) instead of
+    the O(n²) per-candidate walk that bites on large, noisy data with many local
+    maxima. Bit-for-bit identical to :func:`_prominence_bruteforce` on finite
+    data (verified); non-finite residuals fall back to the brute force."""
+    if not bool(np.isfinite(residual).all()):
+        return _prominence_bruteforce(residual, max_idx)
+    pge = _nearest_greater(residual, forward=False)
+    nge = _nearest_greater(residual, forward=True)
+    rmin = _RangeMin(residual)
+    prom = np.zeros(max_idx.size)
+    for k in range(max_idx.size):
+        idx = int(max_idx[k])
+        pk = float(residual[idx])
+        left_min = min(pk, rmin.query(int(pge[idx]) + 1, idx - 1))
+        right_min = min(pk, rmin.query(idx + 1, int(nge[idx]) - 1))
+        prom[k] = pk - max(left_min, right_min)
+    return prom
+
+
+def _estimate_fwhm(
+    x: NDArray[np.float64], residual: NDArray[np.float64], idx: int, n: int
+) -> tuple[float, int]:
+    """FWHM via half-max crossings (linearly interpolated) + points above half."""
+    half_max = residual[idx] / 2.0
+
+    l_idx = 0
+    for j in range(idx - 1, -1, -1):
+        if residual[j] <= half_max:
+            l_idx = j
+            break
+    if 0 <= l_idx < idx:
+        r1, r2 = residual[l_idx], residual[min(l_idx + 1, n - 1)]
+        if abs(r2 - r1) > _EPS:
+            frac = (half_max - r1) / (r2 - r1)
+            x_left = x[l_idx] + frac * (x[min(l_idx + 1, n - 1)] - x[l_idx])
+        else:
+            x_left = x[l_idx]
+    else:
+        x_left = x[max(0, idx - 1)]
+
+    r_idx = n - 1
+    for j in range(idx + 1, n):
+        if residual[j] <= half_max:
+            r_idx = j
+            break
+    if idx < r_idx <= n - 1:
+        r1, r2 = residual[r_idx], residual[max(r_idx - 1, 0)]
+        if abs(r2 - r1) > _EPS:
+            frac = (half_max - r1) / (r2 - r1)
+            x_right = x[r_idx] + frac * (x[max(r_idx - 1, 0)] - x[r_idx])
+        else:
+            x_right = x[r_idx]
+    else:
+        x_right = x[min(n - 1, idx + 1)]
+
+    fw = abs(x_right - x_left)
+    if fw <= 0:
+        fw = abs(x[min(n - 1, idx + 1)] - x[max(0, idx - 1)])
+    n_above = int(np.sum(residual[max(0, l_idx) : min(n, r_idx + 1)] >= half_max))
+    return fw, n_above
+
+
+def find_peaks_robust(
+    x: ArrayLike,
+    y: ArrayLike,
+    *,
+    snr_threshold: float = 5.0,
+    min_separation: float = 0.0,
+    max_peaks: int = 50,
+    max_window_deg: float = 2.0,
+    min_width_deg: float = 0.01,
+    max_width_deg: float = 10.0,
+    min_prominence: float = 0.02,
+    sensitivity: str = "medium",
+) -> tuple[list[dict[str, Any]], NDArray[np.float64]]:
+    """Detect peaks robustly. Port of utilities.findPeaksRobust.
+
+    Returns ``(peaks, background)``. Each peak dict carries center/fwhm/height/
+    area/xRange/status/bg/model/eta/prominence/localSNR (area/eta are NaN and
+    xRange empty — filled later by an explicit fit). ``sensitivity`` (low/medium/
+    high) tightens or loosens the SNR and prominence thresholds.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    n = yv.size
+    if n < 5:
+        return [], yv.copy()
+
+    if sensitivity == "high":
+        snr_thr, min_prom = min(snr_threshold, 3.0), min(min_prominence, 0.005)
+    elif sensitivity == "low":
+        snr_thr, min_prom = max(snr_threshold, 8.0), max(min_prominence, 0.05)
+    else:
+        snr_thr, min_prom = snr_threshold, min_prominence
+
+    x_span = float(xv.max() - xv.min())
+    bg = estimate_background(xv, yv, max_window_deg=max(max_window_deg, x_span * 0.05))
+    residual = yv - bg
+    global_noise = _estimate_noise(yv)
+    local_noise = global_noise * np.ones(n)
+
+    is_max = np.zeros(n, dtype=bool)
+    is_max[1:-1] = (residual[1:-1] >= residual[:-2]) & (residual[1:-1] > residual[2:])
+    is_max &= residual >= snr_thr * local_noise
+    max_idx = np.flatnonzero(is_max)
+    if max_idx.size == 0:
+        return [], bg
+
+    prom = _compute_prominence(residual, max_idx)
+    abs_prom_thresh = max(min_prom * float(residual.max()), 4 * global_noise)
+    rel_prom_ratio = prom / np.maximum(residual[max_idx], _EPS)
+    keep = (prom >= abs_prom_thresh) | ((rel_prom_ratio >= 0.15) & (prom >= 4 * global_noise))
+    max_idx, prom = max_idx[keep], prom[keep]
+    if max_idx.size == 0:
+        return [], bg
+
+    bg_grad = np.abs(_matlab_gradient(bg, xv))
+    nbr_span = np.abs(xv[np.minimum(n - 1, max_idx + 1)] - xv[np.maximum(0, max_idx - 1)])
+    slope_span = bg_grad[max_idx] * nbr_span
+    keep_slope = slope_span <= residual[max_idx] * 0.3
+    max_idx, prom = max_idx[keep_slope], prom[keep_slope]
+    if max_idx.size == 0:
+        return [], bg
+
+    dx = float(np.median(np.diff(xv)))
+    min_width_pts = max(4, _matlab_round(min_width_deg / max(dx, _EPS)))
+    pk_fwhm = np.zeros(max_idx.size)
+    valid = np.ones(max_idx.size, dtype=bool)
+    for k in range(max_idx.size):
+        fw, n_above = _estimate_fwhm(xv, residual, int(max_idx[k]), n)
+        pk_fwhm[k] = fw
+        if fw < min_width_deg or fw > max_width_deg or n_above < min_width_pts:
+            valid[k] = False
+    max_idx, prom, pk_fwhm = max_idx[valid], prom[valid], pk_fwhm[valid]
+    if max_idx.size == 0:
+        return [], bg
+
+    pk_x = xv[max_idx]
+    pk_h = residual[max_idx]
+    pk_bg = bg[max_idx]
+    pk_snr = pk_h / np.maximum(local_noise[max_idx], _EPS)
+    min_sep = min_separation if min_separation > 0 else x_span * 0.005
+
+    # Greedy minimum-separation suppression, strongest peak first.
+    order = np.argsort(-pk_h, kind="stable")
+    cx, ch, cbg, cfw, cprom, csnr = (
+        pk_x[order], pk_h[order], pk_bg[order], pk_fwhm[order], prom[order], pk_snr[order],
+    )
+    keep2 = np.ones(cx.size, dtype=bool)
+    for ii in range(cx.size):
+        if not keep2[ii]:
+            continue
+        for jj in range(ii + 1, cx.size):
+            if keep2[jj] and abs(cx[ii] - cx[jj]) < min_sep:
+                keep2[jj] = False
+    cx, ch, cbg, cfw, cprom, csnr = (
+        cx[keep2], ch[keep2], cbg[keep2], cfw[keep2], cprom[keep2], csnr[keep2],
+    )
+    if cx.size > max_peaks:
+        sl = slice(0, max_peaks)
+        cx, ch, cbg, cfw, cprom, csnr = cx[sl], ch[sl], cbg[sl], cfw[sl], cprom[sl], csnr[sl]
+
+    reorder = np.argsort(cx, kind="stable")
+    cx, ch, cbg, cfw, cprom, csnr = (
+        cx[reorder], ch[reorder], cbg[reorder], cfw[reorder], cprom[reorder], csnr[reorder],
+    )
+
+    nan = float("nan")
+    peaks = [
+        {
+            "center": float(cx[k]),
+            "fwhm": float(cf),
+            "height": float(ch[k]),
+            "area": nan,
+            "xRange": [],
+            "status": "auto",
+            "bg": float(cbg[k]),
+            "model": "",
+            "eta": nan,
+            "prominence": float(cprom[k]),
+            "localSNR": float(csnr[k]),
+        }
+        for k, cf in enumerate(cfw)
+    ]
+    return peaks, bg