quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/_natural_neighbor.py

@@ -0,0 +1,219 @@
+"""Sibson natural-neighbour interpolation (pure; scipy.spatial only, no GPL).
+
+MATLAB ``scatteredInterpolant`` 'natural' (and 'cubic', which it aliases to
+'natural') use Sibson's natural-neighbour interpolation. scipy has no
+equivalent, so this implements it directly from the Delaunay triangulation via
+the local Bowyer-Watson "stolen area" construction:
+
+  Inserting a query point ``q`` into the Voronoi diagram of the data carves a
+  new cell out of the existing ones. The Sibson coordinate of data point ``p``
+  is the area ``q``'s new cell steals from ``p``'s old cell, normalised by the
+  total new-cell area. The interpolated value is the weighted sum
+  ``sum_i lambda_i * z_i``.
+
+Sibson coordinates are *geometrically* unique (they depend only on the point
+configuration, not on any tie-breaking), so this matches MATLAB's 'natural' to
+~1e-9 at non-degenerate interior points. The interpolant has **linear
+precision** — it reproduces any affine ``z = a*x + b*y + c`` exactly — which the
+tests assert to machine precision.
+
+The work per query is *local* (only the few triangles whose circumcircle
+contains ``q``, found by a BFS over Delaunay adjacency), so cost scales with the
+query count, not N^2. The in-circle test reduces to a squared-distance compare
+against precomputed circumradii; ``find_simplex`` is vectorised over all queries.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.spatial import Delaunay
+from scipy.spatial._qhull import QhullError
+
+__all__ = ["sibson_interpolate"]
+
+_COINCIDE_TOL2 = 1e-18  # (distance)^2 below which a query is "at" a data node
+
+
+def _circumcenters(
+    a: NDArray[np.float64], b: NDArray[np.float64], c: NDArray[np.float64]
+) -> NDArray[np.float64]:
+    """Vectorised circumcentres for triangle vertex arrays (each ``(T, 2)``)."""
+    ax, ay = a[:, 0], a[:, 1]
+    bx, by = b[:, 0], b[:, 1]
+    cx, cy = c[:, 0], c[:, 1]
+    d = 2.0 * (ax * (by - cy) + bx * (cy - ay) + cx * (ay - by))
+    a2 = ax * ax + ay * ay
+    b2 = bx * bx + by * by
+    c2 = cx * cx + cy * cy
+    ux = (a2 * (by - cy) + b2 * (cy - ay) + c2 * (ay - by)) / d
+    uy = (a2 * (cx - bx) + b2 * (ax - cx) + c2 * (bx - ax)) / d
+    return np.column_stack([ux, uy])
+
+
+def _circumcenter1(
+    a: NDArray[np.float64], b: NDArray[np.float64], q: NDArray[np.float64]
+) -> NDArray[np.float64]:
+    """Circumcentre of a single triangle (a, b, q) — for new (inserted) triangles."""
+    ax, ay = float(a[0]), float(a[1])
+    bx, by = float(b[0]), float(b[1])
+    qx, qy = float(q[0]), float(q[1])
+    d = 2.0 * (ax * (by - qy) + bx * (qy - ay) + qx * (ay - by))
+    a2 = ax * ax + ay * ay
+    b2 = bx * bx + by * by
+    q2 = qx * qx + qy * qy
+    ux = (a2 * (by - qy) + b2 * (qy - ay) + q2 * (ay - by)) / d
+    uy = (a2 * (qx - bx) + b2 * (ax - qx) + q2 * (bx - ax)) / d
+    return np.array([ux, uy], dtype=float)
+
+
+def _poly_area(pts: NDArray[np.float64]) -> float:
+    """Area of a convex polygon given its (unordered) vertices.
+
+    The stolen region is convex, so ordering vertices by angle about their
+    centroid recovers the boundary; the shoelace formula then gives the area.
+    """
+    if pts.shape[0] < 3:
+        return 0.0
+    cen = pts.mean(axis=0)
+    ang = np.arctan2(pts[:, 1] - cen[1], pts[:, 0] - cen[0])
+    p = pts[np.argsort(ang)]
+    x, y = p[:, 0], p[:, 1]
+    return 0.5 * abs(float(np.dot(x, np.roll(y, -1)) - np.dot(y, np.roll(x, -1))))
+
+
+def _linear_bary(
+    q: NDArray[np.float64],
+    simplex: NDArray[np.intp],
+    points: NDArray[np.float64],
+    values: NDArray[np.float64],
+) -> float:
+    """Barycentric (piecewise-linear) value in one triangle — degenerate fallback."""
+    a, b, c = points[simplex[0]], points[simplex[1]], points[simplex[2]]
+    mat = np.array([[a[0] - c[0], b[0] - c[0]], [a[1] - c[1], b[1] - c[1]]], dtype=float)
+    try:
+        lam = np.linalg.solve(mat, q - c)
+    except np.linalg.LinAlgError:
+        return float("nan")
+    l0, l1 = float(lam[0]), float(lam[1])
+    l2 = 1.0 - l0 - l1
+    return (
+        l0 * float(values[simplex[0]])
+        + l1 * float(values[simplex[1]])
+        + l2 * float(values[simplex[2]])
+    )
+
+
+def _sibson_one(
+    q: NDArray[np.float64],
+    s0: int,
+    simplices: NDArray[np.intp],
+    neighbors: NDArray[np.intp],
+    points: NDArray[np.float64],
+    values: NDArray[np.float64],
+    centers: NDArray[np.float64],
+    radii2: NDArray[np.float64],
+) -> float:
+    """Sibson-interpolated value at one query point (NaN outside the hull)."""
+    if s0 < 0:
+        return float("nan")  # outside convex hull → extrapolation 'none'
+
+    # Query coincident with a data node → return that node's value exactly
+    # (Sibson's new cell degenerates to zero area here, as at any data site).
+    for vi in simplices[s0]:
+        dx0 = q[0] - points[vi, 0]
+        dy0 = q[1] - points[vi, 1]
+        if dx0 * dx0 + dy0 * dy0 <= _COINCIDE_TOL2:
+            return float(values[vi])
+
+    # Cavity = triangles whose circumcircle contains q (squared-distance test).
+    cavity: set[int] = set()
+    stack = [s0]
+    while stack:
+        t = stack.pop()
+        if t < 0 or t in cavity:
+            continue
+        if t != s0:
+            dx = q[0] - centers[t, 0]
+            dy = q[1] - centers[t, 1]
+            if dx * dx + dy * dy >= radii2[t]:
+                continue
+        cavity.add(t)
+        for nb in neighbors[t]:
+            if nb >= 0 and nb not in cavity:
+                stack.append(int(nb))
+
+    try:
+        # New Voronoi vertices: circumcentre of (edge, q) per cavity boundary edge.
+        cc_new: dict[tuple[int, int], NDArray[np.float64]] = {}
+        for t in cavity:
+            tv = simplices[t]
+            nbrs = neighbors[t]
+            for i in range(3):
+                if int(nbrs[i]) in cavity:
+                    continue
+                a_idx = int(tv[(i + 1) % 3])
+                b_idx = int(tv[(i + 2) % 3])
+                cc_new[(a_idx, b_idx)] = _circumcenter1(points[a_idx], points[b_idx], q)
+
+        neighbours: set[int] = set()
+        for t in cavity:
+            neighbours.update(int(v) for v in simplices[t])
+
+        total = 0.0
+        weighted = 0.0
+        for p_idx in neighbours:
+            verts: list[NDArray[np.float64]] = [
+                centers[t] for t in cavity if p_idx in simplices[t]
+            ]
+            for (a_idx, b_idx), cc in cc_new.items():
+                if p_idx in (a_idx, b_idx):
+                    verts.append(cc)
+            if len(verts) < 3:
+                continue
+            stolen = _poly_area(np.asarray(verts, dtype=float))
+            total += stolen
+            weighted += stolen * float(values[p_idx])
+    except ZeroDivisionError:
+        total = 0.0  # collinear new triangle → fall through to the linear fallback
+
+    if total <= 0.0:  # degenerate (q on a circumcircle / collinear cavity)
+        return _linear_bary(q, simplices[s0], points, values)
+    return weighted / total
+
+
+def sibson_interpolate(
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    zv: NDArray[np.float64],
+    xqv: NDArray[np.float64],
+    yqv: NDArray[np.float64],
+) -> NDArray[np.float64]:
+    """Sibson natural-neighbour interpolation of scattered (xv, yv, zv) at queries.
+
+    Returns NaN outside the convex hull (matching MATLAB ``Extrapolation='none'``)
+    and for collinear/degenerate inputs that cannot be triangulated.
+    """
+    pts = np.column_stack([xv, yv])
+    try:
+        tri = Delaunay(pts)
+    except QhullError:
+        return np.full(xqv.size, np.nan, dtype=float)
+
+    simplices = tri.simplices
+    neighbors = tri.neighbors
+    a = pts[simplices[:, 0]]
+    b = pts[simplices[:, 1]]
+    c = pts[simplices[:, 2]]
+    centers = _circumcenters(a, b, c)
+    radii2 = np.asarray(((a - centers) ** 2).sum(axis=1), dtype=float)
+
+    values = np.asarray(zv, dtype=float)
+    queries = np.column_stack([xqv.ravel(), yqv.ravel()])
+    loc = tri.find_simplex(queries)  # vectorised hull/containment query
+    out = np.empty(queries.shape[0], dtype=float)
+    for k in range(queries.shape[0]):
+        out[k] = _sibson_one(
+            queries[k], int(loc[k]), simplices, neighbors, pts, values, centers, radii2
+        )
+    return out

quantized/calc/aggregate.py

@@ -0,0 +1,159 @@
+"""Multi-dataset aggregation utilities (confidence / spread bands).
+
+Pure calc layer: operates on :class:`DataStruct` inputs, no fastapi/pydantic
+imports. Distinct from ``calc.stats`` (single-vector statistics) — these
+functions combine *several* datasets onto a shared grid.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from scipy.interpolate import PchipInterpolator
+
+from ..datastruct import DataStruct
+from .resample import _interp_column, _sanitize_xy
+
+__all__ = ["confidence_band", "dataset_algebra"]
+
+
+def confidence_band(
+    datasets: list[DataStruct],
+    *,
+    method: str = "mean",
+    channel: int = 0,
+    n_points: int = 0,
+) -> dict[str, Any]:
+    """Pointwise confidence/spread band across N datasets. Port of confidenceBand.
+
+    Each dataset is pchip-interpolated onto a shared grid spanning the
+    *overlapping* x-range (``max`` of the per-set minima to ``min`` of the
+    maxima), then reduced column-wise:
+
+    - ``method='mean'``  : center = nanmean, band = center +/- sample std (ddof=1)
+    - ``method='median'``: center = nanmedian, band = [p25, p75], spread = IQR/2
+
+    ``channel`` is 0-based (MATLAB ``Channel`` is 1-based) and clamped to the last
+    channel. Percentiles use the Hazen plotting position ``(i-0.5)/n`` to match
+    MATLAB ``prctile``. ``n_points=0`` uses the longest input length.
+    """
+    if method not in ("mean", "median"):
+        raise ValueError("method must be mean/median")
+    n_sets = len(datasets)
+    if n_sets < 2:
+        raise ValueError(f"need at least 2 datasets, got {n_sets}")
+
+    x_min, x_max, max_len = -np.inf, np.inf, 0
+    for ds in datasets:
+        xi = np.asarray(ds.time, dtype=float)
+        if not np.isfinite(xi).any():
+            continue  # a fully non-finite x axis contributes no overlap
+        x_min = max(x_min, float(np.nanmin(xi)))
+        x_max = min(x_max, float(np.nanmax(xi)))
+        max_len = max(max_len, int(xi.size))
+    if not np.isfinite([x_min, x_max]).all() or x_min >= x_max:
+        raise ValueError("datasets have no overlapping x-range")
+
+    n_pts = n_points if n_points > 0 else max_len
+    x_common = np.linspace(x_min, x_max, n_pts)
+    y_matrix = np.full((n_pts, n_sets), np.nan)
+    for i, ds in enumerate(datasets):
+        xi = np.asarray(ds.time, dtype=float)
+        vals = np.asarray(ds.values, dtype=float)
+        ch = min(channel, vals.shape[1] - 1)
+        # Sanitize first (drop non-finite, sort, average duplicate x): pchip
+        # rejects NaN and non-strictly-increasing x. No-op on clean data.
+        xs, ys = _sanitize_xy(xi, vals[:, ch])
+        if xs.size < 2:
+            continue  # fewer than 2 finite points — leave this set's column NaN
+        interp = PchipInterpolator(xs, ys, extrapolate=False)
+        y_matrix[:, i] = interp(x_common)
+
+    if method == "mean":
+        center = np.nanmean(y_matrix, axis=1)
+        spread = np.nanstd(y_matrix, axis=1, ddof=1)
+        upper = center + spread
+        lower = center - spread
+    else:  # median
+        center = np.nanmedian(y_matrix, axis=1)
+        q25 = np.nanpercentile(y_matrix, 25, axis=1, method="hazen")
+        q75 = np.nanpercentile(y_matrix, 75, axis=1, method="hazen")
+        upper, lower = q75, q25
+        spread = (q75 - q25) / 2.0
+
+    return {
+        "x": x_common,
+        "center": center,
+        "upper": upper,
+        "lower": lower,
+        "spread": spread,
+        "method": method,
+        "nSets": n_sets,
+    }
+
+
+_ALGEBRA_OPS = ("A+B", "A-B", "A*B", "A/B", "(A-B)/(A+B)")
+
+
+def _safe_label(ds: DataStruct, ch: int) -> str:
+    return ds.labels[ch] if ch < len(ds.labels) else f"ch{ch + 1}"
+
+
+def _safe_unit(ds: DataStruct, ch: int) -> str:
+    return ds.units[ch] if ch < len(ds.units) else ""
+
+
+def dataset_algebra(
+    ds_a: DataStruct,
+    ds_b: DataStruct,
+    operation: str,
+    *,
+    interp_method: str = "pchip",
+    channel_a: int = 0,
+    channel_b: int = 0,
+) -> DataStruct:
+    """Combine two datasets pointwise on A's x-grid. Port of utilities.datasetAlgebra.
+
+    B is interpolated onto A's time axis (``interp_method`` = pchip/linear/spline,
+    NaN outside B's range) and combined via ``operation`` (``A+B``, ``A-B``,
+    ``A*B``, ``A/B``, ``(A-B)/(A+B)``). Division/asymmetry guard zeros with NaN.
+    ``channel_a``/``channel_b`` are 0-based and clamped to the last channel.
+    """
+    if operation not in _ALGEBRA_OPS:
+        raise ValueError(f"operation must be one of {_ALGEBRA_OPS}")
+    xa = np.asarray(ds_a.time, dtype=float).ravel()
+    xb = np.asarray(ds_b.time, dtype=float).ravel()
+    va = np.asarray(ds_a.values, dtype=float)
+    vb = np.asarray(ds_b.values, dtype=float)
+    ch_a = min(channel_a, va.shape[1] - 1)
+    ch_b = min(channel_b, vb.shape[1] - 1)
+    ya = va[:, ch_a]
+    yb = _interp_column(xb, vb[:, ch_b], xa, interp_method, False)
+
+    la, lb = _safe_label(ds_a, ch_a), _safe_label(ds_b, ch_b)
+    unit_a = _safe_unit(ds_a, ch_a)
+    if operation == "A+B":
+        y_result, label, unit = ya + yb, f"{la} + {lb}", unit_a
+    elif operation == "A-B":
+        y_result, label, unit = ya - yb, f"{la} - {lb}", unit_a
+    elif operation == "A*B":
+        y_result, label, unit = ya * yb, f"{la} × {lb}", f"{unit_a}²"
+    elif operation == "A/B":
+        with np.errstate(divide="ignore", invalid="ignore"):
+            y_result = ya / yb
+        y_result[yb == 0] = np.nan
+        label, unit = f"{la} / {lb}", "ratio"
+    else:  # (A-B)/(A+B)
+        denom = ya + yb
+        with np.errstate(divide="ignore", invalid="ignore"):
+            y_result = (ya - yb) / denom
+        y_result[denom == 0] = np.nan
+        label = f"({la} - {lb}) / ({la} + {lb})"
+        unit = "asymmetry"
+
+    meta: dict[str, Any] = {}
+    if "source" in ds_a.metadata:
+        meta["source"] = ds_a.metadata["source"]
+    meta["operation"] = operation
+    return DataStruct.create(xa, y_result, labels=[label], units=[unit], metadata=meta)