plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/layers/stats.py

@@ -0,0 +1,1088 @@
+"""Stats: a call's data and settings → columns.  A stat never draws.
+
+``bin`` (histograms), ``bin2d``, ``hexbin``, ``kde``, ``kde2d`` (a density grid),
+``ecdf``, ``box`` (quantiles and whiskers), ``violin`` (a density per category),
+``regression`` (polynomial or LOWESS, with a confidence band) and ``summary`` (an estimate
+and an interval of replicates) are registered
+(:func:`stat`): each takes the call's columns, the resolved settings it reads and the axis
+scales, and returns plain columns; :func:`compute` runs one, cached by the series under
+those values; ``series.stats`` exposes them.  ``contour`` (iso-lines and bands) works on a
+grid.  Statistics on an axis are computed in the axis' space
+(after its scale function): bins are even there and densities are per axis unit.  The
+genome stats (``region_signal``, ``intervals``, ``contact_matrix``) are in
+:mod:`plot_io.genome` (``signal``, ``intervals``, ``contacts``).  The kernels are plot_io's C library's
+(:mod:`plot_io.kernels`).
+"""
+
+import array
+import math
+import warnings
+from typing import Any
+
+from vec_io.arrays import doubles
+
+from .. import kernels
+from ..scales import get_scale
+from ..validators import integer, real, typed
+
+__all__ = ["STATS", "Stat", "Params", "stat", "stat_of", "params", "compute", "run",
+           "value_scale", "axis_scale", "scale_key",
+           "check_bins", "READS", "bin", "bin2d", "hexbin", "kde",
+           "kde_span", "kde2d", "ecdf", "box", "violin", "regression", "summary",
+           "interval_of", "contour",
+           "t_quantile", "norm_quantile", "beta_quantile", "density_at", "lowess"]
+
+class Params(dict):
+    """The resolved settings a stat reads (a mapping, not changed by the stat), and the
+    type's name for messages (``kind``)."""
+
+    def __init__(self, kind: str, values: dict[str, Any]) -> None:
+        super().__init__(values)
+        self.kind = kind
+
+
+class Stat:
+    """A registered stat: ``fn(columns, params, scales[, peers])``, the settings it
+    ``reads``, their ``defaults`` (for a type without the setting), and how a series gives
+    its ``scales`` and ``peers`` (functions of the series; :func:`run`)."""
+
+    __slots__ = ("name", "fn", "reads", "defaults", "scales", "peers")
+
+    def __init__(self, name: str, fn: Any, reads: tuple[str, ...],
+                 defaults: dict[str, Any] | None = None, scales: Any = None,
+                 peers: Any = None) -> None:
+        self.name, self.fn, self.reads = name, fn, reads
+        self.defaults = dict(defaults or {})
+        self.scales = scales
+        self.peers = peers
+
+    def __repr__(self) -> str:
+        return f"Stat({self.name!r})"
+
+
+#: The registered stats by name.
+STATS: dict[str, Stat] = {}
+
+
+def stat(name: str, reads: tuple[str, ...] = (), defaults: dict[str, Any] | None = None,
+         scales: Any = None, peers: Any = None) -> Any:
+    """Register a stat ``fn(columns, params, scales, peers=None)``: the call's
+    :class:`~plot_io.columns.Columns`, the resolved values of the settings it ``reads``
+    (:class:`Params`; ``defaults``: the values of those a type does not have), the axis
+    scales it is computed on (in the axis' space; ``scales(series)`` gives them, default
+    none) and the plot-wide values it shares (``peers(series, scales)``, default none)."""
+    def add(fn: Any) -> Any:
+        STATS[name] = Stat(name, fn, reads, defaults, scales, peers)
+        return fn
+    return add
+
+
+def stat_of(name: str) -> Stat:
+    """The registered stat ``name`` (a ``ValueError`` naming the registered ones)."""
+    st = STATS.get(name)
+    if st is None:
+        raise ValueError(f"unknown stat {name!r} (stats: {', '.join(sorted(STATS))})")
+    return st
+
+
+def params(series: Any, name: str) -> Params:
+    """The params of stat ``name`` for ``series``: the settings it reads, resolved (the
+    stat's defaults for those the type does not have)."""
+    st = STATS[name]
+    have = series.SETTINGS
+    return Params(series.kind, {k: series.resolve(k) if k in have else st.defaults[k]
+                                for k in st.reads if k in have or k in st.defaults})
+
+
+def compute(series: Any, name: str, scales: tuple[Any, ...] = (), peers: Any = None,
+            kind: Any = "stats") -> Any:
+    """Stat ``name`` of ``series``, cached by the series under its params, the scales'
+    keys and ``peers`` (one result per ``kind``; ``None``: per key)."""
+    st = STATS[name]
+
+    def run() -> Any:
+        params_ = params(series, name)
+        if peers is None:
+            return st.fn(series.cols, params_, scales)
+        return st.fn(series.cols, params_, scales, peers)
+
+    key = (name, tuple(scale_key(sc) for sc in scales), peers)
+    return series.cached(key, run, st.reads, kind=kind)
+
+
+def run(series: Any, name: str) -> Any:
+    """Stat ``name`` of ``series`` on the scales and peers the stat asks of it (cached, as
+    :func:`compute`): what a layer declaring the stat draws."""
+    st = stat_of(name)
+    scales = tuple(st.scales(series)) if st.scales is not None else ()
+    peers = st.peers(series, scales) if st.peers is not None else None
+    return compute(series, name, scales, peers)
+
+
+def value_scale(series: Any) -> tuple[Any, ...]:
+    """The scale of the axis ``series``' values are drawn on (data role ``x``)."""
+    from .grammar import axis_of
+    return (axis_scale(axis_of(series, "x")),)
+
+
+def _y_scale(series: Any) -> tuple[Any, ...]:
+    from .grammar import axis_of
+    return (axis_scale(axis_of(series, "y")),)
+
+
+def _bin_scales(series: Any) -> tuple[Any, ...]:
+    """The scale the bins are even on (``bins_scale``), and the axis' scale."""
+    (unit,) = value_scale(series)
+    linear = "bins_scale" in series.SETTINGS and series.resolve("bins_scale") == "linear"
+    return (get_scale("linear") if linear else unit, unit)
+
+
+def _stacked_peers(series: Any) -> list[Any]:
+    """The stacked series of ``series``' type in its plot, in its orientation (``[]``:
+    ``series`` is not stacked)."""
+    from .grammar import flipped
+    if "stack" not in series.SETTINGS or not series.resolve("stack"):
+        return []
+    flip = flipped(series)
+    return [k for k in series.plot.series if type(k) is type(series)
+            and k.resolve("stack") and flipped(k) == flip]
+
+
+def _kde_peers(series: Any, scales: tuple[Any, ...]) -> tuple[float, float] | None:
+    """The grid stacked kde calls of the plot share: the union of their spans."""
+    members = _stacked_peers(series)
+    if not members:
+        return None
+    scale = scales[0]
+    spans = [k.cached(("span", scale_key(scale)),
+                      lambda k=k: kde_span(k.cols, params(k, "kde"), scale), STATS["kde"].reads)
+             for k in members]
+    return min(a for a, _ in spans), max(b for _, b in spans)
+
+
+def _bin_peers(series: Any, scales: tuple[Any, ...]) -> tuple[float, ...] | None:
+    """The bin edges stacked histograms of the plot share (several calls): the first
+    one's ``bins`` and ``range`` over the values of all."""
+    members = _stacked_peers(series)
+    if len(members) < 2:
+        return None
+    first = members[0]
+    if [scale_key(c) for c in scales] != [scale_key(c) for c in _bin_scales(first)]:
+        return None
+    p = params(first, "bin")
+    if isinstance(p["bins"], array.array):
+        return tuple(p["bins"])
+    scale = scales[0]
+    axis = "y" if p["orientation"] == "horizontal" else "x"
+    allv = array.array("d")
+    for k in members:
+        for _, v in k.cols.sets:
+            allv.extend(_f(v, scale))
+    fedges = kernels.bin_edges(allv, p["bins"], _range(p, p["range"], scale, axis))
+    return tuple(scale.inverse(e) for e in fedges)
+
+
+#: The settings each stat reads (contour's: of the contour type's grid).
+READS: dict[str, tuple[str, ...]] = {
+    "contour": ("levels", "lines", "fill", "thresh", "bandwidth", "adjust", "cut", "points"),
+}
+
+
+def axis_scale(axis: Any) -> Any:
+    """The scale of an axis as set (category axes: linear), for stats computed in the
+    axis' space (bins even on a log axis)."""
+    name = axis.nominal_scale
+    if name == "category":
+        name = "linear"
+    return get_scale(name, axis.resolve("linthresh") if name == "symlog" else None)
+
+
+def scale_key(scale: Any) -> tuple:
+    """A scale's part of a cache key: its name and options."""
+    return (scale.name, tuple(sorted(scale.options.items())))
+
+
+def _f(values: Any, scale: Any) -> Any:
+    """``values`` through the scale's function (NaN outside its domain)."""
+    if not scale.function:
+        return values
+    return kernels.scaled(values, 1.0, 0.0, scale.function, **scale.options)
+
+
+@typed("SupportsFloat | "
+       "Literal['auto', 'fd', 'sturges', 'scott', 'sqrt', 'rice', 'doane'] | Column")
+def check_bins(v: Any) -> Any:
+    """A bin count, a rule name, or increasing edges."""
+    if isinstance(v, str):
+        if v not in kernels._RULES:
+            raise ValueError(f"unknown bin rule {v!r} (use a count, edges or "
+                             f"{', '.join(kernels._RULES)})")
+        return v
+    n = integer(v) if real(v) is not None else None
+    if n is not None:
+        if not 1 <= n <= kernels.MAX_BINS:
+            raise ValueError(f"bins must be between 1 and {kernels.MAX_BINS}")
+        return n
+    e = doubles(v)
+    if len(e) < 2 or any(not b > a for a, b in zip(e, e[1:])):
+        raise ValueError("bin edges must increase")
+    return e
+
+
+def _range(s: Any, rng: Any, scale: Any, axis: str) -> tuple[float, float] | None:
+    """A ``range`` setting in the axis' space, checked."""
+    if rng is None:
+        return None
+    lo, hi = float(rng[0]), float(rng[1])
+    if not lo < hi:
+        raise ValueError(f"{s.kind}: range {tuple(rng)} must be (low, high) with low < high")
+    flo, fhi = scale.f(lo), scale.f(hi)
+    if not (math.isfinite(flo) and math.isfinite(fhi)):
+        raise ValueError(f"{s.kind}: range {tuple(rng)} is outside the {axis} axis' "
+                         f"{scale.name} scale")
+    return flo, fhi
+
+
+def _edges_in(s: Any, edges: Any, scale: Any, axis: str) -> array.array:
+    """Bin edges in the axis' space; edges outside the scale's domain are refused."""
+    out = array.array("d", (scale.f(e) for e in edges))
+    bad = [e for e, f in zip(edges, out) if not math.isfinite(f)]
+    if bad:
+        raise ValueError(f"{s.kind}: bin edge {bad[0]:g} is outside the {axis} axis' "
+                         f"{scale.name} scale")
+    return out
+
+
+def _weight(weights: Any, key: Any, i: int) -> Any:
+    if weights is None:
+        return None
+    if isinstance(weights, dict) and key not in weights:
+        raise ValueError(f"setting 'weights': no weights for set {key!r}")
+    return (weights[key] if isinstance(weights, dict) else
+            weights[i] if isinstance(weights, list) else weights)
+
+
+def _category_weights(cols: Any, weights: Any) -> list[Any]:
+    """The weights of each category's values: a dict by category, a list in category
+    order, or one column (long data: a weight per row, grouped as the values)."""
+    n = len(cols.groups)
+    if weights is None:
+        return [None] * n
+    if isinstance(weights, dict):
+        missing = [k for k in cols.categories if k not in weights]
+        if missing:
+            raise ValueError(f"weights: no column for category {missing[0]!r}")
+        return [weights[k] for k in cols.categories]
+    if isinstance(weights, list):
+        if len(weights) != n:
+            raise ValueError(f"{len(weights)} weight columns for {n} categories")
+        return weights
+    key = cols.options.get("long")
+    if key is not None:
+        cats = cols.args[key]
+        if len(weights) != len(cats):
+            raise ValueError(f"{len(weights)} weights for {len(cats)} values")
+        from ..columns import Columns
+        by = Columns._long(weights, cats, cols.orders.get(key))
+        return [by[k] for k in cols.categories]
+    if n == 1:
+        return [weights]
+    raise ValueError(f"weights: one column per category ({n} categories), as the values")
+
+
+def _kept(values: Any, weights: Any) -> tuple[Any, Any]:
+    """``(values, weights)`` without the rows of weight 0 (weights count as repeated rows),
+    the weights checked."""
+    if weights is None:
+        return values, None
+    v = doubles(values)
+    w = kernels._weights(weights, len(v))
+    assert w is not None
+    if min(w, default=1.0) > 0:
+        return v, w
+    keep = [i for i in range(len(v)) if w[i] > 0]
+    return kernels.take(v, keep), kernels.take(w, keep)
+
+
+def _weighted_count(fv: Any, w: Any) -> float:
+    """The weight total of the finite values (an int when whole)."""
+    t = math.fsum(wi for x, wi in zip(fv, w) if math.isfinite(x))
+    return int(t) if t.is_integer() else t
+
+
+# ---------------------------------------------------------------------------
+# 1-D
+# ---------------------------------------------------------------------------
+
+@stat("bin", reads=("bins", "range", "weights", "stat", "cumulative", "bins_scale", "orientation"),
+      defaults={"bins": "auto", "range": None, "weights": None, "stat": "count",
+                "cumulative": False, "bins_scale": "axis", "orientation": "vertical"},
+      scales=_bin_scales, peers=_bin_peers)
+def bin(cols: Any, p: Params, scales: tuple[Any, ...],
+        edges: tuple[float, ...] | None = None) -> dict[str, Any]:
+    """``{"edges", "heights": [per set], "counts": [per set]}``: bins even on the first of
+    ``scales``; densities and frequencies per unit of the second (the axis' scale);
+    ``edges``: shared with other calls (stacked histograms), unless ``bins`` are edges."""
+    scale, ascale = scales
+    axis = "y" if p["orientation"] == "horizontal" else "x"
+    sets = cols.sets
+    fsets = [_f(v, scale) for _, v in sets]
+    bins = p["bins"]
+    frng = _range(p, p["range"], scale, axis)
+    if isinstance(bins, array.array):
+        fedges = _edges_in(p, bins, scale, axis)
+    elif edges is not None:
+        fedges = _edges_in(p, edges, scale, axis)
+    else:
+        if len(fsets) == 1:
+            allv = fsets[0]
+        else:
+            allv = array.array("d")
+            for v in fsets:
+                allv.extend(v)
+        fedges = kernels.bin_edges(allv, bins, frng)
+    out_edges = array.array("d", (scale.inverse(e) for e in fedges))
+    aedges = _edges_in(p, out_edges, ascale, axis) if ascale is not scale else fedges
+    widths = [b - a for a, b in zip(aedges, aedges[1:])]
+    weights = p["weights"]
+    st = p["stat"]
+    counts, heights = [], []
+    for i, ((key, _), fv) in enumerate(zip(sets, fsets)):
+        c = kernels.histogram(fv, fedges, _weight(weights, key, i))
+        counts.append(c)
+        total = math.fsum(c)
+        if st == "count":
+            hgt = list(c)
+        elif st == "probability":
+            hgt = [x / total if total else 0.0 for x in c]
+        elif st == "percent":
+            hgt = [100.0 * x / total if total else 0.0 for x in c]
+        elif st == "frequency":
+            hgt = [x / wd for x, wd in zip(c, widths)]
+        else:
+            hgt = [x / (total * wd) if total else 0.0 for x, wd in zip(c, widths)]
+        if p["cumulative"]:
+            acc, out = 0.0, []
+            for x, wd in zip(hgt, widths):
+                acc += x * wd if st in ("density", "frequency") else x
+                out.append(acc)
+            hgt = out
+        heights.append(array.array("d", hgt))
+    return {"edges": out_edges, "heights": heights, "counts": counts}
+
+
+def _bandwidth(values: Any, rule: Any, weights: Any = None) -> float:
+    """A rule's bandwidth of ``values``, or a number given as is."""
+    if not isinstance(rule, str):
+        return float(rule)
+    return kernels.bandwidth(values, rule, weights)
+
+
+def _kde_sets(cols: Any, p: Params, scale: Any) -> tuple[list[Any], list[Any], list[float], float, float]:
+    """``(f-space sets, weights, bandwidths, lo, hi)``: each set's bandwidth (NaN when it
+    has none) and the span of the data plus ``cut`` bandwidths, within ``range``."""
+    weights = p["weights"]
+    fsets, ws, bws = [], [], []
+    for i, (key, v) in enumerate(cols.sets):
+        v, w = _kept(v, _weight(weights, key, i))
+        fv = _f(v, scale)
+        n = kernels.extent(fv, None)[0]
+        bw = _bandwidth(fv, p["bandwidth"], w) * p["adjust"] if n else math.nan
+        fsets.append(fv)
+        ws.append(w)
+        bws.append(bw if math.isfinite(bw) and bw > 0 else math.nan)
+    cut = p["cut"]
+    lo, hi = math.inf, -math.inf
+    for fv, bw in zip(fsets, bws):
+        n, a, b = kernels.extent(fv, None)
+        if n:
+            pad = cut * bw if math.isfinite(bw) else 0.0
+            lo, hi = min(lo, a - pad), max(hi, b + pad)
+    if not math.isfinite(lo):
+        lo, hi = 0.0, 1.0
+    elif lo == hi:
+        lo, hi = lo - 0.5, hi + 0.5
+    axis = "y" if p["orientation"] == "horizontal" else "x"
+    frng = _range(p, p["range"], scale, axis)
+    if frng is not None:
+        lo, hi = max(lo, frng[0]), min(hi, frng[1])
+        if not lo < hi:
+            lo, hi = frng
+            bws = [math.nan] * len(bws)
+    return fsets, ws, bws, lo, hi
+
+
+def kde_span(cols: Any, p: Params, scale: Any) -> tuple[float, float]:
+    """The span of a kde series' grid in the axis' space (before sharing a stack's)."""
+    return _kde_sets(cols, p, scale)[3:]
+
+
+@stat("kde", reads=("bandwidth", "adjust", "cut", "range", "points", "cumulative", "weights", "stack", "orientation"),
+      defaults={"bandwidth": "scott", "adjust": 1.0, "cut": 3.0, "range": None, "points": 512,
+                "cumulative": False, "weights": None, "stack": False,
+                "orientation": "vertical"},
+      scales=value_scale, peers=_kde_peers)
+def kde(cols: Any, p: Params, scales: tuple[Any, ...],
+        span: tuple[float, float] | None = None) -> dict[str, Any]:
+    """``{"grid", "densities": [per set], "bandwidths": [per set]}``: on a common grid
+    (over ``span`` in the axis' space when given), per unit of ``scale`` (log axes: per
+    log unit).  A set without a bandwidth (no values, one, or all equal) or a ``range``
+    outside the data has no density (NaN), with a warning."""
+    scale = scales[0]
+    fsets, ws, bws, lo, hi = _kde_sets(cols, p, scale)
+    if span is not None:
+        lo, hi = span
+    n = p["points"]
+    nan = array.array("d", [math.nan]) * n
+    dens = [kernels.kde(fv, lo, hi, n, bw, w, p["cumulative"])
+            if math.isfinite(bw) else array.array("d", nan)
+            for fv, bw, w in zip(fsets, bws, ws)]
+    missing = sum(1 for bw in bws if not math.isfinite(bw))
+    if missing:
+        what = "set has" if missing == 1 else "sets have"
+        warnings.warn(f"kde: {missing} {what} no density (no bandwidth: fewer than 2 "
+                      f"distinct values, a weight total of at most 1, or a range outside "
+                      f"the data)", stacklevel=3)
+    grid = array.array("d", (scale.inverse(lo + (hi - lo) * i / (n - 1)) for i in range(n)))
+    return {"grid": grid, "densities": dens, "bandwidths": bws}
+
+
+def _ecdf_peers(series: Any, scales: tuple[Any, ...]) -> tuple[float, ...] | None:
+    """The values stacked ecdf calls of the plot share: every finite value of theirs."""
+    members = _stacked_peers(series)
+    if not members:
+        return None
+    grid: set[float] = set()
+    for k in members:
+        for _, v in k.cols.sets:
+            grid.update(x for x in doubles(v) if math.isfinite(x))
+    return tuple(sorted(grid))
+
+
+@stat("ecdf", reads=("weights", "stat", "complementary"),
+      defaults={"weights": None, "stat": "proportion", "complementary": False},
+      peers=_ecdf_peers)
+def ecdf(cols: Any, p: Params, scales: tuple[Any, ...] = (),
+         grid: tuple[float, ...] | None = None) -> list[tuple[array.array, array.array, float]]:
+    """Per set: sorted values, the cumulative values plotted, and the value before the
+    first step (0, or the total for complementary curves); ``grid``: the values of the
+    stacked calls, each set's steps read at them."""
+    import bisect
+    weights = p["weights"]
+    st = p["stat"]
+    out = []
+    for i, (key, v) in enumerate(cols.sets):
+        xs, cs = kernels.ecdf(v, _weight(weights, key, i))
+        total = cs[-1] if len(cs) else 0.0
+        k = 1.0 if st == "count" else (100.0 if st == "percent" else 1.0) / (total or 1.0)
+        top = total * k
+        ys = array.array("d", (c * k for c in cs))
+        start = 0.0
+        if p["complementary"]:
+            ys = array.array("d", (top - y for y in ys))
+            start = top
+        if grid is not None:
+            at = [bisect.bisect_right(xs, g) - 1 for g in grid]
+            ys = array.array("d", (ys[j] if j >= 0 else start for j in at))
+            xs = array.array("d", grid)
+        out.append((xs, ys, start))
+    return out
+
+
+@stat("box", reads=("whiskers", "weights"), defaults={"whiskers": 1.5, "weights": None})
+def box(cols: Any, p: Params, scales: tuple[Any, ...] = ()) -> dict[Any, Any]:
+    """``{category: BoxStats}``: count, mean, q1, median, q3, low, high, outliers
+    (``weights``: as repeated values)."""
+    w = p["whiskers"]
+    ws = _category_weights(cols, p.get("weights"))
+    return {k: kernels.box_stats(v, w, wk)
+            for k, v, wk in zip(cols.categories, cols.values, ws)}
+
+
+@stat("violin", reads=("bandwidth", "adjust", "cut", "points", "orientation", "weights"),
+      defaults={"bandwidth": "scott", "adjust": 1.0, "cut": 2.0, "points": 512,
+                "orientation": "vertical", "weights": None},
+      scales=_y_scale)
+def violin(cols: Any, p: Params, scales: tuple[Any, ...]) -> dict[Any, dict[str, Any]]:
+    """``{category: {"grid", "density", "count", "box": BoxStats, "bandwidth", "line"}}``:
+    densities in the value axis' space (``scale``), per its unit.  A category without a
+    bandwidth (one value, or all equal) is a line at its value (``"line"``: true), with a
+    warning."""
+    scale = scales[0]
+    out = {}
+    n = p["points"]
+    lines = 0
+    ws = _category_weights(cols, p.get("weights"))
+    for k, d, w in zip(cols.categories, cols.values, ws):
+        bs = kernels.box_stats(d, 1.5, w)
+        d, w = _kept(d, w)
+        fd = _f(d, scale)
+        cnt: float
+        cnt, lo, hi = kernels.extent(fd, None)
+        if cnt and w is not None:
+            cnt = _weighted_count(fd, w)
+        if not cnt:
+            out[k] = {"grid": array.array("d"), "density": array.array("d"), "count": 0,
+                      "box": bs, "bandwidth": 0.0, "line": False}
+            continue
+        bw = _bandwidth(fd, p["bandwidth"], w) * p["adjust"]
+        if not (math.isfinite(bw) and bw > 0) or lo == hi:
+            lines += 1
+            v = scale.inverse(lo)
+            out[k] = {"grid": array.array("d", [v, v]), "density": array.array("d", [1.0, 1.0]),
+                      "count": cnt, "box": bs, "bandwidth": math.nan, "line": True}
+            continue
+        cut = p["cut"]
+        g0, g1 = lo - cut * bw, hi + cut * bw
+        if not (math.isfinite(g0) and math.isfinite(g1)):
+            raise ValueError(f"violin: a bandwidth of {bw:g} (bandwidth × adjust settings) "
+                             "reaches past the largest number")
+        dens = kernels.kde(fd, g0, g1, n, bw, w)
+        grid = array.array("d", (scale.inverse(g0 + (g1 - g0) * i / (n - 1))
+                                 for i in range(n)))
+        out[k] = {"grid": grid, "density": dens, "count": cnt, "box": bs, "bandwidth": bw,
+                  "line": False}
+    if lines:
+        what = "violin is" if lines == 1 else "violins are"
+        warnings.warn(f"violin: {lines} {what} drawn as a line (no bandwidth: one value, "
+                      "all equal, or a weight total of at most 1)", stacklevel=3)
+    return out
+
+
+def density_at(s: dict[str, Any], v: float, scale: Any = None) -> float:
+    """A violin's density at value ``v`` (linear between grid points in the space of
+    ``scale``)."""
+    g, d = s["grid"], s["density"]
+    n = len(g)
+    f = (lambda x: x) if scale is None else scale.f
+    a, b, t = f(g[0]) if n else 0.0, f(g[-1]) if n else 0.0, f(v)
+    if not n or not (a <= t <= b):
+        return 0.0
+    u = (t - a) / (b - a) * (n - 1) if b > a else 0.0
+    i = min(int(u), n - 2)
+    if i < 0:
+        return d[0]
+    r = u - i
+    return d[i] * (1 - r) + d[i + 1] * r
+
+
+def lowess(x: Any, y: Any, frac: float = 2.0 / 3.0,
+           iterations: int = 3) -> tuple[array.array, array.array]:
+    """Locally weighted linear regression: the sorted x values (pairs with a NaN left out)
+    and the fitted y values."""
+    pairs = sorted((a, b) for a, b in zip(doubles(x), doubles(y))
+                   if math.isfinite(a) and math.isfinite(b))
+    xs = array.array("d", (p[0] for p in pairs))
+    ys = array.array("d", (p[1] for p in pairs))
+    if len(xs) < 2:
+        return xs, ys
+    return xs, kernels.lowess(xs, ys, frac, iterations)
+
+
+# ---------------------------------------------------------------------------
+# Regression
+# ---------------------------------------------------------------------------
+
+def _solve(a: list[list[float]], b: list[float]) -> list[float]:
+    """Gaussian elimination with partial pivoting."""
+    n = len(b)
+    m = [row[:] + [bv] for row, bv in zip(a, b)]
+    for i in range(n):
+        p = max(range(i, n), key=lambda r: abs(m[r][i]))
+        if abs(m[p][i]) < 1e-300:
+            raise ValueError("the fit is singular (too few distinct x values for the order)")
+        m[i], m[p] = m[p], m[i]
+        for r in range(i + 1, n):
+            f = m[r][i] / m[i][i]
+            for c in range(i, n + 1):
+                m[r][c] -= f * m[i][c]
+    x = [0.0] * n
+    for i in range(n - 1, -1, -1):
+        x[i] = (m[i][n] - sum(m[i][c] * x[c] for c in range(i + 1, n))) / m[i][i]
+    return x
+
+
+def _inverse(a: list[list[float]]) -> list[list[float]]:
+    n = len(a)
+    cols = [_solve(a, [1.0 if r == c else 0.0 for r in range(n)]) for c in range(n)]
+    return [[cols[c][r] for c in range(n)] for r in range(n)]
+
+
+def _betacf(a: float, b: float, x: float) -> float:
+    qab, qap, qam = a + b, a + 1.0, a - 1.0
+    c, d = 1.0, 1.0 - qab * x / qap
+    d = 1.0 / (d if abs(d) > 1e-300 else 1e-300)
+    h = d
+    for m in range(1, 300):
+        m2 = 2 * m
+        aa = m * (b - m) * x / ((qam + m2) * (a + m2))
+        d = 1.0 + aa * d
+        d = 1.0 / (d if abs(d) > 1e-300 else 1e-300)
+        c = 1.0 + aa / c if abs(c) > 1e-300 else 1e300
+        h *= d * c
+        aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2))
+        d = 1.0 + aa * d
+        d = 1.0 / (d if abs(d) > 1e-300 else 1e-300)
+        c = 1.0 + aa / c if abs(c) > 1e-300 else 1e300
+        de = d * c
+        h *= de
+        if abs(de - 1.0) < 1e-15:
+            break
+    return h
+
+
+def _betai(a: float, b: float, x: float) -> float:
+    if x <= 0:
+        return 0.0
+    if x >= 1:
+        return 1.0
+    lb = math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b) + a * math.log(x) \
+        + b * math.log(1 - x)
+    if x < (a + 1) / (a + b + 2):
+        return math.exp(lb) * _betacf(a, b, x) / a
+    return 1.0 - math.exp(lb) * _betacf(b, a, 1 - x) / b
+
+
+def _t_cdf(t: float, df: float) -> float:
+    x = df / (df + t * t)
+    p = 0.5 * _betai(df / 2.0, 0.5, x)
+    return 1.0 - p if t > 0 else p
+
+
+def t_quantile(p: float, df: float) -> float:
+    """The ``p`` quantile of Student's t distribution with ``df`` degrees of freedom."""
+    if df <= 0:
+        return math.inf
+    lo, hi = -1e3, 1e3
+    for _ in range(200):
+        mid = (lo + hi) / 2
+        if _t_cdf(mid, df) < p:
+            lo = mid
+        else:
+            hi = mid
+    return (lo + hi) / 2
+
+
+# Wichura's AS241 (PPND16): relative error about 1e-16
+_NQ_A = (3.387132872796366608, 133.14166789178437745, 1971.5909503065514427,
+         13731.693765509461125, 45921.953931549871457, 67265.770927008700853,
+         33430.575583588128105, 2509.0809287301226727)
+_NQ_B = (1.0, 42.313330701600911252, 687.1870074920579083, 5394.1960214247511077,
+         21213.794301586595867, 39307.89580009271061, 28729.085735721942674,
+         5226.495278852545925)
+_NQ_C = (1.42343711074968357734, 4.6303378461565452959, 5.7694972214606914055,
+         3.64784832476320460504, 1.27045825245236838258, 0.24178072517745061177,
+         0.0227238449892691845833, 7.7454501427834140764e-4)
+_NQ_D = (1.0, 2.05319162663775882187, 1.6763848301838038494, 0.68976733498510000455,
+         0.14810397642748007459, 0.0151986665636164571966, 5.475938084995344946e-4,
+         1.05075007164441684324e-9)
+_NQ_E = (6.6579046435011037772, 5.4637849111641143699, 1.7848265399172913358,
+         0.29656057182850489123, 0.026532189526576123093, 0.0012426609473880784386,
+         2.71155556874348757815e-5, 2.01033439929228813265e-7)
+_NQ_F = (1.0, 0.59983220655588793769, 0.13692988092273580531, 0.0148753612908506148525,
+         7.868691311456132591e-4, 1.8463183175100546818e-5, 1.4215117583164458887e-7,
+         2.04426310338993978564e-15)
+
+
+def _poly(c: tuple[float, ...], r: float) -> float:
+    v = c[7]
+    for k in range(6, -1, -1):
+        v = v * r + c[k]
+    return v
+
+
+def norm_quantile(p: float) -> float:
+    """The ``p`` quantile of the standard normal distribution (Wichura's AS241); ±inf at 0
+    and 1, NaN outside [0, 1]."""
+    if not 0.0 < p < 1.0:
+        return -math.inf if p == 0.0 else math.inf if p == 1.0 else math.nan
+    q = p - 0.5
+    if abs(q) <= 0.425:
+        r = 0.180625 - q * q
+        return q * _poly(_NQ_A, r) / _poly(_NQ_B, r)
+    r = math.sqrt(-math.log(p if q < 0 else 1.0 - p))
+    if r <= 5.0:
+        v = _poly(_NQ_C, r - 1.6) / _poly(_NQ_D, r - 1.6)
+    else:
+        v = _poly(_NQ_E, r - 5.0) / _poly(_NQ_F, r - 5.0)
+    return -v if q < 0 else v
+
+
+def beta_quantile(p: float, a: float, b: float) -> float:
+    """The ``p`` quantile of the beta distribution with shapes ``a`` and ``b``: the
+    regularized incomplete beta function inverted by Newton steps kept in a bisection
+    bracket (relative error about 1e-12)."""
+    if not 0.0 < p < 1.0:
+        return 0.0 if p <= 0.0 else 1.0
+    lbeta = math.lgamma(a) + math.lgamma(b) - math.lgamma(a + b)
+    s = a + b
+    # start: a normal approximation, or the tails' x^a / (a B) and 1 - (1-x)^b / (b B)
+    x = a / s + norm_quantile(p) * math.sqrt(a * b / (s * s * (s + 1)))
+    if not 0.0 < x < 1.0 or min(a, b) < 10:
+        x = math.exp((math.log(p * a) + lbeta) / a) if p < 0.5 \
+            else -math.expm1((math.log((1 - p) * b) + lbeta) / b)
+        if not 0.0 < x < 1.0:
+            x = a / s
+    lo, hi = 0.0, 1.0
+    for _ in range(200):
+        f = _betai(a, b, x) - p
+        if f < 0:
+            lo = x
+        else:
+            hi = x
+        d = math.exp((a - 1) * math.log(x) + (b - 1) * math.log1p(-x) - lbeta)
+        nx = x - f / d if d > 0 else math.nan
+        if not lo < nx < hi:
+            nx = (lo + hi) / 2
+        if abs(nx - x) <= 1e-12 * min(x, 1.0 - x) or hi - lo <= 4e-16 * hi:
+            return nx
+        x = nx
+    return x
+
+
+@stat("regression", reads=("logx", "points", "range", "lowess", "frac", "order", "ci",
+                           "weights"),
+      defaults={"logx": False, "points": 100, "range": None, "lowess": False,
+                "frac": 2.0 / 3.0, "order": 1, "ci": 95.0, "weights": None})
+def regression(cols: Any, p: Params, scales: tuple[Any, ...] = ()) -> dict[str, Any]:
+    """``coefficients`` (lowest power first, in x or log x), ``r2``, ``se`` (residual
+    standard error), and the curve: ``x``, ``y``, ``low``, ``high``.  ``weights`` count as
+    repeated points (weighted least squares, ``sum w - k`` degrees of freedom)."""
+    logx = p["logx"]
+    weights = p.get("weights")
+    if weights is not None and p["lowess"]:
+        raise ValueError(f"{p.kind}: lowess=True does not take weights")
+    wv = kernels._weights(weights, len(cols["x"])) if weights is not None else None
+    pts = [(math.log(a) if logx else a, b) for a, b in zip(cols["x"], cols["y"])
+           if math.isfinite(a) and math.isfinite(b) and (a > 0 or not logx)]
+    ws = [1.0] * len(pts) if wv is None else \
+        [c for a, b, c in zip(cols["x"], cols["y"], wv)
+         if math.isfinite(a) and math.isfinite(b) and (a > 0 or not logx)]
+    if wv is not None:
+        pts = [q for q, c in zip(pts, ws) if c > 0]
+        ws = [c for c in ws if c > 0]
+    n = len(pts)
+    npts = p["points"]
+    if n < 2:
+        return {"coefficients": [], "r2": math.nan, "se": math.nan, "x": array.array("d"),
+                "y": array.array("d"), "low": None, "high": None}
+    distinct = len({p[0] for p in pts})
+    if distinct < 2:
+        warnings.warn("regression: x has one distinct value: no fit", stacklevel=3)
+        return {"coefficients": [], "r2": math.nan, "se": math.nan, "x": array.array("d"),
+                "y": array.array("d"), "low": None, "high": None}
+    lo = min(p[0] for p in pts)
+    hi = max(p[0] for p in pts)
+    rng = p["range"]
+    if rng is not None:
+        lo, hi = ((math.log(v) if v > 0 else math.nan) if logx else v for v in rng)
+        if not (math.isfinite(lo) and math.isfinite(hi)):
+            raise ValueError(f"range {tuple(rng)} must be positive with logx")
+    grid = [lo + (hi - lo) * i / (npts - 1) for i in range(npts)]
+    if p["lowess"]:
+        xs, fit = lowess([p[0] for p in pts], [p[1] for p in pts], p["frac"])
+        gx = array.array("d", (math.exp(v) for v in xs) if logx else xs)
+        return {"coefficients": [], "r2": math.nan, "se": math.nan, "x": gx, "y": fit,
+                "low": None, "high": None}
+    order = p["order"]
+    if order > distinct - 1:
+        warnings.warn(f"regression: order {order} lowered to {distinct - 1} ({distinct} "
+                      "distinct x values)", stacklevel=3)
+    k = min(order, distinct - 1) + 1
+    sw = math.fsum(ws)
+    mx = math.fsum(c * p[0] for p, c in zip(pts, ws)) / sw
+    d = max(abs(p[0] - mx) for p in pts)              # scaled before squaring
+    sx = d * math.sqrt(math.fsum(c * ((p[0] - mx) / d) ** 2 for p, c in zip(pts, ws))
+                       / sw) or 1.0
+
+    def row(v: float) -> list[float]:
+        u = (v - mx) / sx
+        return [u ** j for j in range(k)]
+
+    rows = [row(p[0]) for p in pts]
+    ata = [[math.fsum(c * r[i] * r[j] for r, c in zip(rows, ws)) for j in range(k)]
+           for i in range(k)]
+    aty = [math.fsum(c * r[i] * p[1] for r, p, c in zip(rows, pts, ws)) for i in range(k)]
+    beta = _solve(ata, aty)
+    fitted = [sum(b * v for b, v in zip(beta, r)) for r in rows]
+    my = math.fsum(c * p[1] for p, c in zip(pts, ws)) / sw
+    ss_res = math.fsum(c * (p[1] - f) ** 2 for p, f, c in zip(pts, fitted, ws))
+    ss_tot = math.fsum(c * (p[1] - my) ** 2 for p, c in zip(pts, ws))
+    dof = sw - k
+    se = math.sqrt(ss_res / dof) if dof > 0 else math.nan
+    gy = [sum(b * v for b, v in zip(beta, row(g))) for g in grid]
+    low = high = None
+    ci = p["ci"]
+    if ci is not None and dof > 0:
+        inv = _inverse(ata)
+        t = t_quantile(0.5 + ci / 200.0, dof)
+        low, high = array.array("d"), array.array("d")
+        for g, yv in zip(grid, gy):
+            r = row(g)
+            var = sum(r[i] * inv[i][j] * r[j] for i in range(k) for j in range(k))
+            h = t * se * math.sqrt(max(var, 0.0))
+            low.append(yv - h)
+            high.append(yv + h)
+    coef = [0.0] * k                            # coefficients in powers of x (or log x)
+    for j, b in enumerate(beta):
+        for i in range(j + 1):
+            try:
+                scale = sx ** -i
+            except OverflowError:
+                scale = math.inf
+            coef[i] += b * math.comb(j, i) * (-mx / sx) ** (j - i) * scale
+    gx = array.array("d", (math.exp(v) for v in grid) if logx else grid)
+    return {"coefficients": coef, "r2": 1.0 - ss_res / ss_tot if ss_tot else math.nan,
+            "se": se, "x": gx, "y": array.array("d", gy), "low": low, "high": high}
+
+
+@typed("Literal['mean', 'median'] | Callable[..., Any]")
+def check_estimate(v: Any) -> Any:
+    """An ``estimate`` setting: ``"mean"``, ``"median"``, a function of an array or
+    ``None``."""
+    if v is None or (isinstance(v, str) and v in ("mean", "median")):
+        return v
+    if callable(v):
+        import inspect
+        try:
+            inspect.signature(v).bind(None)
+        except TypeError:
+            raise ValueError(f"estimate: {v!r} does not take one argument (the values, an "
+                             "array)") from None
+        except ValueError:
+            pass                                    # no signature to check (a builtin)
+        return v
+    raise ValueError(f"estimate is 'mean', 'median' or a function of an array, not {v!r}")
+
+
+@typed("Literal['ci', 'se', 'sd', 'pi'] | tuple[Literal['ci', 'pi'], SupportsFloat] | "
+       "list[Any]")
+def check_interval(v: Any) -> Any:
+    """An ``interval`` setting: ``"ci"``, ``"se"``, ``"sd"``, ``"pi"``, ``("ci", level)``,
+    ``("pi", level)`` (0 < level < 1) or ``None``."""
+    if v is None or (isinstance(v, str) and v in ("ci", "se", "sd", "pi")):
+        return v
+    if isinstance(v, (tuple, list)) and len(v) == 2 and isinstance(v[0], str) and v[0] in ("ci", "pi"):
+        level = real(v[1])
+        if level is not None and 0 < level < 1:
+            return (v[0], level)
+    raise ValueError("interval is 'ci', 'se', 'sd', 'pi', ('ci', level) or ('pi', level) "
+                     f"with 0 < level < 1, not {v!r}")
+
+
+def interval_of(v: Any) -> tuple[str, float] | None:
+    """An ``interval`` setting as ``(name, level)``."""
+    if v is None:
+        return None
+    name, level = (v, 0.95) if isinstance(v, str) else v
+    return name, (1.0 if name in ("se", "sd") else level)
+
+
+@stat("summary", reads=("estimate", "interval"), defaults={"estimate": None, "interval": None})
+def summary(cols: Any, p: Params, scales: tuple[Any, ...] = ()) -> dict[str, Any]:
+    """Replicates summarized per position and set: ``x`` (the positions: numbers sorted,
+    categories in their order), ``sets``: ``(set, estimate, low, high)`` (the interval's
+    extent below and above the estimate; NaN with fewer than 2 values for ``ci``, ``se``,
+    ``sd``), ``keys``: the categories (else ``None``), ``named``."""
+    kinds = cols.kinds
+    name = next(n for n in kinds if n != "x")
+    keys = cols.keys.get("x")
+    if kinds[name] == "heights":
+        pos, sets = cols.categories, [(0, cols[name])]
+    elif kinds[name] == "sets":
+        pos, sets = cols["x"], cols.sets
+    else:
+        if name in cols.keys:
+            raise ValueError(f"{p.kind}: estimate needs numbers in {name}, not categories")
+        pos, sets = cols["x"], [(0, cols[name])]
+    rows: dict[Any, list[int]] = {}
+    for i, k in enumerate(pos):
+        if k is not None and k == k:
+            rows.setdefault(k, []).append(i)
+    if keys is not None and kinds[name] == "heights":
+        xs = [k for k in keys.levels if k in rows]
+    else:
+        xs = sorted(rows)
+    est, iv = p["estimate"], interval_of(p["interval"])
+    ts: dict[int, float] = {}
+    out = []
+    for k, column in sets:
+        e, lo, hi = (array.array("d") for _ in range(3))
+        for x in xs:
+            a = [v for v in (column[i] for i in rows[x]) if v == v]
+            m, below, above = _summary(a, est, iv, ts)
+            e.append(m)
+            lo.append(below)
+            hi.append(above)
+        out.append((k, e, lo, hi))
+    if keys is not None and kinds[name] != "heights":
+        xs = [keys.levels[int(i)] for i in xs]
+    return {"x": xs, "sets": out, "keys": keys, "named": cols.named}
+
+
+def _summary(a: list[float], est: Any, iv: tuple[str, float] | None,
+             ts: dict[int, float]) -> tuple[float, float, float]:
+    """``(estimate, below, above)`` of the values ``a``."""
+    n = len(a)
+    if not n:
+        return math.nan, math.nan, math.nan
+    mean = math.fsum(a) / n
+    if est == "mean":
+        m = mean
+    elif est == "median":
+        m = kernels.quantiles(a, [0.5])[0]
+    else:
+        r = est(array.array("d", a))
+        try:
+            m = float(r)
+        except (TypeError, ValueError):
+            raise ValueError(f"estimate: the function gave {r!r}, not a number") from None
+    if iv is None:
+        return m, math.nan, math.nan
+    name, level = iv
+    if name == "pi":
+        lo, hi = kernels.quantiles(a, [(1 - level) / 2, (1 + level) / 2])
+        return m, m - lo, hi - m
+    sd = math.sqrt(math.fsum((v - mean) ** 2 for v in a) / (n - 1)) if n > 1 else math.nan
+    if name == "sd":
+        return m, sd, sd
+    h = sd / math.sqrt(n) if n > 1 else math.nan
+    if name == "ci" and n > 1:
+        if n - 1 not in ts:
+            ts[n - 1] = t_quantile((1 + level) / 2, n - 1)
+        h *= ts[n - 1]
+    return m, h, h
+
+
+# ---------------------------------------------------------------------------
+# 2-D
+# ---------------------------------------------------------------------------
+
+@stat("bin2d", reads=("bins", "range", "weights", "stat", "min_count"),
+      defaults={"bins": ("auto", "auto"), "range": None, "weights": None, "stat": "count",
+                "min_count": 1.0})
+def bin2d(cols: Any, p: Params, scales: tuple[Any, ...]) -> dict[str, Any]:
+    """``{"x_edges", "y_edges", "counts": rows (first y bin first), "values": rows}``: bins
+    even on the axis scales ``sx``, ``sy``; bins under ``min_count`` are NaN."""
+    sx, sy = scales
+    bx, by = p["bins"]
+    rng = p["range"]
+    fx, fy = _f(cols["x"], sx), _f(cols["y"], sy)
+    w = p["weights"]
+
+    def edges(b: Any, v: Any, sc: Any, r: Any, axis: str) -> Any:
+        if isinstance(b, array.array):
+            return _edges_in(p, b, sc, axis)
+        return kernels.bin_edges(v, b, _range(p, r, sc, axis))
+
+    xe = edges(bx, fx, sx, None if rng is None else rng[0], "x")
+    ye = edges(by, fy, sy, None if rng is None else rng[1], "y")
+    nr, nc, flat = kernels.histogram2d(fx, fy, xe, ye, w)
+    counts = [flat[r * nc:(r + 1) * nc] for r in range(nr)]
+    total = math.fsum(math.fsum(r) for r in counts)
+    st = p["stat"]
+    xd = [sx.inverse(e) for e in xe]
+    yd = [sy.inverse(e) for e in ye]
+    mc = p["min_count"]
+    rows = []
+    for j, r in enumerate(counts):
+        out = array.array("d")
+        for i, c in enumerate(r):
+            if c < mc or c == 0:
+                out.append(math.nan)
+            elif st == "count":
+                out.append(c)
+            elif st == "probability":
+                out.append(c / total)
+            elif st == "percent":
+                out.append(100.0 * c / total)
+            else:
+                area = (xe[i + 1] - xe[i]) * (ye[j + 1] - ye[j])
+                out.append(c / (total * area) if area else math.nan)
+        rows.append(out)
+    return {"x_edges": array.array("d", xd), "y_edges": array.array("d", yd),
+            "counts": counts, "values": rows}
+
+
+_S3 = math.sqrt(3.0)
+
+
+@stat("hexbin", reads=("bins", "weights", "stat", "min_count"),
+      defaults={"bins": 30, "weights": None, "stat": "count", "min_count": 1.0})
+def hexbin(cols: Any, p: Params, scales: tuple[Any, ...], frame: tuple) -> dict[str, Any]:
+    """``{"x", "y": hexagon centres (page units, relative to the axes' top-left corner),
+    "values", "dx": hexagon width (px)}``: a lattice of ``bins`` hexagons across the
+    axes laid out in the page ``frame`` ``(function_x, a_x, b_x, function_y, a_y, b_y,
+    width, height)``."""
+    fx, ax, bx, fy, ay, by, w, h = frame
+    nx = p["bins"]
+    dx = w / nx
+    dy = _S3 * dx
+    nan = math.nan
+    u = kernels.scaled(cols["x"], ax, bx, fx)
+    v = kernels.scaled(cols["y"], ay, by, fy)
+    # Points outside the axes are not counted.
+    u = kernels.scaled(u, 1.0, 0.0, None, low=0.0, high=w, under=nan, over=nan)
+    v = kernels.scaled(v, 1.0, 0.0, None, low=0.0, high=h, under=nan, over=nan)
+    ny = int(h / dy) + 2
+    cx, cy, cs = kernels.hexbin(u, v, 0.0, 0.0, dx, dy, nx + 1, ny, p["weights"])
+    total = math.fsum(cs)
+    mc = p["min_count"]
+    keep = [i for i in range(len(cs)) if cs[i] >= mc and cs[i] > 0]
+    st = p["stat"]
+    k = 1.0 if st == "count" else ((100.0 if st == "percent" else 1.0) / (total or 1.0))
+    return {"x": array.array("d", (cx[i] for i in keep)),
+            "y": array.array("d", (cy[i] for i in keep)),
+            "values": array.array("d", (cs[i] * k for i in keep)), "dx": dx}
+
+
+@stat("kde2d", reads=("bandwidth", "adjust", "cut", "points", "weights"),
+      defaults={"bandwidth": "scott", "adjust": 1.0, "cut": 3.0, "points": 128,
+                "weights": None})
+def kde2d(cols: Any, p: Params, scales: tuple[Any, ...]) -> dict[str, Any]:
+    """``{"fx", "fy": grid nodes after the axis scale functions, "flat", "w", "h"}``: the 2-D
+    Gaussian density of ``(x, y)`` over the data plus ``cut`` bandwidths (``weights``: as
+    repeated points)."""
+    sx, sy = scales
+    from ..density import Density
+    x, y, w = cols["x"], cols["y"], p.get("weights")
+    if w is not None:
+        if len(w) != len(x):
+            raise ValueError(f"{len(w)} weights for {len(x)} points")
+        y, _ = _kept(y, w)
+        x, w = _kept(x, w)
+    fx, fy = _f(x, sx), _f(y, sy)
+    d = Density(p["bandwidth"], p["adjust"])
+    h = d.covariance(fx, fy, w)
+    n = int(p["points"])
+    _, x0, x1 = kernels.extent(fx, None)
+    _, y0, y1 = kernels.extent(fy, None)
+    if not all(math.isfinite(v) for v in (x0, x1, y0, y1)) or \
+            not all(math.isfinite(v) for v in h):
+        return {"fx": array.array("d", [0.0, 1.0]), "fy": array.array("d", [0.0, 1.0]),
+                "flat": array.array("d", [0.0] * 4), "w": 2, "h": 2}
+    cut = p["cut"]
+    x0, x1 = x0 - cut * math.sqrt(h[0]), x1 + cut * math.sqrt(h[0])
+    y0, y1 = y0 - cut * math.sqrt(h[2]), y1 + cut * math.sqrt(h[2])
+    flat = kernels.kde2d_grid(fx, fy, h, x0, x1, n, y0, y1, n, w)
+    gx = array.array("d", (x0 + (x1 - x0) * i / (n - 1) for i in range(n)))
+    gy = array.array("d", (y0 + (y1 - y0) * j / (n - 1) for j in range(n)))
+    return {"fx": gx, "fy": gy, "flat": flat, "w": n, "h": n}
+
+
+def contour(flat: Any, w: int, h: int, fx: Any, fy: Any, levels: list[float], lines: bool,
+            bands: list[tuple[float, float, float]]) -> dict[str, Any]:
+    """``{"levels", "lines": {level: [(x, y, closed)]}, "bands": [(lo, hi, (xs, ys,
+    ring_starts))]}`` of a grid ``flat`` (``h`` rows of ``w``) at nodes ``fx``/``fy`` (after
+    the axis scale functions); ``bands``: ``(lo, hi, top)``, the band's limits and the top
+    used to cut it."""
+    out_lines: dict[float, Any] = {}
+    if lines:
+        for level in levels:
+            out_lines[level] = kernels.contour_lines(flat, w, h, fx, fy, level)
+    out_bands = []
+    for lo, hi, top in bands:
+        rings = kernels.contour_bands(flat, w, h, fx, fy, lo, top)
+        if len(rings[0]):
+            out_bands.append((lo, hi, rings))
+    return {"levels": levels, "lines": out_lines, "bands": out_bands, "f_space": True}