quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/backgrounds.py

@@ -0,0 +1,353 @@
+"""Interactive + domain-specific backgrounds (GOTO_PLAN #2, #3, #7).
+
+New features beyond MATLAB parity (no goldens — reference-value and
+invariant tests in ``tests/test_calc_backgrounds.py``):
+
+- :func:`anchor_baseline` — baseline through user-picked (x, y) anchor
+  points (linear / pchip / spline), extrapolation clamped to the end
+  anchors.
+- :func:`shirley_background` — the classic iterative Shirley step
+  background for XPS/XAS spectra (Shirley 1972).
+- :func:`xrd_low_angle_background` — hyperbolic air-scatter / beam-tail
+  background for powder XRD low-angle upturn (TOPAS ``One_on_X`` form).
+- :func:`footprint_factor` / :func:`footprint_correction` — geometric
+  beam-footprint correction for XRR/NR specular scans (Gibaud & Vignaud).
+
+Pure layer: ndarray in -> ndarray out. No fastapi / pydantic imports.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from quantized.calc._clipfit import _iterative_clip_fit
+
+__all__ = [
+    "anchor_baseline",
+    "footprint_correction",
+    "footprint_factor",
+    "shirley_background",
+    "xrd_low_angle_background",
+]
+
+_EPS = float(np.finfo(float).eps)
+
+
+def anchor_baseline(
+    x: ArrayLike,
+    y: ArrayLike,
+    anchors: ArrayLike,
+    *,
+    method: str = "pchip",
+) -> NDArray[np.float64]:
+    """Baseline through user-picked (x, y) anchor points. GOTO_PLAN #2.
+
+    Interpolates the ``anchors`` — a sequence of ``(x, y)`` pairs picked on
+    the plot — across the full data grid ``x``:
+
+    - ``method='linear'``: piecewise-linear through the anchors.
+    - ``method='pchip'``: shape-preserving cubic (Fritsch & Carlson 1980,
+      SIAM J. Numer. Anal. 17, 238) — no overshoot between anchors.
+    - ``method='spline'``: interpolating B-spline of degree
+      ``min(3, n_anchors - 1)`` (degrades gracefully: 2 anchors -> linear,
+      3 -> quadratic, >=4 -> cubic).
+
+    Outside the anchor x-range the baseline is CLAMPED to the end anchors'
+    y values (constant extrapolation) — a subtraction should never invent
+    a diverging polynomial tail beyond where the user anchored it.
+
+    ``y`` (the signal the baseline sits under) is validated against ``x``
+    for length but does not influence the curve: the baseline is defined
+    by the anchors alone. Anchors are sorted by x internally; duplicate or
+    non-finite anchor x values raise ``ValueError`` (the interpolant needs
+    strictly monotone knots).
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    if xv.size != yv.size:
+        raise ValueError(f"x and y must have the same length (got {xv.size} vs {yv.size})")
+    a = np.asarray(anchors, dtype=float)
+    if a.ndim != 2 or a.shape[1] != 2:
+        raise ValueError("anchors must be a sequence of (x, y) pairs")
+    if a.shape[0] < 2:
+        raise ValueError(f"need at least 2 anchors (got {a.shape[0]})")
+    if not np.all(np.isfinite(a)):
+        raise ValueError("anchor coordinates must be finite")
+    order = np.argsort(a[:, 0], kind="stable")
+    ax, ay = a[order, 0], a[order, 1]
+    if np.any(np.diff(ax) <= 0):
+        raise ValueError("anchor x values must be strictly monotone (no duplicates)")
+
+    if method == "linear":
+        base = np.interp(xv, ax, ay, left=ay[0], right=ay[-1])
+    elif method == "pchip":
+        from scipy.interpolate import PchipInterpolator
+
+        base = PchipInterpolator(ax, ay, extrapolate=False)(xv)
+    elif method == "spline":
+        from scipy.interpolate import make_interp_spline
+
+        k = min(3, ax.size - 1)
+        spl = make_interp_spline(ax, ay, k=k)
+        base = np.asarray(spl(xv), dtype=float)
+        # make_interp_spline extrapolates; clamp outside the anchor range.
+        base[xv < ax[0]] = np.nan
+        base[xv > ax[-1]] = np.nan
+    else:
+        raise ValueError("method must be linear/pchip/spline")
+
+    base = np.asarray(base, dtype=float)
+    # Clamp extrapolation to the end anchors (pchip/spline left NaN outside).
+    base = np.where(xv < ax[0], ay[0], base)
+    base = np.where(xv > ax[-1], ay[-1], base)
+    return np.asarray(base, dtype=float)
+
+
+def shirley_background(
+    x: ArrayLike,
+    y: ArrayLike,
+    *,
+    max_iter: int = 50,
+    tol: float = 1e-6,
+    edge_average: int = 1,
+) -> tuple[NDArray[np.float64], dict[str, Any]]:
+    """Iterative Shirley step background for XPS/XAS spectra. GOTO_PLAN #3.
+
+    The Shirley background at a point is proportional to the integrated
+    peak intensity (signal above background) remaining on ONE side of that
+    point — it steps up under a peak by exactly the fraction of the peak
+    area crossed. With endpoint levels ``I1 = y[0]`` and ``I2 = y[-1]``
+    (each optionally averaged over ``edge_average`` samples) the fixed
+    point iterated here is::
+
+        B_{n+1}(x_i) = I2 + (I1 - I2) * A_i(B_n) / A_0(B_n)
+        A_i(B)       = integral_{x_i}^{x_end} (y - B) dx   (trapezoidal)
+
+    which pins ``B(x_0) = I1`` and ``B(x_end) = I2`` at every iteration.
+    Iteration stops when ``max|B_{n+1} - B_n|`` drops below ``tol`` times
+    the spectrum's peak-to-peak range; exceeding ``max_iter`` raises
+    ``ValueError`` (surfaced as 422 at the route boundary, never a 500).
+
+    A flat spectrum (no peak area, ``A_0 ~ 0``) short-circuits to the
+    linear ramp between the endpoint levels — for constant data that is a
+    constant equal to the data, i.e. a near-zero background after
+    subtraction of the flat level.
+
+    x may be ascending or descending (XPS binding-energy scans are often
+    descending); the result is returned in the input order.
+
+    References:
+        D. A. Shirley, Phys. Rev. B 5, 4709 (1972).
+        A. Proctor & P. M. A. Sherwood, Anal. Chem. 54, 13 (1982)
+        (the iterative scheme).
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    if xv.size != yv.size:
+        raise ValueError(f"x and y must have the same length (got {xv.size} vs {yv.size})")
+    n = xv.size
+    if n < 3:
+        raise ValueError("need at least 3 points for a Shirley background")
+    if not np.all(np.isfinite(xv)) or not np.all(np.isfinite(yv)):
+        raise ValueError("x and y must be finite")
+    if max_iter < 1:
+        raise ValueError("max_iter must be >= 1")
+    if tol <= 0:
+        raise ValueError("tol must be positive")
+    if edge_average < 1:
+        raise ValueError("edge_average must be >= 1")
+
+    dx = np.diff(xv)
+    flipped = False
+    if np.all(dx < 0):
+        xv, yv = xv[::-1], yv[::-1]
+        flipped = True
+    elif not np.all(dx > 0):
+        raise ValueError("x must be strictly monotone (ascending or descending)")
+
+    m = min(edge_average, n)
+    i1 = float(np.mean(yv[:m]))  # background level at the low-x end
+    i2 = float(np.mean(yv[-m:]))  # background level at the high-x end
+    y_range = float(np.ptp(yv))
+    scale = max(y_range, abs(i1 - i2), _EPS)
+
+    # Start from the linear ramp between the endpoint levels.
+    ramp = np.asarray(np.interp(xv, [xv[0], xv[-1]], [i1, i2]), dtype=float)
+    b = ramp.copy()
+    converged = False
+    n_iter = 0
+    for it in range(1, max_iter + 1):
+        n_iter = it
+        resid = yv - b
+        # A_i = trapezoidal integral of (y - B) from x_i to the end.
+        seg = 0.5 * (resid[:-1] + resid[1:]) * np.diff(xv)
+        a_right = np.concatenate([np.cumsum(seg[::-1])[::-1], [0.0]])
+        a_tot = float(a_right[0])
+        if abs(a_tot) < _EPS * scale:
+            b = ramp
+            converged = True  # no peak area -> the ramp IS the fixed point
+            break
+        b_new = i2 + (i1 - i2) * a_right / a_tot
+        delta = float(np.max(np.abs(b_new - b)))
+        b = np.asarray(b_new, dtype=float)
+        if delta < tol * scale:
+            converged = True
+            break
+
+    if not converged:
+        raise ValueError(
+            f"Shirley background did not converge after {max_iter} iterations; "
+            "increase max_iter or loosen tol"
+        )
+    if flipped:
+        b = b[::-1]
+    return np.asarray(b, dtype=float), {"nIter": n_iter, "converged": converged}
+
+
+def xrd_low_angle_background(
+    x: ArrayLike,
+    y: ArrayLike,
+    *,
+    include_x2: bool = True,
+    max_iter: int = 100,
+    tol: float = 1e-6,
+) -> tuple[NDArray[np.float64], dict[str, Any]]:
+    """Low-angle air-scatter / beam-tail background for powder XRD. GOTO_PLAN #7a.
+
+    The low-2theta intensity upturn from air scatter and the direct-beam
+    tail is conventionally modelled with a hyperbolic term in 2theta —
+    the ``One_on_X`` background of TOPAS (A. A. Coelho, J. Appl. Cryst.
+    51, 210 (2018)); GSAS-II and FullProf ship the same 1/x form. Fitted
+    model (linear in its coefficients)::
+
+        B(2theta) = b0 + b1 / (2theta) [+ b2 / (2theta)^2]
+
+    with the optional ``1/x^2`` term (``include_x2``) sharpening the
+    beam-tail rise. So Bragg peaks cannot inflate the fit, the
+    least-squares solve is wrapped in the Lieber-Mahadevan-Jansen
+    iterative clip (Appl. Spectrosc. 57, 1363 (2003)): after each fit the
+    working signal is clamped to ``min(signal, fit)`` and refit, until
+    the RMS change falls below ``tol`` times the data range (converged)
+    or ``max_iter`` is reached (returned with ``converged=False``, like
+    :func:`quantized.calc.baseline.baseline_modpoly`).
+
+    Requires strictly positive x (2theta in degrees) — the hyperbolic
+    basis diverges at 0. Returns ``(background, info)`` with
+    ``info = {"coeffs": [b0, b1(, b2)], "nIter", "converged"}``.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    if xv.size != yv.size:
+        raise ValueError(f"x and y must have the same length (got {xv.size} vs {yv.size})")
+    n = xv.size
+    n_terms = 3 if include_x2 else 2
+    if n < n_terms + 1:
+        raise ValueError(f"need at least {n_terms + 1} points (got {n})")
+    if not np.all(np.isfinite(xv)) or not np.all(np.isfinite(yv)):
+        raise ValueError("x and y must be finite")
+    if np.any(xv <= 0):
+        raise ValueError("x must be strictly positive (2-theta in degrees)")
+    if max_iter < 1:
+        raise ValueError("max_iter must be >= 1")
+
+    cols = [np.ones(n), 1.0 / xv]
+    if include_x2:
+        cols.append(1.0 / xv**2)
+    basis = np.column_stack(cols)
+
+    y_range = max(float(np.ptp(yv)), _EPS)
+
+    def _fit(y_work: NDArray[np.float64]) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+        c, *_ = np.linalg.lstsq(basis, y_work, rcond=None)
+        return np.asarray(c, dtype=float), np.asarray(basis @ c, dtype=float)
+
+    res = _iterative_clip_fit(
+        yv,
+        _fit,
+        max_iter=max_iter,
+        tol=tol,
+        y_range=y_range,
+        init=(np.zeros(n_terms), np.zeros(n)),
+    )
+    info = {
+        "coeffs": [float(c) for c in res.coeffs],
+        "nIter": res.n_iter,
+        "converged": res.converged,
+    }
+    return np.asarray(res.fit, dtype=float), info
+
+
+def footprint_factor(
+    theta_deg: ArrayLike,
+    *,
+    beam_width: float,
+    sample_length: float,
+) -> NDArray[np.float64]:
+    """Illuminated fraction F(theta) of the beam for XRR/NR geometry.
+
+    A beam of (full) width ``w`` incident at grazing angle theta
+    illuminates a strip of length ``w / sin(theta)`` on the sample. Below
+    the spill-over angle ``theta_spill = arcsin(w / L)`` that strip
+    exceeds the sample length ``L`` and only the fraction::
+
+        F(theta) = L * sin(theta) / w        (theta < theta_spill)
+        F(theta) = 1                          (theta >= theta_spill)
+
+    of the beam actually strikes the sample (uniform / top-hat beam
+    profile assumed). Points with ``sin(theta) <= 0`` get ``F = 1``
+    (a non-grazing point cannot be footprint-corrected; leave it alone).
+
+    Reference: A. Gibaud & G. Vignaud, "Specular Reflectivity from Smooth
+    and Rough Surfaces", in J. Daillant & A. Gibaud (eds), *X-ray and
+    Neutron Reflectivity*, Lect. Notes Phys. 770, Springer (2009), sec.
+    3.3 (beam footprint / spill-over).
+    """
+    if beam_width <= 0:
+        raise ValueError("beam_width must be positive")
+    if sample_length <= 0:
+        raise ValueError("sample_length must be positive")
+    th = np.asarray(theta_deg, dtype=float).ravel()
+    s = np.sin(np.radians(th))
+    frac = np.asarray(sample_length * s / beam_width, dtype=float)
+    out = np.where(s <= 0, 1.0, np.minimum(frac, 1.0))
+    return np.asarray(out, dtype=float)
+
+
+def footprint_correction(
+    theta: ArrayLike,
+    y: ArrayLike,
+    *,
+    beam_width: float,
+    sample_length: float,
+    two_theta: bool = False,
+) -> tuple[NDArray[np.float64], dict[str, Any]]:
+    """Beam-footprint (spill-over) correction for XRR/NR scans. GOTO_PLAN #7b.
+
+    Divides the measured intensity by the illuminated fraction
+    :func:`footprint_factor`, i.e. multiplies by ``w / (L sin(theta))``
+    below the spill-over angle and by exactly 1 above it — applying the
+    correction twice above spill-over is therefore a no-op (idempotent
+    there). ``two_theta=True`` reads the axis as the detector angle
+    2theta and uses ``theta = x / 2`` for the geometry.
+
+    ``beam_width`` and ``sample_length`` share any one length unit (only
+    the ratio ``w / L`` enters). Returns ``(corrected, info)`` with
+    ``info = {"spilloverDeg": ...}`` (the incidence angle, in degrees,
+    above which no correction is applied; 90 when ``w >= L``).
+
+    Reference: Gibaud & Vignaud (2009), see :func:`footprint_factor`.
+    """
+    xv = np.asarray(theta, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    if xv.size != yv.size:
+        raise ValueError(f"theta and y must have the same length (got {xv.size} vs {yv.size})")
+    th = xv / 2.0 if two_theta else xv
+    factor = footprint_factor(th, beam_width=beam_width, sample_length=sample_length)
+    corrected = np.asarray(yv / factor, dtype=float)
+    ratio = min(beam_width / sample_length, 1.0)
+    spill = math.degrees(math.asin(ratio))
+    return corrected, {"spilloverDeg": spill}

quantized/calc/baseline.py

@@ -0,0 +1,349 @@
+"""Baseline estimation. Ports of MATLAB +utilities/baseline*.m.
+
+Pure functions: spectrum in, baseline out.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy import sparse
+from scipy.interpolate import interp1d
+from scipy.sparse.linalg import spsolve
+
+from quantized.calc._clipfit import _iterative_clip_fit
+
+__all__ = [
+    "baseline_als",
+    "baseline_modpoly",
+    "baseline_rolling_ball",
+    "estimate_background",
+    "fit_region_background",
+]
+
+_EPS = float(np.finfo(float).eps)
+
+
+def fit_region_background(
+    x: ArrayLike,
+    y: ArrayLike,
+    x_min: float,
+    x_max: float,
+    *,
+    y_min: float | None = None,
+    y_max: float | None = None,
+    order: int = 1,
+) -> dict[str, Any]:
+    """Fit a polynomial background to the data inside a box region.
+
+    Pure core of BosonPlotter's "Fit BG from Box" (``+bosonPlotter/onBGMouseUp``):
+    select points with ``x_min <= x <= x_max`` (and, when given, ``y_min <= y <=
+    y_max``), then ``polyfit`` a degree-``order`` polynomial to them (raw x, no
+    normalisation — matching MATLAB ``polyfit``). The GUI cursor/box drawing and
+    trim/prefix mapping are not part of this pure layer.
+
+    Returns a dict with ``coeffs`` (highest-degree-first, MATLAB ``polyfit``
+    order), ``background`` (the polynomial evaluated across the *full* x for
+    subtraction), ``n_points``, region ``mean``/``std`` (sample, N-1)/``min``/
+    ``max`` of the selected y, and ``order``. Raises ``ValueError`` when fewer
+    than ``order + 1`` points fall inside the box.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    n = min(xv.size, yv.size)
+    xv, yv = xv[:n], yv[:n]
+
+    mask = (xv >= x_min) & (xv <= x_max) & ~np.isnan(xv) & ~np.isnan(yv)
+    if y_min is not None:
+        mask &= yv >= y_min
+    if y_max is not None:
+        mask &= yv <= y_max
+    xp, yp = xv[mask], yv[mask]
+
+    if xp.size < 2:
+        raise ValueError(f"need at least 2 points inside the box to fit (got {xp.size})")
+    if xp.size < order + 1:
+        raise ValueError(f"need at least {order + 1} points for an order-{order} fit")
+
+    coeffs = np.polyfit(xp, yp, order)
+    background = np.asarray(np.polyval(coeffs, xv), dtype=float)
+    return {
+        "coeffs": [float(c) for c in coeffs],
+        "background": background,
+        "n_points": int(xp.size),
+        "mean": float(np.mean(yp)),
+        "std": float(np.std(yp, ddof=1)),
+        "min": float(np.min(yp)),
+        "max": float(np.max(yp)),
+        "order": int(order),
+    }
+
+
+def _matlab_round(x: float) -> int:
+    """Round half away from zero (MATLAB ``round``)."""
+    return int(math.copysign(math.floor(abs(x) + 0.5), x))
+
+
+def baseline_als(
+    y: NDArray[np.float64],
+    *,
+    lam: float = 1e6,
+    p: float = 0.01,
+    max_iter: int = 20,
+    tol: float = 1e-6,
+) -> NDArray[np.float64]:
+    """Asymmetric least-squares (Eilers/Whittaker) baseline. Port of baselineALS.
+
+    Solves ``(W + lam·DᵀD) z = W·y`` iteratively, reweighting w = p where
+    y>z else (1-p), until the weights converge.
+    """
+    if lam <= 0:
+        raise ValueError("lam must be positive")
+    if not 0 < p < 1:
+        raise ValueError("p must be in (0, 1)")
+    yv = np.asarray(y, dtype=float).ravel()
+    n = yv.size
+    if n < 3:
+        return yv.copy()
+    if not np.all(np.isfinite(yv)):
+        # A non-finite y makes the sparse reweighting collapse to a singular
+        # system; the solve then returns all-NaN with a noisy MatrixRankWarning.
+        # MATLAB's backslash propagates NaN the same way, so return NaN directly
+        # (parity-preserving, and skips the warning) rather than computing it.
+        return np.full(n, np.nan)
+
+    # Second-difference operator D: (n-2) x n  (rows: y[i] - 2y[i+1] + y[i+2]).
+    diff2 = sparse.diags(
+        diagonals=[1.0, -2.0, 1.0], offsets=[0, 1, 2], shape=(n - 2, n)
+    ).tocsc()
+    dtd = (diff2.T @ diff2).tocsc()
+
+    w = np.ones(n)
+    z = yv.copy()
+    for _ in range(max_iter):
+        big_w = sparse.diags(w, 0, shape=(n, n))
+        c = (big_w + lam * dtd).tocsc()
+        z = spsolve(c, w * yv)
+        w_new = p * (yv > z) + (1.0 - p) * (yv <= z)
+        if float(np.max(np.abs(w_new - w))) < tol:
+            w = w_new
+            break
+        w = w_new
+    return np.asarray(z, dtype=float)
+
+
+def _snip_background(
+    x: NDArray[np.float64], y: NDArray[np.float64], n: int, max_window_deg: float, passes: int
+) -> NDArray[np.float64]:
+    """SNIP (iterative peak-clipping) background in sqrt space, then boxcar-smoothed."""
+    dx = float(np.median(np.diff(x)))
+    if not math.isfinite(dx) or dx <= 0:
+        # NaN dx (from a NaN in x) must short-circuit too — NaN <= 0 is False,
+        # so the old guard fell through to _matlab_round(NaN) -> ValueError.
+        return y.copy()
+    w_max = max(1, min(_matlab_round(max_window_deg / dx), (n - 1) // 2))
+    v = np.sqrt(np.maximum(y, 0.0))
+    for w in range(w_max, 0, -1):
+        v_new = v.copy()
+        avg = (v[: n - 2 * w] + v[2 * w :]) / 2.0
+        v_new[w : n - w] = np.minimum(v[w : n - w], avg)
+        v = v_new
+    bg = np.asarray(v**2, dtype=float)
+    kernel = np.ones(5) / 5.0
+    for _ in range(passes):
+        padded = np.concatenate([bg[1:3][::-1], bg, bg[n - 3 : n - 1][::-1]])
+        bg = np.asarray(np.convolve(padded, kernel, mode="valid")[:n], dtype=float)
+    return bg
+
+
+def _poly_background(
+    x: NDArray[np.float64], y: NDArray[np.float64], n: int, poly_degree: int, iter_sigma: float
+) -> NDArray[np.float64]:
+    """Polynomial background with iterative robust (MAD) outlier rejection."""
+    deg = min(poly_degree, max(1, n // 3 - 1))
+    mask = np.ones(n, dtype=bool)
+    bg = y.copy()
+    for _ in range(4):
+        xm, ym = x[mask], y[mask]
+        if xm.size < deg + 1:
+            break
+        xc = float(np.mean(xm))
+        xs = max(float(np.std(xm, ddof=1)), _EPS)
+        coeffs = np.polyfit((xm - xc) / xs, ym, deg)
+        bg = np.asarray(np.polyval(coeffs, (x - xc) / xs), dtype=float)
+        residual = y - bg
+        rm = residual[mask]
+        sigma = 1.4826 * float(np.median(np.abs(rm - np.median(rm))))
+        if sigma < _EPS:
+            break
+        mask = residual < iter_sigma * sigma
+        if int(mask.sum()) < deg + 1:
+            mask = np.ones(n, dtype=bool)
+            break
+    return np.asarray(bg, dtype=float)
+
+
+def _iterative_refine(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    bg: NDArray[np.float64],
+    n: int,
+    method: str,
+    max_window_deg: float,
+    passes: int,
+    poly_degree: int,
+    iter_max_passes: int,
+    iter_sigma: float,
+) -> NDArray[np.float64]:
+    """Refine a background by masking+dilating peaks and re-estimating on the rest."""
+    for _ in range(iter_max_passes):
+        residual = y - bg
+        below_med = residual[residual < np.median(residual)]
+        ref = below_med if below_med.size > 5 else residual
+        sigma = 1.4826 * float(np.median(np.abs(ref - np.median(ref))))
+        data_range = float(np.max(y) - np.min(y))
+        if sigma < max(_EPS, data_range * 1e-10):
+            break
+        dilated = residual > iter_sigma * sigma
+        for _ in range(max(3, _matlab_round(0.005 * n))):
+            prev = dilated.copy()
+            dilated[1:] = dilated[1:] | prev[:-1]
+            dilated[:-1] = dilated[:-1] | prev[1:]
+        non_peak = ~dilated
+        if int(non_peak.sum()) < 10:
+            break
+        bg_prev = bg
+        if method == "snip":
+            y_clean = y.copy()
+            fill = interp1d(
+                x[non_peak], y[non_peak], kind="linear", fill_value="extrapolate"
+            )
+            y_clean[dilated] = fill(x[dilated])
+            bg = _snip_background(x, y_clean, n, max_window_deg, passes)
+        else:
+            bg = _poly_background(x, y, n, poly_degree, iter_sigma)
+        if float(np.max(np.abs(bg - bg_prev))) < 0.01 * sigma:
+            break
+    return bg
+
+
+def estimate_background(
+    x: ArrayLike,
+    y: ArrayLike,
+    *,
+    method: str = "snip",
+    max_window_deg: float = 2.0,
+    smooth_passes: int = 3,
+    poly_degree: int = 4,
+    iterative: bool = False,
+    iter_max_passes: int = 3,
+    iter_sigma: float = 3.0,
+) -> NDArray[np.float64]:
+    """Estimate a slowly-varying background. Port of utilities.estimateBackground.
+
+    ``method='snip'`` (default) uses sqrt-space iterative peak clipping; ``'polynomial'``
+    fits a robust low-order polynomial. With ``iterative=True`` peaks are masked,
+    dilated, and the background re-estimated on the remainder. The result is always
+    clamped to ``min(bg, y)``.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    n = yv.size
+    if n < 3:
+        return yv.copy()
+    if method == "snip":
+        bg = _snip_background(xv, yv, n, max_window_deg, smooth_passes)
+    elif method == "polynomial":
+        bg = _poly_background(xv, yv, n, poly_degree, iter_sigma)
+    else:
+        raise ValueError("method must be snip/polynomial")
+    if iterative:
+        bg = _iterative_refine(
+            xv, yv, bg, n, method, max_window_deg, smooth_passes,
+            poly_degree, iter_max_passes, iter_sigma,
+        )
+    return np.asarray(np.minimum(bg, yv), dtype=float)
+
+
+def baseline_rolling_ball(
+    y: ArrayLike, *, radius: int = 100, smooth: int = -1
+) -> tuple[NDArray[np.float64], dict[str, int]]:
+    """Rolling-ball baseline (grayscale morphological opening). Port of baselineRollingBall.
+
+    Erodes then dilates the signal with a ball-shaped structuring element of the
+    given ``radius`` (in samples), boxcar-smooths, and clamps to ``min(bg, y)``.
+    ``smooth=-1`` auto-picks a half-width of ``round(radius/10)``. Returns
+    ``(baseline, {"radius", "smooth"})``.
+    """
+    if radius <= 0:
+        raise ValueError("radius must be a positive integer (in samples)")
+    yv = np.asarray(y, dtype=float).ravel()
+    n = yv.size
+    smooth_hw = max(1, _matlab_round(radius / 10)) if smooth < 0 else _matlab_round(smooth)
+    if n < 3:
+        return yv.copy(), {"radius": radius, "smooth": smooth_hw}
+
+    half_w = min(radius, n - 1)
+    offsets = np.arange(-half_w, half_w + 1)
+    rise = radius - np.sqrt(np.maximum(radius * radius - offsets.astype(float) ** 2, 0.0))
+
+    eroded = np.full(n, np.inf)
+    for off, rise_val in zip(offsets, rise, strict=True):
+        i0, i1 = max(0, -int(off)), min(n - 1, n - 1 - int(off))
+        if i1 >= i0:
+            eroded[i0 : i1 + 1] = np.minimum(
+                eroded[i0 : i1 + 1], yv[i0 + int(off) : i1 + int(off) + 1] + rise_val
+            )
+    dilated = np.full(n, -np.inf)
+    for off, rise_val in zip(offsets, rise, strict=True):
+        i0, i1 = max(0, -int(off)), min(n - 1, n - 1 - int(off))
+        if i1 >= i0:
+            dilated[i0 : i1 + 1] = np.maximum(
+                dilated[i0 : i1 + 1], eroded[i0 + int(off) : i1 + int(off) + 1] - rise_val
+            )
+
+    baseline = dilated
+    if smooth_hw > 0 and n > 2 * smooth_hw:
+        pad = min(smooth_hw, n - 1)
+        kernel = np.ones(2 * smooth_hw + 1) / (2 * smooth_hw + 1)
+        padded = np.concatenate(
+            [baseline[1 : pad + 1][::-1], baseline, baseline[n - 1 - pad : n - 1][::-1]]
+        )
+        baseline = np.convolve(padded, kernel, mode="valid")[:n]
+    baseline = np.asarray(np.minimum(baseline, yv), dtype=float)
+    return baseline, {"radius": radius, "smooth": smooth_hw}
+
+
+def baseline_modpoly(
+    y: ArrayLike, *, order: int = 5, max_iter: int = 100, tol: float = 1e-6
+) -> tuple[NDArray[np.float64], dict[str, Any]]:
+    """Modified-polynomial (Lieber) baseline. Port of baselineModPoly.
+
+    Iteratively fits a polynomial of ``order`` and clips the working signal to
+    ``min(signal, fit)`` until the RMS change (relative to the data range) drops
+    below ``tol``. Returns ``(baseline, {"order", "nIter", "converged"})``.
+    """
+    if order <= 0:
+        raise ValueError("order must be a positive integer")
+    yv = np.asarray(y, dtype=float).ravel()
+    n = yv.size
+    if n < 3:
+        return yv.copy(), {"order": order, "nIter": 0, "converged": True}
+
+    poly_ord = min(order, n - 1)
+    x = np.arange(1, n + 1, dtype=float)
+    xn = (x - float(np.mean(x))) / max(float(np.std(x, ddof=1)), _EPS)
+    y_range = max(float(np.max(yv) - np.min(yv)), _EPS)
+
+    def _fit(y_work: NDArray[np.float64]) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+        c = np.asarray(np.polyfit(xn, y_work, poly_ord), dtype=float)
+        return c, np.asarray(np.polyval(c, xn), dtype=float)
+
+    # `init` preserves the pre-refactor pre-loop fit: with max_iter < 1 the
+    # returned coefficients are the plain polyfit of the unclipped signal.
+    res = _iterative_clip_fit(yv, _fit, max_iter=max_iter, tol=tol, y_range=y_range, init=_fit(yv))
+    baseline = np.asarray(np.minimum(np.polyval(res.coeffs, xn), yv), dtype=float)
+    return baseline, {"order": poly_ord, "nIter": res.n_iter, "converged": res.converged}