plot-io 0.1.0__py3-none-any.whl

plot_io/tables.py

@@ -0,0 +1,141 @@
+"""Columns from tables (``data=``) and grouping of series by a column (``group=``).
+
+``data`` is anything that returns a column for ``data[name]``: a dict of sequences, a
+pandas or polars data frame, a numpy structured array.  Columns are read through
+``__getitem__`` and ``to_numpy()`` when present, so no table library is imported.
+
+A call with ``group=labels`` is split into one series per group (a :class:`SeriesGroup`),
+each with the rows of every per-point argument that belong to it.
+"""
+
+import array
+import math
+import warnings
+from typing import Any
+
+__all__ = ["column", "has_column", "SeriesGroup", "MARKER_CYCLE", "LINE_STYLE_CYCLE"]
+
+MARKER_CYCLE = ("circle", "square", "triangle_up", "diamond", "triangle_down", "plus",
+                "cross", "triangle_left", "triangle_right")
+LINE_STYLE_CYCLE = ("solid", "dashed", "dotted", "dashdot")
+
+
+def has_column(data: Any, name: str) -> bool:
+    try:
+        columns = data.columns if hasattr(data, "columns") else None
+        if columns is not None and not callable(columns):
+            return name in list(columns)
+        names = getattr(getattr(data, "dtype", None), "names", None)
+        if names is not None:
+            return name in names
+        if hasattr(data, "keys"):
+            return name in data.keys()
+        data[name]
+        return True
+    except (KeyError, IndexError, TypeError, ValueError):
+        return False
+
+
+def column(data: Any, name: str) -> tuple[Any, list[Any] | None]:
+    """The column ``name`` of ``data`` and, for categorical columns (pandas
+    ``category``), the order of its categories."""
+    if not has_column(data, name):
+        raise ValueError(f"no column {name!r} in data")
+    v = data[name]
+    order = None
+    cat = getattr(v, "cat", None)
+    if cat is not None and hasattr(cat, "categories"):
+        try:
+            order = list(cat.categories)
+        except TypeError:
+            order = None
+    if order is None and hasattr(v, "dtype") and str(getattr(v, "dtype", "")).startswith("Categorical"):
+        try:                                        # polars
+            order = list(v.cat.get_categories())
+        except (AttributeError, TypeError):
+            order = None
+    if hasattr(v, "to_numpy"):
+        v = v.to_numpy()
+    if hasattr(v, "dtype") and getattr(v.dtype, "kind", "") in "OUS":
+        v = v.tolist()
+    return v, order
+
+
+def is_missing(v: Any) -> bool:
+    return v is None or (isinstance(v, float) and math.isnan(v))
+
+
+def take(v: Any, idx: list[int]) -> Any:
+    """The items ``idx`` of a per-point argument."""
+    if isinstance(v, (list, tuple)):
+        return [v[i] for i in idx]
+    try:
+        mv = memoryview(v)
+    except TypeError:
+        mv = None
+    if mv is not None and mv.ndim == 1 and not isinstance(v, (str, bytes)):
+        from . import _backend
+        d = _backend.doubles(v)
+        return array.array("d", (d[i] for i in idx))
+    if mv is not None and mv.ndim == 2:
+        rows: Any = v.tolist() if hasattr(v, "tolist") else mv.tolist()
+        return [tuple(rows[i]) for i in idx]
+    return [v[i] for i in idx]
+
+
+def group_keys(labels: Any, order: list[Any] | None, given: Any, missing: str) -> tuple[
+        list[Any], list[list[int]]]:
+    """Group keys in order and the row indices of each."""
+    keyed: dict[Any, list[int]] = {}
+    for i, lab in enumerate(labels):
+        if is_missing(lab):
+            if missing == "drop":
+                continue
+            lab = "nan"
+        keyed.setdefault(lab, []).append(i)
+    keys = list(keyed)
+    if given is not None:
+        given = list(given)
+        unknown = [k for k in keys if k not in given]
+        keys = [k for k in given if k in keyed] + unknown
+    elif order is not None:
+        keys = [k for k in order if k in keyed] + [k for k in keys if k not in order]
+    return keys, [keyed[k] for k in keys]
+
+
+class SeriesGroup(list):
+    """The series of a call with ``group=``, one per group, in group order.
+
+    ``set(**settings)`` applies to every member; ``group[label]`` is one member (an
+    integer index also works); ``labels`` lists the group labels.
+    """
+
+    def __init__(self, members: list[Any], labels: list[Any], title: Any = None) -> None:
+        super().__init__(members)
+        self.labels = labels
+        self.title = title
+
+    def __getitem__(self, key: Any) -> Any:
+        if isinstance(key, (int, slice)) and not (isinstance(key, int) and key in self.labels):
+            return super().__getitem__(key)
+        try:
+            return super().__getitem__(self.labels.index(key))
+        except ValueError:
+            raise KeyError(key) from None
+
+    def set(self, **settings: Any) -> "SeriesGroup":
+        for s in self:
+            s.set(**settings)
+        return self
+
+    @property
+    def plot(self) -> Any:
+        return self[0].plot if len(self) else None
+
+    def __repr__(self) -> str:
+        return f"SeriesGroup({', '.join(map(repr, self.labels))})"
+
+
+def color_name_warning(name: str) -> None:
+    warnings.warn(f"{name!r} is both a column and a color name; using the column",
+                  stacklevel=4)

plot_io/text.py

@@ -0,0 +1,109 @@
+"""Text: one line of plain or rich content, measured and drawn on a pdf_io canvas.
+
+Rich content is a list of strings and ``pdf_io.Span`` objects.  Exponents are spans with
+``baseline_shift="super"`` and ``font_scale=0.7``.
+"""
+
+import math
+from collections.abc import Iterator
+from typing import Any
+
+from pdf_io import Span
+
+from . import _backend
+
+__all__ = ["superscript", "Font", "measure", "draw_text", "runs_of", "plain"]
+
+_SUPER_SHIFT = 0.33
+_SUPER_SCALE = 0.7
+
+
+def superscript(text: str) -> Any:
+    return Span(text, baseline_shift="super", font_scale=_SUPER_SCALE)
+
+
+def runs_of(content: Any) -> Iterator[tuple[str, float, float]]:
+    """``(text, size factor, baseline shift in em)`` of each run."""
+    if isinstance(content, str):
+        yield content, 1.0, 0.0
+        return
+    for item in content:
+        if isinstance(item, str):
+            yield item, 1.0, 0.0
+        else:
+            shift = getattr(item, "baseline_shift", None)
+            scale = getattr(item, "font_scale", None) or 1.0
+            em = {"super": _SUPER_SHIFT, "sub": -0.2}.get(shift, shift) if shift else 0.0
+            yield item.text, float(scale), float(em or 0.0)
+
+
+def plain(content: Any) -> str:
+    """The text of content, without styles."""
+    return "".join(t for t, _, _ in runs_of(content))
+
+
+class Font:
+    """Font settings applied to a canvas before measuring or drawing."""
+
+    __slots__ = ("size", "family", "weight", "style", "color")
+
+    def __init__(self, size: float, family: str = "sans-serif", weight: str = "normal",
+                 style: str = "normal", color: Any = "black") -> None:
+        self.size = float(size)
+        self.family = family
+        self.weight = weight
+        self.style = style
+        self.color = color
+
+    def apply(self, canvas: Any) -> None:
+        canvas.font_size = self.size
+        canvas.font_family = self.family
+        canvas.font_weight = self.weight
+        canvas.font_style = self.style
+        canvas.fill_style = self.color
+        canvas.text_align = "start"
+
+
+def measure(canvas: Any, content: Any, font: Font) -> tuple[float, float, float]:
+    """``(width, ascent, descent)`` of a line of content."""
+    if content is None or content == "" or content == []:
+        return 0.0, 0.0, 0.0
+    font.apply(canvas)
+    return _backend.text_extent(canvas, content)
+
+
+def box(canvas: Any, content: Any, font: Font, rotation: float = 0.0) -> tuple[float, float]:
+    """Width and height of the bounding box of rotated text (degrees, counterclockwise)."""
+    w, a, d = measure(canvas, content, font)
+    h = a + d
+    if not rotation:
+        return w, h
+    r = math.radians(rotation)
+    c, s = abs(math.cos(r)), abs(math.sin(r))
+    return w * c + h * s, w * s + h * c
+
+
+def _fill(canvas: Any, content: Any, x: float, y: float) -> None:
+    canvas.fill_text(content, x, y)
+
+
+def draw_text(canvas: Any, content: Any, x: float, y: float, font: Font, ha: str = "left",
+              va: str = "baseline", rotation: float = 0.0) -> None:
+    """Draw a line of content anchored at ``(x, y)``: ``ha`` left/center/right, ``va``
+    baseline/top/center/bottom, in the text's own (rotated) frame; ``rotation`` in degrees,
+    counterclockwise."""
+    if content is None or content == "" or content == []:
+        return
+    w, a, d = measure(canvas, content, font)
+    dx = {"left": 0.0, "center": -w / 2, "right": -w}[ha]
+    dy = {"baseline": 0.0, "top": a, "center": (a - d) / 2, "bottom": -d}[va]
+    if not rotation:
+        _fill(canvas, content, x + dx, y + dy)
+        return
+    canvas.save()
+    try:
+        canvas.translate(x, y)
+        canvas.rotate(-rotation)
+        _fill(canvas, content, dx, dy)
+    finally:
+        canvas.restore()

plot_io/ticks.py

@@ -0,0 +1,284 @@
+"""Tick choice and tick labels.
+
+Every function works on data values and returns :class:`Tick` lists; positions on the
+page are the axis's business.  Labels are strings or rich content (exponents).
+"""
+
+import math
+from collections.abc import Callable, Sequence
+from typing import Any, NamedTuple
+
+from .numbers import NumberStyle, format_axis
+from .scales import Scale
+
+__all__ = ["Tick", "linear_ticks", "nice_step", "format_values", "numeric_ticks",
+           "thin_by_position", "minor_linear", "exponent_label"]
+
+_MANTISSAS = (1.0, 2.0, 2.5, 5.0)
+
+
+class Tick(NamedTuple):
+    value: float
+    label: Any          # str, rich content, or None (unlabelled)
+    major: bool = True
+
+
+def nice_step(raw: float) -> float:
+    """The smallest step 1, 2, 2.5 or 5 × 10^k that is at least ``raw``."""
+    if not raw > 0 or not math.isfinite(raw):
+        return 1.0
+    k = math.floor(math.log10(raw))
+    for m in _MANTISSAS + (10.0,):
+        s = m * 10.0 ** k
+        if s >= raw * (1 - 1e-9):
+            return s
+    return 10.0 ** (k + 1)
+
+
+def _next_step(step: float) -> float:
+    k = math.floor(math.log10(step) + 1e-9)
+    m = step / 10.0 ** k
+    for c in _MANTISSAS + (10.0,):
+        if c > m * (1 + 1e-9):
+            return c * 10.0 ** k
+    return 2.0 * 10.0 ** (k + 1)
+
+
+def _values(lo: float, hi: float, step: float) -> list[float]:
+    eps = step * 1e-9
+    start = math.ceil((lo - eps) / step)
+    end = math.floor((hi + eps) / step)
+    out = []
+    for i in range(start, end + 1):
+        v = i * step
+        out.append(float(f"{v:.12g}") if v else 0.0)
+    return out
+
+
+def linear_ticks(lo: float, hi: float, max_ticks: int,
+                 fits: Callable[[list[float], float], bool] | None = None) -> tuple[list[float], float]:
+    """Tick values in [lo, hi]: the smallest nice step giving at most ``max_ticks``
+    ticks (and for which ``fits(values, step)`` holds).  Returns ``(values, step)``."""
+    if hi < lo:
+        lo, hi = hi, lo
+    if hi == lo:
+        return [lo], 1.0
+    n = max(2, int(max_ticks))
+    step = nice_step((hi - lo) / n)
+    for _ in range(60):
+        vals = _values(lo, hi, step)
+        if len(vals) <= n and (fits is None or fits(vals, step)):
+            return vals, step
+        step = _next_step(step)
+    return _values(lo, hi, step), step
+
+
+def minor_linear(lo: float, hi: float, step: float) -> list[float]:
+    k = math.floor(math.log10(step) + 1e-9)
+    m = round(step / 10.0 ** k, 6)
+    sub = step / (4 if m == 2.0 else 5)
+    return _values(lo, hi, sub)
+
+
+# ---------------------------------------------------------------------------
+# Labels
+# ---------------------------------------------------------------------------
+
+def format_values(values: Sequence[float], sci_limits: tuple[int, int] = (-4, 5),
+                  ) -> tuple[list[str], int]:
+    """``"auto"`` labels of values with the default number style (see
+    :func:`plot_io.numbers.format_axis`)."""
+    labels, exp = format_axis(values, "auto", NumberStyle(), sci_limits)
+    return [str(s) for s in labels], exp
+
+
+# ---------------------------------------------------------------------------
+# Ticks per scale
+# ---------------------------------------------------------------------------
+
+def exponent_label(base: str, k: int, style: NumberStyle | None = None) -> Any:
+    from .text import superscript
+    style = style or NumberStyle()
+    return style.wrap([base, superscript(style.exponent(k))])
+
+
+def _int_powers(flo: float, fhi: float) -> list[int]:
+    return list(range(math.ceil(flo - 1e-9), math.floor(fhi + 1e-9) + 1))
+
+
+def _thin_powers(ks: list[int], max_ticks: int, base: int = 1) -> tuple[list[int], int]:
+    """Every k-th power so that at most ``max_ticks`` remain (k a power of two when
+    ``base`` is 2, else any integer)."""
+    every = 1
+    while len([k for k in ks if k % every == 0]) > max(2, max_ticks):
+        every = every * 2 if base == 2 else every + 1
+    return [k for k in ks if k % every == 0], every
+
+
+def _each(values: list[float], fmt: Any, style: NumberStyle) -> list[Any]:
+    """Labels formatted one by one (log and other non-linear ticks)."""
+    if fmt != "auto":
+        return format_axis(values, fmt, style, None)[0]
+    return [format_axis([v], "auto", style, None)[0][0] for v in values]
+
+
+def numeric_ticks(scale: Scale, lo: float, hi: float, max_ticks: int, fmt: Any = "auto",
+                  style: NumberStyle | None = None, sci_limits: tuple[int, int] = (-4, 5),
+                  minor: bool = True, length: float = 0.0,
+                  fits: Callable[[list[float], float], bool] | None = None,
+                  ) -> tuple[list[Tick], int]:
+    """Ticks of a numeric scale between data limits ``lo`` < ``hi``, labelled with the
+    number format ``fmt``.  Returns the ticks and the exponent of a common ×10ᵏ factor
+    (0: none)."""
+    style = style or NumberStyle()
+    if hi < lo:
+        lo, hi = hi, lo
+    name = scale.name
+    flo, fhi = scale.f(lo), scale.f(hi)
+    if name in ("log", "log2", "log10"):
+        base_num = {"log": math.e, "log2": 2.0, "log10": 10.0}[name]
+        ks = _int_powers(flo, fhi)
+        if name == "log10" and 1 <= len(ks) < 3:
+            values = [m * 10.0 ** k for k in range(min(ks, default=0) - 1, max(ks, default=0) + 1)
+                      for m in (1, 2, 5) if lo * (1 - 1e-9) <= m * 10.0 ** k <= hi * (1 + 1e-9)]
+            if len(values) >= 3 or len(values) > len(ks):
+                ticks = [Tick(v, s) for v, s in zip(values, _each(values, fmt, style))]
+                if minor:
+                    ticks += [Tick(m * 10.0 ** k, None, False)
+                              for k in range(min(ks) - 1, max(ks) + 1)
+                              for m in (3, 4, 6, 7, 8, 9)
+                              if lo <= m * 10.0 ** k <= hi]
+                return ticks, 0
+        if len(ks) >= 2:
+            kept, every = _thin_powers(ks, max_ticks, 2 if name == "log2" else 1)
+            labelled = [base_num ** k for k in kept]
+            custom = dict(zip(kept, _each(labelled, fmt, style))) if fmt != "auto" else {}
+            ticks = []
+            for k in ks:
+                v = base_num ** k
+                if k not in kept:
+                    ticks.append(Tick(v, None, False))
+                    continue
+                if fmt != "auto":
+                    label: Any = custom[k]
+                elif name == "log10":
+                    label = exponent_label("10", k, style)
+                elif name == "log2":
+                    label = (_each([v], "auto", style)[0] if -10 <= k <= 10
+                             else exponent_label("2", k, style))
+                else:
+                    label = style.wrap("1") if k == 0 else exponent_label("e", k, style)
+                ticks.append(Tick(v, label))
+            if name == "log10" and minor and every == 1 and len(ks) <= 8:
+                ticks += [Tick(m * 10.0 ** k, None, False) for k in range(ks[0] - 1, ks[-1] + 1)
+                          for m in range(2, 10) if lo <= m * 10.0 ** k <= hi]
+            return ticks, 0
+        # Less than two powers in range: nice values in data space.
+    if name in ("linear", "log", "log2", "log10"):
+        values, step = linear_ticks(lo, hi, max_ticks, fits)
+        values = [v for v in values if scale.contains(v)]
+        labels, exp = format_axis(values, fmt, style, sci_limits)
+        return [Tick(v, s) for v, s in zip(values, labels)], exp
+    if name == "symlog":
+        return _symlog_ticks(scale, lo, hi, max_ticks, fmt, style, minor, length)
+    if name == "logit":
+        return _logit_ticks(scale, lo, hi, max_ticks, fmt, style, length)
+    # sqrt, exp and other monotone scales: nice candidates thinned on the page.
+    values, step = linear_ticks(lo, hi, max(2 * max_ticks, 4))
+    values = [v for v in values if scale.contains(v)]
+    if length > 0 and len(values) > 2 and fhi != flo:
+        pos = [(scale.f(v) - flo) / (fhi - flo) * length for v in values]
+        keep = thin_by_position(pos, length / max(max_ticks, 1))
+        values = [values[i] for i in keep]
+    return [Tick(v, s) for v, s in zip(values, _each(values, fmt, style))], 0
+
+
+def thin_by_position(pos: Sequence[float], spacing: float) -> list[int]:
+    """Indices of increasing positions kept so that neighbours are at least ``spacing``
+    apart.  Walks from the end where the scale stretches the data most (the sparse end),
+    always keeping both ends."""
+    n = len(pos)
+    if n <= 2:
+        return list(range(n))
+    order = list(range(n))
+    if pos[-1] - pos[-2] > pos[1] - pos[0]:
+        order.reverse()        # sparse at the high end: walk from there
+    kept = [order[0]]
+    for i in order[1:-1]:
+        if abs(pos[i] - pos[kept[-1]]) >= spacing and abs(pos[order[-1]] - pos[i]) >= spacing:
+            kept.append(i)
+    kept.append(order[-1])
+    return sorted(kept)
+
+
+def _thin(scale: Scale, values: list[float], lo: float, hi: float, max_ticks: int,
+          length: float) -> list[float]:
+    flo, fhi = scale.f(lo), scale.f(hi)
+    if length > 0 and len(values) > 2 and fhi != flo:
+        pos = [(scale.f(v) - flo) / (fhi - flo) * length for v in values]
+        keep = thin_by_position(pos, length / max(max_ticks, 1))
+        values = [values[i] for i in keep]
+    return values
+
+
+def _symlog_ticks(scale: Scale, lo: float, hi: float, max_ticks: int, fmt: Any,
+                  style: NumberStyle, minor: bool, length: float) -> tuple[list[Tick], int]:
+    """0, ±linthresh, then decades beyond; linear minor ticks inside the linear region."""
+    c = scale.options.get("linthresh", 1.0)
+    eps = (hi - lo) * 1e-9 + 1e-300
+    majors = [0.0] if lo - eps <= 0.0 <= hi + eps else []
+    for sign in (1.0, -1.0):
+        k = 0
+        while k < 400:
+            v = sign * c * 10.0 ** k
+            if not lo - eps <= v <= hi + eps:
+                if (sign > 0 and v > hi) or (sign < 0 and v < lo):
+                    break
+            else:
+                majors.append(v)
+            k += 1
+    majors = sorted(set(majors))
+    majors = _thin(scale, majors, lo, hi, max_ticks, length)
+    ticks = [Tick(v, s) for v, s in zip(majors, _each(majors, fmt, style))]
+    if minor:
+        have = set(majors)
+        step = _symlog_minor_step(scale, c)
+        if step is not None:
+            n = int(round(c / step))
+            for i in range(-n + 1, n):
+                v = i * step
+                if i and v not in have and lo <= v <= hi:
+                    ticks.append(Tick(v, None, False))
+    return ticks, 0
+
+
+#: Smallest gap between minor ticks in the linear region of a symlog axis, in scale units
+#: (decades): the gap between minor ticks 4 and 5 of a log decade.
+_SYMLOG_MINOR_GAP = math.log10(1.25)
+
+
+def _symlog_minor_step(scale: Scale, c: float) -> float | None:
+    """The finest nice step (c/10, c/5, c/4, c/2) whose ticks in (−c, c) stay at least
+    ``_SYMLOG_MINOR_GAP`` apart on the axis, or ``None`` when no step fits."""
+    if 2.0 * scale.f(c) < 2.0 * _SYMLOG_MINOR_GAP:
+        return None
+    for div in (10, 5, 4, 2):
+        step = c / div
+        pos = [scale.f(i * step) for i in range(0, div + 1)]
+        if min(b - a for a, b in zip(pos, pos[1:])) >= _SYMLOG_MINOR_GAP:
+            return step
+    return None
+
+
+def _logit_ticks(scale: Scale, lo: float, hi: float, max_ticks: int, fmt: Any,
+                 style: NumberStyle, length: float) -> tuple[list[Tick], int]:
+    """0.5, then 0.1/0.9, 0.01/0.99, … inside the limits."""
+    values = [0.5]
+    for k in range(1, 16):
+        values += [10.0 ** -k, 1.0 - 10.0 ** -k]
+    values = sorted(v for v in values if lo <= v <= hi)
+    if len(values) < 2:
+        values, _ = linear_ticks(lo, hi, max_ticks)
+        values = [v for v in values if 0 < v < 1]
+    values = _thin(scale, values, lo, hi, max_ticks, length)
+    return [Tick(v, s) for v, s in zip(values, _each(values, fmt, style))], 0