plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/layers/context.py

@@ -0,0 +1,87 @@
+"""The drawing context: the canvas, the axes rectangle, the mappers, the plot's trained
+colors, and the x↔y swap of horizontal layers (trained color and size axes are in the render,
+:func:`plot_io.mapped.trained`)."""
+
+import copy
+from typing import Any
+from ..canvas import Canvas
+
+__all__ = ["DrawContext", "Frame"]
+
+
+class Frame:
+    """The mappers of a layer's frame: ``u`` for its x, ``v`` for its y; ``flip``: its x is
+    the plot's y (horizontal layers)."""
+
+    __slots__ = ("u", "v", "flip")
+
+    def __init__(self, u: Any, v: Any, flip: bool) -> None:
+        self.u, self.v, self.flip = u, v, flip
+
+    def page(self, a: Any, b: Any) -> tuple[Any, Any]:
+        """Page ``(x, y)`` of frame page coordinates ``(a, b)`` (along u, along v)."""
+        return (b, a) if self.flip else (a, b)
+
+
+class DrawContext:
+    """What a layer needs while drawing: the canvas (``None`` while laying out), the axes
+    rectangle and mappers, and the plot's colors (``cycle``, which ``"C<n>"`` refer to)."""
+
+    def __init__(self, canvas: Canvas | None, plot: Any, rect: tuple[float, float, float, float],
+                 x: Any, y: Any, cycle: tuple) -> None:
+        self.canvas = canvas
+        self.plot = plot
+        self.rect = rect
+        self.x = x
+        self.y = y
+        x0, y0, x1, y1 = rect
+        self.xmap = x.mapper(x0, x1)
+        self.ymap = y.mapper(y1, y0)
+        self.cycle = cycle
+        self.figure_size = (x1, y1)
+        self.root: "DrawContext" = self       # the plot's context (see for_call)
+        #: page boxes ``(x0, y0, x1, y1)`` point labels keep clear of (an inside legend)
+        self.avoid: list[tuple[float, float, float, float]] = []
+
+    def release(self) -> None:
+        """Drops the plot's caches (styles and lazy columns, with their per-point buffers)
+        once the plot is drawn, before the document is written."""
+        for k in ("_memo", "_lazy"):
+            self.__dict__.pop(k, None)
+
+    def color(self, value: Any) -> Any:
+        from ..color.values import resolve_color
+        from ..units import Fixed
+        if isinstance(value, Fixed):                 # a named color kept as given
+            value = value.in_context(self.plot)
+        return resolve_color(value, self.cycle)
+
+    def for_call(self, call: Any) -> "DrawContext":
+        """This context with mappers that apply the call's ``x_origin``/``x_scale``/
+        ``x_extent`` (and ``y_…``), or with the y mapper of its lane (``call.lane``);
+        itself when it has none.  ``root`` is the plot's context."""
+        from ..transform import affine
+        tx, ty = affine(call, "x"), affine(call, "y")
+        lane = getattr(call, "lane", None)
+        if tx is None and ty is None and lane is None:
+            return self
+        root = self.root
+        c = copy.copy(root)
+        if tx is not None:
+            c.xmap = root.xmap.affine(*tx, "x")
+        if lane is not None:
+            c.ymap = lane(root)
+        elif ty is not None:
+            c.ymap = root.ymap.affine(*ty, "y")
+        return c
+
+    def frame(self, layer: Any) -> Frame:
+        """The mappers of ``layer``'s frame (swapped for a flipped layer)."""
+        if layer.flip:
+            return Frame(self.ymap, self.xmap, True)
+        return Frame(self.xmap, self.ymap, False)
+
+    def state(self, frame_role: str, layer: Any) -> Any:
+        """The axis state of a layer's frame axis (``"x"``: along its u)."""
+        role = layer.frame_role(frame_role)
+        return self.x if role == "x" else self.y

plot_io/layers/core.py

@@ -0,0 +1,446 @@
+"""Layers and calls: what a plot type's call becomes before it is drawn.
+
+A **call** (``p.scatter(…)``, ``plt.Box(…)``) is a model object, a :class:`~plot_io.layers.Series`
+holding data and settings.  Each render turns it into a :class:`Call`: its **layers**, one
+per geom it draws, its legend entries, and what the axes and maps need from it.
+
+A **layer** draws one geom from a table:
+
+* the table holds the output of the call's stat (:mod:`~plot_io.layers.stats`), columns
+  in data units (shared by the layers of one call that draw the same output: a density's
+  fill and its line); a layer's ``stat`` and ``position`` name what made and places it,
+  as labels (its ``repr``), and do not run anything;
+* the layer's ``aes`` maps the geom's channels to columns of the table;
+* positions (``stack``, ``dodge``, ``jitter``, ``swarm``, ``pack``), requested on the
+  tables, add or replace columns once per plot over all its layers
+  (:mod:`~plot_io.layers.positions`);
+* ``paint`` gives the per-item aesthetics (colors, widths, markers), resolved once the
+  the plot's colors and the color maps are trained;
+* ``flip`` swaps x and y for the geom: a horizontal layer is a vertical one drawn with
+  its frame's x on the plot's y axis.
+"""
+
+import math
+from array import array
+from typing import Any, Callable
+
+from vec_io import Path
+
+from .. import kernels
+
+__all__ = ["Table", "Layer", "Call", "Entry", "ROLES", "KEY_GLYPH", "part_values",
+           "draw_part"]
+
+ROLES = ("x", "y")
+
+
+class Table(dict):
+    """Columns of one stat output (names → arrays or lists).  Columns whose values need
+    the placed axes (slot widths in px, swarm offsets) are functions of the drawing
+    context in ``lazy``; :meth:`Layer.columns` resolves them."""
+
+    def __init__(self, *args: Any, **kw: Any) -> None:
+        super().__init__(*args, **kw)
+        self.lazy: dict[str, Callable[[Any], Any]] = {}
+        #: position requests (see :mod:`~plot_io.layers.positions`): ``(group,
+        #: normalize)`` to stack, a ``Dodge`` to share category slots
+        self.stack: Any = None
+        self.dodge: Any = None
+        #: ``id`` of the table a resolved copy was made from (see :meth:`Layer.columns`)
+        self.origin = id(self)
+
+    def __repr__(self) -> str:
+        return f"Table({', '.join(self)})"
+
+
+class Layer:
+    """One geom drawing columns of a table (see the module docstring)."""
+
+    __slots__ = ("geom", "table", "aes", "paint", "flip", "stat", "position", "overlay",
+                 "occupy", "key", "options")
+
+    def __init__(self, geom: Any, table: Table, aes: dict[str, str] | None = None,
+                 paint: Any = None, flip: bool = False, stat: str = "identity",
+                 position: str = "identity", overlay: bool = False, occupy: Any = True,
+                 key: bool = True, **options: Any) -> None:
+        self.geom = geom
+        self.table = table
+        self.aes = aes or {}
+        self.paint = paint
+        self.flip = flip
+        self.stat = stat
+        self.position = position
+        #: drawn after every layer of the plot, outside the axes clip (value labels)
+        self.overlay = overlay
+        #: legend placement: ``True`` (the geom's cells), ``False`` or ``"all"`` (the axes)
+        self.occupy = occupy
+        #: whether the call's legend symbol shows this layer
+        self.key = key
+        self.options = options
+
+    def __repr__(self) -> str:
+        return (f"Layer({self.stat} → {self.position} → {type(self.geom).__name__}"
+                f"{', flipped' if self.flip else ''})")
+
+    def col(self, channel: str) -> Any:
+        """The column a channel of the geom reads (``None`` when the table has none)."""
+        return self.table.get(self.aes.get(channel, channel))
+
+    def has(self, channel: str) -> bool:
+        return self.aes.get(channel, channel) in self.table
+
+    def columns(self, ctx: Any) -> "Layer":
+        """This layer with its lazy columns resolved for ``ctx`` (itself if it has none)."""
+        lazy = self.table.lazy
+        if not lazy:
+            return self
+        cache = ctx.root.__dict__.setdefault("_lazy", {})
+        key = id(self.table)
+        t = cache.get(key)
+        if t is None:
+            t = Table(self.table)
+            t.origin = self.table.origin
+            for name, fn in lazy.items():
+                t[name] = fn(ctx)
+            cache[key] = t
+        out = Layer.__new__(Layer)
+        for k in Layer.__slots__:
+            setattr(out, k, getattr(self, k))
+        out.table = t
+        return out
+
+    def frame_role(self, role: str) -> str:
+        """The geom's axis drawn on the plot's axis ``role``."""
+        if not self.flip:
+            return role
+        return "y" if role == "x" else "x"
+
+    def style(self, ctx: Any) -> Any:
+        """The resolved aesthetics: of a :class:`~plot_io.layers.paint.Paint` (a role), or
+        ``paint`` itself (fixed values)."""
+        p = self.paint
+        resolve = getattr(p, "resolve", None)
+        return resolve(ctx, False) if resolve is not None else (p or {})
+
+    def part(self) -> tuple[str, Any] | None:
+        """This layer's part of a legend symbol: ``(kind, options)`` (``None``: none)."""
+        return self.geom.part(self)
+
+
+# ---------------------------------------------------------------------------
+# Legend symbols as data
+# ---------------------------------------------------------------------------
+
+#: Whether a symbol part's values come from the paint resolved for the legend
+#: (``glyph=True``) or as drawn on the axes.
+KEY_GLYPH = {"marker": True, "line": False, "band": False, "rect": True, "polygon": True,
+             "rule": True, "gradient": True}
+
+
+def part_values(kind: str, p: Any) -> Any:
+    """The values a symbol part draws, from its layer's resolved paint ``p`` (``None``:
+    nothing drawn)."""
+    if kind == "marker":
+        return p.key_values() if p else None
+    p = p or {}
+    if kind == "line":
+        c, lw = p.get("color"), p.get("width")
+        if c is None or not lw:
+            return None
+        return (c, lw, p.get("dash"), p.get("opacity"))
+    if kind == "band":
+        return (p.get("color"), p.get("opacity", 1.0), p.get("edge"), p.get("edge_width"))
+    if kind in ("rect", "polygon"):
+        return (p.get("fill"), p.get("stroke"), p.get("line_width"))
+    if kind == "rule":
+        c = p.get("color")
+        return None if c is None else (c, p.get("width"))
+    if kind == "gradient":
+        from ..colorbar import gradient_stops
+        m = p.get("map")
+        return None if m is None else tuple(gradient_stops(m, 16))
+    raise ValueError(f"unknown symbol part {kind!r}")
+
+
+def draw_part(ctx: Any, kind: str, options: Any, v: Any, x: float, y: float, w: float,
+              h: float) -> None:
+    """Draw one symbol part (values ``v`` of :func:`part_values`) in box ``x, y, w, h``."""
+    if v is None:
+        return
+    from ..color.values import with_alpha
+    from ..shapes import swatch
+    canvas = ctx.canvas
+    o = dict(options)
+    if kind == "marker":
+        marker, size, fill, stroke, lw, opacity = v
+        canvas.draw_markers([x + w / 2], [y + h * o.get("at", 0.5)], marker=marker,
+                            size=min(size, h * o.get("max", 1.1)), fill=fill, stroke=stroke,
+                            stroke_width=lw, opacity=opacity)
+    elif kind == "line":
+        c, lw, dash, opacity = v
+        if o.get("top"):
+            x, y, w, h = swatch(x, y, w, h)
+            cy = y
+        else:
+            cy = y + h / 2
+        kw: dict[str, Any] = {}
+        if dash is not None:
+            kw["stroke_dasharray"] = dash
+        if opacity is not None:
+            kw["opacity"] = opacity
+        canvas.draw_lines([x, x + w], [cy, cy], stroke=c, stroke_width=lw, **kw)
+    elif kind == "band":
+        c, opacity, edge, ew = v
+        if o.get("form") == "band":
+            if c is not None:
+                canvas.fill = with_alpha(c, opacity)
+                canvas.draw_rect(x, y + h * 0.2, w, h * 0.6, stroke=None)
+            return
+        x, y, w, h = swatch(x, y, w, h)
+        if c is not None:
+            canvas.fill = with_alpha(c, opacity)
+            canvas.draw_rect(x, y, w, h, stroke=None)
+        if edge is not None and ew:
+            canvas.stroke = edge
+            canvas.stroke_width = ew
+            canvas.draw_rect(x, y, w, h, fill=None)
+    elif kind in ("rect", "polygon"):
+        fill, stroke, lw = v
+        form = o.get("form")
+        if form == "hexagon":
+            canvas.draw_markers([x + w / 2], [y + h / 2], marker="M0.5 -0.29 L0.5 0.29 L0 "
+                                "0.58 L-0.5 0.29 L-0.5 -0.29 L0 -0.58 Z", size=h * 0.9,
+                                fill=fill, stroke=None)
+            return
+        if form == "fill":
+            if fill is not None:
+                canvas.fill = fill
+                canvas.draw_rect(*swatch(x, y, w, h), stroke=None)
+            return
+        path = Path().rect(*swatch(x, y, w, h))
+        if fill is not None:
+            canvas.draw_path(path, fill=fill, stroke=None)
+        if stroke is not None and (lw is not None if kind == "rect" else lw):
+            canvas.stroke_width = lw
+            canvas.draw_path(path, fill=None, stroke=stroke)
+    elif kind == "gradient":
+        from vec_io import LinearGradient
+        sx, sy, sw, sh = swatch(x, y, w, h)
+        canvas.draw_rect(sx, sy, sw, sh, fill=LinearGradient(sx, 0, sx + sw, 0, list(v)), stroke=None)
+    elif kind == "rule":
+        c, lw = v
+        cx = x + w / 2
+        if o.get("form") == "stem":
+            canvas.draw_lines([cx, cx], [y + h, y + h * 0.35], stroke=c, stroke_width=lw)
+            return
+        canvas.draw_lines([cx, cx], [y, y + h], stroke=c, stroke_width=lw)
+        canvas.draw_segments([cx - 3, cx - 3], [y, y + h], [cx + 3, cx + 3], [y, y + h],
+                             stroke=c, stroke_width=lw)
+
+
+class Entry:
+    """A legend entry of a call: its label and symbol, as data.
+
+    ``symbol``: the parts of the call's key layers (``(kind, options)`` each, see
+    :func:`draw_part`); ``paint``: the paint of each part's layer, resolved to values once
+    per drawing context (:meth:`values`); ``colors``: a paint giving ``(fill, stroke)`` for
+    the legend's simple symbols.  Two entries draw the same symbol when their symbols and
+    values are equal."""
+
+    __slots__ = ("label", "symbol", "paint", "colors")
+
+    def __init__(self, label: Any, symbol: Any, paint: Any, colors: Any = None) -> None:
+        self.label = label
+        self.symbol = symbol
+        self.paint = paint
+        self.colors = colors
+
+    def __repr__(self) -> str:
+        return f"Entry({self.label!r})"
+
+    def values(self, ctx: Any) -> tuple[Any, ...]:
+        """The values each part draws in ``ctx``."""
+        cache = ctx.root.__dict__.setdefault("_entry_values", {})
+        got = cache.get(id(self))
+        if got is None:
+            got = cache[id(self)] = tuple(
+                part_values(kind, p.resolve(ctx, KEY_GLYPH[kind]))
+                for (kind, _), p in zip(self.symbol, self.paint))
+        return got
+
+    def key(self, ctx: Any) -> Any:
+        """What the symbol draws, for comparing entries."""
+        return self.symbol, self.values(ctx)
+
+    # the legend's protocol (decorations have it too)
+
+    def legend_key_at(self, ctx: Any, i: int) -> Any:
+        return self.key(ctx)
+
+    def legend_glyph_at(self, ctx: Any, i: int, x: float, y: float, w: float,
+                        h: float) -> None:
+        for (kind, options), v in zip(self.symbol, self.values(ctx)):
+            draw_part(ctx, kind, options, v, x, y, w, h)
+
+    def legend_colors_at(self, ctx: Any, i: int) -> tuple[Any, Any]:
+        return self.colors.resolve(ctx, True)
+
+
+def _no_room(fonts: Any, role: str) -> list[tuple[float, float, int]]:
+    return []
+
+
+class Call:
+    """A call of a plot type in a render: its layers and what the axes, the color and size
+    maps, the plot's colors and the legend need from it."""
+
+    def __init__(self, series: Any) -> None:
+        self.series = series
+        self.layers: list[Layer] = []
+        #: tables positioned but not drawn as such (histogram sets merged into one layer)
+        self.tables: list[Table] = []
+        self.entries: list[Entry] = []
+        #: the plot's colors taken when the call has no color of its own (0: none)
+        self.color_count = 0
+        #: the colors of a level call (:func:`plot_io.levels.assign`; ``None``: ``color_count``)
+        self.level: Any = None
+        #: ``(axis, values)`` pairs mapped on color and size axes (``values`` may be a
+        #: function, called at training: ``None`` until the axes are placed)
+        self.color_sources: list[tuple[Any, Any]] = []
+        self.size_sources: list[tuple[Any, Any]] = []
+        #: whether the call is drawn on axes (pies are not)
+        self.axes = True
+        #: per plot role: categories (categorical data), values included in the extent
+        #: beyond the layers' columns, an extent replacing the layers' (``f(scale)``),
+        #: values automatic padding does not pass, the column name of the axis title
+        self.cats: dict[str, list[Any]] = {}
+        self.extra: dict[str, Any] = {}
+        self.extent_of: dict[str, Callable[[Any], tuple[int, float, float]]] = {}
+        self.sticky_values: dict[str, list[float]] = {}
+        self.titles: dict[str, Any] = {}
+        #: plot roles that include 0 under ``include_zero="auto"``, that take no
+        #: automatic padding, inverted by default; ``role → tz`` of date data
+        self.zero: set[str] = set()
+        self.exact: set[str] = set()
+        self.invert: set[str] = set()
+        #: plot roles whose ticks are integers (rows and columns of a grid)
+        self.whole: set[str] = set()
+        self.times: dict[str, Any] = {}
+        #: per plot role: the scale the call asks of an axis without one (``"genome"``),
+        #: ticks it gives (``[(value, label)]``: named rows; the axis takes them when every
+        #: call on it gives some), roles whose axis it hides (drawn when any call does not)
+        self.scales: dict[str, str] = {}
+        self.ticks: dict[str, list[tuple[float, Any]]] = {}
+        #: plot roles whose given tick labels are left out where they overlap the last kept
+        self.thin: set[str] = set()
+        #: plot roles whose tick labels are leaf names (dendrograms): all drawn, rotated
+        #: and then smaller before any is left out (the axis' ``label_min_size``)
+        self.leaves: set[str] = set()
+        self.hide: set[str] = set()
+        #: the genome region the call reads (genome series), and per plot role where it
+        #: differs (a square Hi-C matrix: its ``region2`` on y)
+        self.region: Any = None
+        self.regions: dict[str, Any] = {}
+        #: ``lane(ctx) -> Mapper``: the y mapper of a call drawn in a lane of its own
+        #: (interval rows, :mod:`plot_io.genome.lanes`), from the plot's context
+        self.lane: Callable[[Any], Any] | None = None
+        #: ``room(fonts, role)``: value labels drawn past their values (bars)
+        self.room: Callable[[Any, str], list[tuple[float, float, int]]] = _no_room
+        #: ``overhang(fonts, w, h) -> (left, right)``: labels drawn past the axes (pies)
+        self.overhang: Callable[..., tuple[float, float]] | None = None
+        #: ``resolution(ctx) -> key``: for stats binned at the placed axes' resolution
+        #: (hexagon lattices), the key of the binning for the axes of a drawing context;
+        #: when it changes between layout rounds, the stats and the color axes they map
+        #: are computed again (see :mod:`plot_io.layout`)
+        self.resolution: Callable[[Any], Any] | None = None
+        #: steps of the preset that need the plot's positions (layers built from stacked
+        #: values), run after them
+        self.after: list[Callable[[], None]] = []
+
+    def __repr__(self) -> str:
+        return f"Call({self.series!r}, {len(self.layers)} layers)"
+
+    # -- what the axes need --------------------------------------------------------
+
+    def has_axis(self, role: str) -> bool:
+        return True
+
+    def categories(self, role: str) -> list[Any] | None:
+        return self.cats.get(role)
+
+    def extent(self, role: str, scale: Any) -> tuple[int, float, float]:
+        """``(count, low, high)`` of the call's values on axis ``role``, through the axis
+        scale's function: the union of its layers' geom extents and its extra values."""
+        fn = self.extent_of.get(role)
+        if fn is not None:
+            return fn(scale)
+        count, lo, hi = 0, math.inf, -math.inf
+        dropped = 0
+        for layer in self.layers:
+            if not layer.options.get("bounds", True):
+                continue
+            n, a, b = layer.geom.extent(layer, layer.frame_role(role), scale)
+            if n:
+                count += n
+                lo, hi = min(lo, a), max(hi, b)
+            if scale.base is not None:
+                dropped += layer.geom.dropped(layer, layer.frame_role(role), scale)
+        if dropped:
+            from ..spec import warn
+            kind = getattr(self.series, "kind", "series")
+            warn(f"{kind}: {dropped} value{'s' if dropped > 1 else ''} not positive on the "
+                 f"log {role} axis, not drawn", key=("not positive", id(self), role))
+        extra = self.extra.get(role)
+        if extra is not None and len(extra):
+            n, a, b = kernels.extent(extra, scale.function)
+            if n:
+                count += n
+                lo, hi = min(lo, a), max(hi, b)
+        if not count:
+            return 0, math.nan, math.nan
+        return count, lo, hi
+
+    def values(self, role: str) -> Any:
+        """Every value on axis ``role`` (for quantile limits)."""
+        out = array("d")
+        for layer in self.layers:
+            if not layer.options.get("bounds", True):
+                continue
+            v = layer.geom.values(layer, layer.frame_role(role))
+            if v is not None:
+                out.extend(v)
+        extra = self.extra.get(role)
+        if extra is not None:
+            out.extend(extra)
+        return out
+
+    def sticky(self, role: str) -> list[float]:
+        return self.sticky_values.get(role, [])
+
+    def zero_default(self, role: str) -> bool:
+        return role in self.zero
+
+    def zero_padding(self, role: str) -> bool:
+        return role in self.exact
+
+    def inverts(self, role: str) -> bool:
+        return role in self.invert
+
+    def whole_ticks(self, role: str) -> bool:
+        return role in self.whole
+
+    def time_role(self, role: str) -> Any:
+        return self.times.get(role)
+
+    def scale_of(self, role: str) -> str | None:
+        return self.scales.get(role)
+
+    def region_of(self, role: str) -> Any:
+        """The genome region the call reads on axis ``role``."""
+        return self.regions.get(role, self.region)
+
+    def axis_title(self, role: str) -> Any:
+        return self.titles.get(role)
+
+    def label_room(self, fonts: Any, role: str) -> list[tuple[float, float, int]]:
+        return self.room(fonts, role)