plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/helpers/clustermap.py

@@ -0,0 +1,202 @@
+"""Clustered heatmaps: a matrix with its rows and columns in the leaf order of their
+clustering trees, the dendrograms beside it, and annotation strips between them."""
+
+import array
+import math
+from typing import Any
+
+from .. import Figure, kernels
+from .grids import _split
+from .tree import Tree, _frame, linkage
+
+__all__ = ["clustermap", "ClusterMap"]
+
+_SIDES = ("right", "left", "top", "bottom")
+
+
+class ClusterMap:
+    """A clustered heatmap (``plt.clustermap``): ``heatmap`` (the series) on ``plot``,
+    ``row_tree`` and ``col_tree`` (``None`` when not clustered), ``row_order`` and
+    ``col_order`` (the matrix's row and column indices, top to bottom and left to right),
+    ``row_dendrogram`` and ``col_dendrogram`` (series or ``None``), ``row_colors`` and
+    ``col_colors`` (the strips' series or ``None``), ``colorbar`` (the heatmap's colorbar,
+    a :class:`~plot_io.colorbar.FigureColorbar` whose ``.set`` changes its label, ticks or
+    side; ``None`` with ``colorbar=None``)."""
+
+    def __init__(self, figure: Figure) -> None:
+        self.figure = figure
+        self.heatmap: Any = None
+        self.plot: Any = None
+        self.row_tree: Tree | None = None
+        self.col_tree: Tree | None = None
+        self.row_order: list[int] = []
+        self.col_order: list[int] = []
+        self.row_dendrogram: Any = None
+        self.col_dendrogram: Any = None
+        self.row_colors: Any = None
+        self.col_colors: Any = None
+        self.colorbar: Any = None
+
+    def __repr__(self) -> str:
+        return f"ClusterMap({len(self.row_order)} × {len(self.col_order)})"
+
+
+def _matrix(values: Any) -> list[array.array]:
+    g = kernels.grid(values)
+    if g is not None:
+        h, w, flat = g[0], g[1], g[3]
+        return [array.array("d", flat[i * w:(i + 1) * w]) for i in range(h)]
+    rows = [kernels.doubles(r) for r in values]
+    if rows and any(len(r) != len(rows[0]) for r in rows):
+        raise ValueError("clustermap: rows of different lengths")
+    return rows
+
+
+def _scaled(m: list[array.array], axis: str, how: str) -> list[array.array]:
+    """``how="z"``: z-scores (sample standard deviation); ``"01"``: (v − min) / (max −
+    min); of each row (``axis="rows"``) or column."""
+    if axis == "cols":
+        w = len(m[0]) if m else 0
+        cols = _scaled([array.array("d", (r[j] for r in m)) for j in range(w)], "rows", how)
+        return [array.array("d", (c[i] for c in cols)) for i in range(len(m))]
+    out = []
+    for r in m:
+        v = [x for x in r if not math.isnan(x)]
+        if how == "z":
+            mean = sum(v) / len(v) if v else 0.0
+            sd = math.sqrt(sum((x - mean) ** 2 for x in v) / (len(v) - 1)) if len(v) > 1 else 0.0
+            a, b = mean, sd
+        else:
+            a = min(v) if v else 0.0
+            b = (max(v) - a) if v else 0.0
+        out.append(array.array("d", (((x - a) / b if b else math.nan) for x in r)))
+    return out
+
+
+def _axis_value(name: str, v: Any) -> Any:
+    if v not in (None, "rows", "cols"):
+        raise ValueError(f"clustermap: {name} is 'rows', 'cols' or None, got {v!r}")
+    return v
+
+
+def _tree(given: Any, m: list[array.array], axis: str, labels: list[str], method: str,
+          metric: str) -> Tree | None:
+    if given is False or given is None:
+        return None
+    if given is True:
+        return linkage(m, method=method, metric=metric, axis=axis, labels=labels)
+    t = given if isinstance(given, Tree) else Tree(given)
+    if t.n != len(labels):
+        raise ValueError(f"clustermap: a tree of {t.n} leaves for {len(labels)} {axis}")
+    return t
+
+
+def _hidden(plot: Any) -> Any:
+    plot.x_axis(visible=False)
+    plot.y_axis(visible=False)
+    return plot
+
+
+def clustermap(matrix: Any, x: Any = None, y: Any = None, method: str = "average",
+               metric: str = "euclidean", rows: Any = True, cols: Any = True,
+               scale: Any = None, standard_scale: Any = None, row_colors: Any = None,
+               col_colors: Any = None, tree_size: Any = "15%", colorbar: Any = "right",
+               **heatmap_settings: Any) -> tuple[Figure, ClusterMap]:
+    """A heatmap of ``matrix`` (rows first: a 2-D buffer, a sequence of rows or a data
+    frame, whose index and columns name them) with its rows and columns in the leaf order
+    of their trees (``rows``, ``cols``: ``True`` clusters them with ``method`` and
+    ``metric``, as ``plt.linkage``; a :class:`Tree` or a scipy ``Z``; ``False`` keeps the
+    order), the dendrograms left and top, ``tree_size`` wide.  ``x``, ``y``: the column and
+    row labels (default: the frame's, else the indices).  ``scale``: z-scores of each row
+    (``"rows"``) or column (``"cols"``); ``standard_scale``: each scaled to 0…1; both before
+    clustering and drawing.  ``row_colors``, ``col_colors``: an annotation strip between
+    the dendrogram and the heatmap, one value per row (column): colours drawn as given, or
+    categories as levels (one colour each, in the legend).  ``colorbar``: its side, or
+    ``None`` (it is ``ClusterMap.colorbar``).  ``heatmap_settings`` go to the heatmap (the
+    figure's to the figure; default 480 × 480 px).  Returns the figure and its :class:`ClusterMap`.
+
+    Example::
+
+        rng = random.Random(1)
+        matrix = [[rng.gauss(r % 3, 1) + c % 2 for c in range(8)] for r in range(12)]
+        fig, cm = plt.clustermap(matrix, width=260, height=240)
+    """
+    if scale is not None and standard_scale is not None:
+        raise ValueError("clustermap: give scale or standard_scale, not both")
+    _axis_value("scale", scale)
+    _axis_value("standard_scale", standard_scale)
+    if colorbar not in (None, False) and colorbar not in _SIDES:
+        raise ValueError(f"colorbar is None or one of {', '.join(map(repr, _SIDES))}")
+    values, row_names, col_names = _frame(matrix)
+    m = _matrix(values)
+    if not m or not m[0]:
+        raise ValueError("clustermap: an empty matrix")
+    nr, nc = len(m), len(m[0])
+    ylab = [str(v) for v in (y if y is not None else row_names or range(nr))]
+    xlab = [str(v) for v in (x if x is not None else col_names or range(nc))]
+    if len(ylab) != nr or len(xlab) != nc:
+        raise ValueError(f"clustermap: {len(ylab)} row and {len(xlab)} column labels for a "
+                         f"{nr} × {nc} matrix")
+    if scale is not None:
+        m = _scaled(m, scale, "z")
+    elif standard_scale is not None:
+        m = _scaled(m, standard_scale, "01")
+    fig_kw = _split("heatmap", heatmap_settings)
+    fig_kw.setdefault("reference", "figure")
+    sized = [k for k in ("width", "height") if k in fig_kw]
+    if not sized:
+        fig_kw["width"] = fig_kw["height"] = 480
+    elif len(sized) == 1:
+        fig_kw.setdefault("aspect_ratio", 1)
+    for k, v in (("share_legend", "all"), ("spacing", 2)):
+        fig_kw.setdefault(k, v)
+    rt = _tree(rows, m, "rows", ylab, method, metric)
+    ct = _tree(cols, m, "cols", xlab, method, metric)
+    left = (["rt"] if rt else []) + (["rc"] if row_colors is not None else [])
+    above = (["ct"] if ct else []) + (["cc"] if col_colors is not None else [])
+    strip = "1em"
+    widths = [tree_size if k == "rt" else strip for k in left] + [1]
+    heights = [tree_size if k == "ct" else strip for k in above] + [1]
+    grid = [[0] * len(left) + [k] for k in above] + [left + ["hm"]]
+    fig = Figure(layout=grid, widths=widths, heights=heights, **fig_kw)
+    cm = ClusterMap(fig)
+    cm.row_tree, cm.col_tree = rt, ct
+    cm.row_order = list(rt.leaves) if rt else list(range(nr))
+    cm.col_order = list(ct.leaves) if ct else list(range(nc))
+    ro, co = cm.row_order, cm.col_order
+    hm = cm.plot = fig.plot("hm")
+    hm.y_axis(side="right")
+    heatmap_settings.setdefault("origin", "top")
+    cm.heatmap = hm.heatmap([[r[j] for j in co] for r in (m[i] for i in ro)],
+                            x=[xlab[j] for j in co], y=[ylab[i] for i in ro],
+                            **heatmap_settings)
+    if rt:
+        p = _hidden(fig.plot("rt", share_y=hm, spines="none"))
+        cm.row_dendrogram = p.dendrogram(rt, labels=ylab, orientation="horizontal")
+    if ct:
+        p = _hidden(fig.plot("ct", share_x=hm, spines="none"))
+        cm.col_dendrogram = p.dendrogram(ct, labels=xlab)
+    bar = {"width": "100%", "fill_opacity": 1, "edge_width": 0}
+    if row_colors is not None:
+        p = _hidden(fig.plot("rc", share_y=hm, spines="none"))
+        p.x_axis(limits="0/1", padding=0)
+        cm.row_colors = p.bar([ylab[i] for i in ro], [1.0] * nr,
+                              orientation="horizontal",
+                              **_strip(row_colors, ro, "row_colors"), **bar)
+    if col_colors is not None:
+        p = _hidden(fig.plot("cc", share_x=hm, spines="none"))
+        p.y_axis(limits="0/1", padding=0)
+        cm.col_colors = p.bar([xlab[j] for j in co], [1.0] * nc,
+                              **_strip(col_colors, co, "col_colors"), **bar)
+    if colorbar:
+        cm.colorbar = fig.add_colorbar(cm.heatmap, plots=[hm], side=colorbar)
+    return fig, cm
+
+
+def _strip(values: Any, order: list[int], name: str) -> dict[str, Any]:
+    """A strip's ``color`` in the drawn order; categories keep their order of appearance
+    in the matrix (``level_order``)."""
+    v = values.tolist() if hasattr(values, "tolist") else list(values)
+    if len(v) != len(order):
+        raise ValueError(f"clustermap: {len(v)} {name} for {len(order)}")
+    return {"color": [v[i] for i in order], "level_order": list(dict.fromkeys(v))}

plot_io/helpers/dendrogram.py

@@ -0,0 +1,172 @@
+"""Dendrograms: the merges of a :class:`~plot_io.helpers.tree.Tree` as U-shaped links."""
+
+import array
+from typing import Any
+
+from .. import ext
+from .._methods import DendrogramMixin
+from .tree import Tree
+
+__all__ = ["Dendrogram"]
+
+
+class Dendrogram(DendrogramMixin, ext.Series):
+    """The merges of ``tree`` (a :class:`Tree`, or a scipy ``Z``) as U-shaped links: the
+    leaves at slots 0, 1, … in ``tree.leaves`` order on the leaf axis, the heights on the
+    value axis, the root at the top (``orientation="horizontal"``: at the left, heights
+    along x, the x axis inverted unless set).  ``labels`` (default: the tree's) make the
+    leaf axis categorical, in leaf order, so a heatmap with the same categories shares it;
+    without labels each leaf is ticked with its observation's index.  Every leaf is
+    labelled: turned 90° when the labels do not fit flat, then smaller, down to the axis'
+    ``label_min_size`` (6 pt), and every k-th only below it.
+
+    ``clusters=k`` draws the links inside each of the ``k`` flat clusters in the next
+    plot's colors, the others in ``color`` (default: the text color).  Trees come from
+    :func:`linkage`, or ``plt.Tree(Z, labels=None)`` of a scipy linkage matrix.
+
+    Example::
+
+        rng = random.Random(1)
+        rows = [[rng.gauss(c, 1) for _ in range(4)] for c in (0, 0, 0, 4, 4, 8, 8, 8)]
+        p = plt.Plot(width=240, height=160)
+        p.dendrogram(plt.linkage(rows), labels=list("abcdefgh"), clusters=3)
+    """
+
+    SETTINGS = ext.table(
+        color=ext.Setting(ext.color, doc="Line color; default: the text color."),
+        clusters=ext.Setting(ext.number(lo=1, integer=True),
+                             doc="Cut into this many flat clusters (`Tree.cut`): the links "
+                                 "within each drawn in the plot's next color."),
+        orientation=ext.Setting(ext.one_of("vertical", "horizontal"),
+                                doc="`vertical`: leaves along x, heights on y; `horizontal`: "
+                                    "leaves along y, heights on x."),
+        **ext.common("line_width", "name", "opacity", "z", "text_color"),
+    )
+
+    def __init__(self, tree: Any, labels: Any = None, plot: Any = None,
+                 **settings: Any) -> None:
+        t = tree if isinstance(tree, Tree) else Tree(tree)
+        labels = t.labels if labels is None else list(labels)
+        if labels is not None:
+            if len(labels) != t.n:
+                raise ValueError(f"Dendrogram: {len(labels)} labels for {t.n} leaves")
+            if len(set(labels)) != len(labels):
+                raise ValueError("Dendrogram: labels must differ (they are categories)")
+        #: the tree drawn
+        self.tree = t
+        #: the names of the leaves (``None``: their indices)
+        self.labels = labels
+        super().__init__(plot=plot, **settings)
+
+    def line_color(self, ctx: Any) -> Any:
+        """The color of the links outside the clusters."""
+        c = self.resolve("color")
+        return ctx.color(self.resolve("text_color") if c is None else c)
+
+    def cluster_colors(self, ctx: Any) -> list[Any]:
+        """The links' colors: outside the clusters, then each cluster's."""
+        k = self._clusters()
+        return [self.line_color(ctx)] + (ext.auto_colors(self, ctx)[:k] if k else [])
+
+    def _clusters(self) -> int:
+        k = self.resolve("clusters")
+        return min(int(k), self.tree.n) if k is not None and self.tree.n > 1 else 0
+
+    def _flip(self) -> bool:
+        return self.resolve("orientation") == "horizontal"
+
+    def _groups(self) -> list[list[int]]:
+        """The merges drawn in each color: outside the clusters, then per cluster."""
+        t, k = self.tree, self._clusters()
+        n = t.n
+        if not k:
+            return [list(range(n - 1))]
+        label = t.cut(k=k) + [0] * (n - 1)
+        out: list[list[int]] = [[] for _ in range(k + 1)]
+        for i, r in enumerate(t.merges):
+            a, b = label[int(r[0])], label[int(r[1])]
+            label[n + i] = a if a == b else 0
+            out[label[n + i]].append(i)
+        return out
+
+    def _positions(self, categories: Any) -> list[float]:
+        """Each observation's slot: its leaf's index, or its label's on the axis."""
+        t = self.tree
+        pos = [0.0] * t.n
+        if categories is None or self.labels is None:
+            for i, leaf in enumerate(t.leaves):
+                pos[leaf] = float(i)
+        else:
+            index: dict[Any, float] = {}
+            for i, c in enumerate(categories):
+                index.setdefault(c, float(i))
+            pos = [index.get(c, float("nan")) for c in self.labels]
+        return pos
+
+    def _links(self, pos: list[float], merges: list[int]) -> dict[str, array.array]:
+        """The three segments of each merge in ``merges``: ``x0, x1, y0, y1``."""
+        t = self.tree
+        n = t.n
+        x = pos + [0.0] * (n - 1)
+        h = [0.0] * n + [r[2] for r in t.merges]
+        for i, r in enumerate(t.merges):
+            x[n + i] = (x[int(r[0])] + x[int(r[1])]) / 2
+        out = {k: array.array("d") for k in ("x0", "x1", "y0", "y1")}
+        for i in merges:
+            a, b, top = int(t.merges[i][0]), int(t.merges[i][1]), t.merges[i][2]
+            out["x0"].extend((x[a], x[b], x[a]))
+            out["x1"].extend((x[a], x[b], x[b]))
+            out["y0"].extend((h[a], h[b], top))
+            out["y1"].extend((top, top, top))
+        return out
+
+
+def _tables(s: Dendrogram, b: Any) -> list[Any] | None:
+    if s.tree.n < 2:
+        return None
+    groups = s._groups()
+    role = "y" if s._flip() else "x"
+    seen: dict[str, Any] = {}
+
+    def links(ctx: Any) -> list[dict[str, array.array]]:
+        cats = (ctx.y if role == "y" else ctx.x).categories
+        if seen.get("cats") is not cats:
+            pos = s._positions(cats)
+            seen["cats"], seen["links"] = cats, [s._links(pos, g) for g in groups]
+        return seen["links"]
+
+    def column(k: int, c: str) -> Any:
+        return lambda ctx: links(ctx)[k][c]
+
+    pos = s._positions(None)
+    out = []
+    for k, g in enumerate(groups):
+        t = ext.Table(**s._links(pos, g))
+        if s.labels is not None:
+            for c in ("x0", "x1"):
+                t.lazy[c] = column(k, c)
+        out.append(t)
+    return out
+
+
+def _finish(s: Dendrogram, b: Any) -> None:
+    call, n = b.call, s.tree.n
+    leaf = "y" if s._flip() else "x"
+    call.color_count = s._clusters()
+    call.leaves.add(leaf)
+    if s._flip():
+        call.invert = {"x"}
+    if s.labels is not None:
+        call.cats[leaf] = [s.labels[i] for i in s.tree.leaves]
+        return
+    call.extra[leaf] = array.array("d", [-0.5, n - 0.5])
+    call.exact.add(leaf)
+    call.ticks[leaf] = [(float(i), str(o)) for i, o in enumerate(s.tree.leaves)]
+
+
+Dendrogram.SPEC = ext.Spec(
+    [ext.Lay("segments", ("stroke", {"color": "cluster_colors()", "opacity": True}),
+             table="links", per_set=True, key="first")],
+    tables={"links": _tables}, key={"stroke": "line_color()"}, zero=("y",), finish=_finish)
+
+ext.register("dendrogram", Dendrogram)

plot_io/helpers/grids.py

@@ -0,0 +1,304 @@
+"""Joint plots and pair grids: figures of plots sharing axes, made by one call.
+
+``fig, joint = plt.joint("a", "b", data=df)``: a main plot with marginal distributions on
+top and on the right.  ``fig, pairs = plt.pairs(df)``: every pair of variables, with each
+variable's distribution on the diagonal.  Both own their figure (as ``plt.facet``); level
+aesthetics (``color="group"``) take one colour per level in every panel and one legend.
+"""
+
+import numbers
+from typing import Any
+
+from .. import Figure, ext
+
+__all__ = ["joint", "pairs", "Joint", "Pairs"]
+
+_MAIN = ("scatter", "hexbin", "hist2d", "kde2d", "regression")
+#: kinds drawn by another type's method (``kde`` of x and y is the 2-D density)
+_METHOD = {"kde2d": "kde"}
+_MARGINAL = ("hist", "kde", "box", "violin", "strip")
+_DIAGONAL = ("hist", "kde")
+#: the call keywords marginal and diagonal calls take from the main call
+_SHARED = ("color", "color_map", "level_order", "level_missing")
+
+
+def _is_number(v: Any) -> bool:
+    return isinstance(v, numbers.Real) and not isinstance(v, bool)
+
+
+def _column(data: Any, name: str) -> Any:
+    try:
+        return data[name]
+    except (KeyError, IndexError, TypeError, ValueError):
+        return None
+
+
+def _numeric(values: Any) -> bool:
+    """Whether a column holds numbers (not text, booleans or categories)."""
+    dtype = getattr(values, "dtype", None)
+    if dtype is not None:
+        if callable(getattr(dtype, "is_numeric", None)):          # polars
+            return bool(dtype.is_numeric())
+        kind = getattr(dtype, "kind", None)
+        if kind is not None:
+            return kind in "iuf"
+    first = next((v for v in values if v is not None), None)
+    return _is_number(first)
+
+
+def _color_kind(color: Any, data: Any) -> str | None:
+    """``"levels"`` (a column of categories), ``"plain"`` (one colour), ``"numbers"`` (a
+    column of numbers through a color map) or ``None``."""
+    if color is None:
+        return None
+    if isinstance(color, str):
+        values = _column(data, color) if data is not None else None
+        if values is None:
+            return "plain"
+        return "numbers" if _numeric(values) else "levels"
+    if isinstance(color, tuple) and len(color) in (3, 4) and all(map(_is_number, color)):
+        return "plain"
+    return "numbers" if _numeric(color) else "levels"
+
+
+def _split(kind: str, settings: dict[str, Any]) -> dict[str, Any]:
+    """Take the figure's settings out of ``settings`` (those the plot type lacks)."""
+    from .. import registry
+    own = registry.layers.get(_METHOD.get(kind, kind)).SETTINGS
+    return {k: settings.pop(k) for k in list(settings)
+            if k not in own and k in Figure.SETTINGS}
+
+
+def _shared(settings: dict[str, Any], data: Any) -> tuple[dict[str, Any], bool]:
+    """The keywords the distributions take from the main call, and whether ``color`` maps
+    levels."""
+    kind = _color_kind(settings.get("color"), data)
+    out = {k: settings[k] for k in _SHARED if settings.get(k) is not None}
+    if kind == "numbers":
+        out.pop("color", None)
+    if kind != "levels":
+        out.pop("color_map", None)
+    return out, kind == "levels"
+
+
+def _check(name: str, value: Any, allowed: tuple[str, ...]) -> Any:
+    if value is not None and value != "auto" and value not in allowed:
+        raise ValueError(f"{name} is one of {', '.join(map(repr, allowed))}, 'auto' or None, "
+                         f"got {value!r}")
+    return value
+
+
+def _figure(grid: list[list[Any]], fig_kw: dict[str, Any]) -> Figure:
+    for k, v in (("share_color", "all"), ("share_size", "all"), ("share_legend", "all"),
+                 ("label_outer", True)):
+        fig_kw.setdefault(k, v)
+    return Figure(layout=grid, **fig_kw)
+
+
+class Joint:
+    """A joint plot (``plt.joint``): ``main`` and the marginal plots ``top`` (sharing x)
+    and ``right`` (sharing y); ``series`` (the main call's), ``marginals`` (the marginal
+    calls')."""
+
+    def __init__(self, figure: Figure, x: Any, y: Any, data: Any) -> None:
+        self.figure = figure
+        self.x, self.y, self.data = x, y, data
+        self.main = figure.plot("main")
+        self.top = figure.plot("top", share_x=self.main, legend=False, spines="bottom")
+        self.right = figure.plot("right", share_y=self.main, legend=False, spines="left")
+        self.top.y_axis(visible=False)
+        self.right.x_axis(visible=False)
+        self.series: Any = None
+        self.marginals: list[Any] = []
+
+    def __repr__(self) -> str:
+        return f"Joint({len(self.marginals)} marginal calls)"
+
+    def marginals_call(self, method: str, **settings: Any) -> list[Any]:
+        """``top.<method>(x, …)`` and ``right.<method>(y, …)`` (along y: box, violin and
+        strip vertical, the others ``orientation="horizontal"``); returns both series."""
+        if self.data is not None:
+            settings.setdefault("data", self.data)
+        across = method in ("box", "violin", "strip")
+        out = []
+        for plot, values, flip in ((self.top, self.x, across), (self.right, self.y, not across)):
+            kw = dict(settings)
+            if flip:
+                kw.setdefault("orientation", "horizontal")
+            out.append(getattr(plot, method)(values, **kw))
+        self.marginals += out
+        return out
+
+
+def joint(x: Any, y: Any, data: Any = None, kind: str = "scatter", marginal: Any = "auto",
+          ratio: float = 5, gap: Any = "0.5em", **settings: Any) -> tuple[Figure, Joint]:
+    """A joint plot: ``kind`` (``scatter``, ``hexbin``, ``hist2d``, ``kde2d``,
+    ``regression``) of ``x`` and ``y`` in the main plot, ``marginal`` distributions
+    (``hist``, ``kde``, ``box``, ``violin``, ``strip``, ``None``; ``"auto"``: ``kde`` when
+    ``color`` maps levels, else ``hist``) above it and on its right, ``ratio`` times
+    narrower, ``gap`` apart.  ``settings`` go to the main call (the figure's to the
+    figure); ``color``, ``level_order``, ``level_missing`` and (with levels) ``color_map`` to the
+    marginals too.  ``width`` and ``height`` measure the whole figure (``reference="figure"``).
+    Returns the figure and its :class:`Joint`.
+
+    Example::
+
+        rng = random.Random(1)
+        x = [rng.gauss(0, 1) for _ in range(200)]
+        fig, joint = plt.joint(x, [v + rng.gauss(0, 0.6) for v in x], width=240, height=240)
+    """
+    if kind not in _MAIN:
+        raise ValueError(f"kind is one of {', '.join(map(repr, _MAIN))}, got {kind!r}")
+    _check("marginal", marginal, _MARGINAL)
+    if not _is_number(ratio) or ratio <= 0:
+        raise ValueError(f"ratio is a positive number, got {ratio!r}")
+    fig_kw = _split(kind, settings)
+    fig_kw.setdefault("reference", "figure")
+    fig_kw.setdefault("spacing", gap)
+    fig_kw.setdefault("widths", [ratio, 1])
+    fig_kw.setdefault("heights", [1, ratio])
+    fig = _figure([["top", 0], ["main", "right"]], fig_kw)
+    j = Joint(fig, x, y, data)
+    shared, levels = _shared(settings, data)
+    if data is not None:
+        settings["data"] = data
+    j.series = getattr(j.main, _METHOD.get(kind, kind))(x, y, **settings)
+    if marginal == "auto":
+        marginal = "kde" if levels else "hist"
+    if marginal is not None:
+        j.marginals_call(marginal, **shared)
+    return fig, j
+
+
+class _Cells(ext.PanelSet):
+    """Cells of a pair grid: a call draws each cell's variables (``(x,)`` on the diagonal,
+    ``(x, y)`` elsewhere) before its own arguments."""
+
+    def __init__(self, figure: Figure, data: Any, panels: dict[Any, Any],
+                 names: list[str]) -> None:
+        super().__init__(figure, data, panels)
+        self._names = names
+
+    def part(self, key: Any) -> tuple[str, ...]:
+        """The variables of cell ``key`` (row, column): ``(x,)`` or ``(x, y)``."""
+        i, j = key
+        return (self._names[j],) if i == j else (self._names[j], self._names[i])
+
+    def arguments(self, key: Any, args: tuple, kw: dict[str, Any]) -> tuple[tuple, dict]:
+        return self.part(key) + tuple(args), {**kw, "data": self.data}
+
+
+def _cell_method(name: str) -> Any:
+    def method(self: _Cells, *args: Any, **settings: Any) -> Any:
+        return self.call(name, args, settings)
+    method.__name__ = name
+    method.__qualname__ = f"_Cells.{name}"
+    method.__doc__ = f"``plot.{name}(<the cell's variables>, …)`` on every cell."
+    return method
+
+
+def _cell_methods() -> None:
+    """The plot types on cells take the data arguments from the cell (the typed methods
+    of a panel set require them)."""
+    from .. import registry
+    for name in registry.layers.names():
+        setattr(_Cells, name, _cell_method(name))
+
+
+class Pairs:
+    """A pair grid (``plt.pairs``): ``vars``, and the :class:`~plot_io.facets.PanelSet`\\ s
+    ``lower``, ``upper`` (empty with ``corner``), ``all`` (both) and ``diagonal`` (each
+    diagonal cell's hidden ``twin_y``); keys ``(row, column)``.  ``plot(i, j)``: a cell."""
+
+    def __init__(self, figure: Figure, data: Any, names: list[str], corner: bool) -> None:
+        self.figure = figure
+        self.vars = names
+        n = len(names)
+        plots: dict[tuple[int, int], Any] = {}
+        diag: dict[tuple[int, int], Any] = {}
+        for i in range(n):
+            for j in range(i + 1 if corner else n):
+                p = figure.plot(f"{i},{j}", legend=False if i == j else None)
+                p.x_axis(label=names[j])
+                p.y_axis(label=names[i])
+                plots[i, j] = p
+                if i == j:
+                    t = p.twin_y(legend=False, spines="none")
+                    t.y_axis(visible=False)
+                    diag[i, j] = t
+        if corner:
+            plots[0, 0].y_axis(visible=False)
+        self._plots = plots
+        lower = {k: p for k, p in plots.items() if k[0] > k[1]}
+        upper = {k: p for k, p in plots.items() if k[0] < k[1]}
+        self.lower = _Cells(figure, data, lower, names)
+        self.upper = _Cells(figure, data, upper, names)
+        self.all = _Cells(figure, data, {k: p for k, p in plots.items() if k[0] != k[1]},
+                          names)
+        self.diagonal = _Cells(figure, data, diag, names)
+
+    def __repr__(self) -> str:
+        return f"Pairs({self.vars!r})"
+
+    def plot(self, i: int, j: int) -> Any:
+        """The cell of row ``i`` (y: ``vars[i]``) and column ``j`` (x: ``vars[j]``)."""
+        return self._plots[i, j]
+
+
+def _names(data: Any) -> list[str]:
+    if isinstance(data, dict):
+        return list(data)
+    cols = getattr(data, "columns", None)
+    if cols is not None:
+        return [str(c) for c in cols]
+    names = getattr(getattr(data, "dtype", None), "names", None)
+    if names:
+        return list(names)
+    raise ValueError("pairs needs a dict, a data frame or a structured array")
+
+
+def pairs(data: Any, vars: Any = None, kind: str = "scatter", diagonal: Any = "auto",
+          corner: bool = False, **settings: Any) -> tuple[Figure, Pairs]:
+    """Every pair of the columns ``vars`` of ``data`` (default: its numeric columns but
+    ``color``'s): an n × n grid, row i plotting ``vars[i]`` on y, column j ``vars[j]`` on
+    x, x shared per column and y per row; ``kind`` (``scatter``, ``hexbin``, ``hist2d``,
+    ``kde2d``, ``regression``) off the diagonal, ``diagonal`` (``hist``, ``kde``, ``None``;
+    ``"auto"``: ``kde`` when ``color`` maps levels, else ``hist``) on it, on a hidden
+    ``twin_y`` of each diagonal cell.  ``corner=True``: no upper triangle.  ``settings`` go
+    to the off-diagonal calls (the figure's to the figure); ``color``,
+    ``level_order``, ``level_missing`` and (with levels) ``color_map`` to the diagonal too.  Returns the figure and its
+    :class:`Pairs`.
+
+    Example::
+
+        rng = random.Random(1)
+        a = [rng.gauss(0, 1) for _ in range(80)]
+        data = {"a": a, "b": [v + rng.gauss(0, 0.5) for v in a], "c": [rng.gauss(0, 1) for _ in a]}
+        fig, grid = plt.pairs(data, width=90, height=90)
+    """
+    if kind not in _MAIN:
+        raise ValueError(f"kind is one of {', '.join(map(repr, _MAIN))}, got {kind!r}")
+    _check("diagonal", diagonal, _DIAGONAL)
+    color = settings.get("color")
+    if vars is None:
+        vars = [c for c in _names(data) if c != color and _numeric(_column(data, c))]
+    names = [str(v) for v in vars]
+    if not names:
+        raise ValueError("pairs: no variables (vars=, or numeric columns in data)")
+    fig_kw = _split(kind, settings)
+    n = len(names)
+    grid = [[f"{i},{j}" if j <= i or not corner else 0 for j in range(n)] for i in range(n)]
+    fig_kw.setdefault("share", "grid")
+    fig = _figure(grid, fig_kw)
+    p = Pairs(fig, data, names, corner)
+    shared, levels = _shared(settings, data)
+    if n > 1:
+        (p.lower if corner else p.all).call(_METHOD.get(kind, kind), (), settings)
+    if diagonal == "auto":
+        diagonal = "kde" if levels else "hist"
+    if diagonal is not None:
+        p.diagonal.call(diagonal, (), shared)
+    return fig, p
+
+
+_cell_methods()