plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/states.py

@@ -0,0 +1,216 @@
+"""The render's states of a figure's areas: each plot resolved (calls, cycle, axes and
+their limits, legend, colorbars), before the layout measures and places them."""
+
+from typing import Any
+
+from .axis import AxisState
+from .layers.pipeline import plot_calls, train_colors, z_of
+from .settings import cascade
+
+__all__ = ["PlotState", "build", "occupy", "z_key", "label_content", "offset_content"]
+
+
+def z_key(item: Any) -> float:
+    """Drawing order key of a call or a decoration (see :func:`~plot_io.layers.pipeline.z_of`)."""
+    return z_of(getattr(item, "series", item))
+
+
+def occupy(call: Any, ctx: Any, occ: Any) -> None:
+    """Mark the cells a call's layers cover (legend placement)."""
+    c = ctx.for_call(call)
+    for layer in call.layers:
+        if not layer.occupy or layer.overlay:
+            continue
+        if layer.occupy == "all":
+            x0, y0, x1, y1 = c.rect
+            occ.rects([x0], [y0], [x1], [y1])
+            continue
+        seg = layer.options.get("segment")
+        if seg is None:
+            _occupy(c, layer, occ)
+        else:
+            with seg.scope(c) as cs:
+                _occupy(cs, layer, occ)
+
+
+def _occupy(c: Any, layer: Any, occ: Any) -> None:
+    lay = layer.columns(c)
+    aes = layer.options.get("occupy_aes")
+    if aes:
+        lay = _with_aes(lay, aes)
+    lay.geom.occupy(c, lay, occ)
+
+
+def _with_aes(layer: Any, aes: dict[str, str]) -> Any:
+    from .layers.core import Layer
+    out = Layer.__new__(Layer)
+    for k in Layer.__slots__:
+        setattr(out, k, getattr(layer, k))
+    out.aes = {**layer.aes, **aes}
+    return out
+
+
+def label_content(state: AxisState) -> Any:
+    """The axis title: its label, or the label it takes from a data column (on a genome
+    axis, the chromosome and unit); ``None`` for ``""`` and under ``hide_title``."""
+    if state.hide_title:
+        return None
+    label = state.axis.resolve("label")
+    if state.genome:
+        from .genome.scale import axis_label
+        label = axis_label(state, label)
+    label = state.auto_label if label is None else label
+    return None if label == "" else label
+
+
+def offset_content(state: AxisState) -> Any:
+    """What is written at the end of the axis, as its formatter gave it: the common ×10ᵏ
+    factor of the tick labels and the value added to them (``+1×10⁹``), or the common date
+    part of a time axis; ``None`` when there is none."""
+    return state.offset_label
+
+
+class PlotState:
+    """A plot while its figure is drawn."""
+
+    def __init__(self, plot: Any, cycle: Any = None) -> None:
+        self.plot = plot
+        self.x = AxisState(plot.x_axis)
+        self.y = AxisState(plot.y_axis)
+        calls = plot_calls(plot)
+        #: the plot's calls, in drawing order
+        self.calls = sorted(calls, key=z_key)
+        twins = list(getattr(plot, "twins", []))
+        twin_calls = [c for t in twins for c in plot_calls(t)]
+        self.cycle = train_colors(plot, calls, twin_calls, cycle)
+        cycle = self.cycle
+        kinds = {c.axes for c in calls}
+        if len(kinds) > 1:
+            raise ValueError(f"{plot!r} mixes series drawn without axes (pie) and with axes")
+        self.axes_on = plot.resolve("axes") and kinds != {False}
+        decos = list(plot.decorations)
+        self.decorations = decos
+        limit_items = list(calls) + [d for d in decos if d.resolve("extend_limits")]
+        self.limit_items, self.padded = limit_items, self.axes_on
+        for role, st in (("x", self.x), ("y", self.y)):
+            st.auto_label = next((t for t in (c.axis_title(role) for c in calls)
+                                  if t is not None), None)
+        self.twins = [PlotState(t, cycle) for t in twins]
+        self.role_items = {"x": list(limit_items), "y": list(limit_items)}
+        for t in self.twins:                       # a twin shares the other axis
+            shared = "x" if t.plot.twin_of[1] == "y" else "y"
+            self.role_items[shared] += t.limit_items
+        self.x.resolve(self.role_items["x"], self.padded)
+        self.y.resolve(self.role_items["y"], self.padded)
+        #: roles whose axis is not drawn: hidden by every call on it, unless set visible
+        self.hidden: set[str] = set()
+        for role, st in (("x", self.x), ("y", self.y)):
+            on = [c for c in calls if c.has_axis(role)]
+            st.call_leaves = any(role in c.leaves for c in on)
+            if on and all(role in c.ticks for c in on):
+                st.call_ticks = [t for c in on for t in c.ticks[role]]
+                st.call_thin = any(role in c.thin for c in on)
+            if on and all(role in c.hide for c in on) \
+                    and cascade(st.axis, "visible")[2] not in ("own", "figure"):
+                self.hidden.add(role)
+        for t in self.twins:
+            shared = "x" if t.plot.twin_of[1] == "y" else "y"
+            mine, theirs = getattr(self, shared), getattr(t, shared)
+            theirs.copy_limits(mine)
+            theirs.shared = mine
+        from .guides import GuideState
+        bars = list(enumerate(GuideState.for_colorbar(cb)
+                              for cb in [*plot.colorbars, *size_keys(plot)]))
+        #: the attached colorbars, each side's from the axes outward (``order``, else
+        #: creation order); those a figure colorbar shows instead are left out (layout)
+        self.bars = [b for _, b in sorted(bars, key=lambda e: (
+            e[0] if e[1].order is None else e[1].order, e[0]))]
+        self.legend = GuideState.for_plot(self)
+        #: in a figure of given width / height, the plot's box width / height as last
+        #: placed (``None``: not given, or not placed yet): an outside legend wraps
+        #: within it (layout)
+        self.box_room: tuple[float | None, float | None] = (None, None)
+        #: the bands last measured (see :func:`plot_io.boxes.measure`), with the row
+        #: label and group bands (:func:`plot_io.rows.bands`)
+        self.bands: Any = None
+        #: the nodes of its box tree with their bands, as last measured (see
+        #: :mod:`plot_io.boxes`)
+        self.tree: list[Any] = []
+
+    def shows(self, role: str) -> bool:
+        """Whether the axis ``role`` is drawn (ticks, labels)."""
+        return role not in self.hidden and getattr(self.plot, f"{role}_axis").resolve("visible")
+
+    def aspect_want(self) -> float | None:
+        """Height / width the axes need for the `data_ratio` (1 without axes), else
+        ``None``."""
+        aspect = self.plot.resolve("data_ratio") or (None if self.axes_on else 1.0)
+        if not aspect:
+            return None
+        dx = abs(self.x.fhi - self.x.flo) or 1.0
+        dy = abs(self.y.fhi - self.y.flo) or 1.0
+        return aspect * dy / dx
+
+    def aspect_rect(self, rect: tuple[float, float, float, float]) -> tuple:
+        want = self.aspect_want()            # h / w
+        if not want:
+            return rect
+        x0, y0, x1, y1 = rect
+        w, h = x1 - x0, y1 - y0
+        if h > w * want:
+            nh = w * want
+            y0 += (h - nh) / 2
+            y1 = y0 + nh
+        else:
+            nw = h / want
+            x0 += (w - nw) / 2
+            x1 = x0 + nw
+        return (x0, y0, x1, y1)
+
+
+def build(fig: Any, areas: list[Any]) -> None:
+    """The areas' states: the color and size axes trained first (:func:`plot_io.mapped.
+    train`), then each plot, colorbar and size legend, then the shared x and y axes."""
+    from .guides import GuideState
+    from .legend import SizeLegend
+    from .mapped import train
+    from .plot import Plot
+    train(fig, areas)
+    for a in areas:
+        if isinstance(a.obj, Plot):
+            a.state = PlotState(a.obj)
+        elif isinstance(a.obj, SizeLegend):
+            a.state = GuideState.for_size_legend(a.obj)
+        else:
+            a.state = GuideState.for_colorbar(a.obj)
+    from .sharing import apply
+    apply(fig, areas)
+
+
+def size_keys(plot: Any) -> list[Any]:
+    """The size keys a plot's series ask for (``size_key="key"`` or a list of values):
+    one per size axis of the plot and its twins, unless a colorbar of the plot or a size
+    legend area (``figure.size_legend``) shows it."""
+    from .colorbar import Colorbar
+    from .legend import SizeLegend
+    from .mapped import _size_key, size_axis_of
+    shown = {id(cb.source) for cb in plot.colorbars if cb.sizes}
+    fig = plot.figure
+    areas = {_size_key(o.size_axis) for o in (fig._areas.values() if fig is not None else ())
+             if isinstance(o, SizeLegend)}
+    areas.discard(None)
+    out = []
+    for p in [plot, *plot.twins]:
+        for s in p.series:
+            v = s.resolve("size_key") if "size_key" in s.SETTINGS else False
+            if v is False or v == "legend":
+                continue
+            axis = size_axis_of(s)
+            if axis is None or id(axis) in shown or (areas and _size_key(axis) in areas):
+                continue
+            shown.add(id(axis))
+            cb = Colorbar(axis, plot=plot)
+            if isinstance(v, list):
+                cb.marks = v
+            out.append(cb)
+    return out

plot_io/styles/__init__.py

@@ -0,0 +1,307 @@
+"""Styles: named presets of settings.
+
+A style is a dict of settings: setting names for inherited settings (``"font_size"``),
+``"Class.name"`` for any setting of a class (``"Axis.grid"``) and ``"Group.member"`` for
+a group (``"Marker.size"``).  The key ``"base"`` names the styles it builds on, one or a
+list (a later base over an earlier one).  Keys starting with ``--`` are custom variables,
+read by ``var(--name)``.
+
+A figure's style chain is its style, then that style's bases (depth first, each once),
+then ``"default"`` (:data:`~plot_io.defaults.DEFAULTS`).  The nearer style wins; within a
+style, the most specific key wins.
+"""
+
+import contextlib
+import contextvars
+import difflib
+from collections.abc import Generator
+from typing import Any
+
+from .. import hints
+from ..defaults import DEFAULTS
+from ..units import given
+from ..settings import ALIASES, BASE_THEME, Setting, Theme, check_value, custom_vars
+
+__all__ = ["add_style", "names", "settings", "set_style", "use_style",
+           "check_style", "effective", "current"]
+
+#: ``"default"``: no keys of its own, as ``DEFAULTS`` ends every chain.
+_STYLES: dict[str, dict[str, Any]] = {"default": {}}
+_version = 0
+_session: Any = None
+#: the styles of the enclosing ``use_style`` blocks of this thread or task
+_stack: contextvars.ContextVar[tuple[Any, ...]] = contextvars.ContextVar("styles", default=())
+
+
+#: Style classes registered by the modules that define them (the genome track preset).
+_REGISTERED: dict[str, Any] = {}
+
+
+def register_class(cls: Any, name: str | None = None) -> None:
+    """Make ``cls`` (a ``Settings`` class) a style class: ``"Name.setting"`` style keys and
+    defaults apply to it.  Plot types added with ``registry.layers.add``
+    are style classes without this."""
+    _REGISTERED[name or cls.__name__] = cls
+
+
+def _classes() -> dict[str, Any]:
+    from ..axis import Axis
+    from ..colorbar import Colorbar, FigureColorbar
+    from ..figure import Figure, FigureTitle, MainTitle
+    from ..plot import FigureLegend, Legend, Plot, Title
+    from .. import decorations as d
+    from ..layers import Series, layer_types
+    out = {"Series": Series, "Decoration": d.Decoration,
+           "Figure": Figure, "FigureTitle": FigureTitle, "MainTitle": MainTitle, "Plot": Plot,
+           "Title": Title,
+           "Legend": Legend, "FigureLegend": FigureLegend, "Axis": Axis, "Colorbar": Colorbar,
+           "FigureColorbar": FigureColorbar}
+    for f in layer_types().values():
+        if isinstance(f, type) and issubclass(f, Series):
+            out[f.__name__] = f
+    out.update({"HLine": d.HLine, "VLine": d.VLine, "AxLine": d.AxLine, "HSpan": d.HSpan,
+                "VSpan": d.VSpan, "Text": d.Text, "Annotate": d.Annotate})
+    from .. import rows
+    out.update({"FigureVLine": rows.FigureVLine, "FigureVSpan": rows.FigureVSpan,
+                "FigureGroup": rows.FigureGroup})
+    out.update(_REGISTERED)
+    return out
+
+
+def _subclass_setting(cls: Any, name: str) -> Setting | None:
+    """Setting ``name`` of ``cls`` or of a subclass (keys of a base class)."""
+    todo = [cls]
+    while todo:
+        c = todo.pop()
+        s = c.SETTINGS.get(name)
+        if s is not None:
+            return s
+        todo.extend(c.__subclasses__())
+    return None
+
+
+def _setting(key: str) -> Setting:
+    """The setting a style key refers to: ``"name"`` (inherited), ``"Class.name"`` (of a
+    class and its subclasses) or ``"Group.member"``."""
+    from ..groups import GROUPS
+    if key.rpartition(".")[2] in ("color_map", "cmap"):
+        from ..color.maps import COLOR_MAP_HINT
+        raise ValueError(f"style key {key!r}: {COLOR_MAP_HINT}")
+    classes = _classes()
+    if "." in key:
+        cls_name, _, name = key.partition(".")
+        group = GROUPS.get(cls_name)
+        if group is not None and cls_name not in classes:
+            if name not in group.MEMBERS:
+                near = difflib.get_close_matches(name, group.MEMBERS, n=1)
+                hint = f" (did you mean {cls_name}.{near[0]}?)" if near else ""
+                raise ValueError(f"unknown member {key!r} in style{hint}")
+            return group.member_setting(name)
+        cls = classes.get(cls_name)
+        if cls_name in ("XAxis", "YAxis"):              # the x or y axis of plots only
+            cls = classes["Axis"]
+        if cls is None:
+            near = difflib.get_close_matches(cls_name, list(classes) + list(GROUPS), n=1)
+            hint = f" (did you mean {near[0]!r}?)" if near else ""
+            raise ValueError(f"unknown class {cls_name!r} in style key {key!r}{hint}")
+        s = _subclass_setting(cls, name)
+        if s is None and cls_name == "Colorbar":         # a setting of colorbar axes only
+            s = classes["Axis"].SETTINGS.get(name)
+        if s is None:
+            use = hints.setting(name, cls.SETTINGS)
+            if use is not None:
+                raise ValueError(f"unknown setting {key!r} in style: use {use}")
+            near = difflib.get_close_matches(name, cls.SETTINGS, n=1)
+            hint = f" (did you mean {cls_name}.{near[0]}?)" if near else ""
+            raise ValueError(f"unknown setting {key!r} in style{hint}")
+        return s
+    names: dict[str, Setting] = {}
+    for cls in classes.values():
+        for n, s in cls.SETTINGS.items():
+            if s.inherited:
+                names.setdefault(n, s)
+    if key not in names:
+        use = hints.setting(key, names)
+        if use is not None:
+            raise ValueError(f"unknown style key {key!r}: use {use}")
+        near = difflib.get_close_matches(key, names, n=1)
+        hint = f" (did you mean {near[0]!r}?)" if near else ""
+        raise ValueError(f"unknown style key {key!r}: not an inherited setting; use "
+                         f"\"Class.{key}\" for a setting of one class{hint}")
+    return names[key]
+
+
+def _bases(v: Any) -> tuple[str, ...]:
+    names = (v,) if isinstance(v, str) else tuple(v)
+    for n in names:
+        if not isinstance(n, str):
+            raise ValueError(f"a style base is a style name, got {n!r}")
+        _get(n)
+    return names
+
+
+def _validate(style: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    given_as: dict[str, str] = {}
+    for key, value in style.items():
+        if key == "base":
+            out["base"] = _bases(value)
+            continue
+        if key.startswith("--"):               # a custom variable, read by var(--name)
+            if value is None or not key[2:]:
+                raise ValueError(f"style key {key!r}: a custom variable needs a name and "
+                                 f"a value")
+            out[key] = value
+            continue
+        cls_part, dot, name = key.rpartition(".")
+        given_key = key
+        if name in ALIASES:
+            key = f"{cls_part}{dot}{ALIASES[name]}"
+        if key in out:
+            raise ValueError(f"style keys {given_as[key]!r} and {given_key!r} are the same "
+                             f"setting; give one")
+        given_as[key] = given_key
+        s = _setting(key)
+        if s.check is custom_vars:
+            raise ValueError(f"style key {key!r}: a style sets custom variables as "
+                             f"\"--name\" keys")
+        if s.name == "style" and s is _classes()["Figure"].SETTINGS["style"]:
+            raise ValueError(f"style key {key!r}: a style builds on others with \"base\"")
+        if value is None:
+            raise ValueError(f"style key {key!r}: None is not a value")
+        try:
+            value = check_value(s, value)
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"style key {key!r}: {e}") from None
+        out[key] = value
+    return out
+
+
+_loaded = False
+
+
+def _load() -> None:
+    """Register the bundled styles (on first use: they refer to every settings class)."""
+    global _loaded
+    if not _loaded:
+        _loaded = True
+        from . import library  # noqa: F401
+
+
+def _get(name: str) -> dict[str, Any]:
+    _load()
+    key = name.strip().lower()
+    if key not in _STYLES:
+        near = difflib.get_close_matches(key, _STYLES, n=1)
+        hint = f" (did you mean {near[0]!r}?)" if near else ""
+        known = ", ".join(repr(n) for n in sorted(_STYLES) if n != "solid")
+        raise ValueError(f"unknown style {name!r}{hint}; the styles: {known}, or a dict")
+    return _STYLES[key]
+
+
+def add_style(name: str, style: dict[str, Any]) -> None:
+    """Register ``style`` (a dict of settings, with an optional ``"base"``) as ``name``."""
+    global _version
+    _load()
+    if name.strip().lower() == "default":
+        raise ValueError('the "default" style is DEFAULTS and cannot be replaced; register '
+                         'a style under another name and set it with set_style')
+    if not isinstance(style, dict):
+        raise ValueError("a style is a dict of settings")
+    key = name.strip().lower()
+    old = _STYLES.get(key)
+    _STYLES[key] = _validate(style)
+    try:
+        chain(key)                              # refuses a cycle of bases
+    except ValueError:
+        if old is None:
+            del _STYLES[key]
+        else:
+            _STYLES[key] = old
+        raise
+    _version += 1
+
+
+def names() -> list[str]:
+    """Names of the registered styles."""
+    _load()
+    return sorted(_STYLES)
+
+
+def check_style(v: Any) -> Any:
+    """Validator of the ``style`` setting: a registered name or a dict."""
+    if isinstance(v, str):
+        _get(v)
+        return v.strip().lower()
+    if isinstance(v, dict):
+        return _validate(v)
+    raise ValueError(f"a style is a style name or a dict of settings, got {v!r}")
+
+
+def chain(style: Any) -> list[tuple[str, dict[str, Any]]]:
+    """The styles of ``style``'s chain other than ``"default"``, nearest first, as
+    ``(label, keys)``."""
+    out: list[tuple[str, dict[str, Any]]] = []
+    done: set[str] = set()
+
+    def walk(st: Any, path: tuple[str, ...], of: str | None) -> None:
+        if isinstance(st, str):
+            key = st.strip().lower()
+            if key in path:
+                raise ValueError(f"style {key!r} is its own base "
+                                 f"({' → '.join(path + (key,))})")
+            if key in done or key == "default":
+                return
+            done.add(key)
+            d, path, name = _get(key), path + (key,), f'"{key}"'
+        else:
+            d, name = check_style(st), "(a dict)"
+        label = name if of is None else f"{name} (base of {of})"
+        out.append((label, {k: v for k, v in d.items() if k != "base"}))
+        for b in reversed(d.get("base", ())):
+            walk(b, path, name)
+
+    walk(style, (), None)
+    return out
+
+
+def settings(style: Any) -> dict[str, Any]:
+    """Every key of ``style``'s chain, ``DEFAULTS`` included, as the nearest style gives
+    it (values as given), to inspect or copy."""
+    out = dict(DEFAULTS)
+    for _, keys in reversed(chain(style)):
+        out.update(keys)
+    return {k: given(v) for k, v in out.items()}
+
+
+def effective(style: Any) -> Theme:
+    """The theme of a figure with ``style`` (``None``: ``DEFAULTS`` only)."""
+    return BASE_THEME if style is None else Theme(chain(style))
+
+
+def version() -> int:
+    """Changes whenever a style is registered (for caches of effective themes)."""
+    _load()
+    return _version
+
+
+def current() -> Any:
+    """The style new figures take: the innermost ``use_style``, else ``set_style``'s."""
+    stack = _stack.get()
+    return stack[-1] if stack else _session
+
+
+def set_style(style: Any) -> None:
+    """Default style of figures created afterwards (``None``: back to ``"default"``)."""
+    global _session
+    _session = None if style is None else check_style(style)
+
+
+@contextlib.contextmanager
+def use_style(style: Any) -> Generator[None]:
+    """Default style of figures created inside the block."""
+    token = _stack.set((*_stack.get(), check_style(style)))
+    try:
+        yield
+    finally:
+        _stack.reset(token)