plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/titles.py

@@ -0,0 +1,225 @@
+"""Titles: the settings plot titles (:class:`~plot_io.plot.Title`) and figure titles
+(:class:`~plot_io.figure.FigureTitle`) share, and the measure of a title's text block.
+
+A title sits on a ``side`` of what it covers (``top``, ``bottom``, ``left``, ``right``),
+aligned along that side (``align``: ``start``, ``center``, ``end``), rotated by
+``rotation`` (``auto``: 0 on top and bottom, 90 on the left, −90 on the right), ``pad``
+from it, with an optional ``rule`` along its span.  The titles of one side stack from what
+they cover outward (``order``).
+"""
+
+import itertools
+from typing import Any
+
+from . import groups
+from .color.values import color
+from .settings import Setting, Settings, boolean, either, number, one_of, table, text
+from .validators import length, real, typed
+
+__all__ = ["TitleBase", "SIDES", "ALIGNS", "align_of", "rotation_of", "along", "rule_extent",
+           "rule_rect", "Block", "block", "CREATED", "document_title"]
+
+SIDES = ("top", "bottom", "left", "right")
+#: ``align`` of titles, figure legends and colorbars: ``start``, ``center``, ``end``, or an
+#: end by name (``left`` and ``right`` along the top and bottom, ``top`` and ``bottom``
+#: along the left and right).
+ALIGNS = ("start", "center", "end", "left", "right", "top", "bottom")
+_ENDS = {"left": "start", "top": "start", "right": "end", "bottom": "end"}
+#: Creation numbers of figure titles and legends: their creation order in the lanes.
+CREATED = itertools.count()
+
+
+@typed("Literal['auto'] | SupportsFloat")
+def _rotation(v: Any) -> Any:
+    """``"auto"``, or 0, 90 or −90 degrees."""
+    if isinstance(v, str) and v.strip().lower() == "auto":
+        return "auto"
+    x = real(v)
+    if x is not None and x in (0, 90, -90):
+        return int(x)
+    raise ValueError(f"expected 'auto', 0, 90 or -90, got {v!r}")
+
+
+@typed("bool | Literal['inside', 'outside']")
+def _rule(v: Any) -> Any:
+    """``False``, ``True`` (between the title and what it covers, as ``"inside"``) or
+    ``"outside"`` (beyond the title)."""
+    return either(boolean, one_of("inside", "outside"))(v)
+
+
+_UNSET = object()
+
+
+class TitleBase(Settings):
+    """Settings of every title: its text, side, alignment, rotation, place in its side's
+    stack, rule, and text style."""
+
+    SETTINGS = table(
+        text=Setting(text, doc="Title text: a string or rich content; `\\n` starts a line."),
+        side=Setting(one_of(*SIDES), doc="`top`, `bottom`, `left` or `right`."),
+        align=Setting(one_of(*ALIGNS),
+                      doc="Alignment along the side: `start`, `center`, `end`, or an end by "
+                          "name: `left`, `right` on top and bottom, `top`, `bottom` on the "
+                          "left and right; there `start` is where rotated text begins (the "
+                          "bottom at 90, the top at −90 and 0)."),
+        over=Setting(one_of("axes", "plot"),
+                     doc="Span the title is aligned within: the axes, or the axes and the "
+                         "axis labels beside them (the y axis' on top and bottom, the x "
+                         "axis' on the left and right)."),
+        rotation=Setting(_rotation,
+                         doc="`auto`: 0 on top and bottom, 90 on the left (reads upward), "
+                             "−90 on the right (reads downward); or 0, 90, −90."),
+        pad=Setting(length(lo=0, percent="axes_height"),
+                    doc="Gap between the title and what it covers."),
+        order=Setting(number(), doc="Place in its side's stack: lower is nearer; unset: "
+                                    "the main title nearest, then the others in creation "
+                                    "order."),
+        rule=Setting(_rule, doc="A line along the span: `True` or `\"inside\"` between the "
+                                "title and what it covers, `\"outside\"` beyond the title, "
+                                "`False` none."),
+        rule_color=Setting(color, doc="Color of the rule."),
+        rule_width=Setting(length(lo=0), doc="Thickness of the rule."),
+        rule_gap=Setting(length(lo=0, percent="em"), doc="Gap between the rule and the title."),
+        **groups.TextStyle.embed(docs={"font_size": "Font size; default the base font size."}),
+        **groups.Font.embed(only=groups.Font.FACE),
+    )
+
+    def __call__(self, text: Any = _UNSET, **settings: Any) -> Any:
+        """Set the title (``None`` removes it) and its settings."""
+        if text is not _UNSET:
+            settings["text"] = text
+        return self.set(**settings)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.get('text')!r})"
+
+    def rule_place(self) -> str | None:
+        """``"inside"``, ``"outside"`` or ``None`` (no rule, or one of zero width)."""
+        r = self.resolve("rule")
+        if r is False or r is None or not self.resolve("rule_width"):
+            return None
+        return "outside" if r == "outside" else "inside"
+
+
+def rotation_of(title: Any) -> int:
+    """The rotation of ``title`` in degrees (``auto`` resolved by its side)."""
+    r = title.resolve("rotation")
+    if r != "auto":
+        return int(r)
+    return {"left": 90, "right": -90}.get(title.resolve("side"), 0)
+
+
+def align_of(value: str) -> str:
+    """An ``align`` value as ``start``, ``center`` or ``end`` along a side's coordinate
+    (``left`` and ``top``: ``start``)."""
+    return _ENDS.get(value, value)
+
+
+def along(title: Any) -> str:
+    """A title's ``align`` as ``start``, ``center`` or ``end`` from where its text begins:
+    ``top`` and ``bottom`` beside text reading upward (90 on the left or right) are its end
+    and start."""
+    a = title.resolve("align")
+    if a in ("top", "bottom") and title.resolve("side") in ("left", "right") \
+            and rotation_of(title) == 90:
+        return "end" if a == "top" else "start"
+    return align_of(a)
+
+
+def rule_extent(title: Any) -> float:
+    """What a title's rule adds across its side: its width and its gap (0 without one)."""
+    if title.rule_place() is None:
+        return 0.0
+    return title.resolve("rule_width") + title.resolve("rule_gap")
+
+
+def rule_inside(title: Any) -> float:
+    """What an ``"inside"`` rule puts between a title and what it covers (else 0)."""
+    return rule_extent(title) if title.rule_place() == "inside" else 0.0
+
+
+def rule_rect(title: Any, side: str, near: float, across: float, s0: float, s1: float
+              ) -> tuple[float, float, float, float] | None:
+    """The rectangle of a title's rule (``None`` without one): along its span ``s0``–``s1``,
+    for text whose edge facing what it covers is at ``near`` and ``across`` thick across
+    the side; ``inside`` between that edge and what it covers, ``outside`` beyond the
+    text."""
+    place = title.rule_place()
+    if place is None:
+        return None
+    width, gap = title.resolve("rule_width"), title.resolve("rule_gap")
+    sign = -1.0 if side in ("top", "left") else 1.0         # away from what it covers
+    start = near - sign * (width + gap) if place == "inside" else near + sign * (across + gap)
+    end = start + sign * width
+    lo, hi = min(start, end), max(start, end)
+    if side in ("top", "bottom"):
+        return (s0, lo, s1 - s0, hi - lo)
+    return (lo, s0, hi - lo, s1 - s0)
+
+
+class Block:
+    """A title's text measured: its ``lines``, each line's width, ascent and descent, the
+    distance between baselines (``pitch``), and the block's ``width`` and ``height`` in the
+    text's own frame (first line's ascent, the pitches, last line's descent)."""
+
+    __slots__ = ("lines", "widths", "ascents", "descents", "pitch", "width", "height")
+
+    def __init__(self, lines: list[Any], metrics: list[tuple[float, float, float]],
+                 pitch: float) -> None:
+        self.lines = lines
+        self.widths = [m[0] for m in metrics]
+        self.ascents = [m[1] for m in metrics]
+        self.descents = [m[2] for m in metrics]
+        self.pitch = pitch
+        self.width = max(self.widths)
+        self.height = self.ascents[0] + (len(lines) - 1) * pitch + self.descents[-1]
+
+    def top(self, k: int) -> float:
+        """Distance from the block's top to the top of line ``k`` (its frame)."""
+        return self.ascents[0] + k * self.pitch - self.ascents[k]
+
+    def bottom(self, k: int) -> float:
+        """Distance from the bottom of line ``k`` to the block's bottom (its frame)."""
+        n = len(self.lines) - 1
+        return self.descents[-1] + (n - k) * self.pitch - self.descents[k]
+
+
+def block(fonts: Any, content: Any, font: Any) -> Block:
+    """The text block of a title's content (split at ``\\n``, its markup read) in ``font``."""
+    from .rows import lines
+    from .text import line_pitch, measure
+    ls = lines(content, font)
+    if len(ls) == 1:
+        ls = [content]                  # one line: as given (its markup read when shaped)
+    return Block(ls, [measure(fonts, ln, font) for ln in ls],
+                 line_pitch(fonts, font) if len(ls) > 1 else 0.0)
+
+
+def _plain_title(title: Any) -> str | None:
+    """The plain text of ``title`` as drawn (its markup read when ``markup`` is on), line
+    breaks as spaces, runs of spaces collapsed; ``None`` when empty or unset, or when its
+    markup is malformed (drawing it raises the error, naming the setting)."""
+    from . import markup
+    from .text import plain
+    content = title.resolve("text")
+    if content is None:
+        return None
+    if title.resolve("markup"):
+        try:
+            content = markup.parse(content)
+        except ValueError:
+            return None
+    words = plain(content).split()
+    return " ".join(words) or None
+
+
+def document_title(fig: Any, only: Any = None) -> str | None:
+    """The document title of an output of ``fig`` (``only``: one plot of it, alone): the
+    plain text of the figure's main title; for one plot alone, or a figure of one plot
+    without a main title, that plot's title; ``None`` without one."""
+    if only is not None:
+        return _plain_title(only.title)
+    got = _plain_title(fig.title)
+    if got is None and len(fig.plots) == 1:
+        got = _plain_title(fig.plots[0].title)
+    return got

plot_io/transform.py

@@ -0,0 +1,114 @@
+"""Shifting and rescaling a series' coordinates: ``x_origin``, ``x_scale`` and ``x_extent``
+(and ``y_…``) of a series, and the ``origin`` of its axis (for every series on it).  A
+series' values ``v`` on an axis are drawn at ``(v - origin) * scale``; ``x_extent=(lo, hi)``
+sets both so that the series' smallest x is drawn at ``lo`` and its largest at ``hi``.
+Limits, ticks and decorations are in the drawn units."""
+
+import math
+from typing import Any
+
+from .settings import Setting, number
+from .validators import typed
+
+__all__ = ["settings", "settings_both", "affine", "apply", "TRANSFORM_KEYS", "check_origin"]
+
+_ANCHORS = ("center", "start", "end")
+TRANSFORM_KEYS = tuple(f"{r}_{k}" for r in "xy" for k in ("origin", "scale", "extent"))
+
+
+@typed("Literal['center', 'start', 'end'] | SupportsFloat")
+def check_origin(v: Any) -> Any:
+    """A number, or ``"center"``, ``"start"`` or ``"end"``."""
+    if isinstance(v, str) and v.strip().lower() in _ANCHORS:
+        return v.strip().lower()
+    return number()(v)
+
+
+@typed("SupportsFloat")
+def _scale(v: Any) -> float:
+    s = number()(v)
+    if isinstance(s, (int, float)) and s == 0:
+        raise ValueError("expected a non-zero number")
+    return s
+
+
+@typed("str | Sequence[SupportsFloat | str]")
+def _extent(v: Any) -> tuple[float, float]:
+    if isinstance(v, str):
+        parts = v.split("/")
+        if len(parts) != 2:
+            raise ValueError(f"expected 'lo/hi' or [lo, hi], got {v!r}")
+        v = [p.strip() for p in parts]
+    if not isinstance(v, (list, tuple)) or len(v) != 2:
+        raise ValueError(f"expected 'lo/hi' or [lo, hi], got {v!r}")
+    lo, hi = (float(number()(float(x) if isinstance(x, str) else x)) for x in v)
+    if lo == hi:
+        raise ValueError("an extent needs two different values")
+    return lo, hi
+
+
+def settings(role: str) -> dict[str, Setting]:
+    """The three settings of axis ``role`` of a series."""
+    return {
+        f"{role}_origin": Setting(
+            check_origin,
+            doc=f"The {role} value drawn at 0: a number, `\"center\"` (the middle of the "
+                f"series' {role} range), `\"start\"` or `\"end\"` (its smallest or largest "
+                f"{role}); unset: the {role} axis' `origin`. Values are drawn at "
+                f"`({role} − {role}_origin) × {role}_scale`."),
+        f"{role}_scale": Setting(
+            _scale,
+            doc=f"Factor on {role} values after `{role}_origin` (e.g. bp per bin); default 1."),
+        f"{role}_extent": Setting(
+            _extent,
+            doc=f"The span the series' {role} range is drawn over, `\"lo/hi\"` or `[lo, hi]`: "
+                f"its smallest {role} at `lo`, its largest at `hi`; replaces `{role}_origin` "
+                f"and `{role}_scale`."),
+    }
+
+
+def settings_both() -> dict[str, Setting]:
+    """The settings of both axes."""
+    return {**settings("x"), **settings("y")}
+
+
+def affine(item: Any, role: str) -> tuple[float, float] | None:
+    """``(origin, scale)`` of a call (or a decoration) on axis ``role`` (values drawn at
+    ``(v - origin) * scale``), or ``None``: no transform, or a category axis."""
+    series = getattr(item, "series", item)
+    if f"{role}_origin" not in series.SETTINGS or item.categories(role) is not None:
+        return None
+    origin = series.resolve(f"{role}_origin")
+    scale = series.resolve(f"{role}_scale")
+    extent = series.resolve(f"{role}_extent")
+    if origin is None:
+        axis = getattr(series.plot, f"{role}_axis")
+        origin = axis.resolve("origin")
+        if origin in _ANCHORS:                  # of the region, on a genome axis
+            from .genome.series import axis_region
+            region = axis_region(axis) or (item.region_of(role) if hasattr(
+                item, "region_of") else getattr(item, "region", None))
+            if region is not None:
+                from .genome.scale import origin_of
+                origin = origin_of(origin, region)
+    if extent is None and origin is None and scale in (None, 1.0):
+        return None
+    lo = hi = 0.0
+    if extent is not None or origin in _ANCHORS:
+        from .scales import get_scale
+        n, lo, hi = item.extent(role, get_scale("linear"))
+        if not n or not (math.isfinite(lo) and math.isfinite(hi)):
+            return None
+    if extent is not None:
+        e0, e1 = extent
+        if hi == lo:                                   # one value: drawn mid-extent
+            return lo - (e0 + e1) / 2, 1.0
+        s = (e1 - e0) / (hi - lo)
+        return lo - e0 / s, s
+    o = {"center": (lo + hi) / 2, "start": lo, "end": hi}.get(origin, origin)
+    return (0.0 if o is None else float(o)), (1.0 if scale is None else float(scale))
+
+
+def apply(t: tuple[float, float], v: float) -> float:
+    """A value through a transform from :func:`affine`."""
+    return (v - t[0]) * t[1]