plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/guides.py

@@ -0,0 +1,503 @@
+"""Guides (legends, colorbars, size keys) and their places: inside the axes at an anchor
+(``inside=``) or outside on a side (``side=``); the ``legend="…"`` shorthand; one
+:class:`GuideState` per guide while drawing, placed by where it is."""
+
+import math
+from typing import Any
+
+from .occupancy import N
+from .settings import Settings
+from .titles import SIDES, align_of
+
+__all__ = ["ANCHORS", "anchor", "where_of", "placement", "set_place", "anchor_box", "along_at",
+           "GuideState", "marked", "best_anchor", "place_inside"]
+
+#: Places of a guide inside the axes (``inside=``); ``"auto"`` chooses one (a legend may go
+#: outside), ``"best"`` chooses one too (outside only when every place covers a marker).
+ANCHORS = ("auto", "best", "top_right", "top_left", "bottom_right", "bottom_left", "top", "bottom",
+           "center_right", "center_left")
+
+
+def _word(v: Any) -> str:
+    s = str(getattr(v, "value", v)).strip().lower().replace("-", " ")
+    return "_".join(s.replace("_", " ").split())
+
+
+def anchor(v: Any) -> str:
+    s = _word(v)
+    if s not in ANCHORS:
+        raise ValueError(f"expected one of {', '.join(map(repr, ANCHORS))}, got {v!r}")
+    return s
+
+
+def where_of(v: Any) -> dict[str, Any]:
+    """The shorthand of a guide's place (``legend="top"``, ``add_legend("top_left")``) as
+    settings: a side name is ``side=``, a corner, a centre or ``"auto"`` is ``inside=``,
+    ``"none"`` hides it."""
+    s = _word(v)
+    if s in SIDES:
+        return {"side": s}
+    if s in ANCHORS:
+        return {"inside": s}
+    if s == "none":
+        return {"visible": False}
+    raise ValueError(f"expected a side ({', '.join(SIDES)}), a place inside the axes "
+                     f"({', '.join(ANCHORS)}) or 'none', got {v!r}")
+
+
+def placement(guide: Settings, side_first: bool) -> tuple[str, Any]:
+    """``("inside", anchor)`` or ``("side", side)`` of a guide: the one of ``inside`` and
+    ``side`` set on it (setting one unsets the other), else from the style the one not
+    ``None`` (``side_first``: ``side`` when both are)."""
+    if guide.is_set("side"):
+        return "side", guide.resolve("side")
+    if guide.is_set("inside"):
+        return "inside", guide.resolve("inside")
+    side, inside = guide.resolve("side"), guide.resolve("inside")
+    if side is not None and (side_first or inside is None):
+        return "side", side
+    return "inside", inside
+
+
+def set_place(guide: Settings, settings: dict[str, Any]) -> None:
+    """After ``guide.set(**settings)``: ``inside=`` unsets ``side`` and ``side=`` unsets
+    ``inside`` (the one given last wins)."""
+    for given, other in (("inside", "side"), ("side", "inside")):
+        if settings.get(given) is not None and settings.get(other) is None:
+            guide._values.pop(other, None)
+
+
+def along_at(lo: float, hi: float, size: float, align: float) -> float:
+    """Where a box ``size`` long starts along ``lo``–``hi`` aligned at ``align`` (0 the
+    start, 0.5 the centre, 1 the end)."""
+    if align == 0.0:
+        return lo
+    if align == 1.0:
+        return hi - size
+    return (lo + hi - size) / 2
+
+
+def anchor_box(rect: tuple[float, float, float, float], where: str, w: float, h: float,
+               px: float, py: float) -> tuple[float, float]:
+    """Top-left corner of a ``w`` × ``h`` box at anchor ``where`` inside ``rect``, ``px``
+    and ``py`` from its edges (a centre: centred)."""
+    x0, y0, x1, y1 = rect
+    vertical, _, horizontal = where.partition("_")
+    if where in ("top", "bottom", "center"):
+        vertical, horizontal = where, "center"
+    x = {"left": x0 + px, "right": x1 - px - w, "center": (x0 + x1 - w) / 2}[horizontal]
+    y = {"top": y0 + py, "bottom": y1 - py - h, "center": (y0 + y1 - h) / 2}[vertical]
+    return x, y
+
+
+
+
+# ---------------------------------------------------------------------------
+# Inside the axes: the occupancy grid
+# ---------------------------------------------------------------------------
+
+#: Inside candidates of ``inside="auto"`` and ``"best"``, in order of preference (ties go to the first).
+CANDIDATES = ("top_right", "top_left", "bottom_left", "bottom_right", "top", "bottom",
+              "center_right", "center_left")
+#: Inside candidates of ``"best"``: matplotlib's ``loc="best"`` places, in its order.
+BEST_CANDIDATES = ("top_right", "top_left", "bottom_left", "bottom_right", "center_right",
+                   "center_left", "bottom", "top", "center")
+#: An inside place covering no marker but other drawn cells is taken when it covers at most
+#: this fraction of them (else ``"auto"`` puts the legend outside right).
+OUTSIDE_THRESHOLD = 0.02
+#: The anchors chosen when drawing (the others are fixed places).
+CHOSEN = ("auto", "best")
+
+
+def _drawn(ps: Any, ctx: Any, fonts: Any = None) -> Any:
+    """The occupancy grid of what a plot and its twins draw on the placed axes (``ctx``):
+    series, the row label inside the axes, and with ``fonts`` decorations."""
+    from .layers.context import DrawContext
+    from .occupancy import Occupancy
+    from .rows import occupy_label
+    from .states import occupy
+    occ = Occupancy(ctx.rect)
+    contexts = [(ps, ctx)] + [(t, DrawContext(ctx.canvas, t.plot, ctx.rect, t.x, t.y,
+                                              t.cycle)) for t in getattr(ps, "twins", [])]
+    for st, c in contexts:
+        for call in st.calls:
+            occupy(call, c, occ)
+    occupy_label(ps.plot, ctx, occ)
+    if fonts is not None:
+        for st, c in contexts:
+            for d in st.plot.decorations:
+                d.occupy(fonts, c, occ)
+    return occ
+
+
+def marked(ps: Any, ctx: Any, fonts: Any = None) -> Any:
+    """The occupancy grid a plot's legend chooses on: what is drawn (:func:`_drawn`) and
+    its colorbars inside the axes (placed in order with ``fonts``, else where last
+    placed)."""
+    occ = _drawn(ps, ctx, fonts)
+    if fonts is not None:
+        place_inside(ps, fonts, ctx, occ)
+    else:
+        for b in ps.bars:
+            if b.inside is not None and b.inside_box is not None:
+                occ.rects(*([v] for v in b.inside_box), solid=True)
+    return occ
+
+
+def best_anchor(occ: Any, rect: tuple, w: float, h: float, px: float, py: float,
+                candidates: tuple[str, ...] = CANDIDATES) -> tuple[str, float]:
+    """The first of ``candidates`` where a ``w`` × ``h`` box covers no marked cell and
+    meets no marker, text or inside guide, else the one covering the fewest (the first of
+    equals); with the fraction it covers (a box meeting one in no marked cell: one
+    cell's)."""
+    best, best_f = candidates[0], math.inf
+    for pos in candidates:
+        box = (*anchor_box(rect, pos, w, h, px, py), w, h)
+        f = occ.covered(*box)
+        if f == 0.0:
+            if not occ.solid_in(*box):
+                return pos, 0.0
+            f = 1.0 / (N * N)
+        if f < best_f - 1e-12:
+            best, best_f = pos, f
+    return best, best_f
+
+
+def place_inside(ps: Any, fonts: Any, ctx: Any, occ: Any = None) -> list[Any]:
+    """The geometries of a plot's colorbars inside its axes, in order; ``"auto"`` ones
+    choose on the occupancy grid ``occ`` (default: :func:`marked` without them), each
+    marking it once placed."""
+    bars = [b for b in ps.bars if b.inside is not None]
+    if not bars:
+        return []
+    if occ is None and any(b.inside in CHOSEN for b in bars):
+        occ = _drawn(ps, ctx, fonts)
+    out = []
+    for b in bars:
+        out.append(b.place(fonts, ctx.rect, occ=occ))
+        if occ is not None and b.inside_box is not None:
+            occ.rects(*([v] for v in b.inside_box), solid=True)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# The guide state
+# ---------------------------------------------------------------------------
+
+#: What a :class:`GuideState` holds itself (the rest is its content's).
+_OWN = frozenset({"content", "spot", "choice", "free", "moved", "inside_box"})
+
+
+class GuideState:
+    """A guide while drawing: its content and its place.
+
+    ``content``: what it shows and how it lays that out, its attributes read through the
+    guide: a legend's entries and size keys (:class:`plot_io.legend.Entries`), a colorbar
+    or size key (:class:`plot_io.colorbar.Bar`), or a size legend's rows
+    (:class:`plot_io.legend.SizeRows`).
+
+    ``spot``, its place in the one vocabulary: ``("inside", anchor)`` inside its plot's
+    axes (``"auto"`` included), ``("side", side)`` in a band on a side of its plot,
+    ``("lanes", side)`` in the lanes beside a set of plots, ``("area", None)`` in its own
+    grid area.  :meth:`measure` and :meth:`place` lay the content out for it."""
+
+    def __init__(self, content: Any, spot: tuple[str, Any]) -> None:
+        self.content = content
+        self.spot = spot
+        #: ``inside="auto"``: the anchor chosen once the axes are placed
+        self.choice: str | None = None
+        #: ``"inside"`` (a free place, not an anchor): where, as fractions of the room
+        self.free: tuple[float, float] = (0.0, 0.0)
+        #: an inside legend larger than its axes, drawn on their right side instead
+        self.moved = False
+        #: inside the axes: its box where last placed
+        self.inside_box: tuple[float, float, float, float] | None = None
+        content.guide = self
+
+    def __getattr__(self, name: str) -> Any:
+        if name == "content":
+            raise AttributeError(name)
+        return getattr(self.content, name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name not in _OWN:
+            raise AttributeError(f"GuideState.{name}: set on its content")
+        object.__setattr__(self, name, value)
+
+    @classmethod
+    def for_plot(cls, ps: Any) -> "GuideState":
+        """A plot's legend (a twin's: empty, its main plot's shows its entries)."""
+        from .legend import Entries
+        return cls(Entries.of_plot(ps), ps.plot.legend.placement())
+
+    @classmethod
+    def for_figure_legend(cls, legend: Any, states: list[Any]) -> "GuideState":
+        """A figure legend (:class:`~plot_io.plot.FigureLegend`) of the plots ``states``."""
+        from .legend import Entries
+        return cls(Entries.merged(legend, states), ("lanes", legend.resolve("side")))
+
+    @classmethod
+    def for_colorbar(cls, cb: Any) -> "GuideState":
+        """A colorbar or size key: attached to its plot, in the lanes, or in its area."""
+        from .colorbar import Bar, own_area
+        kind, where = ("area", None) if own_area(cb) else cb.placement()
+        spot = ("lanes", where) if cb.lanes else (kind, where)
+        return cls(Bar(cb, spot), spot)
+
+    @classmethod
+    def for_size_legend(cls, sl: Any) -> "GuideState":
+        """A size legend in its own area (``figure.size_legend``)."""
+        from .legend import SizeRows
+        return cls(SizeRows(sl), ("area", None))
+
+    @property
+    def inside(self) -> str | None:
+        """Its anchor inside the axes (``"auto"`` included), else ``None``."""
+        kind, where = self.spot
+        return where if kind == "inside" else None
+
+    # -- a legend's place ---------------------------------------------------------------
+
+    def setting(self) -> str:
+        """A legend's place as set: an anchor inside the axes (``"auto"`` included),
+        ``"outside_<side>"``, or ``"none"`` (hidden)."""
+        c = self.content
+        if c.twin or not c.legend.resolve("visible"):
+            return "none"
+        kind, where = self.spot
+        return where if kind == "inside" else "outside_" + where
+
+    def active(self) -> bool:
+        """Whether a legend shows something."""
+        if self.spot[0] == "lanes":
+            return bool(self.content.entries)
+        return bool(self.content.entries) and self.setting() != "none"
+
+    def position(self) -> str:
+        """A legend's place (:meth:`setting`; in the lanes, its side), ``"auto"`` and
+        ``"best"`` replaced by the choice once made and ``"outside_right"`` once moved there
+        (:meth:`fit`)."""
+        if self.spot[0] == "lanes":
+            return self.spot[1]
+        if self.moved:
+            return "outside_right"
+        pos = self.setting()
+        return self.choice if pos in CHOSEN and self.choice else pos
+
+    def horizontal(self) -> bool:
+        """Whether a legend runs along a horizontal side."""
+        if self.spot[0] == "lanes":
+            return self.spot[1] in ("top", "bottom")
+        o = self.content.legend.resolve("orientation")
+        if o == "auto":
+            # The setting, not an ``"auto"`` choice: the box was measured before choosing.
+            return not self.moved and self.setting() in ("top", "bottom", "outside_top",
+                                                         "outside_bottom")
+        return o == "horizontal"
+
+    @property
+    def row_major(self) -> bool:
+        """A legend's entries in rows (side by side, wrapped), not in columns: horizontal,
+        without ``columns`` (in the lanes: on top and bottom, ``columns`` or not)."""
+        if self.spot[0] == "lanes":
+            return self.horizontal()
+        return self.horizontal() and not self.content.legend.is_set("columns")
+
+    def align(self) -> float:
+        """A plot legend outside its axes, along its side: 0 at the start (left, top), 0.5
+        centred, 1 at the end; ``align="auto"``: centred when horizontal on top or
+        bottom, else at the start."""
+        a = self.content.legend.resolve("align")
+        if a == "auto":
+            return 0.5 if self.position() in ("outside_top", "outside_bottom") \
+                and self.horizontal() else 0.0
+        return {"start": 0.0, "center": 0.5, "end": 1.0}[align_of(a)]
+
+    def outside(self) -> str | None:
+        """A plot legend's place when outside its axes, else ``None``."""
+        if self.spot[0] == "lanes":
+            return None
+        pos = self.position()
+        return pos if self.active() and pos.startswith("outside") else None
+
+    def fit(self, fonts: Any, w: float, h: float) -> None:
+        """Inside axes ``w`` × ``h``: the legend measured to wrap within them (into
+        columns, or rows when horizontal); one still larger than them moves outside right
+        (``moved``), with a warning when its place was given."""
+        c = self.content
+        px, py = c.legend.pads()
+        room = max(w - 2 * px, 1.0) if self.row_major else max(h - 2 * py, 1.0)
+        lw, lh = c.measure(fonts, room)
+        if lw <= w - 2 * px + 1e-6 and lh <= h - 2 * py + 1e-6:
+            return
+        self.moved = True
+        if self.setting() not in CHOSEN:
+            from .spec import warn
+            warn(f"the legend ({len(c.entries)} entries) is larger than its axes inside; "
+                 f"drawn outside on the right")
+
+    def choose(self, ctx: Any, outside: bool = True, fonts: Any = None) -> str:
+        """A legend's place for ``"auto"`` and ``"best"``, from the occupancy grid
+        (:func:`marked`: every series of the plot and its twins marks what it draws:
+        points, lines, bars, areas, …; with ``fonts``, the decorations and the colorbars
+        inside the axes too):
+
+        1. the first candidate (``CANDIDATES``; ``"best"``: ``BEST_CANDIDATES``) whose
+           box covers no drawn cell and meets no marker disc, text or inside guide;
+        2. else the free box (one grid cell apart, anywhere inside) nearest to a corner of
+           the axes and meeting none of them (``"inside"``, its place kept as fractions of
+           the free room);
+        3. else the candidate meeting no marker, text or guide and covering the fewest
+           cells, at most ``OUTSIDE_THRESHOLD`` of them (``"best"``: any number of them);
+        4. else ``"outside_right"`` (when ``outside``);
+        5. else the candidate covering the fewest marker cells, then the fewest cells."""
+        c = self.content
+        occ = marked(c.ps, ctx, fonts)
+        w, h = c.size
+        px, py = c.legend.pads()
+        candidates = BEST_CANDIDATES if self.setting() == "best" else CANDIDATES
+        best, best_f = best_anchor(occ, ctx.rect, w, h, px, py, candidates)
+        if best_f == 0.0:
+            return best
+        x0, y0, x1, y1 = ctx.rect
+        def corner(p: tuple[float, float]) -> float:
+            x, y = p
+            return min(x - x0, x1 - x - w) + min(y - y0, y1 - y - h)
+        free = next((p for p in sorted(occ.free_boxes(w, h, px), key=corner)
+                     if not occ.solid_in(*p, w, h)), None)
+        if free is not None:
+            x, y = free
+            room_x, room_y = x1 - x0 - 2 * px - w, y1 - y0 - 2 * py - h
+            self.free = ((x - x0 - px) / room_x if room_x > 0 else 0.0,
+                         (y - y0 - py) / room_y if room_y > 0 else 0.0)
+            return "inside"
+        cover = []                          # (marker cells, cells, order, place)
+        for i, pos in enumerate(candidates):
+            box = (*anchor_box(ctx.rect, pos, w, h, px, py), w, h)
+            cover.append((max(occ.covered(*box, markers=True), float(occ.solid_in(*box))),
+                          occ.covered(*box), i, pos))
+        clean = [(f, i, pos) for m, f, i, pos in cover if m == 0.0 and f <= OUTSIDE_THRESHOLD]
+        if clean:
+            return min(clean)[2]
+        if self.setting() == "best":            # any amount of lines and areas, no marker
+            unmarked = [(f, i, pos) for m, f, i, pos in cover if m == 0.0]
+            if unmarked:
+                return min(unmarked)[2]
+        if outside:
+            return "outside_right"
+        return min(cover)[3]
+
+    def _legend_at(self, ctx: Any, used: dict[str, float] | None = None,
+                   fonts: Any = None) -> tuple[float, float]:
+        """Top-left corner of a plot legend's box: outside, past what the axes and twins
+        take on its side (``used``, px); inside, at its position in the axes."""
+        c = self.content
+        x0, y0, x1, y1 = ctx.rect
+        w, h = c.size
+        px, py = c.legend.pads()
+        pos = self.position()
+        used = used or {}
+        if pos == "outside_right":
+            return x1 + used.get("right", 0.0) + px, along_at(y0, y1, h, self.align())
+        if pos == "outside_left":
+            return x0 - used.get("left", 0.0) - px - w, along_at(y0, y1, h, self.align())
+        if pos == "outside_top":
+            return along_at(x0, x1, w, self.align()), y0 - used.get("top", 0.0) - py - h
+        if pos == "outside_bottom":
+            return along_at(x0, x1, w, self.align()), y1 + used.get("bottom", 0.0) + py
+        if pos in CHOSEN:
+            pos = self.choose(ctx, outside=False, fonts=fonts)
+        if pos == "inside":
+            fx, fy = self.free
+            return (x0 + px + fx * max(0.0, x1 - x0 - 2 * px - w),
+                    y0 + py + fy * max(0.0, y1 - y0 - 2 * py - h))
+        return anchor_box(ctx.rect, pos, w, h, px, py)
+
+    def _room(self, pos: str, w: float, h: float) -> float | None:
+        """The length an outside plot legend wraps within along its side: the axes height
+        on the left and right (entries in columns), the axes width on top and bottom
+        (entries in rows), or in a figure of given size the plot's box along that side
+        when longer (the legend passes the axes' ends into the box's margins rather than
+        widening and taking the axes' room); ``None`` elsewhere."""
+        bw, bh = self.content.ps.box_room
+        if pos in ("outside_right", "outside_left") and not self.row_major:
+            return h if bh is None else max(h, bh)
+        if pos in ("outside_top", "outside_bottom") and self.row_major:
+            return w if bw is None else max(w, bw)
+        return None
+
+    # -- measure and place, by spot -------------------------------------------------------
+
+    def measure(self, fonts: Any, w: float, h: float, placed: bool = True) -> Any:
+        """The content laid out for its place, ``w`` × ``h`` the room: the axes (inside,
+        side), its area, or in the lanes the length of its span along them (``placed``:
+        once the areas are placed; before, a legend there does not wrap).  Returns:
+
+        * a legend: its size (inside its axes: wrapped within them, or moved: :meth:`fit`);
+        * a colorbar: inside, its box's size; on a side, its band (pad included); in the
+          lanes, its lane's thickness (pad included); in its area, its margins;
+        * a size legend: its margins."""
+        c = self.content
+        kind = self.spot[0]
+        if c.form == "entries":
+            if kind == "lanes":
+                return c.measure(fonts, w if placed and self.row_major else None)
+            if self.active() and not self.position().startswith("outside"):
+                from .spec import set_boxes
+                set_boxes(c.ps.plot, axes_width=w, axes_height=h)
+                self.fit(fonts, w, h)
+            pos = self.position()
+            if not self.active() or pos.startswith("outside"):
+                c.measure(fonts, self._room(pos, w, h))
+            return c.size
+        if kind == "area":
+            return c.measure_area(fonts, w, h)
+        if kind == "side":
+            return c.measure_attached(fonts, w, h)
+        if kind == "inside":
+            return c.inside_size(fonts, w, h)[:2]
+        return c.lane_pad() + c.lane_extent(fonts, w)
+
+    def place(self, fonts: Any, rect: tuple[float, float, float, float], *, ctx: Any = None,
+              offsets: dict[str, float] | None = None, occ: Any = None,
+              span: tuple[float, float] | None = None, line: float | None = None) -> Any:
+        """The content's geometry at its place; ``rect``:
+
+        * inside and on a side: its plot's axes; a legend chooses ``"auto"`` in ``ctx``
+          (their drawing context), a colorbar on the occupancy grid ``occ``; ``offsets``:
+          by side, where its band starts past the axes; keys sharing a line: ``span``,
+          a key's place along the side, and ``line``, how far the line's middle line is
+          from where it starts;
+        * in the lanes: a legend's box; a colorbar's near edge across its side, its span
+          along it (``(near, s0, near, s1)`` on the left and right, ``(s0, near, s1,
+          near)`` on top and bottom);
+        * in its area: the area's axes.
+
+        A legend showing nothing: ``None``."""
+        c = self.content
+        kind, where = self.spot
+        if c.form == "entries":
+            if kind == "lanes":
+                return c.place_at(fonts, rect[0], rect[1])
+            if not self.active() or not c.size[0]:
+                return None
+            return c.place_at(fonts, *self._legend_at(ctx, offsets, fonts))
+        if kind == "area":
+            return c.place_area(fonts, rect)
+        if kind == "lanes":
+            if c.side in ("left", "right"):
+                return c.place_lane(fonts, rect[0], rect[1], rect[3])
+            return c.place_lane(fonts, rect[1], rect[0], rect[2])
+        if kind == "side":
+            assert offsets is not None
+            return c.place_attached(fonts, rect, offsets[c.side], span, line)
+
+        def at(w: float, h: float, pad: float) -> tuple[float, float]:
+            anchor = where
+            if anchor in CHOSEN:
+                anchor = best_anchor(occ, rect, w, h, pad, pad, BEST_CANDIDATES
+                                     if anchor == "best" else CANDIDATES)[0]
+            x, y = anchor_box(rect, anchor, w, h, pad, pad)
+            self.inside_box = (x, y, x + w, y + h)
+            return x, y
+        return c.place_inside(fonts, rect, at)

plot_io/helpers/__init__.py

@@ -0,0 +1,17 @@
+"""Plot types and figures built on :mod:`plot_io.ext`: clustering trees and dendrograms
+(:mod:`.tree`, :mod:`.dendrogram`), QQ plots (:mod:`.qq`), rainclouds (:mod:`.raincloud`),
+volcano, MA and Manhattan plots (:mod:`.volcano`), joint plots and pair grids
+(:mod:`.grids`), clustered heatmaps (:mod:`.clustermap`).  Each module imports only
+``plot_io.ext``, ``plot_io.kernels`` and public names."""
+
+from .dendrogram import Dendrogram
+from .qq import QQ
+from .raincloud import Raincloud
+from .tree import Tree, linkage
+from .volcano import Ma, Manhattan, Volcano
+# the figure helpers after every type (pair cells take each type's method)
+from .grids import Joint, Pairs, joint, pairs  # noqa: E402
+from .clustermap import ClusterMap, clustermap  # noqa: E402
+
+__all__ = ["Tree", "linkage", "Dendrogram", "QQ", "Raincloud", "Volcano", "Ma", "Manhattan",
+           "joint", "pairs", "Joint", "Pairs", "clustermap", "ClusterMap"]