plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/kernels.py

@@ -0,0 +1,740 @@
+"""Numeric kernels in plot_io's C library (``plot_io/_native``), on arrays.
+
+Arguments are sequences of numbers (``None`` for missing values) or any object exporting
+the buffer protocol (``array.array``, ``memoryview``, numpy arrays, ...).  Buffers are read
+through :class:`memoryview` and converted in C; numpy is never imported.  1-D intake is
+vec_io's :func:`vec_io.arrays.doubles` (re-exported as :func:`doubles`, with
+:func:`rows`, :func:`grid` and :func:`buffer_shape` for 2-D and 3-D buffers).
+
+:func:`scaled` (values through a function and an affine map), :func:`extent`,
+:func:`quantiles`, :func:`box_stats`; binning (:func:`histogram`, :func:`bin_edges`,
+:func:`histogram2d`, :func:`hexbin`, :func:`ecdf`), kernel densities (:func:`kde`,
+:func:`bandwidth`; 2-D: :func:`kde2d_at`, :func:`kde2d_grid`, :func:`kde2d_bandwidth`),
+contours (:func:`contour_lines`, :func:`contour_bands`), :func:`lowess`, :func:`swarm`,
+:func:`argsort` and :func:`take`; hierarchical clustering (:func:`linkage`).  Heatmap cells are mapped by :meth:`plot_io.ColorMap.cells`.
+"""
+
+import array
+import bisect
+import ctypes
+import math
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+from vec_io import threads
+from vec_io.arrays import buffer_shape, doubles, grid, rows
+
+from ._native import kernels as _k
+
+
+__all__ = ["doubles", "buffer_shape", "rows", "grid", "scaled", "extent", "quantiles",
+           "box_stats", "BoxStats", "histogram", "bin_edges", "histogram2d", "hexbin", "ecdf",
+           "kde", "bandwidth", "kde2d_bandwidth", "kde2d_at", "kde2d_grid", "contour_lines",
+           "contour_bands", "lowess", "swarm", "argsort", "take", "linkage", "LINKAGE_METHODS",
+           "LINKAGE_METRICS"]
+
+def scaled(values: Any, scale: float = 1.0, offset: float = 0.0, function: str | None = None,
+           low: float | None = None, high: float | None = None, under: float | None = None,
+           over: float | None = None, nan: float | None = None,
+           linthresh: float = 1.0, below: float | None = None,
+           above: float | None = None) -> array.array:
+    """``scale * f(v) + offset`` for every value, as ``array('d')``.
+
+    ``function``: ``None``, ``"log"`` (natural), ``"log2"``, ``"log10"``, ``"sqrt"``,
+    ``"exp"``, ``"symlog"`` (``sign(v) log10(1 + |v| / linthresh)``) or ``"logit"``
+    (``log10(p / (1 - p))``, for 0 < p < 1).  Missing values, values outside the function's domain and results that are not
+    finite become NaN, or ``nan`` when it is given.  Other results below ``low`` become
+    ``under`` (default ``low``: clamped) and results above ``high`` become ``over`` (default
+    ``high``); NaN as ``under`` or ``over`` makes those values missing.  ``below`` and
+    ``above``, when given, replace the results of finite values below the function's domain
+    (``log``: ≤ 0, ``sqrt``: < 0, ``logit``: ≤ 0) and above it (``logit``: ≥ 1, ``exp``:
+    overflowing)."""
+    low_ = -math.inf if low is None else float(low)
+    high_ = math.inf if high is None else float(high)
+    return _k.scaled(doubles(values), float(scale), float(offset), function, low_, high_,
+                        low_ if under is None else float(under),
+                        high_ if over is None else float(over),
+                        None if nan is None else float(nan), float(linthresh),
+                        None if below is None else float(below),
+                        None if above is None else float(above))
+
+
+def extent(values: Any, function: str | None = None) -> tuple[int, float, float]:
+    """``(count, min, max)`` of the finite values in the domain of ``function`` (names as in
+    :func:`scaled`); ``(0, nan, nan)`` when there are none."""
+    return _k.extent(doubles(values), function)
+
+
+def quantiles(values: Any, qs: Any, weights: Any = None) -> list[float]:
+    """Quantiles ``qs`` (each in [0, 1]) of the finite values, by linear interpolation between
+    closest ranks (numpy's default); NaN for each when there are no finite values.
+
+    ``weights`` count as repeated values (integer weights give the quantiles of the values
+    repeated): Hmisc's ``wtd.quantile`` (type ``"quantile"``), positions ``1 + (n - 1) q``
+    on the cumulative weights, ``n`` their total."""
+    qs = [float(q) for q in qs]
+    if weights is None:
+        return _k.quantiles(doubles(values), qs)
+    if not all(0.0 <= q <= 1.0 for q in qs):
+        raise ValueError("each q must be in [0, 1]")
+    xs, cw = _weighted_sorted(values, weights)
+    return [_weighted_quantile(xs, cw, q) for q in qs]
+
+
+def _weighted_sorted(values: Any, weights: Any) -> tuple[list[float], list[float]]:
+    """The finite values of positive weight, sorted, and their cumulative weights."""
+    v = doubles(values)
+    w = _weights(weights, len(v))
+    assert w is not None
+    xs: list[float] = []
+    cw: list[float] = []
+    total = 0.0
+    for i in argsort(v):
+        x, wi = v[i], w[i]
+        if wi > 0 and math.isfinite(x):
+            total += wi
+            xs.append(x)
+            cw.append(total)
+    return xs, cw
+
+
+def _weighted_quantile(xs: list[float], cw: list[float], q: float) -> float:
+    """Quantile ``q`` of sorted values ``xs`` with cumulative weights ``cw``: the value at
+    (1-based) position ``r`` is the first whose cumulative weight reaches ``r``, positions
+    clamped to the ends; between the positions ``floor`` and ``floor + 1`` of
+    ``1 + (n - 1) q``, linear as :func:`quantiles` (integer weights: equal to the values
+    repeated)."""
+    if not xs:
+        return math.nan
+    n = cw[-1]
+
+    def at(r: float) -> float:
+        return xs[min(bisect.bisect_left(cw, r), len(xs) - 1)]
+
+    h = (n - 1.0) * q
+    lo = math.floor(h)
+    t = h - lo
+    if lo < 0:                          # a weight total below 1
+        order = 1.0 + h
+        a, b, t = at(1.0), at(min(2.0, n)), order % 1.0
+        return (1.0 - t) * a + t * b
+    a = at(lo + 1.0)
+    if lo + 1.0 >= n or t == 0:
+        return a
+    b = at(min(lo + 2.0, n))
+    d = b - a
+    return b - d * (1.0 - t) if t >= 0.5 else a + d * t
+
+
+@dataclass(frozen=True)
+class BoxStats:
+    """Box-plot statistics of the finite values (NaN fields when there are none)."""
+    count: float         # with weights: their total
+    mean: float
+    q1: float
+    median: float
+    q3: float
+    low: float           # whisker ends
+    high: float
+    outliers: array.array   # values outside [low, high], in data order
+
+
+def box_stats(values: Any, whiskers: Any = 1.5, weights: Any = None) -> BoxStats:
+    """Quartiles, median, mean, whisker ends and outliers of the finite values.
+
+    ``whiskers``: a number w (whiskers at the furthest data within w * IQR of the box),
+    ``"range"`` (the minimum and maximum) or ``(low, high)`` percentiles (0-100).
+    ``weights`` count as repeated values (quantiles as :func:`quantiles`); values of weight
+    0 are left out, and each outlier is listed once."""
+    if isinstance(whiskers, str):
+        if whiskers != "range":
+            raise ValueError(f"whiskers must be a number, 'range' or (low, high), not {whiskers!r}")
+        mode, a, b = 1, 0.0, 0.0
+    elif isinstance(whiskers, (tuple, list)):
+        if len(whiskers) != 2:
+            raise ValueError("whisker percentiles must be a (low, high) pair")
+        mode, a, b = 2, float(whiskers[0]), float(whiskers[1])
+    else:
+        mode, a, b = 0, float(whiskers), 0.0
+    if weights is not None:
+        return _weighted_box_stats(values, weights, mode, a, b)
+    count, out, outliers = _k.box_stats(doubles(values), mode, a, b)
+    mean, q1, median, q3, low, high = out
+    return BoxStats(count, mean, q1, median, q3, low, high, outliers)
+
+
+_SPLIT = 134217729.0                    # 2^27 + 1
+
+
+def _two_product(a: float, b: float) -> tuple[float, float]:
+    """``(p, e)`` with ``p + e == a * b`` exactly (Dekker; ``e`` 0 when not finite)."""
+    p = a * b
+    c = _SPLIT * a
+    ah = c - (c - a)
+    al = a - ah
+    c = _SPLIT * b
+    bh = c - (c - b)
+    bl = b - bh
+    e = ((ah * bh - p) + ah * bl + al * bh) + al * bl
+    return p, (e if math.isfinite(e) else 0.0)
+
+
+def _weighted_box_stats(values: Any, weights: Any, mode: int, a: float, b: float) -> BoxStats:
+    if mode == 0 and not a >= 0:
+        raise ValueError("whiskers must be at least 0 IQR")
+    if mode == 2 and not 0 <= a <= b <= 100:
+        raise ValueError("whisker percentiles 0 <= low <= high <= 100")
+    v = doubles(values)
+    w = _weights(weights, len(v))
+    assert w is not None
+    xs, cw = _weighted_sorted(v, w)
+    nan = math.nan
+    if not xs:
+        return BoxStats(0, nan, nan, nan, nan, nan, nan, array.array("d"))
+    total = cw[-1]
+    parts: list[float] = []             # w x exactly, as two doubles each
+    for x, wi in zip(v, w):
+        if wi > 0 and math.isfinite(x):
+            parts += _two_product(wi, x)
+    mean = math.fsum(parts) / total
+    q1, median, q3 = (_weighted_quantile(xs, cw, q) for q in (0.25, 0.5, 0.75))
+    if mode == 1:
+        low, high = xs[0], xs[-1]
+    elif mode == 2:
+        low, high = _weighted_quantile(xs, cw, a / 100.0), _weighted_quantile(xs, cw, b / 100.0)
+    else:
+        iqr = q3 - q1
+        lo_fence, hi_fence = q1 - a * iqr, q3 + a * iqr
+        i = min(bisect.bisect_left(xs, lo_fence), len(xs) - 1)
+        j = max(bisect.bisect_right(xs, hi_fence) - 1, 0)
+        low, high = min(xs[i], q1), max(xs[j], q3)
+    outliers = array.array("d", (x for x, wi in zip(v, w)
+                                 if wi > 0 and math.isfinite(x) and (x < low or x > high)))
+    count = int(total) if total.is_integer() else total
+    return BoxStats(count, mean, q1, median, q3, low, high, outliers)
+
+
+def _weights(weights: Any, n: int) -> array.array | None:
+    if weights is None:
+        return None
+    w = doubles(weights)
+    if len(w) != n:
+        raise ValueError(f"{len(w)} weights for {n} values")
+    if n:
+        total = sum(w)
+        if not math.isfinite(total) or min(w) < 0 or total <= 0:
+            raise ValueError("weights must be finite and non-negative, with a positive sum")
+    return w
+
+
+def _edges(edges: Any) -> array.array:
+    e = doubles(edges)
+    if len(e) < 2:
+        raise ValueError("at least 2 bin edges are needed")
+    return e
+
+
+def histogram(values: Any, edges: Any, weights: Any = None) -> array.array:
+    """Counts (sums of ``weights``) of the values in each bin between increasing ``edges``:
+    ``edges[k] <= v < edges[k + 1]``, the last bin closed, as numpy's ``histogram``.  NaN
+    values and values outside the edges are not counted."""
+    v = doubles(values)
+    return _k.histogram(v, _edges(edges), _weights(weights, len(v)))
+
+
+_RULES = ("auto", "fd", "sturges", "scott", "sqrt", "rice", "doane")
+
+#: The most bins :func:`bin_edges` makes.
+MAX_BINS = 1_000_000
+
+
+def bin_edges(values: Any, rule: Any = "auto", range: Any = None) -> array.array:
+    """Even bin edges for ``values``: ``rule`` is a count of bins or one of numpy's rules
+    (``auto``, ``fd``, ``sturges``, ``scott``, ``sqrt``, ``rice``, ``doane``), over
+    ``range`` (default: the finite values' span).  The rules give numpy's results; when every
+    finite value is a whole number, a rule's bin width is at least 1.  Values outside ``range`` are left out of the rule; NaN values are ignored.  A
+    rule asking for more than :data:`MAX_BINS` bins raises ``ValueError``, and so does a
+    count of bins narrower than the floats of the span can tell apart; a span that is not
+    finite gives one bin.  Constant values span 0.5 on each side (more where floats are
+    coarser)."""
+    count_given = isinstance(rule, int) and not isinstance(rule, bool)
+    if count_given:
+        if not 1 <= rule <= MAX_BINS:
+            raise ValueError(f"bins must be between 1 and {MAX_BINS}, not {rule}")
+    elif rule not in _RULES:
+        raise ValueError(f"unknown bin rule {rule!r} (use {', '.join(_RULES)})")
+    v = doubles(values)
+    if range is not None:
+        first, last = float(range[0]), float(range[1])
+        if not (math.isfinite(first) and math.isfinite(last) and first < last):
+            raise ValueError(f"range must be finite (low, high) with low < high, not "
+                             f"{tuple(range)}")
+        if not count_given:
+            v = scaled(v, 1.0, 0.0, None, first, last, math.nan, math.nan)
+    count, lo, hi = _k.extent(v, None)
+    if range is None:
+        if not count:
+            first, last = 0.0, 1.0
+        else:
+            first, last = lo, hi
+    constant = first == last
+    if constant:                          # wide enough for its bins to increase
+        half = max(0.5, (rule if count_given else 1) * 2.0 * math.ulp(first))
+        first, last = first - half, last + half
+    span = last - first
+    if not math.isfinite(span):
+        return array.array("d", [first, last])
+    n_bins = 1
+    if count_given:
+        n_bins = rule
+    elif count and not constant:
+        width = _bin_width(v, rule, count, hi - lo)
+        if width < 1 and all(map(float.is_integer, filter(math.isfinite, v))):
+            width = 1.0                       # whole numbers: no bin narrower than 1
+        if width:                             # no bin narrower than the floats there
+            width = max(width, 4.0 * math.ulp(max(-first, last)))
+        if width and math.isfinite(width):
+            bins = math.ceil(span / width)
+            if bins > MAX_BINS:
+                raise ValueError(f"bins={rule!r} asks for {bins:.3g} bins (at most "
+                                 f"{MAX_BINS}); give a count or another rule")
+            n_bins = max(1, int(bins))
+    step = span / n_bins
+    edges = array.array("d", [first + i * step for i in _range(n_bins + 1)])
+    edges[-1] = last
+    if step < 4.0 * math.ulp(max(-first, last)) and any(
+            a >= b for a, b in zip(edges, edges[1:])):
+        raise ValueError(f"{n_bins} bins over the range {first!r} to {last!r} are "
+                         f"narrower than its floats can tell apart; give fewer bins")
+    return edges
+
+
+_range = range
+
+
+def _bin_width(v: array.array, rule: str, n: int, ptp: float) -> float:
+    if rule == "sqrt":
+        return ptp / math.sqrt(n)
+    if rule == "sturges":
+        return ptp / (math.log2(n) + 1.0)
+    if rule == "rice":
+        return ptp / (2.0 * n ** (1.0 / 3))
+    if rule in ("scott", "doane"):
+        unit = 1.0
+        if ptp and not 2.0 ** -256 < ptp < 2.0 ** 256:    # moments in a unit of about ptp
+            unit = math.ldexp(1.0, math.frexp(ptp)[1])  # (a power of 2: exact scaling)
+            v = scaled(v, 1.0 / unit)
+        _, sw, _, mean, m2, m3 = _k.moments(v, None)
+        sigma = math.sqrt(m2 / sw) if sw else 0.0
+        if rule == "scott":
+            return (24.0 * math.pi ** 0.5 / n) ** (1.0 / 3.0) * sigma * unit
+        if n > 2 and sigma > 0:
+            sg1 = math.sqrt(6.0 * (n - 2) / ((n + 1.0) * (n + 3)))
+            g1 = m3 / sw / sigma ** 3
+            return ptp / (1.0 + math.log2(n) + math.log2(1.0 + abs(g1) / sg1))
+        return 0.0
+    q75, q25 = _k.quantiles(v, [0.75, 0.25])
+    fd = 2.0 * (q75 - q25) * n ** (-1.0 / 3.0)
+    if rule == "fd":
+        return fd
+    sturges = ptp / (math.log2(n) + 1.0)
+    return min(max(fd, ptp / math.sqrt(n) / 2), sturges)     # numpy 2: at most ~2 sqrt(n) bins
+
+
+def histogram2d(x: Any, y: Any, x_edges: Any, y_edges: Any,
+                weights: Any = None) -> tuple[int, int, array.array]:
+    """2-D counts as ``(rows, columns, array('d'))``, rows over the y bins (bins as in
+    :func:`histogram`); pairs with a NaN are not counted."""
+    xv, yv = doubles(x), doubles(y)
+    if len(xv) != len(yv):
+        raise ValueError("x and y must have the same length")
+    xe, ye = _edges(x_edges), _edges(y_edges)
+    out = _k.histogram2d(xv, yv, _weights(weights, len(xv)), xe, ye)
+    return len(ye) - 1, len(xe) - 1, out
+
+
+def hexbin(x: Any, y: Any, x0: float, y0: float, dx: float, dy: float, nx: int, ny: int,
+           weights: Any = None) -> tuple[array.array, array.array, array.array]:
+    """Hexagonal binning: ``(centres_x, centres_y, counts)`` of the non-empty cells.
+
+    The cells are those of two offset lattices: centres ``(x0 + i dx, y0 + j dy)`` and
+    ``(x0 + (i + 1/2) dx, y0 + (j + 1/2) dy)`` for ``i < nx``, ``j < ny``; each point goes to
+    the nearest centre.  With ``dy = sqrt(3) dx`` the cells are regular hexagons of width
+    ``dx`` (corner to corner ``2 dx / sqrt(3)``), so pass coordinates in page units."""
+    xv, yv = doubles(x), doubles(y)
+    if len(xv) != len(yv):
+        raise ValueError("x and y must have the same length")
+    nx, ny = int(nx), int(ny)
+    counts = _k.hexbin(xv, yv, _weights(weights, len(xv)), float(x0), float(y0), float(dx),
+                         float(dy), nx, ny)
+    cx, cy, cc = array.array("d"), array.array("d"), array.array("d")
+    cells = nx * ny
+    for k, c in enumerate(counts):
+        if c:
+            j, i = divmod(k % cells, nx)
+            off = 0.5 if k >= cells else 0.0
+            cx.append(x0 + (i + off) * dx)
+            cy.append(y0 + (j + off) * dy)
+            cc.append(c)
+    return cx, cy, cc
+
+
+def ecdf(values: Any, weights: Any = None) -> tuple[array.array, array.array]:
+    """``(sorted values, cumulative weights)`` of the finite values (weights default to 1:
+    the cumulative counts); divide by the last for proportions."""
+    v = doubles(values)
+    return _k.ecdf(v, _weights(weights, len(v)))
+
+
+def bandwidth(values: Any, rule: str = "scott", weights: Any = None) -> float:
+    """Gaussian kernel bandwidth by Scott's (``n^(-1/5)``) or Silverman's
+    (``(3n/4)^(-1/5)``) rule times the unbiased standard deviation, as scipy's
+    ``gaussian_kde``.  Weights count as repeated values: ``n`` is their total.  NaN when
+    fewer than 2 values (a weight total of at most 1)."""
+    if rule not in ("scott", "silverman"):
+        raise ValueError(f"unknown bandwidth rule {rule!r} (use 'scott' or 'silverman')")
+    v = doubles(values)
+    count, sw, _, _, m2, _ = _k.moments(v, _weights(weights, len(v)))
+    if count < 2 or not sw > 1:
+        return math.nan
+    var = m2 / (sw - 1)
+    factor = sw ** -0.2 if rule == "scott" else (sw * 0.75) ** -0.2
+    return factor * math.sqrt(var)
+
+
+def kde(values: Any, grid_min: float, grid_max: float, n: int, bandwidth: float,
+        weights: Any = None, cumulative: bool = False) -> array.array:
+    """Gaussian kernel density of the finite values at ``n`` points evenly spaced over
+    ``[grid_min, grid_max]``; it integrates to 1 over the real line.  ``cumulative``: the
+    integral from minus infinity instead.  Each kernel is cut at 5 bandwidths, so the
+    density is 0 farther than that from every value.  Direct sums when the kernel is narrow
+    against the grid spacing or the work is small; otherwise linear binning and convolution
+    (relative error below 1e-4 when the bandwidth is at least twice the spacing)."""
+    v = doubles(values)
+    return _k.kde(v, _weights(weights, len(v)), float(grid_min), float(grid_max), int(n),
+                    float(bandwidth), cumulative)
+
+
+_grid = grid
+
+
+def _contour_grid(grid: Any, w: int, h: int, xs: Any, ys: Any):
+    shape = buffer_shape(grid)
+    if shape is not None and len(shape) == 2:
+        g = _grid(grid)[3]
+    elif not isinstance(grid, array.array) and grid is not None and len(grid) and \
+            not isinstance(grid[0], (int, float)) and grid[0] is not None:
+        g = array.array("d", [math.nan if v is None else float(v) for row in grid for v in row])
+    else:
+        g = doubles(grid)
+    w, h = int(w), int(h)
+    if w < 2 or h < 2 or len(g) != w * h:
+        raise ValueError(f"a grid of w x h values is needed (w, h >= 2; got {len(g)} for "
+                         f"{w} x {h})")
+    xv = doubles(xs) if xs is not None else array.array("d", map(float, range(w)))
+    yv = doubles(ys) if ys is not None else array.array("d", map(float, range(h)))
+    if len(xv) != w or len(yv) != h:
+        raise ValueError("xs needs w values and ys h values (the node coordinates)")
+    return g, w, h, xv, yv
+
+
+def contour_lines(grid: Any, w: int, h: int, xs: Any = None, ys: Any = None,
+                  level: float = 0.0) -> list[tuple[array.array, array.array, bool]]:
+    """Contour lines of ``level`` on a ``w`` x ``h`` grid (rows over y; a 2-D buffer,
+    nested rows or ``w * h`` values) with nodes at ``xs[i]``, ``ys[j]``: a list of
+    ``(x, y, closed)``.
+
+    Marching squares, a node being above the level when ``v >= level``; saddles are resolved
+    by the cell's mean; cells with a NaN node are skipped (lines stop there)."""
+    g, w, h, xv, yv = _contour_grid(grid, w, h, xs, ys)
+    pts, starts, closed = _k.contour_lines(g, w, h, xv, yv, float(level))
+    lines = []
+    for k in range(len(closed)):
+        a, b = starts[k], starts[k + 1]
+        lines.append((pts[2 * a:2 * b:2], pts[2 * a + 1:2 * b:2], bool(closed[k])))
+    return lines
+
+
+def contour_bands(grid: Any, w: int, h: int, xs: Any = None, ys: Any = None,
+                  lo: float = -math.inf,
+                  hi: float = math.inf) -> tuple[array.array, array.array, array.array]:
+    """The region ``lo <= v < hi`` of a grid (as :func:`contour_lines`) as its outline
+    ``(xs, ys, ring_starts)`` (``ring_starts`` holds each ring's first index plus the total):
+    closed rings with the band on their left, holes included, to fill together in one path
+    with the nonzero rule.  The rings follow the contour lines of ``lo`` and ``hi`` and the
+    border of the data; cells with a NaN node are left out."""
+    g, w, h, xv, yv = _contour_grid(grid, w, h, xs, ys)
+    pts, starts = _k.contour_bands(g, w, h, xv, yv, float(lo), float(hi))
+    return pts[0::2], pts[1::2], starts
+
+
+def lowess(x: Any, y: Any, frac: float = 2.0 / 3.0, iterations: int = 3,
+           delta: Any = "auto") -> array.array:
+    """LOWESS fit at each x (input order; NaN for pairs with a NaN): local linear fits over
+    the ``floor(frac n)`` nearest points (at least 2) of the ``n`` complete pairs, with
+    tricube weights as in statsmodels, then ``iterations`` robust passes with bisquare
+    weights of the residuals.  As statsmodels' ``delta``, points within ``delta`` of the
+    last fitted x are interpolated instead of fitted; ``"auto"`` is 0 up to 10,000 pairs
+    and 1 % of the x range above."""
+    xv, yv = doubles(x), doubles(y)
+    if len(xv) != len(yv):
+        raise ValueError("x and y must have the same length")
+    if delta == "auto":
+        finite = [v for v, w in zip(xv, yv) if math.isfinite(v) and math.isfinite(w)]
+        delta = 0.01 * (max(finite) - min(finite)) if len(finite) > 10_000 else 0.0
+    return _k.lowess(xv, yv, float(frac), int(iterations), float(delta))
+
+
+def swarm(positions: Any, size: Any, slot_width: float) -> tuple[array.array, int]:
+    """Swarm layout: offsets across the value axis (input order) for markers of diameter
+    ``size`` (one value or one per point) centred at ``positions``, so that none overlap,
+    and the number of points clamped to half the ``slot_width``.  Use page units.  NaN
+    positions get NaN offsets."""
+    p = doubles(positions)
+    if isinstance(size, (int, float)):
+        sizes, uniform = array.array("d", [float(size)]), True
+    else:
+        sizes, uniform = doubles(size), False
+        if len(sizes) != len(p):
+            raise ValueError(f"{len(sizes)} sizes for {len(p)} positions")
+    if not len(p):
+        return array.array("d"), 0
+    if len(p) < 20_000:
+        return _k.swarm(p, sizes, uniform, float(slot_width))
+    return _interruptible(_k.swarm, p, sizes, uniform, float(slot_width))
+
+
+def _interruptible(fn: Any, *args: Any) -> Any:
+    """``fn(*args)`` (a native call that can run for seconds) on a thread while this one
+    waits, so that Ctrl-C interrupts the wait; the abandoned call ends on its own."""
+    import threading
+    result: list[Any] = []
+    error: list[BaseException] = []
+
+    def run() -> None:
+        try:
+            result.append(fn(*args))
+        except BaseException as e:            # raised again on the waiting thread
+            error.append(e)
+
+    t = threading.Thread(target=run, name="plot_io-native", daemon=True)
+    t.start()
+    t.join()
+    if error:
+        raise error[0]
+    return result[0]
+
+
+def _xy_weights(x: Any, y: Any, weights: Any) -> tuple[array.array, array.array,
+                                                         array.array | None]:
+    xa, ya = doubles(x), doubles(y)
+    if len(xa) != len(ya):
+        raise ValueError("x and y must have the same length")
+    return xa, ya, _weights(weights, len(xa))
+
+
+def kde2d_bandwidth(x: Any, y: Any, rule: str = "scott",
+                    weights: Any = None) -> tuple[float, float, float]:
+    """Kernel covariance ``(h11, h12, h22)`` of a 2-D Gaussian density, as scipy's
+    ``gaussian_kde``: the unbiased data covariance times the squared factor ``n^(-1/6)``
+    (Scott's and Silverman's rules agree in 2-D).  Weights count as repeated points: ``n``
+    is their total.  A singular covariance (collinear points) falls back to an isotropic
+    kernel from the larger variance.  NaN when fewer than 2 points (a weight total of at
+    most 1), or all equal."""
+    if rule not in ("scott", "silverman"):
+        raise ValueError(f"unknown bandwidth rule {rule!r} (use 'scott' or 'silverman')")
+    xa, ya, w = _xy_weights(x, y, weights)
+    count, sw, _, _, _, cxx, cyy, cxy = _k.moments2(xa, ya, w)
+    nan = (math.nan, math.nan, math.nan)
+    if count < 2 or not sw > 1:
+        return nan
+    d = sw - 1
+    vxx, vyy, vxy = cxx / d, cyy / d, cxy / d
+    f2 = sw ** (-1.0 / 3.0)                     # (n^(-1/6))^2
+    if not (vxx * vyy - vxy * vxy > 1e-12 * vxx * vyy) or vxx <= 0 or vyy <= 0:
+        v = max(vxx, vyy)
+        return (v * f2, 0.0, v * f2) if v > 0 else nan
+    return vxx * f2, vxy * f2, vyy * f2
+
+
+def _kde2d_h(bandwidth: Any, x: array.array, y: array.array,
+             w: array.array | None) -> tuple[float, float, float]:
+    if isinstance(bandwidth, str):
+        return kde2d_bandwidth(x, y, bandwidth, w)
+    if isinstance(bandwidth, (int, float)):
+        s = float(bandwidth)
+        return s * s, 0.0, s * s
+    h = tuple(float(v) for v in bandwidth)
+    if len(h) != 3:
+        raise ValueError("bandwidth: a rule name, a standard deviation, or (h11, h12, h22)")
+    return h
+
+
+#: Above this many points, ``method="auto"`` evaluates through the lattice.
+KDE2D_EXACT_MAX = 20000
+
+
+def kde2d_at(x: Any, y: Any, bandwidth: Any = "scott", method: str = "auto", grid: int = 512,
+             weights: Any = None) -> array.array:
+    """Gaussian kernel density of the points ``(x, y)`` at the points themselves, as
+    ``gaussian_kde(np.array([x, y]))(np.array([x, y]))``.
+
+    ``bandwidth``: a rule (``"scott"``, ``"silverman"``; see :func:`kde2d_bandwidth`), a
+    standard deviation (isotropic kernel), or a kernel covariance ``(h11, h12, h22)``.
+    ``method``: ``"exact"`` (direct sums on the worker threads; terms below ``e^-40`` of
+    their weight are left out), ``"grid"`` (a lattice of at least ``grid`` points per side,
+    up to 2048 to keep its spacing at most 0.1 kernel widths: relative error about 1e-4,
+    at most a few 1e-3) or ``"auto"`` (exact up to 20,000 points).  Points with a missing
+    coordinate are not sources and get NaN."""
+    if method not in ("auto", "exact", "grid"):
+        raise ValueError(f"unknown method {method!r} (use 'auto', 'exact' or 'grid')")
+    xa, ya, w = _xy_weights(x, y, weights)
+    h = _kde2d_h(bandwidth, xa, ya, w)
+    if not all(math.isfinite(v) for v in h):
+        raise ValueError("kde2d_at: no bandwidth (fewer than 2 distinct points)")
+    n = len(xa)
+    exact = method == "exact" or (method == "auto" and n <= KDE2D_EXACT_MAX)
+    if not exact:
+        return _k.kde2d(xa, ya, w, h, xa, ya, int(grid))
+    step = 512
+    if n <= step:
+        return _k.kde2d(xa, ya, w, h, xa, ya)
+    parts = threads.map_ordered(
+        lambda i: _k.kde2d(xa, ya, w, h, xa[i:i + step], ya[i:i + step]),
+        range(0, n, step))
+    out = array.array("d")
+    for part in parts:
+        out.extend(part)
+    return out
+
+
+def kde2d_grid(x: Any, y: Any, bandwidth: Any, x0: float, x1: float, nx: int, y0: float,
+               y1: float, ny: int, weights: Any = None, grid: int = 512) -> array.array:
+    """The density of :func:`kde2d_at` (through the lattice) on a regular ``ny`` x ``nx``
+    grid: row ``j`` at ``y0 + j (y1 - y0) / (ny - 1)``, column ``i`` likewise; row-major."""
+    xa, ya, w = _xy_weights(x, y, weights)
+    h = _kde2d_h(bandwidth, xa, ya, w)
+    if not all(math.isfinite(v) for v in h):
+        raise ValueError("kde2d_grid: no bandwidth (fewer than 2 distinct points)")
+    nx, ny = int(nx), int(ny)
+    if nx < 1 or ny < 1:
+        raise ValueError("kde2d_grid: nx and ny must be at least 1")
+    gx = [x0 + (x1 - x0) * i / (nx - 1) if nx > 1 else x0 for i in range(nx)]
+    gy = [y0 + (y1 - y0) * j / (ny - 1) if ny > 1 else y0 for j in range(ny)]
+    tx = array.array("d", gx * ny)
+    ty = array.array("d", (v for v in gy for _ in range(nx)))
+    return _k.kde2d(xa, ya, w, h, tx, ty, int(grid))
+
+
+def argsort(values: Any, descending: bool = False) -> array.array:
+    """Indices that sort the values (``array('q')``), stable: ascending with NaN first, or
+    descending with NaN last; -0 equals 0."""
+    return _k.argsort(doubles(values), bool(descending))
+
+
+_INTEGER_FORMATS = frozenset("bBhHiIlLqQnN")
+
+
+def _numeric_view(value):
+    """A memoryview of ``value`` when it has a numeric buffer, else ``None``."""
+    if buffer_shape(value) is None:
+        return None
+    return memoryview(value)
+
+
+def _indices(indices: Any) -> array.array:
+    """``indices`` as ``array('q')``; 8-byte integer buffers are read without a copy loop."""
+    if isinstance(indices, array.array) and indices.typecode == "q":
+        return indices
+    mv = _numeric_view(indices)
+    if mv is not None:
+        if mv.ndim != 1:
+            raise ValueError("take: indices must be 1-D")
+        fmt = mv.format.lstrip("@=<>!")
+        native = mv.format[0] not in "<>!" or (mv.format[0] == "<") == (sys.byteorder == "little")
+        if fmt in ("q", "l", "n") and mv.itemsize == 8 and native:
+            out = array.array("q")
+            out.frombytes(mv.cast("B") if mv.c_contiguous else mv.tobytes())
+            return out
+        if fmt in _INTEGER_FORMATS:
+            return array.array("q", mv.tolist())
+        raise TypeError("take: indices must be integers")
+    try:
+        return array.array("q", indices)
+    except TypeError:
+        raise TypeError("take: indices must be integers") from None
+    except OverflowError:
+        raise IndexError("take: index out of range") from None
+
+
+def take(values: Any, indices: Any) -> array.array:
+    """``values[indices]`` as ``array('d')``, gathered in C.
+
+    ``values`` is anything :func:`doubles` accepts, or an ``(n, k)`` buffer of rows (e.g.
+    RGBA colors per point), in which case the result holds ``len(indices)`` rows of ``k``,
+    flat and row-major.  ``indices`` are integers in ``[0, n)`` (``array('q')`` from
+    :func:`argsort`, numpy integer arrays, lists); others raise ``IndexError``."""
+    idx = _indices(indices)
+    mv = _numeric_view(values)
+    if mv is not None and mv.ndim in (1, 2):
+        k = mv.shape[1] if mv.ndim == 2 else 1
+        if k < 1:
+            raise ValueError("take: rows of at least one value")
+        native = mv.format[0] not in "<>!" or (mv.format[0] == "<") == (sys.byteorder == "little")
+        if (mv.format.lstrip("@=<>!") == "d" and native and mv.c_contiguous
+                and not mv.readonly and mv.nbytes):
+            # read in place: no copy of large inputs
+            holder = (ctypes.c_char * mv.nbytes).from_buffer(mv)
+            return _k.take_rows(None, k, idx, ctypes.addressof(holder), mv.shape[0])
+        flat = doubles(values) if mv.ndim == 1 else _grid(values)[3]
+        return _k.take_rows(flat, k, idx)
+    return _k.take_rows(doubles(values), 1, idx)
+
+
+#: Methods and metrics of :func:`linkage`.
+LINKAGE_METHODS = tuple(_k.LINKAGE_METHODS)
+LINKAGE_METRICS = tuple(_k.LINKAGE_METRICS)
+
+
+def linkage(data: Any, method: str = "average",
+            metric: str = "euclidean") -> tuple[int, array.array]:
+    """``(n, merges)``: scipy's ``linkage`` of the rows of ``data`` (a 2-D buffer or a
+    sequence of equal-length rows), or of a condensed distance vector (``metric``
+    "precomputed": the ``n(n - 1)/2`` distances ``d(i, j)``, ``i < j``, in row order).
+    ``merges`` holds ``n - 1`` rows of ``(left, right, height, size)``, flat: row ``i`` makes
+    cluster ``n + i``.  Methods: :data:`LINKAGE_METHODS`; metrics: :data:`LINKAGE_METRICS`
+    (ward, centroid and median take euclidean or precomputed distances).  Equal to scipy's
+    on input without equal distances; among equal distances the first found merges (scipy's
+    loops, lower indices first), the same on every platform.  At most 16,384 observations."""
+    if method not in _k.LINKAGE_METHODS:
+        raise ValueError(f"linkage: unknown method {method!r} (use "
+                         f"{', '.join(map(repr, LINKAGE_METHODS))})")
+    if metric not in _k.LINKAGE_METRICS:
+        raise ValueError(f"linkage: unknown metric {metric!r} (use "
+                         f"{', '.join(map(repr, LINKAGE_METRICS))})")
+    if metric == "precomputed":
+        flat = doubles(data)
+        m = len(flat)
+        n = (1 + math.isqrt(1 + 8 * m)) // 2
+        if n * (n - 1) // 2 != m:
+            raise ValueError(f"linkage: {m} distances is not n(n - 1)/2 for any n")
+        d = 0
+    else:
+        g = _grid(data)
+        if g is not None:
+            if g[2] != 1:
+                raise ValueError("linkage: data must be 2-D (observations x values)")
+            n, d, flat = g[0], g[1], g[3]
+        else:
+            rs = [doubles(r) for r in data]
+            n = len(rs)
+            d = len(rs[0]) if rs else 0
+            if any(len(r) != d for r in rs):
+                raise ValueError("linkage: rows of different lengths")
+            flat = array.array("d")
+            for r in rs:
+                flat.extend(r)
+        if n > 1 and d < 1:
+            raise ValueError("linkage: rows of at least one value")
+    return n, _k.linkage(flat, n, max(d, 1), method, metric)