plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/presets/pie.py

@@ -0,0 +1,502 @@
+"""Pie and donut charts, on a plot without axes: wedges (``Polygons``) and labels
+(``Text``)."""
+
+import array
+import math
+import warnings
+from typing import Any
+
+import vec_io
+
+from ..canvas import Canvas
+from .._methods import PieMixin
+from .. import groups
+from ..color.values import ink_for
+from ..numbers import NumberStyle, check_format, format_numbers
+from ..color.values import color
+from ..settings import Setting, boolean, either, literal, number, one_of, table
+from ..units import resolve_raw
+from ..validators import Custom, angle, length
+from ..color.values import with_alpha
+from ..text import Font, font_of, measure
+from ..layers.base import Series, common
+from ..layers.core import Call, Layer, Table
+from ..layers.geoms import GEOMS
+from ..layers.grammar import entry
+from ..layers.paint import Paint, auto_colors, role
+from ..labels import column
+from ._util import given_colors, map_or_color, placed_text
+
+__all__ = ["Pie"]
+
+
+_OFFSET = length(lo=0, percent="radius")
+
+
+def _explode(v: Any) -> Any:
+    if isinstance(v, (list, tuple)):
+        return [_OFFSET(x) for x in v]
+    return _OFFSET(v)
+
+
+_EXPLODE = Custom(_explode, like=_OFFSET, inner=_OFFSET)
+
+
+def _outline(w: dict[str, Any], cx: float, cy: float, r: float, hole: float, end_seam: bool,
+             start_seam: bool) -> Any:
+    """The outline of an unexploded wedge without its seamed radial edges: open paths."""
+    a0, a1 = math.radians(w["start"]), math.radians(w["end"])
+    point = (lambda a, rr: (cx + rr * math.cos(a), cy - rr * math.sin(a)))
+    inner = hole * r
+    # edges in order around the wedge: (start point, append to the path, removed)
+    edges: list[tuple[tuple[float, float], Any, bool]] = [
+        (point(a0, inner), lambda p: p.line_to(*point(a0, r)), start_seam),
+        (point(a0, r), lambda p: _arc(p, cx, cy, r, a0, a1), False),
+        (point(a1, r), lambda p: p.line_to(*point(a1, inner)), end_seam)]
+    if hole:
+        edges.append((point(a1, inner), lambda p: _arc(p, cx, cy, inner, a1, a0), False))
+    first = next(i for i, e in enumerate(edges) if e[2])
+    edges = edges[first + 1:] + edges[:first + 1]   # starts after a removed edge
+    p = vec_io.Path()
+    open_ = False
+    for start, add, removed in edges:
+        if removed:
+            open_ = False
+            continue
+        if not open_:
+            p.move_to(*start)
+            open_ = True
+        add(p)
+    return p
+
+
+def _arc(path: Any, cx: float, cy: float, r: float, a0: float, a1: float) -> None:
+    """Append an arc of radius ``r`` from angle ``a0`` to ``a1`` (radians, counterclockwise
+    on the page: y up) as cubic Béziers of at most 90°."""
+    n = max(1, math.ceil(abs(a1 - a0) / (math.pi / 2) - 1e-9))
+    step = (a1 - a0) / n
+    k = 4.0 / 3.0 * math.tan(step / 4.0)
+    for i in range(n):
+        t0, t1 = a0 + i * step, a0 + (i + 1) * step
+        x0, y0 = cx + r * math.cos(t0), cy - r * math.sin(t0)
+        x3, y3 = cx + r * math.cos(t1), cy - r * math.sin(t1)
+        x1, y1 = x0 - k * r * math.sin(t0), y0 - k * r * math.cos(t0)
+        x2, y2 = x3 + k * r * math.sin(t1), y3 + k * r * math.cos(t1)
+        path.curve_to(x1, y1, x2, y2, x3, y3)
+
+
+class Pie(PieMixin, Series):
+    """A pie (or donut, with ``hole``) of ``values``: a sequence, or a dict
+    ``{label: value}``; the plot is drawn without axes.
+
+    Wedges start at ``start``; the plot is drawn without axes (``Plot.axes=False``, aspect
+    1).  ``hole`` makes a donut (``"40%"`` of the radius), ``explode`` moves wedges out
+    (``%`` of the radius, one value or one per wedge).  Names go outside (beside their
+    wedges; a crowded side's in a column beside the pie with elbow leaders, the smallest
+    wedges' left out with a warning when the column is taller than the plot), inside, or
+    into the legend (``name_position="none"``, the legend then outside right); ``color_map``
+    colors them (a map's colors for the wedges); ``value_labels`` writes percents or values inside, or outside with
+    a leader line when a wedge is too thin.
+
+    Example::
+
+        p = plt.Plot(width=240, height=160)
+        p.pie({"apples": 5, "pears": 3, "plums": 2, "figs": 1}, value_labels="percent")
+    """
+
+    SETTINGS = table(
+        names=Setting(lambda v: [str(x) for x in v],
+                      doc="Wedge names (default: the dict's keys)."),
+        color_map=Setting(map_or_color,
+                          doc="Wedge colors: a map (a list of colors or a qualitative map: "
+                              "taken in turn; another kind: evenly spaced), one color, a "
+                              "kind (that kind's map) or `\"auto\"` (the plot's next "
+                              "colors)."),
+        start=Setting(angle(), doc="Angle where the first wedge starts (degrees, 0: "
+                                          "3 o'clock, 90: 12 o'clock)."),
+        counterclockwise=Setting(boolean, doc="Direction of the wedges."),
+        hole=Setting(length(lo=0, percent="radius"), doc="Radius of the hole (`%` of the "
+                                               "radius): a donut."),
+        explode=Setting(_EXPLODE, doc="Offset of the wedges from the centre (`%` of the "
+                                      "radius): one value or one per wedge."),
+        sort=Setting(boolean, doc="Sort the wedges by decreasing value."),
+        name_position=Setting(one_of("outside", "inside", "none"),
+                              doc="Where the names go: `outside`, `inside` or `none` (in "
+                                   "the legend instead)."),
+        value_labels=Setting(either(literal(False), one_of("percent", "value")),
+                             doc="Write each wedge's `percent` or `value` inside it (outside, "
+                                 "with a leader line, when it does not fit)."),
+        label_spacing=Setting(length(positive=True, percent="em"),
+                              doc="Smallest distance between outside labels on a side."),
+        value_label_format=Setting(check_format,
+                                   doc="Number format of the value labels (percentages: of "
+                                       "100)."),
+        **groups.Stroke.embed("edge_",
+                              only=("color", "line_width"),
+                              checks={"color": groups.series_color},
+                              docs={"color": "Wedge outline color: a color, `\"series\"` "
+                                             "(each wedge's own color) or `none`.",
+                                    "line_width": "Wedge outline width."}),
+        opacity=Setting(number(0, 1), doc="Opacity."),
+        **groups.FillStyle.embed(docs={"fill": "Wedge fill: `True` (each wedge's color), a "
+                                               "color, or `False`.",
+                                       "fill_opacity": "Opacity of the fills, times "
+                                                       "`opacity` (outlines keep `opacity`)."}),
+        seam_color=Setting(color,
+                           doc="The edges neighbouring wedges share, in this color; `none`: "
+                               "both outlines as drawn."),
+        **common("name", "z", "rasterize", "simplify", "font_size", "font_family", "text_color"),
+        **groups.NumberFormat.embed(),
+    )
+    AXES = False
+
+    DATA = {"values": "wedges"}
+
+    def __init__(self, values: Any, plot: Any = None, **settings: Any) -> None:
+        if any(not (v >= 0) for v in self.vals if math.isfinite(v)):
+            raise ValueError("pie values must be non-negative")
+        super().__init__(plot=plot, **settings)
+        if not self.plot.is_set("axes"):
+            self.plot.set(axes=False)
+        if not self.plot.legend.is_placed():
+            self.plot.legend.set(side="right")
+
+    @property
+    def vals(self) -> Any:
+        """The value of each wedge."""
+        return self.cols["values"]
+
+    # -- geometry ---------------------------------------------------------------------
+
+    def wedge_names(self) -> list[Any]:
+        given = self.resolve("names")
+        if given is not None:
+            if len(given) != len(self.vals):
+                raise ValueError(f"{len(given)} names for {len(self.vals)} wedges")
+            return given
+        return list(self.cols.categories)
+
+    def order(self) -> list[int]:
+        idx = [i for i in range(len(self.vals)) if math.isfinite(self.vals[i]) and self.vals[i] > 0]
+        if self.resolve("sort"):
+            idx.sort(key=lambda i: -self.vals[i])
+        return idx
+
+    @property
+    def stats(self) -> list[dict[str, Any]]:
+        """Per wedge (in drawing order): ``index``, ``value``, ``fraction``, ``start`` and
+        ``end`` angles (degrees, counterclockwise from 3 o'clock)."""
+        order = self.order()
+        total = math.fsum(self.vals[i] for i in order)
+        sign = 1.0 if self.resolve("counterclockwise") else -1.0
+        a = self.resolve("start")
+        if not isinstance(a, (int, float)):
+            raise ValueError(f"Pie: start is not an angle: {self.get('start')!r}")
+        out = []
+        for i in order:
+            frac = self.vals[i] / total if total else 0.0
+            b = a + sign * 360.0 * frac
+            out.append({"index": i, "value": self.vals[i], "fraction": frac, "start": a, "end": b})
+            a = b
+        return out
+
+    def _fraction(self, name: str, raw: Any, r: float | None) -> float:
+        """A length of setting ``name`` as a fraction of the radius ``r`` (px; ``None``:
+        unknown, lengths count as 0)."""
+        a = resolve_raw(self, name, _OFFSET, raw, of=0.0)
+        b = resolve_raw(self, name, _OFFSET, raw, of=1.0)
+        if a is None or b is None:
+            raise ValueError(f"Pie setting {name!r}: {raw!r} gives no length")
+        return b - a + (a / r if r else 0.0)
+
+    def _explode_of(self, i: int, r: float | None = None) -> float:
+        e = self._raw("explode")
+        if e is None:
+            return 0.0
+        if isinstance(e, list):
+            if len(e) != len(self.vals):
+                raise ValueError(f"{len(e)} explode values for {len(self.vals)} wedges")
+            e = e[i]
+        return self._fraction("explode", e, r)
+
+    def _hole(self, r: float) -> float:
+        """``hole`` as a fraction of the radius ``r``."""
+        return self._fraction("hole", self._raw("hole"), r)
+
+    def _reach(self) -> float:
+        n = len(self.vals) if self._raw("explode") is not None else 0
+        ex = max((self._explode_of(i) for i in range(n)), default=0.0)
+        out = self.resolve("name_position") == "outside" or self.resolve("value_labels")
+        return 1.0 + ex + (0.45 if out else 0.05)
+
+    def wedge_colors(self, ctx: Any) -> list[Any]:
+        """Colors in value order (one per value)."""
+        n = len(self.vals)
+        given = given_colors(self, n)
+        if given is not None:
+            given = given if isinstance(given, list) else [given]
+            cols = [ctx.color(given[i % len(given)]) for i in range(n)]
+        else:
+            cols = auto_colors(self, ctx)
+            cols = (cols * (n // max(len(cols), 1) + 1))[:n]
+        a = self._opacity()
+        return [with_alpha(c, a) for c in cols]
+
+    def _opacity(self) -> float:
+        a = self.resolve("opacity")
+        if not isinstance(a, (int, float)):
+            raise ValueError(f"Pie: opacity is not a number: {self.get('opacity')!r}")
+        return a
+
+    def wedge_fills(self, ctx: Any) -> list[Any]:
+        """Fills in value order: the colors at ``fill_opacity``."""
+        fc, f = groups.fill_parts(self)
+        cols = self.wedge_colors(ctx)
+        if fc is not None:
+            cols = [with_alpha(ctx.color(fc), self._opacity())] * len(cols)
+        return [with_alpha(c, (c[3] if isinstance(c, tuple) and len(c) > 3 else 1.0) * f)
+                for c in cols]
+
+    def wedge_edges(self, ctx: Any) -> list[Any]:
+        """Outline colors in value order (``None``: no outline)."""
+        v = self.resolve("edge_color")
+        if v == "series":
+            return self.wedge_colors(ctx)
+        return [ctx.color(v)] * len(self.vals)
+
+    # -- the preset --------------------------------------------------------------------
+
+    def _center(self, ctx: Any) -> tuple[float, float, float]:
+        cx, cy = ctx.xmap(0.0), ctx.ymap(0.0)
+        r = abs(ctx.xmap(1.0) - cx)
+        return cx, cy, r
+
+    def _wedges(self, ctx: Any) -> dict[str, Any]:
+        """The wedges in page units: paths, fills, outline colors, and with seams the
+        outlines (without the seamed radial edges) and the seams."""
+        cx, cy, r = self._center(ctx)
+        hole = self._hole(r)
+        cols, edges = self.wedge_fills(ctx), self.wedge_edges(ctx)
+        paths, fills, strokes = [], [], []
+        st = self.stats
+        for w in st:
+            i = w["index"]
+            a0, a1 = math.radians(w["start"]), math.radians(w["end"])
+            mid = (a0 + a1) / 2
+            ex = self._explode_of(i, r) * r
+            ox, oy = cx + ex * math.cos(mid), cy - ex * math.sin(mid)
+            p = vec_io.Path()
+            if w["fraction"] >= 1.0 - 1e-12:
+                p.move_to(ox + r, oy)
+                _arc(p, ox, oy, r, 0.0, 2 * math.pi)
+                p.close()
+                if hole:
+                    p.move_to(ox + hole * r, oy)
+                    _arc(p, ox, oy, hole * r, 2 * math.pi, 0.0)
+                    p.close()
+            else:
+                p.move_to(ox + r * math.cos(a0), oy - r * math.sin(a0))
+                _arc(p, ox, oy, r, a0, a1)
+                if hole:
+                    p.line_to(ox + hole * r * math.cos(a1), oy - hole * r * math.sin(a1))
+                    _arc(p, ox, oy, hole * r, a1, a0)
+                else:
+                    p.line_to(ox, oy)
+                p.close()
+            paths.append(p)
+            fills.append(cols[i])
+            strokes.append(edges[i])
+        lw = self.resolve("edge_width")
+        seam = ctx.color(self.resolve("seam_color"))
+        seamed = set()                            # wedges k whose end touches wedge k + 1
+        if seam is not None and lw and len(st) > 1:
+            for k, w in enumerate(st):
+                nxt = st[(k + 1) % len(st)]
+                if not (self._explode_of(w["index"], r) or self._explode_of(nxt["index"], r)):
+                    seamed.add(k)                 # exploded wedges do not touch
+        out: dict[str, Any] = {"paths": paths, "fill": fills, "stroke": strokes,
+                               "line_width": lw, "simplify": self.resolve("simplify")}
+        if not seamed:
+            return out
+        n = len(st)
+        outlines = []
+        for k, w in enumerate(st):
+            end, start = k in seamed, (k - 1) % n in seamed
+            whole = not (end or start) or w["fraction"] >= 1.0 - 1e-12
+            outlines.append(paths[k] if whole else _outline(w, cx, cy, r, hole, end, start))
+        segs: list[tuple[float, ...]] = []
+        for k in sorted(seamed):
+            a = math.radians(st[k]["end"])
+            c, s_ = math.cos(a), -math.sin(a)
+            segs.append((cx + hole * r * c, cy + hole * r * s_, cx + r * c, cy + r * s_, lw))
+        out.update(outlines=outlines, seams=segs, seam=seam)
+        return out
+
+    def layers(self) -> Call:
+        call = Call(self)
+        key = id(self)
+
+        t = Table()
+        t.lazy["page_paths"] = lambda ctx: _wedges(self, ctx)["paths"]
+
+        call.layers.append(Layer(GEOMS["polygons"], t, paint=Paint(self, "pie.wedges"),
+                                 stat="identity", key=False))
+
+        def font(ctx: Any) -> Any:
+            return font_of(self, self.resolve("font_size"),
+                           color=ctx.color(self.resolve("text_color")))
+
+        def labels(ctx: Any) -> list[Any]:
+            cx, cy, r = self._center(ctx)
+            f = font(ctx)
+            inside, placed = self._labels(ctx.canvas, cx, cy, r, f, self.wedge_fills(ctx))
+            return inside + self._outside_labels(placed, f, cx, r, ctx.rect[1], ctx.rect[3],
+                                                 True)
+
+        call.layers.append(placed_text(self, key, labels, font))
+        if self.resolve("name_position") == "none":
+            names = self.wedge_names()
+            if names:
+                for k, w in enumerate(self.stats):
+                    key_layer = Layer(GEOMS["rects"], Table(),
+                                      paint=Paint(self, "pie.key", index=k))
+                    call.entries.append(entry(self, names[w["index"]], [key_layer],
+                                              fill="symbol", stroke="symbol",
+                                              marker=key_layer.paint))
+        call.axes = False
+        call.color_count = 0 if given_colors(self, len(self.vals)) is not None \
+            else len(self.vals)
+        r = self._reach()
+        call.extra = {"x": array.array("d", [-r, r]), "y": array.array("d", [-r, r])}
+        call.exact = {"x", "y"}
+        call.overhang = self.overhang
+        return call
+
+    def overhang(self, fonts: Any, w: float, h: float) -> tuple[float, float]:
+        """How far (px) the outside labels reach past the left and right of axes ``w`` ×
+        ``h``."""
+        r = min(w, h) / (2 * self._reach())
+        font = font_of(self, self.resolve("font_size"))
+        left = right = 0.0
+        placed = self._labels(fonts, w / 2, h / 2, r, font, None)[1]
+        for text, tx, _, _, ha, *_ in self._outside_labels(placed, font, w / 2, r, 0.0, h):
+            tw = measure(fonts, text, font)[0]
+            if ha == "right":
+                left = max(left, tw - tx)
+            else:
+                right = max(right, tx + tw - w)
+        return left, right
+
+    def _labels(self, canvas: Canvas, cx: float, cy: float, r: float, font: Font,
+                cols: list[Any] | None) -> tuple[list[Any], list[list[Any]]]:
+        """The labels inside the wedges (``cols``: the wedge fills; ``None``: measure only)
+        as ``(text, x, y, color, ha, va)``, and the outside ones, for
+        :meth:`_outside_labels`."""
+        hole = self._hole(r)
+        names = self.wedge_names()
+        pos = self.resolve("name_position")
+        vl = self.resolve("value_labels")
+        stats = self.stats
+        texts: list[Any] = [None] * len(stats)
+        placed: list[list[Any]] = []
+        inside: list[Any] = []
+        if vl:
+            vals = [100.0 * w["fraction"] if vl == "percent" else w["value"] for w in stats]
+            style = NumberStyle.of(self)
+            fmt = self.resolve("value_label_format")
+            if vl == "percent" and fmt == "auto":
+                style.suffix = style.suffix or "%"
+                if style.precision is None:
+                    style.precision = 2
+            texts = format_numbers(vals, fmt, style)
+        for k, w in enumerate(stats):
+            i = w["index"]
+            a0, a1 = math.radians(w["start"]), math.radians(w["end"])
+            mid = (a0 + a1) / 2
+            ex = self._explode_of(i, r) * r
+            ox, oy = cx + ex * math.cos(mid), cy - ex * math.sin(mid)
+            ux, uy = math.cos(mid), -math.sin(mid)
+            side = "left" if ux >= 0 else "right"
+            outside_texts = []
+            if names and pos == "outside":
+                outside_texts.append(names[i])
+            if names and pos == "inside" and cols is not None:
+                inside.append((names[i], ox + ux * r * (0.5 + hole / 2),
+                               oy + uy * r * (0.5 + hole / 2), ink_for(cols[i]), "center",
+                               "bottom" if vl else "center"))
+            if texts[k] is not None:
+                rin = r * (0.5 + hole / 2) if hole else r * 0.62
+                tw, ta, td = measure(canvas, texts[k], font)
+                arc_len = abs(a1 - a0) * rin
+                fits = arc_len >= 1.2 * max(tw, ta + td) and (1 - hole) * r >= 1.1 * (ta + td)
+                if fits:
+                    if cols is not None:
+                        inside.append((texts[k], ox + ux * rin, oy + uy * rin,
+                                       ink_for(cols[i]), "center",
+                                       "top" if names and pos == "inside" else "center"))
+                else:
+                    outside_texts.append(texts[k])
+            if outside_texts:
+                text = "  ".join(str(t) for t in outside_texts) if all(
+                    isinstance(t, str) for t in outside_texts) else outside_texts[0]
+                lead = not (names and pos == "outside") or len(outside_texts) > 1
+                placed.append([oy + uy * r * 1.12, ox + ux * r * 1.12, side, text, lead,
+                               (ox + ux * r, oy + uy * r), w["value"]])
+        return inside, placed
+
+    def _outside_labels(self, placed: list[list[Any]], font: Font, cx: float, r: float,
+                        lo: float, hi: float, warn: bool = False) -> list[Any]:
+        """The outside labels of each side: beside their wedges when they keep
+        ``label_spacing`` apart within ``lo``–``hi`` (page y), else in a column beside the
+        pie with elbow leaders (:func:`~plot_io.labels.column`), the smallest wedges'
+        left out (with a warning: ``warn``) when the column is taller than ``lo``–``hi``."""
+        gap = self.resolve("label_spacing")
+        n = len(self.vals) if self._raw("explode") is not None else 0
+        ex = max((self._explode_of(i, r) for i in range(n)), default=0.0)
+        out: list[Any] = []
+        dropped = 0
+        for side in ("left", "right"):
+            items = sorted((p for p in placed if p[2] == side), key=lambda p: p[0])
+            ys = [p[0] for p in items]
+            if all(b - a >= gap - 1e-9 for a, b in zip(ys, ys[1:])) and all(
+                    lo + gap / 2 <= y <= hi - gap / 2 for y in ys):
+                for ty, tx, _, text, lead, (ax, ay), _ in items:
+                    leader = (ax, ay, tx - (3 if side == "left" else -3), ty) if lead else None
+                    out.append((text, tx, ty, font.color, side, "center", 0.0, None, leader))
+                continue
+            x = cx + (1 if side == "left" else -1) * r * (1.12 + ex)
+            got = column([p[5] for p in items], ys, [gap] * len(items), x,
+                         max(0.06 * r, 4.0), lo, hi, [p[6] for p in items])
+            for p, g in zip(items, got):
+                if g is None:
+                    dropped += 1
+                    continue
+                out.append((p[3], x, g[0], font.color, side, "center", 0.0, None, g[1]))
+        if dropped and warn:
+            warnings.warn(f"pie: {dropped} outside labels do not fit beside the pie; the "
+                          "smallest wedges' are left out", UserWarning, stacklevel=2)
+        return out
+
+
+def _wedges(s: Pie, ctx: Any) -> dict[str, Any]:
+    from ._util import memo
+    return memo(ctx, (id(s), "wedges"), lambda: s._wedges(ctx))
+
+
+@role("pie.wedges")
+def _wedges_paint(s: Pie, ctx: Any, glyph: bool) -> dict[str, Any]:
+    p = dict(_wedges(s, ctx))
+    p.pop("paths")
+    return p
+
+
+@role("pie.key")
+def _key_paint(s: Pie, ctx: Any, glyph: bool, index: int = 0) -> dict[str, Any]:
+    """The legend rectangle of wedge ``index``."""
+    st = s.stats
+    if index >= len(st):
+        return {"fill": None, "stroke": None, "line_width": None}
+    k = st[index]["index"]
+    edge = s.wedge_edges(ctx)[k] if s.resolve("edge_width") else None
+    return {"fill": s.wedge_fills(ctx)[k], "stroke": edge,
+            "line_width": s.resolve("edge_width") if edge is not None else None}

plot_io/presets/regression.py

@@ -0,0 +1,115 @@
+"""Regression (stat ``regression``): a fitted curve (``Path``, polynomial or LOWESS) with a
+confidence band (``Band``) and the points (``Points``)."""
+
+from typing import Any
+
+from .._methods import RegressionMixin
+from .. import columns, groups
+from ..color.values import color
+from ..layers import stats
+from ..layers.base import Series, column, common
+from ..layers.core import Table
+from ..layers.grammar import Lay, Spec
+from ..layers.paint import xy_density_points
+from ..settings import Setting, boolean, either, literal, number, one_of, pair, table
+from ..transform import settings_both as coord_settings
+
+__all__ = ["Regression", "t_quantile"]
+
+t_quantile = stats.t_quantile
+
+
+class Regression(RegressionMixin, Series):
+    """A regression of ``y`` on ``x``: a polynomial of ``order`` (least squares) with a
+    confidence band of the mean, or a LOWESS curve; ``scatter`` also draws the points
+    (numbers per point in ``marker_color`` map through the series' color axis).
+
+    The band is Student's t.  ``lowess=True``: no band; above 10,000 points it fits at
+    points 1 % of the x range apart and interpolates between them (as statsmodels'
+    ``delta``).  ``logx`` fits against log x; ``range`` sets the x range of the polynomial
+    curve (default the data's), drawn in ``points`` points.  With fewer distinct x values
+    than ``order`` + 1 the order is lowered (one distinct x: no fit), with a warning.  The
+    points take marker settings with the ``marker_`` prefix.  With ``weights``, weighted
+    least squares, the band with the weight total minus the coefficients as degrees of
+    freedom (as the repeated rows); ``lowess=True`` takes no weights.
+    ``regression.stats``: ``coefficients`` (lowest power first), ``r2``, ``se``, and the
+    curve.
+
+    Example::
+
+        rng = random.Random(1)
+        x = [rng.uniform(0, 10) for _ in range(60)]
+        p = plt.Plot(width=240, height=160)
+        p.regression(x, [0.5 * v + rng.gauss(0, 1) for v in x])
+    """
+
+    SETTINGS = table(
+        **coord_settings(),
+        order=Setting(number(lo=1, hi=5, integer=True), doc="Polynomial order (1–5)."),
+        lowess=Setting(boolean, doc="Fit a LOWESS curve instead (no band)."),
+        frac=Setting(number(0, 1), doc="Fraction of the points in each LOWESS fit."),
+        weights=Setting(lambda v: columns.numbers(v, "weights"),
+                        doc="A weight per point, counted as repeated points (weighted least "
+                            "squares; not with `lowess`)."),
+        ci=Setting(either(literal(None), number(0, 100)),
+                   doc="Confidence level of the band (%); `None`: no band."),
+        logx=Setting(boolean, doc="Fit y against log(x) (x > 0)."),
+        scatter=Setting(boolean, doc="Draw the points too."),
+        range=Setting(either(literal(None), pair(number())),
+                      doc="x range of the fitted polynomial (and band); default the "
+                          "data range."),
+        points=Setting(number(lo=2, hi=65536, integer=True), doc="Points of the fitted curve."),
+        color=Setting(color, doc="Line, band and point color; default the plot's next color."),
+        **groups.Stroke.embed(only=("line_width", "line_style"),
+                              inherited=("line_width",),
+                              docs={"line_width": "Line width; default 1.4 × the plot's.",
+                                    "line_style": "Line style or dash list."}),
+        band_opacity=Setting(number(0, 1), doc="Opacity of the band."),
+        **groups.Marker.embed("marker_"),
+        **common("color_map"),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (y on x) or `horizontal` (the fit drawn with x "
+                                "along the y axis)."),
+        **common("name", "opacity", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    DATA = {"x": "numbers", "y": "numbers"}
+    x = column("x", "x of each point (categories at their index among their own).")
+    y = column("y", "y of each point (as x).")
+
+    def __init__(self, x: Any, y: Any, plot: Any = None, **settings: Any) -> None:
+        super().__init__(plot=plot, **settings)
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        """``coefficients`` (lowest power first, in x or log x), ``r2``, ``se`` (residual
+        standard error), and the curve: ``x``, ``y``, ``low``, ``high``."""
+        return stats.run(self, "regression")
+
+    def density_points(self) -> tuple[Any, Any]:
+        """The points' positions on the plot's axes (a density in ``marker_color``)."""
+        return xy_density_points(self, self.x, self.y)
+
+    SPEC = Spec(
+        [Lay("points", ("marker", {"prefix": "marker_", "color": "faded", "when": "scatter",
+                                   "n": lambda s: len(s.x)}),
+             key=False, occupy=lambda s: bool(s.resolve("scatter"))),
+         Lay("band", ("band", {"color": "faded", "opacity": "band_opacity"}), table="band",
+             stat="regression", glyph="band"),
+         # the curve stays within the data's and the band's extent (it does not widen the
+         # axes)
+         Lay("path", ("stroke", {"color": "faded", "dash": True}), table="curve",
+             aes={"x": "curve_x", "y": "curve_y"}, stat="regression", bounds=False)],
+        tables={"band": lambda s, b: _band(s.stats), "curve": lambda s, b: _curve(s.stats)},
+        key={"stroke": "faded"}, color_sources="scatter")
+
+
+def _band(st: dict[str, Any]) -> Table | None:
+    if not len(st["x"]) or st["low"] is None:
+        return None
+    return Table(x=st["x"], y1=st["low"], y2=st["high"])
+
+
+def _curve(st: dict[str, Any]) -> Table | None:
+    return Table(curve_x=st["x"], curve_y=st["y"]) if len(st["x"]) else None