plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/figure.py

@@ -0,0 +1,788 @@
+"""Figures: plots (and colorbars) arranged in a grid, with sizes and output."""
+
+import contextlib
+import math
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any, Self, Unpack
+
+from .canvas import Canvas
+from ._methods import FigureMixin, FigureTitleMixin, MainTitleMixin
+from . import groups
+from .color.values import VARIANT_DOC, check_variant, color
+
+from .settings import (DECLINE, custom_vars, BASE_THEME, Setting, Settings, Theme, boolean, dpi,
+                       dpi_or_bool, either, literal, number, one_of, overriding,
+                       simplify_value, table)
+from .titles import CREATED, TitleBase
+from .units import Dim, parse
+from .validators import Custom, length, real, typed
+
+if TYPE_CHECKING:
+    from .genome.layout import Track
+    from .mapped import ColorAxis, SizeAxis
+    from .plot import Plot
+    from .rows import FigureVLine, FigureVSpan
+    from .types import (ColorAxisSettings, FigureSettings, FigureVLineSettings,
+                        FigureVSpanSettings, PlotSettings, SizeAxisSettings, TrackSettings,
+                        WriteOptions)
+
+__all__ = ["Figure"]
+
+
+def _side(what: str) -> Any:
+    """A figure width or height: a length, or a paper size's side (``"a4"``, px)."""
+    base = length(positive=True, scaled=False)
+
+    def check(v: Any) -> Any:
+        if isinstance(v, str):
+            from vec_io.units import named_size
+            pt = named_size(v.strip(), what)
+            if pt is not None:
+                return pt / 0.75
+        return base(v)
+    return Custom(check, like=base)
+
+
+def _grid(v: Any) -> list[list[Any]]:
+    if isinstance(v, (str, bytes)):
+        raise ValueError(f"expected \"auto\", \"tracks\" or rows of ids, got {v!r}")
+    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 _layout(v: Any) -> Any:
+    """``"auto"``, ``"tracks"`` or rows of ids (an explicit grid)."""
+    if v in ("auto", "tracks"):
+        return v
+    return _grid(v)
+
+
+_TRACK = length(positive=True, percent="room", fr=True)
+
+
+def _tracks(v: Any) -> list[Any]:
+    """Column widths or row heights: ratios (numbers or ``fr``) and fixed lengths."""
+    if isinstance(v, str) or real(v) is not None or not hasattr(v, "__iter__"):
+        raise ValueError(f"expected a list of widths, got {v!r}")
+    out = [_TRACK(x) for x in v]
+    if not out:
+        raise ValueError("expected at least one width")
+    return out
+
+
+_UNSET = object()
+_WIDTH_OF_HEIGHT = parse("calc(var(height) * var(aspect_ratio))")
+_TRACKS_WIDTH = 480.0
+_FR = Dim("1fr", 1.0, "fr")
+
+
+def _kind_settings() -> Any:
+    from .color.maps import kind_settings
+    return kind_settings()
+
+
+def _check_fonts(v: Any) -> Any:
+    """A vec_io ``Fonts``, or a dict of its fields (kept as given)."""
+    import vec_io
+    vec_io.Fonts.of(v, "fonts")
+    return dict(v) if isinstance(v, dict) else v
+
+
+def _sharing() -> Any:
+    from . import sharing
+    return sharing
+
+
+def _styles() -> Any:
+    from . import styles
+    return styles
+
+
+
+@typed("Literal['auto', 'lossless'] | SupportsFloat")
+def check_quality(v: Any) -> Any:
+    """``"auto"``, ``"lossless"`` or a quality from 1 to 100."""
+    return either(literal("auto", "lossless"), number(lo=1, hi=100, integer=True))(v)
+
+
+def output_quality(value: Any, fmt: str) -> int | None:
+    """The vec_io quality of a ``quality`` value for output format ``fmt`` (``"png"``,
+    ``"jpeg"``, ``"jxl"``, ``"avif"`` or ``"pdf"``): ``None`` for lossless, or for vec_io's
+    default (JPEG 90)."""
+    v = check_quality(value)
+    if v == "auto":
+        return 90 if fmt == "png" else None
+    if v == "lossless":
+        if fmt == "jpeg":
+            raise ValueError("JPEG has no lossless mode (use PNG, JPEG XL or AVIF)")
+        return None
+    return v
+
+class FigureTitle(FigureTitleMixin, TitleBase):
+    """A title of the figure: its main title (``figure.title``), a band above the plots,
+    or another one over a set of plots (``figure.add_title``), in the lanes between them.
+
+    The main title is the outermost lane of the top, over every plot: the figure grows by it
+    (with ``reference="figure"`` the plots shrink).  ``over``: ``"axes"`` aligns it within
+    the leftmost to rightmost axes, ``"plot"`` within their boxes, ``"figure"`` within the
+    figure less ``margin``.  ``rule="outside"`` draws a bar above it, ``True`` a line
+    between it and the plots.  Style keys ``"MainTitle.name"`` apply to the main title alone,
+    ``"FigureTitle.name"`` to every figure title.
+
+    ``figure.add_title(text, plots=…, side=…)`` covers the grid rectangle of its plots' cells
+    (a plot inside it but not given is an error naming it).  Lanes: a title sits in the line
+    between cells beside its plots; the titles of one side stack outward, a title whose
+    plots are a subset of another's nearer, titles over disjoint spans sharing a lane,
+    overlapping ones in creation order; ``order`` overrides (lower nearer).  A lane is as
+    thick as its thickest title.  Over the same plots, from the plots outward: legend,
+    colorbar, title.  The gap at a line is ``spacing`` plus its lanes, along the whole line,
+    so the titles in it line up.  Titles on top and bottom wrap to their span; on the left
+    and right they do not, and read upward (left) or downward (right).
+    """
+
+    SETTINGS = table(**{
+        **TitleBase.SETTINGS,
+        "over": Setting(one_of("axes", "plot", "figure"),
+                        doc="Span it is aligned and wrapped within: from the first to the "
+                            "last axes of its plots, their boxes, or the whole figure."),
+        "pad": Setting(length(lo=0), doc="Gap between the title and the plots."),
+        "order": Setting(number(), doc="Place in its side's lanes: lower is nearer the plots; "
+                                       "unset: a title nested in another nearer, then "
+                                       "creation order."),
+    })
+
+    def __init__(self, figure: "Figure", 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)
+        super().__init__(**settings)
+
+    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)
+
+
+class MainTitle(MainTitleMixin, FigureTitle):
+    """The figure's main title (``figure.title``): ``MainTitle.*`` style keys apply to it
+    alone, ``FigureTitle.*`` keys to every figure title."""
+
+
+def _tracks_rule(value: Any) -> Any:
+    """A figure rule giving ``value`` in a tracks layout."""
+    def rule(fig: "Figure") -> Any:
+        return value if fig.tracks_layout() else DECLINE
+    return rule
+
+
+class Figure(FigureMixin, Settings):
+    """A figure: plots arranged in an explicit grid of ids (``layout``) or automatically
+    (``rows``, ``cols``, ``fill_order``), sized by ``width``, ``height`` and ``aspect_ratio`` (CSS px)
+    of the box ``reference`` names: each cell's axes, each cell's plot, or the figure.
+
+    **Arrangement.** ``layout=[[1, 1, 2], [3, 3, 2]]``: each id covers a rectangle of cells
+    (``0`` or ``None``: empty) and holds a plot or a colorbar; ``figure.plot()`` returns the
+    next id without a plot.  ``layout="auto"`` places plots in creation order: ``cols=4`` row
+    by row, at most 4 per row; ``rows=4`` column by column; ``rows=2, cols=3`` a fixed grid
+    (full: ``ValueError``); neither, ⌈√n⌉ columns chosen when drawn.  ``layout="tracks"``:
+    one column top to bottom, sharing x, ``spacing`` 0 and ``width`` 480 px unless given,
+    each row as high as its plot's ``height`` (a :class:`Track`: from its content; other
+    plots ``1fr``).
+
+    **Sizes.** With one of ``width`` and ``height``, ``aspect_ratio`` gives the other;
+    giving all three raises ``ValueError``.  Plots with a ``data_ratio`` (and pies) take the
+    other side from it.  ``reference="figure"``: the cells share what the decorations leave
+    with axes of at least 8 px (a figure too small for them grows, with one warning).
+    ``widths``/``heights``: ratios, or fixed lengths the ratios share the rest around (in
+    ``%``, of the plots' room: what the cells share, as in a CSS grid; more than 100 %, or
+    100 % beside ratio cells, raises); a plot spanning cells gets their sizes plus the gaps.
+    ``align="axes"``: a gutter holds the widest margin before it, the widest after it and
+    ``spacing``; ``align="borders"``: each plot's axes are what its own decorations leave of
+    its box.  Columns (rows) of vertical (horizontal) colorbars only
+    are as wide as the bar, unless ``widths`` (``heights``) is given.
+
+    **Layout.** A plot is its axes rectangle with four stacks of bands, from the axes
+    outward: tick marks, tick labels, the axis label, twin axes, the ×10ᵏ offset, an
+    outside legend, attached colorbars, the plot's titles and ``space_above``; outermost on
+    the left, the row label band and the band of group letters.  A side's margin is its
+    bands' thicknesses, at least the overhangs of the bands across it; an axis label longer
+    than the plot's box wraps at spaces.  Each line between cells takes the largest margin
+    of the plots there, and its lanes: figure titles, legends, colorbars and group labels
+    (:class:`FigureTitle`).  Only what is circular is repeated, in rounds: tick labels set
+    the margins, which set the axes length (``reference="plot"`` or ``"figure"``),
+    ``data_ratio``, stats binned at the axes' resolution, wrapping figure titles.  Rounds
+    stop when no axes size moves by more than 1/3 px, after 5 at most; ``inside="auto"``
+    legends are placed on the placed axes.  The layout ends in a frozen geometry (every
+    box, tick and shaped text run in px) that drawing reads without measuring.
+
+    **One plot.** ``plot.save()`` lays out the whole figure and keeps the plot at its size
+    in it (its axes; with ``align="borders"`` its box), with its outer tick labels, row
+    label, titles, legend and attached colorbars, and the limits of its shared axes; figure
+    titles, legends and colorbars are left out.
+
+    **Fonts.** Each character takes the first family of ``font_family`` that is available
+    (from ``fonts``: its ``dirs``, then ``VEC_IO_FONT_DIRS``, then installed fonts unless
+    ``system=False``; a missing family tries its metric aliases: Helvetica and Arial →
+    Liberation Sans, Arimo, …), then a generic family's list, then any font with the
+    character; a ``font_family`` none of whose families is available warns once.  The
+    default list is Helvetica where installed, else the first of the others (all have
+    Helvetica's widths); with none installed, vec_io downloads Nimbus Sans.  With no outline
+    font at all, output raises ``NoFontError`` (a ``ValueError``).
+    """
+
+    SETTINGS = table(
+        layout=Setting(_layout,
+                       doc="`auto`: plots in automatic rows and columns (`rows`, `cols`, "
+                           "`fill_order`); rows of ids (`[[1, 1, 2], [3, 4, 2]]`): each id "
+                           "covers a rectangle of cells, `0`/`None` leaves a cell empty; "
+                           "`tracks`: one column of plots top to bottom in creation order, "
+                           "sharing x, each row as high as its plot's `height` (tracks: from "
+                           "their content; other plots `1fr`)."),
+        rows=Setting(number(lo=1, hi=10_000, integer=True), doc="Automatic arrangement: rows."),
+        cols=Setting(number(lo=1, hi=10_000, integer=True), doc="Automatic arrangement: columns."),
+        fill_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(_tracks, doc="Column widths: ratios (numbers or `fr`) sharing the "
+                                    "room left by fixed lengths (`\"2in\"`, `\"30%\"` of "
+                                    "the plots' room)."),
+        heights=Setting(_tracks, doc="Row heights, as `widths`."),
+        width=Setting(_side("width"),
+                      doc="Width of the `reference` box: one cell's axes, one cell's "
+                          "plot, or the figure; a paper size names its width (`\"a4\"`, "
+                          "`\"letter\"`, `\"a4-landscape\"`)."),
+        height=Setting(_side("height"), doc="Height of the `reference` box (a paper size: its "
+                                            "height)."),
+        aspect_ratio=Setting(number(lo=0.001, hi=1000),
+                             doc="Width / height of the `reference` box (16:9 → `16 / 9`), "
+                                 "when only one of `width` and `height` is given."),
+        reference=Setting(one_of("axes", "plot", "figure"),
+                          doc="What `width` and `height` measure: `axes` (each grid cell's "
+                              "axes rectangle), `plot` (each cell's whole plot box) or "
+                              "`figure`."),
+        spacing=Setting(length(lo=0, percent="figure"), doc="Minimum gap between neighbouring plots."),
+        margin=Setting(length(lo=0, percent="figure"), doc="Space around the figure."),
+        background=Setting(color, doc="Figure background, default the style's (white); "
+                                      "`\"none\"` or `\"transparent\"`: transparent (white "
+                                      "in JPEG, which has no transparency). `None` unsets it."),
+        fonts=Setting(_check_fonts, expr=False,
+                      doc="Where fonts come from: a vec_io `Fonts` or a dict of its fields "
+                          "(`dirs`, `system`, `downloads`: `True`, `False` or `\"cache\"`, "
+                          "`db`); unset: `VEC_IO_FONT_DIRS`, installed fonts and "
+                          "`VEC_IO_FONT_DOWNLOADS` (downloads on by default)."),
+        default_dpi=Setting(dpi,
+                            doc="Resolution of PNG, JPEG, JPEG XL and AVIF output when "
+                                "`save`/`write` give no `dpi`: dots per inch, or a multiple "
+                                "of 96 (`\"2x\"` is 192); `96` gives one image pixel per px, "
+                                "the default `\"4x\"` four. PDF, EPS and SVG output never use "
+                                "it."),
+        quality=Setting(check_quality,
+                        doc="Quality (1–100), as vec_io's: of PNG output (lossy: at most 256 "
+                            "indexed colors), JPEG, JPEG XL and AVIF output, and of "
+                            "rasterized content in PDF and SVG output (stored as JPEG); `\"lossless\"` "
+                            "(not JPEG); `\"auto\"`: 90 for PNG and JPEG, lossless for JPEG "
+                            "XL, AVIF and PDF content."),
+        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."),
+        share_color=Setting(lambda v: _sharing().check_figure_share(v),
+                            doc="Plots whose series' own color axes are one (limits over "
+                                "all their values), as `share_x`."),
+        share_size=Setting(lambda v: _sharing().check_figure_share(v),
+                           doc="Plots whose series' own size axes are one (limits over all "
+                               "their values, one size key), as `share_x`."),
+        share_legend=Setting(lambda v: _sharing().check_legend_share(v),
+                             doc="Legends shared by plots, made by the figure: `False`, "
+                                 "`True`/`\"all\"` (one on the right of the figure), "
+                                 "`\"row\"` (one on the right of each row), `\"col\"` "
+                                 "(one at the bottom of each column); a plot with "
+                                 "`legend=False` adds no entries."),
+        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\"`."),
+        vars=Setting(custom_vars, expr=False,
+                     doc="Custom variables, read by `var(--name)` in any setting here and "
+                         "below: `{\"accent\": \"#c00\"}`."),
+        scaling=Setting(number(positive=True),
+                        doc="Multiplies every font size, line width, marker size, tick "
+                            "length and pad of the style; default 1."),
+        **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\"` (default), `True`, a "
+                             "dpi, `False`, or a `Simplify` (or a dict of its fields)."),
+        data=Setting(lambda v: v, inherited=True,
+                     doc="A table whose columns the series' data arguments name."),
+        **groups.NumberFormat.embed(),
+    )
+
+    #: Keywords accepted besides settings: ``title="…"`` sets the main title's text.
+    EXTRA = ("title",)
+
+    def __init__(self, **settings: "Unpack[FigureSettings]") -> None:
+        from .axis import Axis
+        self._areas: dict[Any, Any] = {}     # id → Plot or Colorbar, in creation order
+        self._value_axes: list[Any] = []     # shared color and size axes
+        #: settings every plot's x (y) axis takes unless set on the axis itself
+        self.x_axis = Axis(self, "x")
+        self.y_axis = Axis(self, "y")
+        #: lines and bands through rows (``vline``, ``vspan``), groups of rows (``group``)
+        self.decorations: list[Any] = []
+        self.groups: list[Any] = []
+        self.title: FigureTitle = MainTitle(self)
+        self._titles: list[FigureTitle] = []
+        self._legends: list[Any] = []
+        self._colorbars: list[Any] = []
+        self._session_style = _styles().current()
+        self._theme_key: Any = None
+        self._theme_value: Theme = BASE_THEME
+        super().__init__(**settings)
+
+    def _width(self) -> Any:
+        """Only ``height`` set: the width follows from ``aspect_ratio``; tracks: 480 px."""
+        if self.is_set("height") and not self.is_set("width"):
+            return _WIDTH_OF_HEIGHT
+        if self.tracks_layout():
+            return _TRACKS_WIDTH
+        return DECLINE
+
+    def _heights(self) -> Any:
+        """Tracks: each row as high as its plot's ``height`` (px), other areas ``1fr``."""
+        if not self.tracks_layout() or not self._areas:
+            return DECLINE
+        out = []
+        for a in self._areas.values():
+            h = a.resolve("height") if "height" in getattr(a, "SETTINGS", {}) else None
+            if isinstance(h, tuple):                      # ("fr", share)
+                out.append(Dim(f"{h[1]!r}fr", h[1], "fr"))
+            elif isinstance(h, (int, float)):
+                out.append(Dim(f"{float(h)!r}px", float(h), "px"))
+            else:
+                out.append(_FR)
+        return out
+
+    RULES = {"width": _width, "heights": _heights, "cols": _tracks_rule(1),
+             "spacing": _tracks_rule(0.0), "share_x": _tracks_rule("all")}
+
+    def tracks_layout(self) -> bool:
+        return self._values.get("layout") == "tracks"
+
+    def explicit_grid(self) -> list[list[Any]] | None:
+        """The rows of ids of an explicit grid (``layout``), else ``None``."""
+        v = self.resolve("layout")
+        return v if isinstance(v, list) else None
+
+    def _children(self) -> list[Settings]:
+        return [self.title, *self._titles, *self._legends, *self._colorbars, *self._value_axes,
+                *(a for a in self._areas.values() if isinstance(a, Settings)),
+                *self.decorations, *self.groups]
+
+    def _theme(self) -> Theme:
+        styles = _styles()
+        style = self._values.get("style", self._session_style)
+        key = (id(style), styles.version())
+        if key != self._theme_key:
+            self._theme_value = styles.effective(style)
+            self._theme_key = key
+        return self._theme_value
+
+    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, **settings: "Unpack[FigureSettings]") -> Self:  # type: ignore[override]
+        title = settings.pop("title", None)
+        super().set(**settings)
+        if title is not None:
+            self.title.set(text=title)
+        if self.explicit_grid() is not None and any(self.is_set(k) for k in ("rows", "cols")):
+            raise ValueError("give either a grid layout or rows/cols, not both")
+        if self.tracks_layout() and self.is_set("cols") and self._values["cols"] != 1:
+            raise ValueError("a tracks layout is one column of tracks: cols does not apply "
+                             "(for tracks beside other plots, use a grid figure)")
+        if self.explicit_grid() is not None and self.resolve("fill_order") != "auto":
+            raise ValueError("fill_order applies to the automatic arrangement, not to a "
+                             "grid")
+        if all(self.is_set(k) for k in ("width", "height", "aspect_ratio")):
+            raise ValueError("give at most two of width, height and aspect_ratio")
+        return self
+
+    def reference_size(self) -> tuple[float, float]:
+        """Width and height (px) of the `reference` box: as given, or completed by
+        `aspect_ratio`."""
+        return self.resolve("width"), self.resolve("height")
+
+    def one_size_given(self) -> str | None:
+        """``"width"`` or ``"height"`` when only that one is set (no `aspect_ratio`): plots
+        with a `data_ratio` then take the other side from it."""
+        if self.is_set("aspect_ratio"):
+            return None
+        w, h = self.is_set("width"), self.is_set("height")
+        return "width" if w and not h else ("height" if h and not w else None)
+
+    def __repr__(self) -> str:
+        n = len(self.plots)
+        style = self._values.get("style", self._session_style)
+        style = "default" if style is None else style
+        parts = [f"{n} plot{'' if n == 1 else 's'}",
+                 f'style "{style}"' if isinstance(style, str) else "custom style"]
+        try:
+            w, h = self.size()
+            parts.insert(0, f"{round(w)} × {round(h)} px")
+        except Exception:                          # a figure that cannot lay out yet
+            pass
+        return f"Figure({', '.join(parts)})"
+
+    @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.explicit_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.resolve("rows"), self.resolve("cols")
+        return rows * cols if rows and cols else math.inf
+
+    def _next_id(self) -> Any:
+        if self.explicit_grid() is not None:
+            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.resolve('rows')} × {self.resolve('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.explicit_grid() is not None 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 self.explicit_grid() is None and len(self._areas) >= self._capacity():
+            raise ValueError(f"the {self.resolve('rows')} × {self.resolve('cols')} arrangement is full")
+        self._areas[id] = area
+        return id
+
+    def plot(self, id: Any = None, **settings: "Unpack[PlotSettings]") -> "Plot":
+        """The plot with ``id``, created if needed; without ``id``, the next available
+        plot (a :class:`~plot_io.Track` in a tracks layout)."""
+        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
+        if self.tracks_layout():
+            return self.track(id=id, **settings)
+        return Plot(figure=self, id=id, **settings)
+
+    def track(self, id: Any = None, **settings: "Unpack[TrackSettings]") -> "Track":
+        """A new, empty :class:`~plot_io.Track` (series added with its methods are
+        overlaid)."""
+        from .genome.layout import Track
+        return Track(figure=self, id=id, **settings)
+
+    def _new_plot(self, cls: Any, settings: dict[str, Any]) -> Any:
+        """A new plot for a ``cls`` call made on the figure (``figure.scatter(…)``): the
+        settings of the plot (a track in a tracks layout) that ``cls`` lacks, ``title``,
+        ``x_axis`` and ``y_axis``, are taken out of ``settings`` for it."""
+        from .settings import canonical
+        from .plot import Plot
+        kind: Any = Plot
+        if self.tracks_layout():
+            from .genome.layout import Track
+            kind = Track
+        own = getattr(cls, "SETTINGS", {})
+        plot_kw = {k: settings.pop(k) for k in list(settings)
+                   if (k in kind.SETTINGS or k in Plot.CALL_EXTRA)
+                   and canonical(k, own) not in own}
+        return self.plot(**plot_kw)
+
+    # -- figure decorations ----------------------------------------------------------
+
+    def vline(self, x: Any, rows: Any = None,
+              **settings: "Unpack[FigureVLineSettings]") -> "FigureVLine":
+        """A vertical line at ``x`` through the plots ``rows`` (plots or their series; all
+        by default) and the gaps between them, over the plots."""
+        from .rows import FigureVLine
+        d = FigureVLine(self, x, rows, **settings)
+        self.decorations.append(d)
+        return d
+
+    def vspan(self, x0: Any, x1: Any = None, rows: Any = None,
+              **settings: "Unpack[FigureVSpanSettings]") -> "FigureVSpan":
+        """A vertical band from ``x0`` to ``x1`` (or over a genome region given as ``x0``)
+        through the plots ``rows``, under them."""
+        from .rows import FigureVSpan
+        d = FigureVSpan(self, x0, x1, rows, **settings)
+        self.decorations.append(d)
+        return d
+
+    @property
+    def titles(self) -> list[FigureTitle]:
+        """The figure's titles: its main title first, then those of :meth:`add_title`."""
+        return [self.title, *self._titles]
+
+    def add_title(self, text: Any, plots: Any = None, side: Any = None,
+                  **settings: Any) -> FigureTitle:
+        """A title over ``plots`` (plots or their series; default every plot) on ``side``
+        (default ``"top"``); returns it.  The plots' cells must fill the grid rectangle
+        they span."""
+        covered = self._covered("add_title", plots)
+        if side is not None:
+            settings["side"] = side
+        t = FigureTitle(self, covered, text=text, **settings)
+        self._titles.append(t)
+        return t
+
+    @property
+    def legends(self) -> list[Any]:
+        """The figure's legends (:meth:`add_legend`), in creation order."""
+        return list(self._legends)
+
+    def add_legend(self, plots: Any = None, side: Any = None, **settings: Any) -> Any:
+        """A legend of the entries of ``plots`` (plots or their series; default every
+        plot) on ``side`` (default ``"right"``), in the lanes beside them; returns it.
+        The plots' cells must fill the grid rectangle they span."""
+        from .plot import FigureLegend
+        covered = self._covered("add_legend", plots)
+        if side is not None:
+            settings["side"] = side
+        g = FigureLegend(self, covered, **settings)
+        self._legends.append(g)
+        return g
+
+    @property
+    def colorbars(self) -> list[Any]:
+        """The figure's colorbars in the lanes (:meth:`add_colorbar`), in creation order."""
+        return list(self._colorbars)
+
+    def add_colorbar(self, source: Any = None, plots: Any = None, side: Any = None,
+                     **settings: Any) -> Any:
+        """A colorbar of the color axis of ``source`` (a mapped series or a color axis;
+        default: the last mapped series of the first of ``plots`` that has one) over
+        ``plots`` (plots or their series; default every plot) on ``side`` (default
+        ``"bottom"``), in the lanes beside them; returns it.  The plots' cells must fill
+        the grid rectangle they span; their attached colorbars of the same axis are left
+        out."""
+        from .colorbar import FigureColorbar
+        covered = self._covered("add_colorbar", plots)
+        if side is not None:
+            settings["side"] = side
+        cb = FigureColorbar(self, source, covered, **settings)
+        self._colorbars.append(cb)
+        return cb
+
+    def _covered(self, what: str, plots: Any) -> list[Any] | None:
+        """The plots ``plots`` names (``None``: every plot), checked to be this figure's."""
+        from .rows import plots_of
+        covered = plots_of(plots)
+        for p in covered or []:
+            if p.figure is not self:
+                raise ValueError(f"{what}: {p!r} is not a plot of this figure")
+        if covered is not None and not covered:
+            raise ValueError(f"{what}: plots= names no plot")
+        return covered
+
+    def group(self, first: Any, last: Any = None, **settings: Any) -> Any:
+        """Plots ``first`` to ``last`` (plots or their series, in creation order) as a
+        group: ``label`` (rotated, left of their row labels), ``letter`` (a panel letter),
+        and the tick labels of a shared x axis under the last one."""
+        from .rows import FigureGroup, _plot_of
+        g = FigureGroup(self, _plot_of(first), _plot_of(last if last is not None else first),
+                        **settings)
+        self.groups.append(g)
+        return g
+
+    def color_axis(self, **settings: "Unpack[ColorAxisSettings]") -> "ColorAxis":
+        """A shared color axis: series given it as ``color_axis=`` map their values through
+        its gradient (``color_map``), scale and limits (``"auto"`` covers them all)."""
+        from .mapped import ColorAxis
+        return self.adopt_axis(ColorAxis(**settings))
+
+    def size_axis(self, **settings: "Unpack[SizeAxisSettings]") -> "SizeAxis":
+        """A shared size axis (``size_axis=``): its sizes (``size_map``), scale and limits."""
+        from .mapped import SizeAxis
+        return self.adopt_axis(SizeAxis(**settings))
+
+    def adopt_axis(self, axis: Any) -> Any:
+        """Make the figure the parent of a shared color or size axis (its style applies)."""
+        if axis._parent() is None:
+            axis._owner = self
+            self._value_axes.append(axis)
+        return axis
+
+    def colorbar_area(self, source: Any, id: Any = None, **settings: Any) -> Any:
+        """A colorbar in its own grid area (a grid id, or the next position): the guide of
+        the color axis of ``source`` (a mapped series, or a color axis); see
+        :meth:`add_colorbar` for one in the lanes beside plots."""
+        from .colorbar import Colorbar
+
+        cb = Colorbar(source, figure=self, **settings)
+        cb.id = self._attach(cb, id)
+        return cb
+
+    def size_legend(self, source: Any, id: Any = None, **settings: Any) -> Any:
+        """A size key in its own area (a grid id, or the next position): the guide of the
+        size axis of ``source`` (a series mapping sizes, or a size axis): its title, then
+        sample markers with their values; ``settings``: ``values``, ``title``,
+        ``font_size`` (``.set`` changes them); returns it."""
+        from .legend import SizeLegend
+
+        sl = SizeLegend(source, self, **settings)
+        sl.id = self._attach(sl, id)
+        return sl
+
+    # -- output ----------------------------------------------------------------------
+
+    @contextlib.contextmanager
+    def _region(self, region: Any) -> Generator[None]:
+        """The figure drawn over another genome region (the x axes' ``region``)."""
+        with overriding(self.x_axis, region=region):
+            yield
+
+    def draw(self, canvas: Canvas, x: float = 0.0, y: float = 0.0,
+             region: Any = None) -> tuple[float, float]:
+        """Draw the figure 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.  ``region``: a genome region drawn instead of
+        the x axes' (as ``save``)."""
+        from . import render
+        with self._region(region):
+            return render.draw(self, canvas, x, y)
+
+    def size(self, region: Any = None) -> tuple[float, float]:
+        """Width and height of the figure in px."""
+        from . import render
+        with self._region(region):
+            return render.size(self)
+
+    def save(self, file: Any, *, region: Any = None, format: str | None = None,
+             **options: "Unpack[WriteOptions]") -> None:
+        """Write the figure to ``file``, a path or a binary file object, as :meth:`write`
+        does, in ``format`` (``"pdf"``, ``"eps"``, ``"svg"``, ``"png"``, ``"jpeg"``,
+        ``"jxl"``, ``"avif"``) or the path's extension (none, or another: ``ValueError``)."""
+        from . import render
+        with self._region(region):
+            render.save(self, file, format=format, **options)
+
+    def save_each(self, regions: Any, file: str,
+                  **options: "Unpack[WriteOptions]") -> list[str]:
+        """Write the figure once per region (as :meth:`save` with ``region=``) to ``file``
+        with ``{chr}``, ``{start}`` (1-based), ``{end}``, ``{name}`` and ``{i}`` (from 0)
+        filled in; ``regions``: a list of regions, or a mapping of names to regions (else
+        a region's name is its text, ``chr2:1,000-2,000``).  Returns the paths written."""
+        from .genome.regions import parse_region
+        from collections.abc import Mapping
+        named: list[tuple[str | None, Any]]
+        if isinstance(regions, Mapping):
+            named = [(str(k), parse_region(v)) for k, v in regions.items()]
+        elif isinstance(regions, (list, tuple)) and not isinstance(regions, str):
+            named = [(None, parse_region(v)) for v in regions]
+        else:
+            raise ValueError(f"save_each: expected a list of regions or a mapping of names to "
+                             f"regions, got {regions!r}")
+        paths = []
+        for i, (name, r) in enumerate(named):
+            paths.append(str(file).format(chr=r.chr, start=r.start + 1, end=r.end, i=i,
+                                          name=str(r) if name is None else name))
+        if len(set(paths)) < len(paths):
+            raise ValueError(f"save_each: {file!r} gives two regions the same path (use "
+                             f"{{name}} or {{i}})")
+        for path, (_, r) in zip(paths, named):
+            self.save(path, region=r, **options)
+        return paths
+
+    def write(self, format: str, *, region: Any = None,
+              **options: "Unpack[WriteOptions]") -> bytes:
+        """The figure as ``format`` bytes: ``"pdf"``, ``"eps"``, ``"svg"``, ``"png"``,
+        ``"jpeg"`` (``"jpg"``), ``"jxl"`` or ``"avif"``.
+
+        ``options`` are :meth:`vec_io.Document.write`'s (option objects or dicts of their
+        fields: ``flatten``, ``images``, ``png``, ``jpeg``, ``jxl``, ``avif``; and
+        ``compression``, ``font_hinting``, …) but its ``view`` and ``pages``, vec_io
+        ``Document`` arguments (``title``, ``creation_date``, …; ``title`` by default the plain
+        text of the main title, else of the one plot's title; ``None``: none), and plot_io's:
+        ``dpi`` (dots per inch, or ``"2x"``: images rendered at it; PDF, EPS and SVG images
+        resampled to it), ``default_dpi`` (images without ``dpi``; default the figure's),
+        ``background`` (images: in place of the figure's; ``None``: transparent),
+        ``quality`` (the figure's by default; into ``images`` or the image format's option
+        unless it sets its own), ``simplify`` (the figure's for this output) and ``fonts``
+        (a vec_io ``Fonts`` or a dict; default the figure's).  ``region``: a genome region
+        drawn instead of the x axes' ``region`` (the data are read for it).
+        """
+        from . import render
+        with self._region(region):
+            return render.write(self, format, **options)
+
+    def _repr_mimebundle_(self, include: Any = None, exclude: Any = None) -> dict[str, str]:
+        """The figure as SVG for notebooks (``image/svg+xml`` only)."""
+        from . import render
+        return render.repr_svg(self, None, include, exclude)