plot-io 0.1.0__py3-none-any.whl

plot_io/density.py

@@ -0,0 +1,97 @@
+"""Point density: a 2-D Gaussian kernel density estimate at each point of a series, as
+scipy's ``gaussian_kde(np.array([x, y]))(np.array([x, y]))`` computes it.
+
+The kernel covariance is the data covariance scaled by Scott's factor n^(-1/6) (or
+Silverman's), and the density is computed on the axis positions (log axes in log space).
+pdf_io does the work in C: an exact sum for small inputs, a binned and blurred grid for
+large ones.
+"""
+
+import math
+from typing import Any
+
+from . import _backend
+from .settings import number, one_of
+
+__all__ = ["Density"]
+
+_check_normalize = one_of("pdf", "count", "max")
+_check_method = one_of("auto", "exact", "grid")
+
+
+def _bandwidth(v: Any) -> Any:
+    if isinstance(v, str):
+        return one_of("scott", "silverman")(v)
+    if isinstance(v, (tuple, list)):
+        m = [list(map(float, row)) for row in v]
+        if len(m) != 2 or any(len(r) != 2 for r in m):
+            raise ValueError("a bandwidth matrix is 2 × 2")
+        if abs(m[0][1] - m[1][0]) > 1e-12 * max(1.0, abs(m[0][1])):
+            raise ValueError("a bandwidth matrix is symmetric")
+        if not (m[0][0] > 0 and m[1][1] > 0 and m[0][0] * m[1][1] - m[0][1] ** 2 > 0):
+            raise ValueError("a bandwidth matrix is positive definite")
+        return (m[0][0], m[0][1], m[1][1])
+    return number(positive=True)(v)
+
+
+class Density:
+    """The local density of a series' points, as values for ``color``, ``size``, ``alpha``
+    or ``order``.
+
+    ``bandwidth``: ``"scott"`` (default), ``"silverman"``, a number (isotropic standard
+    deviation in axis units) or a 2 × 2 covariance matrix; ``adjust`` multiplies it.
+    ``normalize``: ``"pdf"`` (scipy's values), ``"count"`` (points per unit area) or
+    ``"max"`` (0–1).  ``method``: ``"exact"``, ``"grid"`` or ``"auto"`` (exact up to
+    20,000 points); ``grid``: grid size of the grid method.
+    """
+
+    def __init__(self, bandwidth: Any = "scott", adjust: float = 1.0, normalize: str = "pdf",
+                 method: str = "auto", grid: int = 512) -> None:
+        self.bandwidth = _bandwidth(bandwidth)
+        self.adjust = number(positive=True)(adjust)
+        self.normalize = _check_normalize(normalize)
+        self.method = _check_method(method)
+        self.grid = int(number(lo=16, hi=4096, integer=True)(grid))
+
+    def __repr__(self) -> str:
+        return f"Density({self.bandwidth!r}, normalize={self.normalize!r})"
+
+    def label(self) -> str:
+        return {"pdf": "density", "count": "points per unit area",
+                "max": "relative density"}[self.normalize]
+
+    def compute(self, series: Any) -> Any:
+        """The density at each point of ``series`` (its ``density_points()``)."""
+        xs, ys = series.density_points()
+        return self.at(xs, ys)
+
+    def at(self, xs: Any, ys: Any) -> Any:
+        """The density at each point ``(xs[i], ys[i])`` (positions, not data)."""
+        xs, ys = _backend.doubles(xs), _backend.doubles(ys)
+        h = self.covariance(xs, ys)
+        if not all(math.isfinite(v) for v in h):          # fewer than 2 distinct points
+            import array
+            return array.array("d", [math.nan]) * len(xs)
+        dens = _backend.kde2d_at(xs, ys, h, self.method, self.grid)
+        return self._normalized(dens, xs, ys)
+
+    def covariance(self, xs: Any, ys: Any) -> tuple[float, float, float]:
+        """The kernel covariance ``(h11, h12, h22)``."""
+        a = self.adjust * self.adjust
+        if isinstance(self.bandwidth, tuple):
+            h11, h12, h22 = self.bandwidth
+            return (h11 * a, h12 * a, h22 * a)
+        if isinstance(self.bandwidth, float):
+            s = self.bandwidth * self.bandwidth * a
+            return (s, 0.0, s)
+        h11, h12, h22 = _backend.kde2d_bandwidth(xs, ys, self.bandwidth)
+        return (h11 * a, h12 * a, h22 * a)
+
+    def _normalized(self, dens: Any, xs: Any, ys: Any) -> Any:
+        if self.normalize == "pdf":
+            return dens
+        if self.normalize == "count":
+            n = sum(1 for x, y in zip(xs, ys) if x == x and y == y)
+            return _backend.scaled(dens, float(n))
+        _, _, hi = _backend.extent(dens, None)
+        return _backend.scaled(dens, 1.0 / hi if hi and math.isfinite(hi) and hi > 0 else 1.0)

plot_io/enums.py

@@ -0,0 +1,63 @@
+"""String enums for enum-like settings; plain strings work everywhere."""
+
+import enum
+
+__all__ = ["Marker", "LineStyle", "Orientation", "Scale", "Position", "Order", "Align"]
+
+
+class Marker(enum.StrEnum):
+    CIRCLE = "circle"
+    SQUARE = "square"
+    DIAMOND = "diamond"
+    TRIANGLE_UP = "triangle_up"
+    TRIANGLE_DOWN = "triangle_down"
+    TRIANGLE_LEFT = "triangle_left"
+    TRIANGLE_RIGHT = "triangle_right"
+    PLUS = "plus"
+    CROSS = "cross"
+
+
+class LineStyle(enum.StrEnum):
+    SOLID = "solid"
+    DASHED = "dashed"
+    DOTTED = "dotted"
+    DASHDOT = "dashdot"
+
+
+class Orientation(enum.StrEnum):
+    VERTICAL = "vertical"
+    HORIZONTAL = "horizontal"
+
+
+class Scale(enum.StrEnum):
+    LINEAR = "linear"
+    LOG = "log"
+    LOG2 = "log2"
+    LOG10 = "log10"
+    SQRT = "sqrt"
+    EXP = "exp"
+    CATEGORY = "category"
+
+
+class Position(enum.StrEnum):
+    AUTO = "auto"
+    TOP_RIGHT = "top right"
+    TOP_LEFT = "top left"
+    BOTTOM_RIGHT = "bottom right"
+    BOTTOM_LEFT = "bottom left"
+    TOP = "top"
+    BOTTOM = "bottom"
+    OUTSIDE_RIGHT = "outside right"
+    OUTSIDE_TOP = "outside top"
+    NONE = "none"
+
+
+class Order(enum.StrEnum):
+    AUTO = "auto"
+    ROW = "row"
+    COL = "col"
+
+
+class Align(enum.StrEnum):
+    AXES = "axes"
+    BORDERS = "borders"

plot_io/facets.py

@@ -0,0 +1,184 @@
+"""Facets: small multiples of one table, split by the values of one or two columns.
+
+``pl.facet(data, col=…, row=…)`` makes a :class:`FacetFigure` with one plot per
+combination of values; series methods called on it (``fig.scatter("x", "y")``) are called
+on every panel with that panel's rows, with colors, groups and maps kept consistent across
+panels.
+"""
+
+from typing import Any, Callable
+
+from .figure import Figure
+from .tables import column, group_keys, take
+
+__all__ = ["facet", "FacetFigure"]
+
+_SERIES = ("scatter", "line", "fill", "box", "heatmap", "bar", "hist", "kde", "ecdf",
+           "violin", "strip", "swarm", "area", "errorbar", "stem", "regression", "hist2d",
+           "hexbin", "contour", "pie", "hline", "vline", "axline", "hspan", "vspan", "text",
+           "annotate")
+
+
+def subset(data: Any, idx: list[int]) -> Any:
+    """The rows ``idx`` of a table."""
+    if hasattr(data, "iloc"):                        # pandas
+        return data.iloc[idx]
+    if isinstance(data, dict):
+        return {k: take(v, idx) for k, v in data.items()}
+    if getattr(getattr(data, "dtype", None), "names", None) is not None:
+        return data[idx]                             # numpy structured array
+    try:
+        return data[idx]                             # polars and others
+    except (TypeError, KeyError, IndexError):
+        raise ValueError("facets need a dict, a data frame or a structured array") from None
+
+
+def _levels(data: Any, name: str | None, order: Any) -> tuple[list[Any], list[list[int]]]:
+    if name is None:
+        n = len(next(iter(data.values()))) if isinstance(data, dict) else len(data)
+        return [None], [list(range(n))]
+    values, cat_order = column(data, name)
+    if hasattr(values, "tolist"):
+        values = values.tolist()
+    given = order.get(name) if isinstance(order, dict) else None
+    return group_keys(values, cat_order, given, "drop")
+
+
+class FacetFigure(Figure):
+    """A figure of facet panels (``pl.facet``)."""
+
+    def __init__(self, data: Any, col: str | None = None, row: str | None = None,
+                 wrap: int | None = None, share: Any = "grid", order: Any = None,
+                 title_format: str = "{name} = {value}", colorbar: Any = None,
+                 **settings: Any) -> None:
+        if col is None and row is None:
+            raise ValueError("facet needs col, row or both")
+        if wrap is not None and (row is not None or col is None):
+            raise ValueError("wrap applies to col alone")
+        self.data = data
+        cols, col_rows = _levels(data, col, order)
+        rows, row_rows = _levels(data, row, order)
+        self.facet_names = (row, col)
+        panels: list[tuple[Any, Any, list[int]]] = []
+        for rk, ri in zip(rows, row_rows):
+            rset = set(ri)
+            for ck, ci in zip(cols, col_rows):
+                idx = [i for i in ci if i in rset]
+                panels.append((rk, ck, idx))
+        if wrap:
+            ncol = wrap
+            nrow = -(-len(panels) // ncol)
+        else:
+            nrow, ncol = len(rows), len(cols)
+        grid: list[list[Any]] = [[None] * ncol for _ in range(nrow)]
+        ids = []
+        for k, (rk, ck, _) in enumerate(panels):
+            r, c = divmod(k, ncol)
+            pid = f"panel{k}"
+            grid[r][c] = pid
+            ids.append(pid)
+        self._colorbar_side = colorbar
+        if colorbar == "right":
+            for cells in grid:
+                cells.append("colorbar")
+        elif colorbar not in (None, False):
+            raise ValueError("colorbar is None or 'right'")
+        super().__init__(grid=grid, share=share, **settings)
+        self.panels: dict[Any, Any] = {}
+        self._rows: dict[Any, list[int]] = {}
+        for pid, (rk, ck, idx) in zip(ids, panels):
+            key = ck if row is None else (rk if col is None else (rk, ck))
+            parts = [(n, v) for n, v in ((row, rk), (col, ck)) if n is not None]
+            title = ", ".join(title_format.format(name=n, value=v) for n, v in parts)
+            p = Figure.plot(self, pid, title=title)
+            self.panels[key] = p
+            self._rows[key] = idx
+        self._cmap: Any = None
+        self._group_levels: dict[str, list[Any]] = {}
+        self._colorbar: Any = None
+
+    def plot(self, id: Any = None, **settings: Any) -> Any:
+        """The panel of facet key ``id`` (a value, or ``(row value, col value)``)."""
+        if id in getattr(self, "panels", {}):
+            p = self.panels[id]
+            if settings:
+                p.set(**settings)
+            return p
+        return super().plot(id, **settings)
+
+    def subsets(self) -> list[tuple[Any, Any, Any]]:
+        """``(key, plot, rows)`` of every panel."""
+        return [(k, p, subset(self.data, self._rows[k])) for k, p in self.panels.items()]
+
+    def map(self, func: Callable[[Any, Any], Any]) -> list[Any]:
+        """``func(plot, rows)`` for every panel; returns the results."""
+        return [func(p, rows) for _, p, rows in self.subsets()]
+
+    def _shared_map(self) -> Any:
+        if self._cmap is None:
+            from .maps import ColorMap
+            self._cmap = ColorMap(self.get("color_map"))
+            if self._colorbar_side == "right":
+                self._colorbar = self.colorbar(self._cmap, id="colorbar")
+        return self._cmap
+
+    def _call(self, method: str, args: tuple, kw: dict[str, Any]) -> list[Any]:
+        kw = dict(kw)
+        group = kw.get("group")
+        if isinstance(group, str):
+            levels = self._group_levels.get(group)
+            if levels is None:
+                values, cat = column(self.data, group)
+                if hasattr(values, "tolist"):
+                    values = values.tolist()
+                levels = group_keys(values, cat, kw.get("group_order"),
+                                    kw.get("group_missing", "keep"))[0]
+                self._group_levels[group] = levels
+            kw.setdefault("group_order", levels)
+            colors = {lv: f"C{i}" for i, lv in enumerate(levels)}
+            colors.update(kw.get("group_colors") or {})
+            kw["group_colors"] = colors
+        mapped = any(k in kw for k in ("color", "c")) and not any(
+            k in kw for k in ("color_map", "cmap"))
+        if mapped:
+            c = kw.get("color", kw.get("c"))
+            if c == "density" or (isinstance(c, str) and _is_column(self.data, c)) \
+                    or not isinstance(c, (str, tuple)):
+                kw["color_map"] = self._shared_map()
+        if "color_map" in kw and self._colorbar_side == "right" and self._colorbar is None:
+            self._cmap = kw["color_map"]
+            self._colorbar = self.colorbar(self._cmap, id="colorbar")
+        out = []
+        for _, p, rows in self.subsets():
+            out.append(getattr(p, method)(*args, data=rows, **kw))
+        if self._colorbar is not None and not self._colorbar.is_set("label") and out:
+            first = out[0][0] if isinstance(out[0], list) else out[0]
+            label = self._colorbar.__class__(first, plot=first.plot).auto_label() \
+                if hasattr(first, "color_sources") and first.color_sources() else None
+            if label is not None:
+                self._colorbar.set(label=label)
+        return out
+
+    def __getattr__(self, name: str) -> Any:
+        if name in _SERIES:
+            def method(*args: Any, **kw: Any) -> list[Any]:
+                return self._call(name, args, kw)
+            method.__name__ = name
+            return method
+        raise AttributeError(name)
+
+
+def _is_column(data: Any, name: str) -> bool:
+    from .tables import has_column
+    return has_column(data, name)
+
+
+def facet(data: Any, col: str | None = None, row: str | None = None, wrap: int | None = None,
+          share: Any = "grid", order: Any = None, title_format: str = "{name} = {value}",
+          colorbar: Any = None, **figure_settings: Any) -> FacetFigure:
+    """Small multiples of ``data``: one plot per value of ``col`` (and ``row``); ``wrap``
+    wraps ``col`` into rows of that many panels. ``order``: ``{column: [values]}``.
+    ``colorbar="right"``: one colorbar, in an extra column, for the shared color map."""
+    return FacetFigure(data, col, row, wrap, share, order, title_format, colorbar,
+                       **figure_settings)
+

plot_io/figure.py

@@ -0,0 +1,331 @@
+"""Figures: plots (and colorbars) arranged in a grid, with sizes and output."""
+
+import math
+from typing import Any
+
+from .settings import (THEME, Setting, Settings, boolean, color, either, literal, number,
+                       one_of, table, text)
+from .numbers import number_settings
+from .style import check_palette
+
+__all__ = ["Figure", "POINTS_PER_UNIT"]
+
+POINTS_PER_UNIT = {"pt": 1.0, "in": 72.0, "cm": 72.0 / 2.54, "mm": 72.0 / 25.4}
+
+
+def _grid(v: Any) -> list[list[Any]]:
+    rows = [list(r) for r in v]
+    if not rows or not rows[0]:
+        raise ValueError("a grid needs at least one cell")
+    if any(len(r) != len(rows[0]) for r in rows):
+        raise ValueError("grid rows must have the same length")
+    cells: dict[Any, list[tuple[int, int]]] = {}
+    for i, r in enumerate(rows):
+        for j, k in enumerate(r):
+            if k is None or k == 0:
+                continue
+            cells.setdefault(k, []).append((i, j))
+    for k, cs in cells.items():
+        r0 = min(c[0] for c in cs)
+        r1 = max(c[0] for c in cs) + 1
+        c0 = min(c[1] for c in cs)
+        c1 = max(c[1] for c in cs) + 1
+        if len(cs) != (r1 - r0) * (c1 - c0) or any(rows[i][j] != k for i in range(r0, r1)
+                                                    for j in range(c0, c1)):
+            raise ValueError(f"grid id {k!r} does not cover a rectangle of cells")
+    return rows
+
+
+def _ratios(v: Any) -> list[float]:
+    out = [number(positive=True)(x) for x in v]
+    if not out:
+        raise ValueError("expected at least one ratio")
+    return out
+
+
+_UNSET = object()
+
+
+def _check_cmap(v: Any) -> Any:
+    from .maps import check_cmap
+    return check_cmap(v)
+
+
+def _sharing() -> Any:
+    from . import sharing
+    return sharing
+
+
+def _styles() -> Any:
+    # the module (``plot_io.styles`` the attribute is the function listing styles)
+    import importlib
+    return importlib.import_module("plot_io.styles")
+
+
+class FigureTitle(Settings):
+    """The title of a figure (``figure.title``): a band above the plots."""
+
+    SETTINGS = table(
+        text=Setting(text, doc="Title text: a string or rich content; `\\n` starts a line."),
+        font_size=Setting(number(positive=True),
+                          doc="Font size (pt); default 1.4 × the base font size.", length=True),
+        font_weight=Setting(one_of("normal", "bold"), doc="`bold` or `normal`."),
+        align=Setting(one_of("center", "left", "right"), doc="Alignment."),
+        over=Setting(one_of("axes", "figure"),
+                     doc="Width it is aligned and wrapped within: from the leftmost to the "
+                         "rightmost axes, or the whole figure."),
+        pad=Setting(number(lo=0),
+                    doc="Gap between the title and the plots (pt); default half the font "
+                        "size.", length=True),
+        color=Setting(color, doc="Text color."),
+        font_family=Setting(str, inherited=True, doc="Font family."),
+    )
+
+    def __init__(self, figure: "Figure") -> None:
+        self._figure = figure
+        super().__init__()
+
+    def _parent(self) -> Settings:
+        return self._figure
+
+    def __call__(self, text: Any = _UNSET, **settings: Any) -> "FigureTitle":
+        """Set the title (``None`` removes it) and its settings."""
+        if text is not _UNSET:
+            settings["text"] = text
+        return self.set(**settings)
+
+    def __repr__(self) -> str:
+        return f"FigureTitle({self.get('text')!r})"
+
+
+class Figure(Settings):
+    """A figure: plots arranged in an explicit ``grid`` of ids or automatically
+    (``rows``, ``cols``, ``order``), sized by plot (``plot_width``, ``plot_height``) or as
+    a whole (``width``, ``height``)."""
+
+    SETTINGS = table(
+        grid=Setting(_grid, doc="Rows of ids; each id covers a rectangle of cells, "
+                                "`0`/`None` leaves a cell empty."),
+        rows=Setting(number(lo=1, integer=True), doc="Automatic arrangement: rows."),
+        cols=Setting(number(lo=1, integer=True), doc="Automatic arrangement: columns."),
+        order=Setting(one_of("auto", "row", "col"),
+                      doc="Fill order of the automatic arrangement: `auto` (row by row "
+                          "with `cols`, column by column with `rows`), `row` or `col`."),
+        align=Setting(one_of("axes", "borders"),
+                      doc="`axes`: axis lines line up across plots; `borders`: plot boxes "
+                          "line up."),
+        widths=Setting(_ratios, doc="Column width ratios."),
+        heights=Setting(_ratios, doc="Row height ratios."),
+        plot_width=Setting(number(positive=True),
+                           doc="Width of one grid cell's aligned box (axes, or whole plot "
+                               "with `align=\"borders\"`), in `unit`; default 3 in."),
+        plot_height=Setting(number(positive=True),
+                            doc="Height of one grid cell's aligned box, in `unit`; "
+                                "default 2.25 in."),
+        width=Setting(number(positive=True), doc="Figure width in `unit` (instead of "
+                                                 "`plot_width`)."),
+        height=Setting(number(positive=True), doc="Figure height in `unit` (instead of "
+                                                  "`plot_height`)."),
+        unit=Setting(one_of("in", "cm", "mm", "pt"),
+                     doc="Unit of the figure's sizes: `in`, `cm`, `mm` or `pt`."),
+        spacing=Setting(number(lo=0),
+                        doc="Minimum gap between neighbouring plots, in `unit`; default "
+                            "10 pt."),
+        margin=Setting(number(lo=0),
+                       doc="Space around the figure, in `unit`; default 4 pt."),
+        background=Setting(color, doc="Figure background; unset: none in PDF, "
+                                      "`image_background` in images."),
+        image_background=Setting(color, doc="Background of PNG, JPEG and JPEG XL output "
+                                            "when `background` is unset."),
+        dpi=Setting(number(positive=True), doc="Resolution of PNG, JPEG and JPEG XL output."),
+        quality=Setting(number(lo=1, hi=100, integer=True),
+                        doc="Quality (1–100), as pdf_io's: of JPEG and JPEG XL output, and of "
+                            "rasterized content in PDFs (stored as JPEG). Unset: pdf_io's "
+                            "defaults (JPEG 90; JPEG XL and PDF images lossless)."),
+        title_rule=Setting(color, doc="Color of a rule above the figure title, across its "
+                                      "width (The Economist's red bar); default none."),
+        title_rule_width=Setting(number(lo=0), doc="Thickness of the title rule (pt).",
+                                 length=True),
+        share_x=Setting(lambda v: _sharing().check_figure_share(v),
+                        doc="Plots sharing their x axis: `False`, `True`/`\"all\"`, `\"col\"` "
+                            "(same column span) or `\"row\"` (same row span)."),
+        share_y=Setting(lambda v: _sharing().check_figure_share(v),
+                        doc="Plots sharing their y axis, as `share_x`."),
+        share=Setting(lambda v: _sharing().check_share(v),
+                      doc="Both axes at once: as `share_x`, or `\"grid\"` (x per column, y "
+                          "per row); `share_x`/`share_y` override it."),
+        label_outer=Setting(boolean,
+                            doc="Tick labels and axis titles of shared axes only on the outer "
+                                "plots (bottom of each column, left of each row); default "
+                                "`True` for groups from the figure's settings, `False` for "
+                                "plots paired with `share_x=plot`."),
+        style=Setting(lambda v: _styles().check_style(v),
+                      doc="A style name (`\"ggplot2\"`, …) or a dict of settings with an "
+                          "optional `\"base\"`; default: the session style (`set_style`, "
+                          "`use_style`), else `\"default\"`."),
+        scaling=Setting(number(positive=True),
+                        doc="Multiplies every font size, line width, marker size, tick "
+                            "length and pad of the style; default 1."),
+        font_size=Setting(number(positive=True), inherited=True, doc="Base font size (pt).", length=True),
+        font_family=Setting(str, inherited=True, doc="Font family."),
+        text_color=Setting(color, inherited=True, doc="Text color."),
+        line_width=Setting(number(lo=0), inherited=True, doc="Default line width (pt).", length=True),
+        palette=Setting(check_palette, inherited=True,
+                        doc="Colors of series without one."),
+        alpha=Setting(number(0, 1), inherited=True, doc="Default opacity of series."),
+        rasterize=Setting(either(boolean, number(positive=True)), inherited=True,
+                          doc="`True` or a dpi: series drawn as images inside the PDF."),
+        simplify=Setting(either(literal("auto"), boolean, number(positive=True)),
+                         inherited=True,
+                         doc="pdf_io's `simplify` for every series; default `\"auto\"`."),
+        data=Setting(lambda v: v, inherited=True,
+                     doc="A table whose columns the series' data arguments name."),
+        color_map=Setting(lambda v: _check_cmap(v), inherited=True,
+                          doc="Default color map (alias `cmap`): of heatmaps, contours and "
+                              "numbers given as colors."),
+        **number_settings(),
+    )
+
+    def __init__(self, **settings: Any) -> None:
+        self._areas: dict[Any, Any] = {}     # id → Plot or Colorbar, in creation order
+        self.title = FigureTitle(self)
+        self._session_style = _styles().current()
+        self._theme_key: Any = None
+        self._theme_value: dict[str, Any] = THEME
+        super().__init__(**settings)
+
+    def _theme(self) -> dict[str, Any]:
+        styles = _styles()
+        style = self._values.get("style", self._session_style)
+        scaling = self._values.get("scaling")
+        key = (id(style), scaling, styles.version())
+        if key != self._theme_key:
+            self._theme_value = styles.effective(style, scaling)
+            self._theme_key = key
+        return self._theme_value
+
+    def set(self, **settings: Any) -> "Figure":
+        super().set(**settings)
+        if self.is_set("grid") and any(self.is_set(k) for k in ("rows", "cols")):
+            raise ValueError("give either grid or rows/cols, not both")
+        if self.is_set("grid") and self.get("order") != "auto":
+            raise ValueError("order applies to the automatic arrangement, not to a grid")
+        for a, b in (("width", "plot_width"), ("height", "plot_height")):
+            if self.is_set(a) and self.is_set(b):
+                raise ValueError(f"give either {a} or {b}, not both")
+        return self
+
+    @property
+    def points_per_unit(self) -> float:
+        return POINTS_PER_UNIT[self.get("unit")]
+
+    def __repr__(self) -> str:
+        return f"Figure({len(self.plots)} plots)"
+
+    @property
+    def plots(self) -> list[Any]:
+        from .plot import Plot
+        return [a for a in self._areas.values() if isinstance(a, Plot)]
+
+    # -- areas -----------------------------------------------------------------------
+
+    def _grid_ids(self) -> list[Any]:
+        ids: list[Any] = []
+        for r in self.get("grid") or []:
+            for k in r:
+                if k is not None and k != 0 and k not in ids:
+                    ids.append(k)
+        return ids
+
+    def _capacity(self) -> float:
+        rows, cols = self.get("rows"), self.get("cols")
+        return rows * cols if rows and cols else math.inf
+
+    def _next_id(self) -> Any:
+        if self.is_set("grid"):
+            for k in self._grid_ids():
+                if k not in self._areas:
+                    return k
+            raise ValueError("every grid id already has a plot")
+        if len(self._areas) >= self._capacity():
+            raise ValueError(f"the {self.get('rows')} × {self.get('cols')} arrangement is full")
+        i = 1
+        while i in self._areas:
+            i += 1
+        return i
+
+    def _attach(self, area: Any, id: Any) -> Any:
+        if id is None:
+            id = self._next_id()
+        elif self.is_set("grid") and id not in self._grid_ids():
+            raise ValueError(f"id {id!r} is not in the grid")
+        elif id in self._areas:
+            raise ValueError(f"id {id!r} is already taken")
+        elif not self.is_set("grid") and len(self._areas) >= self._capacity():
+            raise ValueError(f"the {self.get('rows')} × {self.get('cols')} arrangement is full")
+        self._areas[id] = area
+        return id
+
+    def plot(self, id: Any = None, **settings: Any) -> Any:
+        """The plot with ``id``, created if needed; without ``id``, the next available
+        plot."""
+        from .plot import Plot
+
+        if id is not None and id in self._areas:
+            p = self._areas[id]
+            if not isinstance(p, Plot):
+                raise ValueError(f"id {id!r} holds a colorbar")
+            if settings:
+                p.set(**settings)
+            return p
+        return Plot(figure=self, id=id, **settings)
+
+    def colorbar(self, source: Any, id: Any = None, **settings: Any) -> Any:
+        """A colorbar in its own area (a grid id, or the next position)."""
+        from .colorbar import Colorbar
+
+        cb = Colorbar(source, figure=self, **settings)
+        cb.id = self._attach(cb, id)
+        return cb
+
+    def size_legend(self, size_map: Any, id: Any = None, values: Any = None,
+                    font_size: Any = None, title: Any = None) -> Any:
+        """A size key of ``size_map`` in its own area (a grid id, or the next position):
+        the map's label, then sample markers with their values (``values``: which)."""
+        from .legend import SizeLegend
+
+        sl = SizeLegend(size_map, self, values, font_size, title)
+        sl.id = self._attach(sl, id)
+        return sl
+
+    # -- output ----------------------------------------------------------------------
+
+    def draw(self, canvas: Any, x: float = 0.0, y: float = 0.0) -> tuple[float, float]:
+        """Draw the figure on a pdf_io canvas with its top-left corner at ``(x, y)`` (page
+        units); returns its size in points."""
+        from . import render
+        return render.draw(self, canvas, x, y)
+
+    def size(self) -> tuple[float, float]:
+        """Width and height of the figure in points."""
+        from . import render
+        return render.size(self)
+
+    def save(self, path: Any, **options: Any) -> None:
+        """Write a PDF, PNG, JPEG or JPEG XL (``.jxl``) by the extension of ``path``.
+
+        Options: ``dpi`` (images, default 150), ``background``, ``quality`` (JPEG, default
+        90; lossy JPEG XL, default lossless; in a PDF, of rasterized content, stored as
+        JPEG), and pdf_io ``Document`` arguments (``pdf_a``, ``color_mode``, …).  Images
+        inside a PDF are PNG-like (lossless) or JPEG, never JPEG XL.
+        """
+        from . import render
+        render.save(self, path, **options)
+
+    def to_bytes(self, format: str = "pdf", **options: Any) -> bytes:
+        """The figure as ``"pdf"``, ``"png"``, ``"jpeg"`` or ``"jxl"`` bytes."""
+        from . import render
+        return render.to_bytes(self, format, **options)
+
+    def _repr_png_(self) -> bytes:
+        return self.to_bytes("png")