plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/plot.py

@@ -0,0 +1,597 @@
+"""Plots: one area of a figure, with axes, series, title, legend and colorbars."""
+
+from typing import TYPE_CHECKING, Any, Self, Unpack
+
+from .canvas import Canvas
+from ._methods import FigureLegendMixin, PlotMixin, TitleMixin
+from . import groups
+from .axis import Axis
+from .color.values import VARIANT_DOC, check_variant, color
+from .settings import (DECLINE, custom_vars, Setting, Settings, boolean, canonical_kwargs,
+                       dpi_or_bool, either, literal, number, one_of, route, simplify_value,
+                       table, text)
+from .guides import anchor as _anchor, placement, set_place, where_of
+from .titles import ALIGNS, CREATED, SIDES, TitleBase, align_of
+from .validators import length, typed
+from .color.maps import kind_settings
+
+if TYPE_CHECKING:
+    from .colorbar import Colorbar
+    from .decorations import AxLine, Annotate, Bracket, HLine, HSpan, Text, VLine, VSpan
+    from .types import (AnnotateSettings, AxLineSettings, BracketSettings, ColorbarSettings,
+                        HLineSettings, HSpanSettings, LegendSettings, NewPlotSettings,
+                        PlotSettings, TextSettings, VLineSettings, VSpanSettings, WriteOptions)
+
+__all__ = ["Plot", "Title", "Legend", "FigureLegend"]
+
+_SPINES = ("left", "bottom", "right", "top")
+@typed("str | Iterable[str]")
+def _spines(v: Any) -> frozenset[str]:
+    if isinstance(v, str):
+        s = v.strip().lower()
+        if s == "all":
+            return frozenset(_SPINES)
+        if s == "none":
+            return frozenset()
+        parts = s.replace(",", " ").split()
+    else:
+        parts = [str(p).lower() for p in v]
+    bad = [p for p in parts if p not in _SPINES]
+    if bad:
+        raise ValueError(f"unknown spine {bad[0]!r} (use left, bottom, right, top, all, none)")
+    return frozenset(parts)
+
+
+@typed("Plot")
+def _plot(v: Any) -> Any:
+    if not isinstance(v, Plot):
+        raise ValueError(f"expected a Plot, got {v!r}")
+    return v
+
+
+_INHERITED = dict(
+    **groups.Font.embed(),
+    text_color=Setting(color, inherited=True, doc="Text color."),
+    line_width=Setting(length(lo=0), inherited=True, doc="Default line width."),
+    **kind_settings(),
+    color_variant=Setting(check_variant, inherited=True, doc=VARIANT_DOC),
+    plain_color=Setting(color, inherited=True,
+                        doc="Color of a series that needs no hue (no levels, one color, no "
+                            "`name`); unset: the plot's next color."),
+    opacity=Setting(number(0, 1), inherited=True, doc="Default opacity of series."),
+    rasterize=Setting(dpi_or_bool, inherited=True,
+                      doc="`True` or a dpi: series drawn as images inside the PDF."),
+    simplify=Setting(simplify_value, inherited=True,
+                     doc="vec_io's `simplify` for every series: `\"auto\"`, `True`, a dpi, "
+                         "`False`, or a `Simplify` (or a dict of its fields)."),
+    data=Setting(lambda v: v, inherited=True,
+                 doc="A table (dict, pandas or polars data frame, numpy structured array): "
+                     "strings in the data arguments of series name its columns."),
+    **groups.NumberFormat.embed(),
+)
+
+
+def _legend_title(legend: "Legend") -> Any:
+    """``Legend.title="auto"``: the name of the `group` column of the plot's series."""
+    return getattr(legend._plot, "_legend_title", None)
+
+
+class Title(TitleMixin, TitleBase):
+    """A title of a plot: its main title (``plot.title``) or another one
+    (``plot.add_title``), in a band of the plot's box on its ``side``.
+
+    The titles of one side stack outward from the axes, outermost of the side's bands: the
+    main title nearest, then the others in creation order; ``order`` places one elsewhere,
+    lower nearer (``order=-1``: a subtitle between the main title and the axes).  Each takes
+    a band of its ``pad``, its text and, with a ``rule``, ``rule_width + rule_gap``.  A line
+    break starts a line; the last line is nearest the axes on top, left and right.  Left
+    titles read upward, right titles downward (``rotation="auto"``).  ``align``: ``start``,
+    ``center``, ``end``, or an end by name (``left``, ``right`` on top and bottom; ``top``,
+    ``bottom`` on the left and right, where ``start`` is where the text begins).
+    """
+
+    def __init__(self, plot: "Plot", **settings: Any) -> None:
+        self._plot = plot
+        super().__init__(**settings)
+
+    def _parent(self) -> Settings:
+        return self._plot
+
+
+class Legend(Settings):
+    """The legend of a plot (``plot.legend``): an entry per named series.
+
+    Entries are drawn as the series draws itself (marker, line, swatch, box), or as
+    ``glyph`` (``"box"``, ``"circle"``, ``"line"``) in its color; ``name=""`` gives none.  A
+    plot and its twins share one legend.  ``inside`` (an anchor, ``"auto"`` or ``"best"``)
+    places it inside the axes, ``side`` outside; setting one unsets the other, and a
+    ``side`` from the style yields to an ``inside`` set on the legend.  On the top and
+    bottom entries are side by side unless ``orientation`` or ``columns`` is set; without
+    ``columns`` they wrap within the axes' length (inside: less ``pad``).  An inside legend
+    larger than its axes goes to the right side, with a warning.  Outside, a legend wraps
+    within the axes' length along its side, or in a figure of given size within the
+    plot's box when longer (passing the axes' ends); ``align`` places it along its side
+    (``auto``: centred on top and bottom, else at the axes' start).
+
+    ``inside="auto"`` marks what the series of the plot and its twins draw on a 64 × 64 grid
+    over the axes (markers with their size, curves along their length, the areas of bars,
+    boxes, violins and fills, the whole axes for heatmaps and contours; data sampled beyond
+    50,000 points), with the text and lines of decorations and inside colorbars.  The legend
+    takes the first of ``top_right``, ``top_left``, ``bottom_left``, ``bottom_right``,
+    ``top``, ``bottom``, ``center_right``, ``center_left`` that covers no marked cell, else
+    the free place nearest a corner, else the candidate covering no marker and the fewest
+    marked cells (at most 2 %), else the right side.  ``inside="best"`` (matplotlib's
+    ``loc="best"``) chooses among nine places, any covering no marker (the fewest marked
+    cells first), else goes outside on the right like ``"auto"``.
+    """
+
+    SETTINGS = table(
+        inside=Setting(_anchor,
+                       doc="Place inside the axes: `auto` (the least covered place, "
+                           "never over a marker; else outside right), `best` (the "
+                           "least covered place, never outside), `top_right`, `top_left`, "
+                           "`bottom_right`, `bottom_left`, `top`, `bottom`, `center_right` "
+                           "or `center_left`; setting it unsets `side`."),
+        side=Setting(one_of(*SIDES),
+                     doc="Outside the axes on a side of the plot: `top`, `bottom`, `left` "
+                         "or `right`; setting it unsets `inside`."),
+        align=Setting(one_of("auto", *ALIGNS),
+                      doc="Alignment along its side, outside the axes: `start` (left, or "
+                          "top), `center`, `end` (right, or bottom), or an end by name; "
+                          "`auto`: centred when horizontal on top or bottom, else `start`."),
+        visible=Setting(boolean, doc="Draw the legend."),
+        columns=Setting(number(lo=1, hi=10_000, integer=True), doc="Number of columns."),
+        frame=Setting(boolean, doc="Draw a frame and background."),
+        title=Setting(text, auto=_legend_title,
+                      doc="Legend title; `\"auto\"`: the `group` column name, if any."),
+        **groups.TextStyle.embed(only=("font_size", "color")),
+        background=Setting(color, doc="Background of a framed legend."),
+        **groups.Stroke.embed("frame_", only=("color", "line_width"),
+                              docs={"color": "Frame color.",
+                                    "line_width": "Frame line width."}),
+        pad=Setting(length(lo=0, percent="axes"), doc="Gap to the axes."),
+        frame_radius=Setting(length(lo=0), doc="Corner radius of the frame."),
+        frame_opacity=Setting(number(0, 1), doc="Opacity of the frame and background."),
+        glyph_opacity=Setting(number(0, 1),
+                            doc="Fill opacity of `box` and `circle` symbols, outlined in the "
+                                "opaque color; default: the series' own fill."),
+        glyph=Setting(one_of("series", "box", "circle", "line"),
+                      doc="Entry symbol: as the series draws itself, or a filled `box`, a "
+                          "`circle` or a `line` in the series color."),
+        orientation=Setting(one_of("auto", "vertical", "horizontal"),
+                            doc="`horizontal`: entries side by side; `auto`: horizontal on "
+                                "the top and bottom sides and at `inside` `top` and "
+                                "`bottom`."),
+        glyph_length=Setting(length(positive=True, percent="em"),
+                            doc="Width of an entry's symbol."),
+        row_height=Setting(length(positive=True, percent="em"), doc="Height of an entry."),
+        glyph_gap=Setting(length(lo=0, percent="em"), doc="Gap between a symbol and its text."),
+        column_gap=Setting(length(lo=0, percent="em"), doc="Gap between columns."),
+        title_gap=Setting(length(lo=0, percent="em"), doc="Gap below the title."),
+        inner_pad=Setting(either(literal("auto"), length(lo=0, percent="em")),
+                          auto=lambda g: (0.5 if g.resolve("frame") else 0.15)
+                          * g.resolve("font_size"),
+                          doc="Space inside the box; `\"auto\"`: 0.5em with a frame, 0.15em "
+                              "without."),
+        **groups.Font.embed(only=groups.Font.FACE),
+    )
+
+    def __init__(self, plot: "Plot") -> None:
+        self._plot = plot
+        super().__init__()
+
+    def _parent(self) -> Settings:
+        return self._plot
+
+    def pads(self) -> tuple[float, float]:
+        """``pad`` across and down (px), while drawn: `%` of the axes width and height."""
+        return (self.resolve("pad", of=self._box("axes_width", "pad")),
+                self.resolve("pad", of=self._box("axes_height", "pad")))
+
+    def set(self, **settings: "Unpack[LegendSettings]") -> Self:  # type: ignore[override]
+        super().set(**settings)
+        set_place(self, dict(settings))
+        return self
+
+    def placement(self) -> tuple[str, Any]:
+        """``("inside", anchor)`` or ``("side", side)``: where the legend goes."""
+        return placement(self, side_first=True)
+
+    def is_placed(self) -> bool:
+        """Whether its place (``inside``, ``side`` or ``visible``) is set on it."""
+        return any(self.is_set(k) for k in ("inside", "side", "visible"))
+
+    def __repr__(self) -> str:
+        return f"Legend({self.placement()!r})"
+
+
+def _figure_legend_title(legend: "FigureLegend") -> Any:
+    """``FigureLegend.title="auto"``: its plots' legend titles (each the name of the
+    `group` column of its series unless set) when they are all the same (otherwise each
+    heads its own entries)."""
+    plots = legend.plots if legend.plots is not None else legend._figure.plots
+    titles = [p.legend.resolve("title") for p in plots]
+    return titles[0] if titles and all(t == titles[0] for t in titles) else None
+
+
+class FigureLegend(FigureLegendMixin, Legend):
+    """A legend of the figure (``figure.add_legend``, or made by ``share_legend``): the
+    entries of a set of plots, in the lanes beside them as figure titles are.
+
+    Its plots' cells must fill the grid rectangle they span.  Entries come in plot order (row
+    by row), then series order; entries with the same label and the same symbol are one,
+    the same label with another symbol keeps both.  Its plots' legends lose those entries
+    (a plot left without entries shows none), unless the plot's legend has ``inside``,
+    ``side`` or ``visible`` set.  A size key whose plots the legend all covers goes into it.
+    ``side`` and ``align`` place it within the axes of its plots, in the lanes of
+    :class:`FigureTitle` (a legend nearer the plots than a title over the same plots; one
+    without entries takes no lane).  ``share_legend`` (figure setting) makes one per group
+    of plots, as ``share_color`` groups them (a group with a plot an ``add_legend`` legend
+    covers gets none).  ``plot.save()`` leaves figure legends out.
+    """
+
+    SETTINGS = table(**{
+        **{k: s for k, s in Legend.SETTINGS.items()
+           if k not in ("inside", "side", "visible", "orientation", "pad", "title")},
+        "side": Setting(one_of(*SIDES), doc="`top`, `bottom`, `left` or `right` of its plots."),
+        "align": Setting(one_of("auto", *ALIGNS),
+                         doc="Alignment along the side: `start` (left, or top), `center`, "
+                             "`end` (right, or bottom), or an end by name: `left`, `right` "
+                             "on top and bottom, `top`, `bottom` on the left and right; "
+                             "`auto`: `center`."),
+        "order": Setting(number(), doc="Place in its side's lanes, as figure titles' "
+                                       "`order`: lower is nearer the plots."),
+        "pad": Setting(length(lo=0), doc="Gap between the legend and the plots."),
+        "title": Setting(text, auto=_figure_legend_title,
+                         doc="Legend title; `\"auto\"`: its plots' legend title when they "
+                             "share one, else each heads its own entries."),
+    })
+
+    def __init__(self, figure: Any, plots: Any = None, **settings: Any) -> None:
+        self._figure = figure
+        #: the plots it covers (``None``: every plot)
+        self.plots: list[Any] | None = plots
+        self._made = next(CREATED)
+        Settings.__init__(self, **settings)
+
+    def _parent(self) -> Settings:
+        return self._figure
+
+    def __repr__(self) -> str:
+        return f"FigureLegend({self.get('side')!r})"
+
+    def along(self) -> str:
+        """``align`` as ``start``, ``center`` or ``end`` (``auto``: ``center``)."""
+        a = self.resolve("align")
+        return "center" if a == "auto" else align_of(a)
+
+
+def _data_ratio(plot: "Plot") -> Any:
+    """1 when a series asks for equal units on both axes (a square Hi-C matrix)."""
+    if any(getattr(s, "equal_aspect", lambda: False)() for s in plot.series):
+        return 1.0
+    return DECLINE
+
+
+class Plot(PlotMixin, Settings):
+    """One plot: axes, series and decorations.
+
+    ``plt.Plot(**settings)`` creates a one-plot figure (``plot.figure``);
+    ``figure.plot(…)`` adds a plot to an existing figure.
+
+    At creation and in ``set``: ``title=`` sets the title text, ``x_axis={…}`` and
+    ``y_axis={…}`` the axes' settings, ``legend=`` (a place, a dict of legend settings or
+    ``False``) calls :meth:`add_legend` and ``colorbar=`` (``True``, a place or a dict)
+    :meth:`add_colorbar`.  A place is a side (``"right"``: ``side=``), an anchor inside the
+    axes (``"top_left"``, ``"auto"``: ``inside=``) or ``"none"``.  ``plot.title``,
+    ``plot.x_axis`` and ``plot.y_axis`` are objects: calling one sets its settings and
+    returns it.  Series are drawn in ``z`` order (default: call order) inside the axes clip.
+
+    ``twin_y()`` (``twin_x()``) returns a plot on the same axes rectangle sharing the x (y)
+    axis, limits from the series of both, with its own y axis on the right (x axis on top).
+    Its axis adds margin on its side; its series continue the plot's colors and appear in the
+    plot's legend (``twin.legend is plot.legend``); background, title, frame and grid are
+    the plot's (a twin draws a grid only when its axis asks).  ``save`` includes the twins.
+    """
+
+    SETTINGS = table(
+        spines=Setting(_spines,
+                       doc="Axis lines drawn: any of `left`, `bottom`, `right`, `top`, or "
+                           "`all`, `none`."),
+        data_ratio=Setting(number(positive=True),
+                           doc="Data aspect ratio: 1 makes one unit as long on both axes; "
+                               "unset: 1 for a square Hi-C matrix (outside a tracks "
+                               "figure)."),
+        background=Setting(color, doc="Background color of the axes area."),
+        **groups.Stroke.embed("border_", only=("color", "line_width"),
+                              docs={"color": "Color of a frame around the axes area (drawn "
+                                             "under the axis lines); default none.",
+                                    "line_width": "Width of the frame."}),
+        clip=Setting(boolean, doc="Clip series to the axes area."),
+        axes=Setting(boolean, doc="Draw axes; `False` hides both axes, drops padding "
+                                        "and fixes the aspect to 1 (set by pie charts)."),
+        share_x=Setting(_plot, doc="Another plot of the figure whose x axis this plot "
+                                   "shares (groups chain); overrides the figure's `share_x`."),
+        share_y=Setting(_plot, doc="Another plot whose y axis this plot shares."),
+        vars=Setting(custom_vars, expr=False,
+                     doc="Custom variables, read by `var(--name)` in any setting here and "
+                         "below: `{\"accent\": \"#c00\"}`."),
+        share=Setting(_plot, doc="Another plot whose x and y axes this plot shares."),
+        space_above=Setting(length(lo=0, percent="em"),
+                            doc="Space above the plot, beyond the figure's `spacing`."),
+        **_INHERITED,
+    )
+    RULES = {"data_ratio": _data_ratio}
+    #: Keywords accepted besides settings: ``title="…"`` sets the title text,
+    #: ``x_axis={…}`` and ``y_axis={…}`` the axes' settings, ``legend=`` and ``colorbar=``
+    #: call :meth:`add_legend` and :meth:`add_colorbar`.
+    EXTRA = ("title", "x_axis", "y_axis", "legend", "colorbar")
+    #: Of those, the ones a series call making the plot passes on to it (``colorbar=`` is
+    #: a series setting there).
+    CALL_EXTRA = ("title", "x_axis", "y_axis", "legend")
+
+    def __init__(self, figure: Any = None, id: Any = None, _twin: Any = None,
+                 **settings: Unpack["NewPlotSettings"]) -> None:
+        from .figure import Figure
+
+        own, fig_kw = route(dict(settings), [Plot, Figure], extra={0: Plot.EXTRA})
+        title = own.pop("title", None)
+        axes: dict[str, Any] = {k: own.pop(k) for k in ("x_axis", "y_axis") if k in own}
+        guides: dict[str, Any] = {k: own.pop(k) for k in ("legend", "colorbar") if k in own}
+        if figure is None:
+            figure = Figure(**fig_kw)
+        elif fig_kw:
+            from .layers.base import upward_message
+            raise ValueError(upward_message("Plot", [("figure", "figure", fig_kw)]))
+        self.figure = figure
+        self.x_axis = Axis(self, "x")
+        self.y_axis = Axis(self, "y")
+        self.title = Title(self)
+        self._titles: list[Title] = []
+        #: the legend: a twin's is its main plot's (one legend per axes rectangle)
+        self.legend = _twin[0].legend if _twin is not None else Legend(self)
+        self.series: list[Any] = []
+        self.decorations: list[Any] = []
+        self.colorbars: list[Any] = []
+        self.twins: list[Plot] = []
+        #: ``(main plot, "y" or "x")`` for a twin: the axis it has of its own.
+        self.twin_of: tuple[Plot, str] | None = _twin
+        super().__init__(**own)
+        if title is not None:
+            self.title.set(text=title)
+        self._set_axes(axes)
+        self.id = figure._attach(self, id) if _twin is None else None
+        self._set_guides(guides)
+
+    def _parent(self) -> Settings:
+        return self.twin_of[0] if self.twin_of is not None else self.figure
+
+    def _children(self) -> list[Settings]:
+        legend = [] if self.twin_of is not None else [self.legend]
+        return [self.title, *self._titles, *legend, self.x_axis, self.y_axis, *self.series,
+                *self.decorations, *self.colorbars, *self.twins]
+
+    @property
+    def titles(self) -> list[Title]:
+        """The plot's titles: its main title first, then those of :meth:`add_title`."""
+        return [self.title, *self._titles]
+
+    def add_title(self, text: Any, side: Any = None, **settings: Any) -> Title:
+        """Another title of the plot, on ``side`` (default ``"top"``), stacked outward of
+        the titles before it there (``order`` places it elsewhere); returns it."""
+        if side is not None:
+            settings["side"] = side
+        t = Title(self, text=text, **settings)
+        self._titles.append(t)
+        return t
+
+    def twin_y(self, **settings: Unpack["PlotSettings"]) -> "Plot":
+        """A plot on the same axes with its own y axis (on the right) and the x axis of
+        this plot: add series to it and set its ``y_axis``."""
+        return self._twin("y", dict(settings))
+
+    def twin_x(self, **settings: Unpack["PlotSettings"]) -> "Plot":
+        """A plot on the same axes with its own x axis (on top) and the y axis of this
+        plot."""
+        return self._twin("x", dict(settings))
+
+    def _twin(self, role: str, settings: dict[str, Any]) -> "Plot":
+        """A twin with its own ``role`` axis on the far side (its line drawn there with
+        the axis) and the other axis hidden."""
+        t = Plot(figure=self.figure, _twin=(self, role), **settings)
+        own, other = (t.y_axis, t.x_axis) if role == "y" else (t.x_axis, t.y_axis)
+        other.set(visible=False)
+        if not own.is_set("side"):
+            own.set(side="right" if role == "y" else "top")
+        if not t.is_set("spines"):
+            t.set(spines="left" if role == "y" else "bottom")
+        self.twins.append(t)
+        return t
+
+    def get(self, name: str) -> Any:
+        """As :meth:`Settings.get`; ``"title"``: the title's text."""
+        if name == "title":
+            return self.title.get("text")
+        return super().get(name)
+
+    def set(self, **given: "Unpack[PlotSettings]") -> Self:  # type: ignore[override]
+        settings = canonical_kwargs(dict(given), self.SETTINGS, "Plot")
+        fig_share = {k: settings.pop(k) for k in ("share_x", "share_y", "share")
+                     if k in settings and settings[k] is not None
+                     and not isinstance(settings[k], Plot)}
+        if fig_share:
+            self.figure.set(**fig_share)
+        title = settings.pop("title", None)
+        if title is not None:
+            self.title.set(text=title)
+        self._set_axes({k: settings.pop(k) for k in ("x_axis", "y_axis") if k in settings})
+        guides: dict[str, Any] = {k: settings.pop(k) for k in ("legend", "colorbar")
+                                  if k in settings}
+        super().set(**settings)
+        self._set_guides(guides)
+        return self
+
+    def _set_axes(self, axes: dict[str, Any]) -> None:
+        """``x_axis={…}``, ``y_axis={…}``: settings of the plot's axes."""
+        for k, v in axes.items():
+            if not isinstance(v, dict):
+                raise ValueError(f"{k}= takes a dict of axis settings, got {v!r}")
+            getattr(self, k).set(**v)
+
+    def _set_guides(self, guides: dict[str, Any]) -> None:
+        """``legend=``: a place (a side, a place inside the axes, ``"none"``), a dict of
+        legend settings or ``False`` (no legend); ``colorbar=``: ``True``, a place or a
+        dict of colorbar settings (one more colorbar each time)."""
+        legend = guides.get("legend")
+        if legend is not None:
+            if legend is False:
+                self.add_legend(visible=False)
+            elif isinstance(legend, dict):
+                self.add_legend(**legend)
+            elif isinstance(legend, str):
+                self.add_legend(legend)
+            else:
+                raise ValueError(f"legend= takes a place, a dict of legend settings or "
+                                 f"False, got {legend!r}")
+        bar = guides.get("colorbar")
+        if bar is not None and bar is not False:
+            if bar is True:
+                self.add_colorbar()
+            elif isinstance(bar, dict):
+                self.add_colorbar(**bar)
+            elif isinstance(bar, str) and "visible" not in where_of(bar):
+                self.add_colorbar(None, bar)
+            else:
+                raise ValueError(f"colorbar= takes True, a place or a dict of colorbar "
+                                 f"settings, got {bar!r}")
+
+    def __repr__(self) -> str:
+        from .layout import arrange
+        main = self.twin_of[0] if self.twin_of is not None else self
+        cell = next(((a.r0, a.c0) for a in arrange(self.figure)[0] if a.obj is main), None)
+        where = f"row {cell[0]}, col {cell[1]}, " if cell is not None else ""
+        return f"Plot({where}{len(self.series)} series)"
+
+    def own_share(self, role: str) -> Any:
+        """The plot this plot's ``role`` axis is paired with, or ``None``."""
+        return self.resolve(f"share_{role}") or self.resolve("share")
+
+    def _add_series(self, s: Any) -> None:
+        self.series.append(s)
+        from .spec import current
+        r = current()
+        if r is not None:                    # added during a render: its calls change
+            r.plots.clear()
+            r.calls.clear()
+
+    # Plot types are methods added by ``registry.layers.add``
+    # (``p.scatter(…)``, ``p.hist(…)``, ``p.bigwig(…)``…).
+
+    # -- decorations -----------------------------------------------------------------
+
+    def hline(self, y: Any, **settings: Unpack["HLineSettings"]) -> "HLine":
+        """A horizontal reference line at ``y``."""
+        from .decorations import HLine
+        return HLine(self, y, **settings)
+
+    def vline(self, x: Any, **settings: Unpack["VLineSettings"]) -> "VLine":
+        """A vertical reference line at ``x``."""
+        from .decorations import VLine
+        return VLine(self, x, **settings)
+
+    def axline(self, point: Any, slope: Any = None, point2: Any = None,
+               **settings: Unpack["AxLineSettings"]) -> "AxLine":
+        """An infinite line through ``point`` with ``slope``, or through ``point2``."""
+        from .decorations import AxLine
+        return AxLine(self, point, slope, point2, **settings)
+
+    def hspan(self, y0: Any, y1: Any, **settings: Unpack["HSpanSettings"]) -> "HSpan":
+        """A horizontal band from ``y0`` to ``y1``."""
+        from .decorations import HSpan
+        return HSpan(self, y0, y1, **settings)
+
+    def vspan(self, x0: Any, x1: Any, **settings: Unpack["VSpanSettings"]) -> "VSpan":
+        """A vertical band from ``x0`` to ``x1``."""
+        from .decorations import VSpan
+        return VSpan(self, x0, x1, **settings)
+
+    def text(self, x: Any, y: Any, content: Any,
+             **settings: Unpack["TextSettings"]) -> "Text":
+        """Text at ``(x, y)``."""
+        from .decorations import Text
+        return Text(self, x, y, content, **settings)
+
+    def annotate(self, content: Any, xy: Any, xytext: Any = None,
+                 **settings: Unpack["AnnotateSettings"]) -> "Annotate":
+        """Text at ``xytext`` with an arrow to ``xy``."""
+        from .decorations import Annotate
+        return Annotate(self, content, xy, xytext, **settings)
+
+    def bracket(self, a: Any, b: Any, text: Any = None,
+                **settings: Unpack["BracketSettings"]) -> "Bracket":
+        """A bracket from ``a`` to ``b`` (categories or positions) with ``text``, or ``p=``
+        written as stars or a p-value."""
+        from .decorations import Bracket
+        return Bracket(self, a, b, text, **settings)
+
+    def brackets(self, pairs: Any, p: Any = None, text: Any = None,
+                 **settings: Unpack["BracketSettings"]) -> list["Bracket"]:
+        """A bracket per ``(a, b)`` of ``pairs``, with the p-value (``p``) or text
+        (``text``) of the same index; the same settings."""
+        from .decorations import Bracket
+        pairs = list(pairs)
+        for name, v in (("p", p), ("text", text)):
+            if v is not None and len(v) != len(pairs):
+                raise ValueError(f"brackets: {len(v)} {name} values for {len(pairs)} pairs")
+        return [Bracket(self, a, b, None if text is None else text[i],
+                        p=None if p is None else p[i], **settings)
+                for i, (a, b) in enumerate(pairs)]
+
+    def add_legend(self, where: Any = None, /, **settings: Unpack["LegendSettings"]) -> Legend:
+        """Set the plot's legend (``plot.legend``, shared with its twins) and return it:
+        ``where`` is a side (``"right"``: ``side=``), a place inside the axes
+        (``"top_left"``: ``inside=``) or ``"none"``; then any legend settings."""
+        kw: dict[str, Any] = {**where_of(where), **settings} if where is not None \
+            else dict(settings)
+        return self.legend.set(**kw)
+
+    def add_colorbar(self, source: Any = None, where: Any = None,
+                     **settings: Unpack["ColorbarSettings"]) -> "Colorbar":
+        """A colorbar attached to this plot: the guide of the color (or size) axis of
+        ``source`` (a mapped series or an axis; default: the plot's last mapped series);
+        ``where``: a side (``side=``, default ``"bottom"``) or a place inside the axes
+        (``inside=``); returns it."""
+        from .colorbar import Colorbar
+        kw: dict[str, Any] = {**where_of(where), **settings} if where is not None \
+            else dict(settings)
+        cb = Colorbar(source, plot=self, **kw)
+        self.colorbars.append(cb)
+        return cb
+
+    # -- output ----------------------------------------------------------------------
+
+    def draw(self, canvas: Canvas, x: float = 0.0, y: float = 0.0) -> tuple[float, float]:
+        """Draw the plot alone on a canvas (a vec_io page, a
+        :class:`~plot_io.canvas.Recording`) with its top-left corner at ``(x, y)``
+        (page units); returns its size in px."""
+        from . import render
+        return render.draw(self.figure, canvas, x, y, only=self)
+
+    def save(self, file: Any, *, region: Any = None, format: str | None = None,
+             **options: Unpack["WriteOptions"]) -> None:
+        """Save the plot alone (see :meth:`Figure.save`)."""
+        from . import render
+        with self.figure._region(region):
+            render.save(self.figure, file, only=self, format=format, **options)
+
+    def write(self, format: str, *, region: Any = None,
+              **options: Unpack["WriteOptions"]) -> bytes:
+        """The plot alone as ``format`` bytes (see :meth:`Figure.write`)."""
+        from . import render
+        with self.figure._region(region):
+            return render.write(self.figure, format, only=self, **options)
+
+    def _repr_mimebundle_(self, include: Any = None, exclude: Any = None) -> dict[str, str]:
+        """The plot alone as SVG for notebooks (``image/svg+xml`` only)."""
+        from . import render
+        return render.repr_svg(self.figure, self, include, exclude)

plot_io/presets/__init__.py

@@ -0,0 +1,51 @@
+"""The plot types: each a :class:`~plot_io.layers.Series` declared by a ``SPEC`` (its data,
+layers and what the axes need, built by :mod:`plot_io.layers.grammar`) or with a
+``layers()`` of its own, registered as a ``Plot`` method (``registry.layers.add``)."""
+
+from ..layers import add_layer
+from ..levels import adopt
+from ..styles import register_class
+from .area import Area
+from .bar import Bar
+from .box import Box
+from .catpoints import Strip, Swarm
+from .contour import Contour
+from .dots import Dots, group_summary
+from .ecdf import Ecdf
+from .errorbar import Errorbar
+from .errors import Errors
+from .fill import Fill
+from .heatmap import Heatmap
+from .hexbin import Hexbin
+from .hist import Hist
+from .hist2d import Hist2d
+from .kde import Kde
+from .kde2d import Kde2d
+from .line import Line
+from .pie import Pie
+from .regression import Regression
+from .scatter import Scatter
+from .stem import Stem
+from .violin import Violin
+
+__all__ = ["Area", "Bar", "Box", "Strip", "Swarm", "Contour", "Dots", "group_summary", "Ecdf", "Errorbar",
+           "Errors", "Fill", "Heatmap", "Hexbin", "Hist", "Hist2d", "Kde", "Kde2d", "Line",
+           "Pie", "Regression", "Scatter", "Stem", "Violin", "TYPES"]
+
+#: The plot types by ``Plot`` method name.
+TYPES = {"scatter": Scatter, "line": Line, "fill": Fill, "box": Box, "heatmap": Heatmap,
+         "bar": Bar, "hist": Hist, "kde": Kde, "ecdf": Ecdf, "violin": Violin,
+         "strip": Strip, "swarm": Swarm, "area": Area, "errorbar": Errorbar, "stem": Stem,
+         "regression": Regression, "hist2d": Hist2d, "hexbin": Hexbin, "contour": Contour,
+         "pie": Pie, "dots": Dots}
+
+for _split in (Line, Fill, Area, Hist, Kde, Ecdf, Regression, Bar, Box, Violin, Strip, Swarm,
+               Errorbar, Stem):
+    adopt(_split, "split")
+adopt(Scatter, "items")
+Heatmap.LEVELS = Contour.LEVELS = Hexbin.LEVELS = "grid"
+Pie.LEVELS = "refuse"
+
+for _name, _cls in TYPES.items():
+    add_layer(_name, _cls)
+register_class(Kde2d)                  # p.kde(x, y): a style class of its own