plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/presets/hist.py

@@ -0,0 +1,391 @@
+"""Histograms: counts (or densities…) of values in bins (stat ``bin``), as bars
+(``Rects``) or steps (``Band`` and ``Path``)."""
+
+import array
+import math
+from typing import Any
+
+from .._methods import HistMixin
+from .. import columns, groups, kernels
+from ..color.values import with_alpha
+from ..labels import bar_labels, check_labels, label_size
+from ..layers import stats
+from ..layers.base import Series, common
+from ..layers.core import Layer, Table
+from ..layers.geoms import GEOMS, RECTS
+from ..layers.grammar import Lay, Spec, axis_of, flipped
+from ..layers.paint import Paint, base_colors, role
+from ..layers.positions import Dodge, bin_parts, check_stack
+from ..numbers import NumberStyle, check_format, format_numbers
+from ..settings import Setting, boolean, either, literal, number, one_of, pair, table
+from ..text import font_of
+from ..transform import settings_both as coord_settings
+from ._util import faded, placed_text, set_color_value
+
+__all__ = ["Hist"]
+
+_STATS = ("count", "density", "probability", "percent", "frequency")
+
+
+def _auto_fill_opacity(h: "Hist") -> Any:
+    """``fill_opacity="auto"``: 0.5 for overlaid sets, else 1."""
+    if len(h.cols.sets) > 1 and not h.resolve("stack") and not h.resolve("dodge"):
+        return 0.5
+    return 1.0
+
+
+class Hist(HistMixin, Series):
+    """A histogram of ``values``: one array, or several (a dict or a list of arrays) that
+    share the same bins.
+
+    Dates draw on a time axis.  ``bins``: a count (at most 10⁶), edges, or numpy's rules
+    (``auto`` is numpy 2's; a rule asking for more than 10⁶ bins, or a count of bins
+    narrower than the floats of the range can tell apart, is an error).  Bins are even on
+    the axis scale (``bins_scale="axis"``): on a log axis, in log space; edges or a
+    ``range`` outside the axis' scale (0 on a log axis) are refused.  ``stat`` turns counts
+    into densities (area 1), probabilities, percents or counts per unit, per unit of the
+    axis' space; ``cumulative`` accumulates them.  Several sets overlay (``fill="auto"``:
+    opacity 0.5), stack (``stack=True``) or dodge (``dodge=True``).  ``hist.stats``:
+    ``edges``, ``counts`` and ``heights`` per set.
+
+    Example::
+
+        rng = random.Random(1)
+        p = plt.Plot(width=240, height=160)
+        p.hist({"a": [rng.gauss(0, 1) for _ in range(400)],
+                "b": [rng.gauss(1.5, 0.7) for _ in range(400)]}, bins=24)
+    """
+
+    SETTINGS = table(
+        **coord_settings(),
+        bins=Setting(stats.check_bins,
+                     doc="A count, edges, or a rule: `auto`, `fd`, `sturges`, `scott`, `sqrt`, "
+                         "`rice`, `doane` (numpy's)."),
+        range=Setting(either(literal(None), pair(number())), doc="Range of the bins; default "
+                                                                 "the data range."),
+        weights=Setting(columns.weights, doc="A weight per value (per set for several sets)."),
+        stat=Setting(one_of(*_STATS),
+                     doc="`count`, `density` (area 1), `probability`, `percent` or "
+                         "`frequency` (count per unit); densities and frequencies per unit "
+                         "of the axis' space (log axes: per log unit, as `kde`)."),
+        cumulative=Setting(boolean, doc="Accumulate the bins."),
+        shape=Setting(one_of("bar", "step", "stepfilled"),
+                      doc="`bar` (adjacent bars), `step` (outline) or `stepfilled`."),
+        bins_scale=Setting(one_of("axis", "linear"),
+                           doc="`axis`: bins even on the axis scale (log axes: in log space); "
+                               "`linear`: even in data units."),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (bins along x) or `horizontal`."),
+        stack=Setting(check_stack, doc="Stack the sets (and other stacked histograms "
+                                              "with the same bins)."),
+        dodge=Setting(boolean, doc="Put the sets side by side within each bin."),
+        color=Setting(set_color_value,
+                      doc="Fill color, one per set (a list, or a dict by set name); default "
+                          "the plot's colors."),
+        **groups.Stroke.embed("edge_",
+                              only=("color", "line_width"),
+                              docs={"color": "Bar outline color; default none.",
+                                    "line_width": "Bar outline width; default 0 (none)."}),
+        **groups.Stroke.embed("line_",
+                              only=("color", "line_width"),
+                              inherited=("line_width",),
+                              docs={"color": "Step and outline color; default each set's "
+                                             "color.",
+                                    "line_width": "Step line width."}),
+        outline=Setting(boolean,
+                        doc="`bar` and `stepfilled` shapes: the outer outline of each set, in "
+                            "`line_color` (dodged bars: each bar's outline)."),
+        fill=Setting(groups.fill_value,
+                     doc="Fill: `True` (each set's color), a color, or `False` (none)."),
+        fill_opacity=Setting(either(literal("auto"), number(0, 1)), auto=_auto_fill_opacity,
+                             doc="Opacity of the fills, times `opacity` (lines keep "
+                                 "`opacity`); `\"auto\"`: 0.5 for overlaid sets, else 1."),
+        saturation=Setting(number(0, 1), doc="Saturation of the fills."),
+        value_labels=Setting(check_labels, doc="Value labels on bars (as `Bar.value_labels`)."),
+        value_label_format=Setting(check_format, doc="Number format of the value labels."),
+        **common("name", "opacity", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+        **groups.NumberFormat.embed(),
+    )
+    DATA = {"values": "samples"}
+
+    def __init__(self, values: Any, plot: Any = None, **settings: Any) -> None:
+        super().__init__(plot=plot, **settings)
+
+    @property
+    def sets(self) -> list[tuple[Any, Any]]:
+        """``(name, values)`` of each set."""
+        return self.cols.sets
+
+    def _axis_scale(self) -> Any:
+        return stats.axis_scale(axis_of(self))
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        """``{"edges": bin edges, "heights": [per set], "counts": [per set]}`` (stacked
+        calls on the edges they share)."""
+        return stats.run(self, "bin")
+
+    def set_colors(self, ctx: Any) -> list[Any]:
+        """Each set's color (saturation applied), before opacity."""
+        return base_colors(self, ctx, [k for k, _ in self.cols.sets])
+
+    def _fills(self, ctx: Any) -> list[Any]:
+        """Each set's fill: ``fill``'s color at ``fill_opacity`` times ``opacity``."""
+        fc, fa = groups.fill_parts(self)
+        cols = self.set_colors(ctx)
+        if fc is not None:
+            cols = [ctx.color(fc)] * len(cols)
+        return faded(cols, self._opacity() * fa)
+
+    def _lines(self, ctx: Any) -> list[Any]:
+        """Each set's line color at ``opacity``."""
+        return faded(self.set_colors(ctx), self._opacity())
+
+    def _opacity(self) -> float:
+        a = self.resolve("opacity")
+        return 1.0 if a is None else a
+
+    SPEC = Spec(
+        [Lay("rects", ("hist.bars", {"table": "#bars"}), table="bars", when=("shape", "bar"),
+             key=False, stat="bin", drop_empty=True,
+             position=lambda s: "stack" if s.resolve("stack") else
+             "dodge" if s._dodged() else "identity"),
+         # the legend symbol
+         Lay("path", ("stroke", {"color": "_key_strokes()"}), table="sets", per_set=True,
+             when=("shape", "step"), drawn=False),
+         Lay("rects", ("hist.key", {}), table="sets", per_set=True,
+             when=("shape", ("bar", "stepfilled")), drawn=False)],
+        tables={"sets": lambda s, b: _sets(s, b), "bars": lambda s, b: Table()},
+        entries="sets", key={"fill": "_key_fills()", "stroke": "_key_strokes()"},
+        color_count="sets", zero=("y",), titles={"values": "x"}, finish=lambda s, b: _finish(s, b))
+
+    def _dodged(self) -> bool:
+        return bool(self.resolve("dodge")) and len(self.cols.sets) > 1
+
+    # -- bars -----------------------------------------------------------------------
+
+    def _bars(self, bars: Table, sets: list[Table], edges: Any) -> None:
+        """The bins of every set in one table, set after set: edges ``x0``/``x1`` (dodged
+        sets: their part of the bin, even on the axis scale), bottoms and tops; ``owner``:
+        the set of each bin.  Bins without height are drawn as none (``drop_empty``)."""
+        m = len(edges) - 1
+        lo_e, hi_e = edges[:-1], edges[1:]
+        x0, x1, y0, y1 = (array.array("d") for _ in range(4))
+        owner: list[int] = []
+        scale = self._axis_scale()
+        for k, s in enumerate(sets):
+            if s.dodge is not None:
+                a, b = bin_parts(s.dodge, lo_e, hi_e, scale)
+                x0.extend(a)
+                x1.extend(b)
+            else:
+                x0.extend(lo_e)
+                x1.extend(hi_e)
+            y0.extend(s["bottom"])
+            y1.extend(s["top"])
+            owner.extend([k] * m)
+        bars.update(x0=x0, x1=x1, y0=y0, y1=y1, owner=owner)
+
+    def _bar_paint(self, ctx: Any, bars: Table) -> dict[str, Any]:
+        fills_by = self._fills(ctx)
+        lc, lw = self.resolve("edge_color"), self.resolve("edge_width")
+        return {"fill": [fills_by[k] for k in bars["owner"]],
+                "stroke": with_alpha(ctx.color(lc), self._opacity()) if lc is not None and lw
+                else None,
+                "line_width": lw or None, "simplify": self.resolve("simplify")}
+
+    # -- steps and outlines ------------------------------------------------------------
+
+    @staticmethod
+    def _steps(edges: Any, s: Table) -> tuple[array.array, array.array, array.array]:
+        """The step polylines of a set: bin coordinates (each bin's two edges), tops and
+        bottoms (each twice; bins without a finite value at 0)."""
+        m = len(edges) - 1
+        tb = array.array("d", bytes(16 * m))
+        tb[0::2] = edges[:-1]
+        tb[1::2] = edges[1:]
+        steps = []
+        for col in ("top", "bottom"):
+            v = kernels.scaled(s[col], 1.0, 0.0, None, nan=0.0)
+            out = array.array("d", bytes(16 * m))
+            out[0::2] = v
+            out[1::2] = v
+            steps.append(out)
+        return tb, steps[0], steps[1]
+
+    def _outline_colors(self, ctx: Any) -> list[Any]:
+        """Each set's step and outline color: ``line_color`` at ``opacity``, else the
+        set's line color."""
+        lc = self.resolve("line_color")
+        if lc is None:
+            return self._lines(ctx)
+        return [with_alpha(ctx.color(lc), self._opacity())] * len(self.cols.sets)
+
+    def _outline_layer(self, s: Table, edges: Any, k: int, flip: bool) -> Layer:
+        """A set's outer outline: down to the bottom at both ends, along the tops."""
+        tb, tv, bv = self._steps(edges, s)
+        b = array.array("d", [tb[0]]) if len(tb) else array.array("d")
+        b.extend(tb)
+        v = array.array("d", [bv[0]]) if len(bv) else array.array("d")
+        v.extend(tv)
+        if len(tb):
+            b.append(tb[-1])
+            v.append(bv[-1])
+        t = Table(x=b, y=v)
+        return Layer(GEOMS["path"], t, paint=Paint(self, "stroke", color="_outline_colors()",
+                                                   index=k), flip=flip, key=False, ends=True)
+
+    # -- labels ---------------------------------------------------------------------
+
+    def _label_items(self, ctx: Any, bars: Layer) -> list[Any]:
+        if self.resolve("shape") != "bar":
+            return []
+        lay = bars.columns(ctx)
+        rects = RECTS.page_rects(ctx, lay)
+        keep = RECTS.kept(lay, rects)
+        fills = self._bar_paint(ctx, bars.table)["fill"]
+        t = bars.table
+        texts = format_numbers([t["y1"][i] - t["y0"][i] for i in keep],
+                               self.resolve("value_label_format"), NumberStyle.of(self))
+        font = font_of(self, self.resolve("font_size"),
+                       color=ctx.color(self.resolve("text_color")))
+        return bar_labels(ctx.canvas, [rects[i] for i in keep], texts, [fills[i] for i in keep],
+                          self.resolve("value_labels"), bars.flip, font,
+                          stacked=bool(self.resolve("stack")))
+
+    def _label_room(self, fonts: Any, role: str, sets: list[Table],
+                    val: str) -> list[tuple[float, float, int]]:
+        if self.resolve("value_labels") != "outside" or self.resolve("shape") != "bar" \
+                or role != val:
+            return []
+        pairs = [(lo, hi) for s in sets for lo, hi in zip(s["bottom"], s["top"])
+                 if math.isfinite(lo) and math.isfinite(hi) and hi != lo]
+        texts = format_numbers([hi - lo for lo, hi in pairs], self.resolve("value_label_format"),
+                               NumberStyle.of(self))
+        font = font_of(self, self.resolve("font_size"))
+        horizontal = flipped(self)
+        return [(hi, label_size(fonts, text, font, horizontal), -1 if hi < lo else 1)
+                for (lo, hi), text in zip(pairs, texts) if text not in (None, "")]
+
+    # -- legend ---------------------------------------------------------------------
+
+    def _key_strokes(self, ctx: Any) -> list[Any]:
+        """Each set's symbol outline: the step line, the bar edges or the outline."""
+        n = len(self.cols.sets)
+        if self.resolve("shape") == "step":
+            return self._lines(ctx)
+        lc = self.resolve("edge_color")
+        if lc is not None and self.resolve("edge_width"):
+            return [with_alpha(ctx.color(lc), self._opacity())] * n
+        if self.resolve("outline") and self.resolve("line_width"):
+            return self._outline_colors(ctx)
+        return [None] * n
+
+    def _key_fills(self, ctx: Any) -> list[Any]:
+        return [None] * len(self.cols.sets) if self.resolve("shape") == "step" \
+            else self._fills(ctx)
+
+
+@role("hist.bars")
+def _bars_paint(s: Hist, ctx: Any, glyph: bool, table: Any = None) -> dict[str, Any]:
+    return s._bar_paint(ctx, table)
+
+
+@role("hist.key")
+def _key_paint(s: Hist, ctx: Any, glyph: bool, index: int = 0) -> dict[str, Any]:
+    """A set's legend rectangle."""
+    edge = s.resolve("edge_color") is not None and s.resolve("edge_width")
+    fills, strokes = s._key_fills(ctx), s._key_strokes(ctx)
+    return {"fill": fills[index] if index < len(fills) else None,
+            "stroke": strokes[index] if index < len(strokes) else None,
+            "line_width": s.resolve("edge_width" if edge else "line_width")}
+
+
+@role("hist.outlines")
+def _outlines_paint(s: Hist, ctx: Any, glyph: bool, table: Any = None) -> dict[str, Any]:
+    """Dodged bars' outlines: ``line_color`` at ``opacity``, else each set's line color."""
+    c = s._outline_colors(ctx)
+    return {"fill": None, "stroke": [c[k] for k in table["owner"]],
+            "line_width": s.resolve("line_width"), "simplify": s.resolve("simplify")}
+
+
+def _sets(s: Hist, b: Any) -> list[Table]:
+    """A table per set: the heights of the bins, stacked (with the plot's stacked
+    histograms), dodged in the bins, or from 0."""
+    st = s.stats
+    edges = st["edges"]
+    stack = s.resolve("stack")
+    keys = [(round(a, 12), round(b_, 12)) for a, b_ in zip(edges, edges[1:])]
+    dodge = s._dodged() and s.resolve("shape") == "bar"
+    out = []
+    for k, h in enumerate(st["heights"]):
+        t = Table(keys=keys, heights=h)
+        if stack:
+            t.stack = (("hist", b.flip), stack)
+        else:
+            t["bottom"], t["top"] = [0.0] * len(h), list(h)
+        if dodge:
+            t.dodge = Dodge(s, ("hist", id(s)), b.flip, keys, token=k)
+        out.append(t)
+    return out
+
+
+def _finish(s: Hist, b: Any) -> None:
+    """The layers that need the stacked values (after the plot's positions), the value
+    labels, the value axis' extent."""
+    call, flip = b.call, b.flip
+    sets = b.tables["sets"]
+    edges = s.stats["edges"]
+    call.tables = sets
+    shape = s.resolve("shape")
+    val = b.role("y")
+    if shape == "bar":
+        bars = b.tables["bars"]
+        layer = call.layers[0]
+
+        def bar_layers() -> None:
+            s._bars(bars, sets, edges)
+            if s.resolve("outline") and s.resolve("line_width"):
+                if s._dodged():
+                    call.layers.append(Layer(GEOMS["rects"], bars,
+                                             paint=Paint(s, "hist.outlines", table=bars),
+                                             flip=flip, occupy=False, key=False,
+                                             drop_empty=True))
+                else:
+                    for k, t in enumerate(sets):
+                        call.layers.append(s._outline_layer(t, edges, k, flip))
+            if s.resolve("value_labels"):
+                call.layers.append(placed_text(
+                    s, id(s), lambda ctx: s._label_items(ctx, layer),
+                    lambda ctx: font_of(s, s.resolve("font_size"),
+                                        color=ctx.color(s.resolve("text_color")))))
+        call.after.append(bar_layers)
+        call.room = lambda fonts, role: s._label_room(fonts, role, sets, val)
+    else:
+        def step_layers() -> None:
+            stack = s.resolve("stack")
+            lw = s.resolve("line_width")
+            for k, t in enumerate(sets):
+                tb, tv, bv = s._steps(edges, t)
+                if not len(tb):
+                    continue
+                t["step_t"], t["step_top"], t["step_bottom"] = tb, tv, bv
+                if shape == "stepfilled":
+                    call.layers.append(Layer(GEOMS["band"], t, aes={
+                        "x": "step_t", "y1": "step_top", "y2": "step_bottom"},
+                        paint=Paint(s, "band", color="_fills()", index=k), flip=flip,
+                        stat="bin", position="stack" if stack else "identity", key=False))
+                if lw and (shape == "step" or s.resolve("outline")):
+                    call.layers.append(s._outline_layer(t, edges, k, flip))
+        call.after.append(step_layers)
+    allv = array.array("d", [0.0])
+
+    def value_extent() -> None:
+        for t in sets:
+            allv.extend(x for x in t["top"] if math.isfinite(x))
+            allv.extend(x for x in t["bottom"] if math.isfinite(x))
+    call.after.insert(0, value_extent)
+    call.extra[val] = allv
+    call.extra[b.role("x")] = edges
+    call.sticky_values[val] = [0.0]

plot_io/presets/hist2d.py

@@ -0,0 +1,87 @@
+"""2-D histograms (stat ``bin2d``): counts of points in rectangular bins, drawn as a
+heatmap (``Cells``)."""
+
+import array
+import numbers
+from typing import Any
+
+from .._methods import Hist2dMixin
+from .. import columns
+from ..layers import stats
+from ..layers.base import Series
+from ..settings import Setting, either, literal, number, one_of, pair, table
+from ..validators import real
+from .heatmap import Coords, Heatmap
+
+__all__ = ["Hist2d"]
+
+
+def _bins2(v: Any) -> Any:
+    if isinstance(v, (tuple, list)) and len(v) == 2 and not all(
+            real(x) is not None for x in v):
+        return (stats.check_bins(v[0]), stats.check_bins(v[1]))
+    if isinstance(v, (tuple, list)) and len(v) == 2 and all(
+            isinstance(x, numbers.Integral) and not isinstance(x, bool) for x in v):
+        return (stats.check_bins(v[0]), stats.check_bins(v[1]))
+    b = stats.check_bins(v)
+    return (b, b)
+
+
+def _range2(v: Any) -> Any:
+    return (pair(number())(v[0]), pair(number())(v[1]))
+
+
+class Hist2d(Hist2dMixin, Heatmap):
+    """A 2-D histogram of points ``(x, y)``: counts in bins (even on the axis scales),
+    drawn as a heatmap; bins with fewer than ``min_count`` points are left empty.
+
+    Drawn with :class:`Heatmap`'s settings; ``stat="density"`` is per unit area of the axes'
+    space; a colorbar source.
+
+    Example::
+
+        rng = random.Random(1)
+        x = [rng.gauss(0, 1) for _ in range(1000)]
+        p = plt.Plot(width=240, height=160)
+        p.hist2d(x, [v + rng.gauss(0, 0.7) for v in x], bins=20)
+    """
+
+    SETTINGS = table(
+        **{k: v for k, v in Heatmap.SETTINGS.items() if k not in ("origin",)},
+        bins=Setting(_bins2,
+                     doc="Bins of both axes, or `(x bins, y bins)`: counts, edges or rules "
+                         "(as `Hist`)."),
+        range=Setting(either(literal(None), _range2),
+                      doc="`((x0, x1), (y0, y1))`; default the data range."),
+        weights=Setting(lambda v: columns.numbers(v, "weights"), doc="A weight per point."),
+        stat=Setting(one_of("count", "density", "probability", "percent"),
+                     doc="`count`, `density` (volume 1), `probability` or `percent`."),
+        min_count=Setting(number(lo=0), doc="Bins below this count are transparent."),
+        origin=Setting(one_of("top", "bottom"), doc="Row of the first y bin."),
+    )
+
+    DATA = {"x": "numbers", "y": "numbers"}
+
+    def __init__(self, x: Any, y: Any, plot: Any = None, **settings: Any) -> None:
+        self.k = 1
+        Series.__init__(self, plot=plot, **settings)
+
+    def _inverts(self) -> bool:
+        return False
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        """``{"x_edges", "y_edges", "counts": rows (first y bin first), "values": rows}``."""
+        sx = stats.axis_scale(self.plot.x_axis)
+        sy = stats.axis_scale(self.plot.y_axis)
+        return stats.compute(self, "bin2d", (sx, sy))
+
+    def _grid(self) -> tuple[Any, int, int, int, Coords, Coords]:
+        st = self.stats
+        rows = st["values"]
+        flat = array.array("d")
+        for r in rows:
+            flat.extend(r)
+        h = len(rows)
+        w = len(rows[0]) if rows else 0
+        return flat, h, w, 1, Coords(st["x_edges"], w, "x"), Coords(st["y_edges"], h, "y")

plot_io/presets/kde.py

@@ -0,0 +1,162 @@
+"""Kernel density estimates (stat ``kde``): a curve per set (``Path``), filled
+(``Band``) or stacked."""
+
+import math
+from typing import Any
+
+from .._methods import KdeMixin
+from .. import columns, groups
+from ..color.values import with_alpha
+from ..layers import stats
+from ..layers.base import Series, common
+from ..layers.core import Table
+from ..layers.grammar import Lay, Spec
+from ..layers.positions import check_stack
+from ..settings import Setting, boolean, either, literal, number, one_of, pair, table
+from ..transform import settings_both as coord_settings
+from ..layers.paint import base_colors
+from ._util import set_color_value
+
+__all__ = ["Kde", "check_bandwidth"]
+
+
+def check_bandwidth(v: Any) -> Any:
+    if isinstance(v, str):
+        return one_of("scott", "silverman")(v)
+    return number(positive=True)(v)
+
+
+class Kde(KdeMixin, Series):
+    """A Gaussian kernel density estimate of ``values`` (one array, or several as a dict or
+    a list of arrays, on a common grid).
+
+    With ``y``, ``Kde(x, y)`` is a :class:`Kde2d`.  Each set's density is on a common grid
+    of ``points`` points, extending ``cut`` bandwidths past the data (within ``range``);
+    dates draw on a time axis.  ``fill`` fills under each curve (``True``, or a color, at
+    ``fill_opacity``).  ``bandwidth``: ``scott``, ``silverman`` (as scipy's
+    ``gaussian_kde``) or a number, times ``adjust``.  On log axes the density is computed in
+    log space, per log unit.  A set without a bandwidth (no values, one, all equal) or a
+    ``range`` outside the data has no curve (NaN densities), with a warning.
+    ``kde.stats``: ``grid``, ``densities``, ``bandwidths``.
+
+    Example::
+
+        rng = random.Random(1)
+        p = plt.Plot(width=240, height=160)
+        p.kde({"a": [rng.gauss(0, 1) for _ in range(200)],
+               "b": [rng.gauss(1.5, 0.7) for _ in range(200)]}, fill=True)
+    """
+
+    SETTINGS = table(
+        **coord_settings(),
+        bandwidth=Setting(check_bandwidth,
+                          doc="`scott`, `silverman`, or a bandwidth in data units."),
+        adjust=Setting(number(positive=True), doc="Factor applied to the bandwidth."),
+        cut=Setting(number(lo=0), doc="The curve extends this many bandwidths past the "
+                                           "data."),
+        range=Setting(either(literal(None), pair(number())),
+                      doc="Limits of the curve (within the data plus `cut`); default none."),
+        points=Setting(number(lo=16, hi=65536, integer=True),
+                       doc="Number of points of the curve."),
+        cumulative=Setting(boolean, doc="Plot the cumulative distribution."),
+        **groups.FillStyle.embed(docs={"fill": "Fill under the curve: `True` (its color), a "
+                                               "color, or `False` (stacked curves are "
+                                               "filled anyway)."}),
+        weights=Setting(columns.weights, doc="A weight per value (per set for several sets)."),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (values along x) or `horizontal`."),
+        stack=Setting(check_stack, doc="Stack the sets (seaborn's `multiple=\"stack\"`)."),
+        color=Setting(set_color_value,
+                      doc="Color, one per set (a list, or a dict by set name); default "
+                          "the plot's colors."),
+        **groups.Stroke.embed(only=("line_width", "line_style"),
+                              inherited=("line_width",),
+                              docs={"line_style": "Line style."}),
+        **common("name", "opacity", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    DATA = {"values": "samples"}
+
+    def __init__(self, values: Any, plot: Any = None, **settings: Any) -> None:
+        super().__init__(plot=plot, **settings)
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        """``{"grid": values, "densities": [per set], "bandwidths": [per set]}`` (densities
+        per unit of the axis scale; NaN for a set without a bandwidth; stacked calls on the
+        grid they share)."""
+        return stats.run(self, "kde")
+
+    def colors(self, ctx: Any) -> list[Any]:
+        return base_colors(self, ctx, [k for k, _ in self.cols.sets])
+
+    def _fill(self) -> tuple[Any, float, bool]:
+        """``(fill color or None, fill opacity times opacity, filled)``."""
+        fill_color, fill_opacity = groups.fill_parts(self)
+        stack = self.resolve("stack")
+        if stack and self.resolve("fill") is False:
+            fill_opacity = self.resolve("fill_opacity")
+        opacity = self.resolve("opacity")
+        fill_opacity *= 1.0 if opacity is None else opacity
+        return fill_color, fill_opacity, fill_opacity > 0 or bool(stack)
+
+    def _filled(self) -> bool:
+        return self._fill()[2]
+
+    def _fills(self, ctx: Any) -> list[Any]:
+        """Each set's fill: its color (or ``fill``'s) at the fill opacity."""
+        fill_color, fill_opacity, _ = self._fill()
+        out = []
+        for c in self.colors(ctx):
+            c = c if fill_color is None else ctx.color(fill_color)
+            out.append(with_alpha(c, fill_opacity) if c is not None else None)
+        return out
+
+    def _key_fills(self, ctx: Any) -> list[Any]:
+        return self._fills(ctx) if self._filled() else [None] * len(self.cols.sets)
+
+    def _lines(self, ctx: Any) -> list[Any]:
+        opacity = self.resolve("opacity")
+        return [with_alpha(c, 1.0 if opacity is None else opacity) for c in self.colors(ctx)]
+
+    SPEC = Spec(
+        [Lay("band", ("band", {"color": "_fills()", "extra": ("simplify",)}), table="sets",
+             per_set=True,
+             when="_filled()", aes={"y1": "top", "y2": "bottom"}, stat="kde",
+             position=lambda s: "stack" if s.resolve("stack") else "identity"),
+         Lay("path", ("stroke", {"color": "_lines()", "dash": True, "extra": ("simplify",)}),
+             table="sets", per_set=True, aes={"y": "top"}, stat="kde",
+             position=lambda s: "stack" if s.resolve("stack") else "identity",
+             occupy=lambda s: not s._filled(),
+             glyph=lambda s: "top" if s._filled() else "line")],
+        tables={"sets": lambda s, b: _sets(s, b)},
+        entries="sets", key={"fill": "_key_fills()", "stroke": "colors()"}, color_count="sets",
+        zero=("y",), titles={"values": "x"}, finish=lambda s, b: _value_extent(b))
+
+
+def _sets(s: Kde, b: Any) -> list[Table]:
+    """A table per set: the densities on the grid (stacked or from 0: the position)."""
+    st = b.stats["kde"]
+    g = st["grid"]
+    keys = [round(v, 12) for v in g]
+    return [Table(x=g, keys=keys, heights=d) for d in st["densities"]]
+
+
+def _value_extent(b: Any) -> None:
+    """The densities' axis includes 0 and the stacked tops."""
+    tops: list[float] = [0.0]
+
+    def extent() -> None:
+        for t in b.tables["sets"]:
+            tops.extend(v for v in t["top"] if math.isfinite(v))
+    b.call.after.append(extent)
+    b.call.extra[b.role("y")] = tops
+
+
+def _kde2d() -> type:
+    from .kde2d import Kde2d
+    return Kde2d
+
+
+Kde.with_y = staticmethod(_kde2d)          # type: ignore[attr-defined]