quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/peak_batch.py

@@ -0,0 +1,128 @@
+"""Batch peak integration across a spectra series, with optional alignment.
+
+ORIGIN_GAP_PLAN #35. Composes the shipped primitives — cross-correlation
+alignment (``calc.spectral.cross_correlation``) and per-region trapezoid
+integration (``calc.peak_integrate.integrate_peaks``) — over a stack of
+spectra sharing one x-axis. Produces per-spectrum results plus area /
+centroid / FWHM matrices (one row per spectrum, one column per region) so the
+caller gets parameter-vs-spectrum trends for free. Failure is isolated
+per spectrum: one bad trace yields a flagged row, never a dead batch (the
+batch-run philosophy of #3).
+
+Pure calc layer — ndarrays in, plain dict out.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from quantized.calc.peak_integrate import integrate_peaks
+from quantized.calc.spectral import cross_correlation
+
+__all__ = ["batch_integrate_peaks"]
+
+
+def _shift_samples(y: NDArray[np.float64], s: int) -> NDArray[np.float64]:
+    """Shift ``y`` by ``s`` samples (``s>0`` delays / moves right); edge-filled.
+
+    Edge fill (not wrap-around) keeps a shifted feature from bleeding across the
+    trace ends into an integration region.
+    """
+    n = y.size
+    if s == 0:
+        return y.copy()
+    out = np.empty_like(y)
+    if s > 0:
+        out[:s] = y[0]
+        out[s:] = y[: n - s]
+    else:
+        k = -s
+        out[n - k:] = y[-1]
+        out[: n - k] = y[k:]
+    return out
+
+
+def batch_integrate_peaks(
+    x: ArrayLike,
+    spectra: list[ArrayLike],
+    regions: list[tuple[float, float]],
+    *,
+    baseline: str = "linear",
+    align: bool = False,
+    reference: int = 0,
+    labels: list[str] | None = None,
+) -> dict[str, Any]:
+    """Integrate ``regions`` across every spectrum in ``spectra`` (shared ``x``).
+
+    With ``align=True`` each spectrum is cross-correlated against the
+    ``reference`` spectrum and shifted by the integer sample lag so a common
+    feature lines up before integrating (regions are defined in the reference
+    frame). Returns per-spectrum results and area/centroid/FWHM matrices
+    ``(n_spectra, n_regions)``; a spectrum that fails integration gets an
+    ``error`` and an all-NaN row rather than aborting the batch.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    if len(spectra) == 0:
+        raise ValueError("batch_integrate_peaks needs at least one spectrum")
+    if not regions:
+        raise ValueError("batch_integrate_peaks needs at least one region")
+    if not 0 <= reference < len(spectra):
+        raise ValueError(f"reference index {reference} out of range")
+    if labels is not None and len(labels) != len(spectra):
+        raise ValueError("labels length must match the number of spectra")
+
+    ys = [np.asarray(s, dtype=float).ravel() for s in spectra]
+    for i, y in enumerate(ys):
+        if y.size != xv.size:
+            raise ValueError(f"spectrum {i} length ({y.size}) must equal x length ({xv.size})")
+
+    ref = ys[reference]
+    dx = float(np.median(np.diff(xv))) if xv.size > 1 else 0.0
+    n_reg = len(regions)
+    results: list[dict[str, Any]] = []
+    area_m, cen_m, fwhm_m = [], [], []
+
+    for i, y in enumerate(ys):
+        label = labels[i] if labels else f"spectrum {i + 1}"
+        row: dict[str, Any] = {"index": i, "label": label, "shift_samples": 0, "shift_x": 0.0}
+        try:
+            shift = 0
+            yi = y
+            if align and i != reference:
+                # cross_correlation(ref, y) peaks at the lag by which y trails
+                # ref; shift y back by that lag to align onto the reference.
+                shift = int(cross_correlation(ref, y)["peakLag"])
+                yi = _shift_samples(y, -shift)
+                row["shift_samples"], row["shift_x"] = shift, shift * dx
+            integ = integrate_peaks(xv, yi, regions, baseline=baseline)
+            row["ok"] = True
+            row["total_area"] = integ["total_area"]
+            row["peaks"] = integ["peaks"]
+            area_m.append([p["area"] for p in integ["peaks"]])
+            cen_m.append([p["centroid"] for p in integ["peaks"]])
+            fwhm_m.append([p["fwhm"] for p in integ["peaks"]])
+        except ValueError as exc:
+            row["ok"] = False
+            row["error"] = str(exc)
+            row["total_area"] = float("nan")
+            area_m.append([float("nan")] * n_reg)
+            cen_m.append([float("nan")] * n_reg)
+            fwhm_m.append([float("nan")] * n_reg)
+        results.append(row)
+
+    return {
+        "regions": [[float(lo), float(hi)] for lo, hi in regions],
+        "n_spectra": len(ys),
+        "n_regions": n_reg,
+        "aligned": bool(align),
+        "reference": reference,
+        "baseline": baseline,
+        "results": results,
+        "area_matrix": area_m,
+        "centroid_matrix": cen_m,
+        "fwhm_matrix": fwhm_m,
+        "n_failed": sum(1 for r in results if not r["ok"]),
+    }

quantized/calc/peak_fit.py

@@ -0,0 +1,259 @@
+"""Single-peak fitting + peak de-duplication. Port of +bosonPlotter/+peak.
+
+Pure calc layer (ndarray in → result dict out). ``fit_single_peak`` fits one
+peak inside a user window to one of five line-shape models via Nelder-Mead
+(scipy's ``minimize`` ↔ MATLAB ``fminsearch`` — shared simplex constants), then
+derives FWHM / area / eta exactly as ``+bosonPlotter/+peak/fitSinglePeak.m``.
+``deduplicate_peaks`` is the overlap-merge rule from ``deduplicatePeaks.m``.
+
+The objective mirrors MATLAB's choice of evaluator per model: raw inline
+formulas (no clamping) for Gaussian/Lorentzian/Pseudo-Voigt, and the validating
+``split_pearson_vii`` / ``tch_pseudo_voigt`` for the asymmetric/TCH models — so a
+simplex that probes an invalid region aborts the fit with ``fminsearch-error``
+the same way MATLAB's ``utilities.splitPearsonVII`` ``error`` does.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.optimize import minimize
+
+from .peakshapes import split_pearson_vii, tch_pseudo_voigt
+
+__all__ = [
+    "MODELS",
+    "deduplicate_peaks",
+    "eval_multi_peak",
+    "eval_multi_peak_pv",
+    "fit_single_peak",
+]
+
+_LN2 = math.log(2.0)
+_A_L = math.pi / 2.0  # integrated-area constant, Lorentzian
+_A_G = math.sqrt(math.pi) / (2.0 * math.sqrt(_LN2))  # ... Gaussian
+
+MODELS = ("Lorentzian", "Gaussian", "Pseudo-Voigt", "Split Pearson VII", "TCH-pV")
+
+
+def _model_eval(model: str, p: NDArray[np.float64], x: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Raw model evaluation used inside the objective (matches fitSinglePeak.m)."""
+    if model == "Gaussian":
+        return np.asarray(p[0] * np.exp(-4.0 * _LN2 * ((x - p[1]) / p[2]) ** 2) + p[3], dtype=float)
+    if model == "Pseudo-Voigt":
+        u = (x - p[1]) / p[2]
+        lor = 1.0 / (1.0 + 4.0 * u**2)
+        gau = np.exp(-4.0 * _LN2 * u**2)
+        return np.asarray(p[0] * (p[4] * lor + (1.0 - p[4]) * gau) + p[3], dtype=float)
+    if model == "Split Pearson VII":
+        return split_pearson_vii(x, p)
+    if model == "TCH-pV":
+        return tch_pseudo_voigt(x, p)
+    # Lorentzian (default)
+    return np.asarray(p[0] / (1.0 + 4.0 * ((x - p[1]) / p[2]) ** 2) + p[3], dtype=float)
+
+
+def _result(reason: str, model: str, window: list[float]) -> dict[str, Any]:
+    nan = float("nan")
+    return {
+        "success": False, "reason": reason, "center": nan, "fwhm": nan, "height": nan,
+        "bg": nan, "eta": nan, "area": nan, "params": [], "model": model, "window": window,
+    }
+
+
+def fit_single_peak(
+    x: ArrayLike,
+    y: ArrayLike,
+    x_lo: float,
+    x_hi: float,
+    *,
+    seed_center: float,
+    seed_fwhm: float = float("nan"),
+    model: str = "Lorentzian",
+    snip_bg: ArrayLike | None = None,
+) -> dict[str, Any]:
+    """Fit one peak in ``[x_lo, x_hi]`` to ``model``. Port of fitSinglePeak.m.
+
+    ``model`` ∈ ``MODELS``. ``seed_center``/``seed_fwhm`` seed the initial guess
+    (``seed_fwhm`` NaN → derived from the window). ``snip_bg`` (optional, aligned
+    with ``x``) is subtracted at finite positions before fitting. Returns a dict
+    with ``success``/``reason`` and, on success, ``center``/``fwhm``/``height``/
+    ``bg``/``eta``/``area``/``params``. ``reason`` ∈ {``too-few-points``,
+    ``window-too-narrow``, ``center-drift``, ``fwhm-too-wide``, ``fminsearch-error``}.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    window = [float(x_lo), float(x_hi)]
+
+    if xv.size < 5:
+        return _result("too-few-points", model, window)
+    x_span = float(np.max(xv) - np.min(xv))
+
+    y_work = yv.copy()
+    if snip_bg is not None:
+        bgv = np.asarray(snip_bg, dtype=float).ravel()
+        if bgv.size == yv.size:
+            ok = np.isfinite(bgv)
+            y_work[ok] = yv[ok] - bgv[ok]
+
+    in_win = (xv >= x_lo) & (xv <= x_hi)
+    if int(np.sum(in_win)) < 4:
+        return _result("window-too-narrow", model, window)
+    x_fit = xv[in_win]
+    y_fit = y_work[in_win]
+
+    # ── Initial guesses (interp1 'linear' with max(y_fit) as the extrap value) ─
+    bg0 = float(np.min(y_fit))
+    if x_fit[0] <= x_fit[-1]:
+        xi, yi = x_fit, y_fit
+    else:  # honour decreasing-x active data
+        xi, yi = x_fit[::-1], y_fit[::-1]
+    if xi[0] <= seed_center <= xi[-1]:
+        h0 = float(np.interp(seed_center, xi, yi)) - bg0
+    else:
+        h0 = float(np.max(y_fit)) - bg0
+    if h0 <= 0:
+        h0 = float(np.max(y_fit)) - bg0
+    if math.isfinite(seed_fwhm) and seed_fwhm > 0:
+        fw0 = float(seed_fwhm)
+    else:
+        dx = (x_fit[-1] - x_fit[0]) / max(1, x_fit.size - 1)
+        fw0 = max((x_hi - x_lo) * 0.3, dx * 2.0)
+
+    is_pv = model == "Pseudo-Voigt"
+    is_spvii = model == "Split Pearson VII"
+    is_tch = model == "TCH-pV"
+    if is_spvii:
+        hw0 = fw0 / 2.0
+        p0 = np.array([h0, seed_center, hw0, hw0, 1.5, 1.5, bg0], dtype=float)
+    elif is_tch:
+        fw_seed = fw0 / math.sqrt(2.0)
+        p0 = np.array([h0, seed_center, fw_seed, fw_seed, bg0], dtype=float)
+    elif is_pv:
+        p0 = np.array([h0, seed_center, fw0, bg0, 0.5], dtype=float)
+    else:
+        p0 = np.array([h0, seed_center, fw0, bg0], dtype=float)
+
+    def objective(p: NDArray[np.float64]) -> float:
+        resid = _model_eval(model, p, x_fit) - y_fit
+        return float(np.sum(resid**2))
+
+    try:
+        res = minimize(
+            objective, p0, method="Nelder-Mead",
+            options={"maxiter": 8000, "maxfev": 8000, "xatol": 1e-10, "fatol": 1e-14},
+        )
+        p_fit = np.asarray(res.x, dtype=float)
+    except Exception:  # noqa: BLE001 — mirror MATLAB's blanket fminsearch try/catch
+        return _result("fminsearch-error", model, window)
+
+    if is_spvii:
+        fwhm_fit = abs(float(p_fit[2])) + abs(float(p_fit[3]))
+        eta_fit = float("nan")
+        bg_fit = float(p_fit[6])
+    elif is_tch:
+        f_g, f_l = abs(float(p_fit[2])), abs(float(p_fit[3]))
+        f5 = (
+            f_g**5 + 2.69269 * f_g**4 * f_l + 2.42843 * f_g**3 * f_l**2
+            + 4.47163 * f_g**2 * f_l**3 + 0.07842 * f_g * f_l**4 + f_l**5
+        )
+        fwhm_fit = f5 ** (1.0 / 5.0)
+        if fwhm_fit > 0:
+            rr = f_l / fwhm_fit
+            eta_fit = max(0.0, min(1.0, 1.36603 * rr - 0.47719 * rr**2 + 0.11116 * rr**3))
+        else:
+            eta_fit = float("nan")
+        bg_fit = float(p_fit[4])
+    else:
+        fwhm_fit = abs(float(p_fit[2]))
+        eta_fit = max(0.0, min(1.0, float(p_fit[4]))) if is_pv else float("nan")
+        bg_fit = float(p_fit[3])
+
+    if p_fit[1] < x_lo or p_fit[1] > x_hi:
+        return _result("center-drift", model, window)
+    if not (fwhm_fit > 0 and fwhm_fit < x_span * 0.5):
+        return _result("fwhm-too-wide", model, window)
+
+    height = float(p_fit[0])
+    if model == "Gaussian":
+        area = height * fwhm_fit * math.sqrt(math.pi / _LN2) / 2.0
+    elif model in ("Pseudo-Voigt", "TCH-pV"):
+        area = height * fwhm_fit * (eta_fit * _A_L + (1.0 - eta_fit) * _A_G)
+    elif is_spvii:
+        x_dense = np.linspace(x_lo, x_hi, 500)
+        y_dense = split_pearson_vii(x_dense, p_fit) - float(p_fit[6])
+        area = float(np.trapezoid(y_dense, x_dense))
+    else:  # Lorentzian
+        area = height * fwhm_fit * math.pi / 2.0
+
+    return {
+        "success": True, "reason": "", "center": float(p_fit[1]), "fwhm": fwhm_fit,
+        "height": height, "bg": bg_fit, "eta": eta_fit, "area": area,
+        "params": [float(v) for v in p_fit], "model": model, "window": window,
+    }
+
+
+def eval_multi_peak(
+    p: ArrayLike, x: ArrayLike, n_peaks: int, *, gaussian: bool = False
+) -> NDArray[np.float64]:
+    """Sum of ``n_peaks`` Lorentzian (or Gaussian) peaks + linear background.
+
+    Port of evalMultiPeak.m. ``p`` layout: ``[H, x0, fw] * n_peaks`` then
+    ``[slope, intercept]``. ``gaussian=True`` selects the Gaussian shape.
+    """
+    pv = np.asarray(p, dtype=float).ravel()
+    xv = np.asarray(x, dtype=float)
+    y = pv[-2] * xv + pv[-1]
+    for k in range(n_peaks):
+        height, x0, fw = pv[k * 3], pv[k * 3 + 1], abs(pv[k * 3 + 2])
+        if gaussian:
+            y = y + height * np.exp(-4.0 * _LN2 * ((xv - x0) / fw) ** 2)
+        else:
+            y = y + height / (1.0 + 4.0 * ((xv - x0) / fw) ** 2)
+    return np.asarray(y, dtype=float)
+
+
+def eval_multi_peak_pv(p: ArrayLike, x: ArrayLike, n_peaks: int) -> NDArray[np.float64]:
+    """Sum of ``n_peaks`` pseudo-Voigt peaks + linear background.
+
+    Port of evalMultiPeakPV.m. ``p`` layout: ``[H, x0, fw, eta] * n_peaks`` then
+    ``[slope, intercept]``; ``eta`` is clamped to [0, 1].
+    """
+    pv = np.asarray(p, dtype=float).ravel()
+    xv = np.asarray(x, dtype=float)
+    y = pv[-2] * xv + pv[-1]
+    for k in range(n_peaks):
+        height, x0, fw = pv[k * 4], pv[k * 4 + 1], abs(pv[k * 4 + 2])
+        eta = max(0.0, min(1.0, float(pv[k * 4 + 3])))
+        u = (xv - x0) / fw
+        lor = height / (1.0 + 4.0 * u**2)
+        gau = height * np.exp(-4.0 * _LN2 * u**2)
+        y = y + eta * lor + (1.0 - eta) * gau
+    return np.asarray(y, dtype=float)
+
+
+def deduplicate_peaks(peaks: list[dict[str, Any]], min_sep: float) -> list[dict[str, Any]]:
+    """Drop peaks within ``min_sep`` of each other, keeping the taller (``auto``
+    beats ``manual`` at equal height). Port of deduplicatePeaks.m."""
+    n = len(peaks)
+    if n <= 1:
+        return list(peaks)
+    keep = [True] * n
+    for i in range(n):
+        if not keep[i]:
+            continue
+        for j in range(i + 1, n):
+            if not keep[j]:
+                continue
+            if abs(float(peaks[i]["center"]) - float(peaks[j]["center"])) < min_sep:
+                hi, hj = float(peaks[i]["height"]), float(peaks[j]["height"])
+                i_wins = hi > hj or (hi == hj and peaks[i].get("status") == "auto")
+                if i_wins:
+                    keep[j] = False
+                else:
+                    keep[i] = False
+                    break
+    return [pk for pk, k in zip(peaks, keep, strict=True) if k]

quantized/calc/peak_integrate.py

@@ -0,0 +1,104 @@
+"""Integrate-only peak analysis: areas / centroid / FWHM without a fit.
+
+ORIGIN_GAP_PLAN #32 backend — per-region trapezoidal integration over a
+local shoulder-to-shoulder linear baseline (or none), plus the %-area
+deconvolution table. Wizard page 5's "integrate instead of fit" path.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__all__ = ["integrate_peaks"]
+
+
+def _fwhm(xm: NDArray[np.float64], net: NDArray[np.float64], height: float) -> float:
+    """Full width at half the (net) maximum via linear-interp crossings."""
+    if height <= 0:
+        return float("nan")
+    half = height / 2.0
+    above = net >= half
+    if not above.any():
+        return float("nan")
+    i = int(np.argmax(above))
+    j = int(len(above) - 1 - np.argmax(above[::-1]))
+    # left crossing between i-1 and i (exact when the edge point sits on half)
+    if i == 0:
+        left = float(xm[0])
+    else:
+        f = (half - net[i - 1]) / (net[i] - net[i - 1])
+        left = float(xm[i - 1] + f * (xm[i] - xm[i - 1]))
+    if j == len(net) - 1:
+        right = float(xm[-1])
+    else:
+        f = (half - net[j + 1]) / (net[j] - net[j + 1])
+        right = float(xm[j + 1] - f * (xm[j + 1] - xm[j]))
+    return right - left
+
+
+def integrate_peaks(
+    x: ArrayLike,
+    y: ArrayLike,
+    regions: list[tuple[float, float]],
+    *,
+    baseline: str = "linear",
+) -> dict[str, Any]:
+    """Integrate each x-region of a trace without fitting a model.
+
+    ``baseline='linear'`` subtracts the straight line through the region's
+    endpoints (shoulder-to-shoulder — standard manual peak integration);
+    ``'none'`` integrates the raw trace. Per region: net area (trapezoid),
+    intensity-weighted centroid, net height + its position, FWHM of the net
+    signal, and the percent of the summed area (the deconvolution table).
+    """
+    if baseline not in ("linear", "none"):
+        raise ValueError(f'baseline must be "linear" or "none", got "{baseline}"')
+    if not regions:
+        raise ValueError("integrate_peaks needs at least one region")
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    if xv.size != yv.size:
+        raise ValueError("x and y must have the same length")
+    finite = np.isfinite(xv) & np.isfinite(yv)
+    xv, yv = xv[finite], yv[finite]
+    order = np.argsort(xv, kind="stable")
+    xv, yv = xv[order], yv[order]
+
+    peaks: list[dict[str, Any]] = []
+    for k, (r0, r1) in enumerate(regions):
+        lo, hi = (r0, r1) if r0 <= r1 else (r1, r0)
+        mask = (xv >= lo) & (xv <= hi)
+        if int(mask.sum()) < 3:
+            raise ValueError(f"region {k} [{lo:g}, {hi:g}] contains fewer than 3 points")
+        xm, ym = xv[mask], yv[mask]
+        if baseline == "linear":
+            slope = (ym[-1] - ym[0]) / (xm[-1] - xm[0]) if xm[-1] != xm[0] else 0.0
+            base = ym[0] + slope * (xm - xm[0])
+        else:
+            base = np.zeros_like(ym)
+        net = ym - base
+        area = float(np.trapezoid(net, xm))
+        weight = float(np.trapezoid(np.abs(net), xm))
+        if weight > 0:
+            centroid = float(np.trapezoid(xm * np.abs(net), xm) / weight)
+        else:
+            centroid = float("nan")
+        i_max = int(np.argmax(net))
+        height = float(net[i_max])
+        peaks.append({
+            "region": [lo, hi],
+            "area": area,
+            "centroid": centroid,
+            "height": height,
+            "position": float(xm[i_max]),
+            "fwhm": _fwhm(xm, net, height),
+            "n_points": int(mask.sum()),
+        })
+
+    total = sum(p["area"] for p in peaks)
+    for p in peaks:
+        p["area_pct"] = 100.0 * p["area"] / total if total != 0 else float("nan")
+    return {"peaks": peaks, "total_area": total, "baseline": baseline}