plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/levels.py

@@ -0,0 +1,509 @@
+"""Level axes: a column of categories as an aesthetic (``color``, ``marker``,
+``line_style``, ``size``).
+
+An aesthetic holds **levels** when it is a pandas or polars categorical, a ``data=``
+column of text or booleans, or a list or array holding a value the setting does not take
+(a list of colours, markers… stays one value per item).  A :class:`LevelAxis` holds the
+levels of one column (``level_order`` first, then the categorical order or first
+appearance; a missing value is the level ``"nan"``, or its rows are left out with
+``level_missing="drop"``) and maps each to a value of its aesthetics: colours from the
+plot's ``qualitative_map`` (its next colours in call order, as ``group=`` members take
+them), or from the series' own ``color_map`` (a map's colours for the levels, a dict by
+level), markers from
+``markers``, line styles from ``line_styles``, sizes from ``size_map`` (even by area).
+Calls of a plot mapping the same column, and plots grouped by ``share_color``, give a
+level one colour.
+
+A type paints by levels (``Series.LEVELS``) as ``"items"`` (scatter: each point by its
+levels, one call) or ``"split"`` (one member call per level combination, drawn,
+positioned and coloured as the members of ``group=``: their points in data order).  The legend has a section per
+axis, titled by its column (or ``name``), with an entry per level; with one axis the
+section's title is the legend's.
+"""
+
+import array
+import functools
+import math
+from typing import Any
+
+from . import kernels
+from .columns import _length, _missing, _order
+from .validators import typed
+
+__all__ = ["AESTHETICS", "adopt", "LevelAxis", "Section", "detect", "make", "calls_of", "assign",
+           "level_color_count", "facet_orders", "level_order"]
+
+AESTHETICS = ("color", "marker", "line_style", "size")
+
+
+# -- settings ------------------------------------------------------------------------
+
+@typed("Column | Mapping[Any, Any]")
+def level_order(v: Any) -> Any:
+    """``level_order``, ``markers``, ``line_styles``: a list, or a dict of values by
+    column (by level for markers and line styles); the values are checked where used."""
+    if isinstance(v, dict):
+        return dict(v)
+    if isinstance(v, (str, bytes)) or not hasattr(v, "__iter__") or not len(v := list(v)):
+        raise ValueError(f"expected a list or a dict, got {v!r}")
+    return v
+
+
+def adopt(cls: Any, kind: str) -> None:
+    """Make ``cls`` draw levels as ``kind`` (``"items"``, ``"split"``), with the settings
+    of its level axes."""
+    from .layers.base import common
+    from .settings import table
+    names = ["level_order"] + [f"{a}s" for a in ("marker", "line_style") if a in cls.SETTINGS]
+    cls.LEVELS = kind
+    cls.SETTINGS = {**cls.SETTINGS, **{k: v for k, v in table(**common(*names)).items()
+                                       if k not in cls.SETTINGS}}
+
+
+# -- detection -----------------------------------------------------------------------
+
+def _items(v: Any) -> list[Any] | None:
+    if isinstance(v, (str, bytes, dict, tuple, int, float)) or v is None:
+        return None
+    if isinstance(v, (array.array, memoryview)) and getattr(v, "typecode", "") != "u":
+        return None                                       # numbers
+    if hasattr(v, "to_numpy") and not hasattr(v, "__array_interface__"):
+        v = v.to_numpy()
+    kind = getattr(getattr(v, "dtype", None), "kind", None)
+    if kind is not None and kind not in "OUSb":
+        return None                                       # numbers
+    if hasattr(v, "tolist") and not isinstance(v, list):
+        v = v.tolist()
+    return v if isinstance(v, list) else None
+
+
+def _is_levels(cls: type, name: str, v: Any, titled: bool, order: Any) -> bool:
+    if order is not None:
+        return True
+    items = _items(v)
+    if not items:
+        return False
+    check = cls.SETTINGS[name].check                      # type: ignore[attr-defined]
+    first = next((x for x in items if x is not None), None)
+    if not isinstance(first, (str, bool)):
+        return False                                  # numbers, colour tuples: per item
+    try:
+        unique = set(items)
+    except TypeError:                                 # colour rows among the items
+        unique = {x for x in items if isinstance(x, (str, bool))}
+    for x in (x for x in unique if isinstance(x, (str, bool))):
+        if isinstance(x, bool) or titled:
+            return True
+        try:
+            check(x)
+        except (ValueError, TypeError):
+            return True
+    return False
+
+
+def detect(cls: type, kw: dict[str, Any], titles: dict[str, Any],
+           orders: dict[str, Any]) -> list[tuple[str, Any, Any, Any]]:
+    """The aesthetics of a call holding levels, taken out of ``kw``: ``(name, values,
+    column title, categorical order)``.  Types that map none refuse them."""
+    settings = getattr(cls, "SETTINGS", {})
+    kind = getattr(cls, "LEVELS", None)
+    found: list[tuple[str, Any, Any, Any]] = []
+    if kind is None:
+        return found
+    for name in (*AESTHETICS, "opacity"):
+        v = kw.get(name)
+        if v is None or name not in settings:
+            continue
+        order = orders.get(name)
+        if order is None and not isinstance(v, (list, tuple, str)):
+            order = _order(v)                                 # a categorical given directly
+        if not _is_levels(cls, name, v, name in titles, order):
+            continue
+        if name == "opacity":
+            raise ValueError(f"{cls.__name__}: opacity takes numbers, not levels (use color, "
+                             "marker, line_style or size)")
+        if kind not in ("items", "split"):
+            raise ValueError(f"{cls.__name__}: {name} takes no levels; use plt.facet")
+        found.append((name, kw.pop(name), titles.get(name), order))
+    return found
+
+
+# -- axes ----------------------------------------------------------------------------
+
+class LevelAxis:
+    """The levels of one column and the aesthetics mapped from it.
+
+    ``key``: the column title (``"#color"`` for an untitled list); ``levels`` in order;
+    ``codes``: each row's level index (``-1``: left out); ``present``: the levels with
+    rows, in order."""
+
+    __slots__ = ("key", "title", "aesthetics", "levels", "codes", "present")
+
+    def __init__(self, name: str, values: Any, title: Any, order: Any, given: Any,
+                 missing: str) -> None:
+        self.key = title if title is not None else "#" + name
+        self.title = title
+        self.aesthetics = [name]
+        if isinstance(given, dict):
+            given = given.get(self.key, given.get(name))
+        if hasattr(values, "to_numpy") and not hasattr(values, "__array_interface__"):
+            values = values.to_numpy()
+        if hasattr(values, "tolist") and not isinstance(values, list):
+            values = values.tolist()
+        seen = dict.fromkeys(values)                       # first appearance
+        gone = [k for k in seen if _missing(k) or (isinstance(k, float) and math.isnan(k))]
+        found = [k for k in seen if not any(k is g for g in gone)]
+        first = list(given or [])
+        rest = [k for k in (order or []) if k in seen and k not in first]
+        levels = first + rest + [k for k in found if k not in first and k not in rest]
+        if gone and missing == "keep" and "nan" not in levels:
+            levels.append("nan")
+        index = {k: i for i, k in enumerate(levels)}
+        for k in gone:
+            index[k] = index["nan"] if missing == "keep" else -1
+        self.levels = levels
+        self.codes = array.array("q", map(index.__getitem__, values))
+        used = {index[k] for k in seen}
+        self.present = [lv for i, lv in enumerate(levels) if i in used]
+
+    def take(self, rows: Any) -> None:
+        self.codes = array.array("q", (int(c) for c in kernels.take(
+            array.array("d", self.codes), rows)))
+        used = set(self.codes)
+        self.present = [lv for i, lv in enumerate(self.levels) if i in used]
+
+    def value(self, series: Any, name: str, level: Any) -> Any:
+        """The value of aesthetic ``name`` (not colour) for ``level``."""
+        k = self.levels.index(level)
+        if name == "size":
+            from .sizemaps import SizeMap
+            sm = series.resolve("size_map") if "size_map" in series.SETTINGS else None
+            lo, hi = (sm or SizeMap()).diameters(None if isinstance(series, _Probe)
+                                                 else series)
+            t = k / (len(self.levels) - 1) if len(self.levels) > 1 else 1.0
+            return math.sqrt(lo * lo + t * (hi * hi - lo * lo))
+        from .tables import LINE_STYLE_CYCLE, MARKER_CYCLE
+        given = series.resolve(f"{name}s") if f"{name}s" in series.SETTINGS else None
+        if isinstance(given, dict) and level in given:
+            return given[level]
+        cycle = given if isinstance(given, list) else (
+            MARKER_CYCLE if name == "marker" else LINE_STYLE_CYCLE)
+        return cycle[k % len(cycle)]
+
+    def __repr__(self) -> str:
+        return f"LevelAxis({self.key!r}, {self.levels!r})"
+
+
+class Section:
+    """A legend section's header (a level axis' title)."""
+
+    header = True
+
+    def __init__(self, label: Any) -> None:
+        self.label = label
+
+
+class Levels:
+    """The level axes of a series and the calls it is drawn as (``parts``)."""
+
+    def __init__(self, axes: list[LevelAxis], color: LevelAxis | None) -> None:
+        self.axes = axes
+        self.color = color
+        #: ``(series, colour spec, legend-only)`` of each call, in drawing order
+        self.parts: list[tuple[Any, Any, bool]] = []
+        self.headers: dict[int, Section] = {}
+
+    def item_colors(self, series: Any, ctx: Any) -> Any:
+        """Each point's colour (items types): its level's, through ``kernels.take``."""
+        from .color.values import rgba_of
+        from .layers.paint import memo
+        from .spec import auto_colors
+
+        def make() -> Any:
+            table = array.array("d")
+            for c in auto_colors(series) or []:
+                rgba = rgba_of(ctx.color(c)) or (0.0, 0.0, 0.0, 0.0)
+                table.extend(rgba if len(rgba) == 4 else (*rgba, 1.0))
+            rows = memoryview(table).cast("B").cast("d", (len(table) // 4, 4))
+            flat = kernels.take(rows, self.color.codes)        # type: ignore[union-attr]
+            n = len(flat) // 4
+            return memoryview(flat).cast("B").cast("d", (n, 4)) if n else []
+        return memo(ctx, ("levels", id(series)), make)
+
+
+def make(cls: Any, cols: Any, pos: dict[str, Any], kw: dict[str, Any],
+         found: list[tuple[str, Any, Any, Any]]) -> Any:
+    """The series of a call with levels (``found``, from :func:`detect`)."""
+    n = len(found[0][1])
+    if "group" in kw:
+        raise ValueError(f"{cls.__name__}: group= and levels in {found[0][0]}: use one")
+    given = level_order(kw["level_order"]) if kw.get("level_order") is not None else None
+    axes: dict[str, LevelAxis] = {}
+    for name, v, title, order in found:
+        if len(v) != n:
+            raise ValueError(f"{name} has {len(v)} levels for {n} in {found[0][0]}")
+        ax = LevelAxis(name, v, title, order, given, kw.get("level_missing", "keep"))
+        if ax.key in axes:
+            axes[ax.key].aesthetics.append(name)
+        else:
+            axes[ax.key] = ax
+    every = list(axes.values())
+    if any(-1 in ax.codes for ax in every):                 # level_missing="drop"
+        keep = array.array("q", (i for i in range(n) if all(ax.codes[i] >= 0 for ax in every)))
+        for ax in every:
+            ax.take(keep)
+        cols, pos, kw, n = (*_rows(cols, pos, kw, keep, n), len(keep))
+    color = next((ax for ax in every if "color" in ax.aesthetics), None)
+    title = kw.pop("name", None)
+    items = cls.LEVELS == "items"
+    for ax in every if items else ():                       # per item, but colours
+        for a in ax.aesthetics:
+            if a != "color":
+                values = [ax.value(_Probe(cls, kw), a, lv) for lv in ax.levels]
+                kw[a] = (kernels.take(array.array("d", values), ax.codes) if a == "size"
+                         else [values[c] for c in ax.codes])
+    s = cls._make(cols, pos, kw)
+    lv = s._lv = Levels(every, color)
+    if title is None and len(every) == 1:
+        title = every[0].title
+    if title is not None:
+        s.plot._legend_title = title
+    if items:
+        lv.parts.append((s, ("items", color) if color is not None else None, False))
+    token = object()                                        # members drawn in data order
+    for rows, combo in () if items else _combos(every, n):
+        m = _part(s, *_rows(cols, pos, kw, rows, n), dict(zip(every, combo)),
+                  str(combo[0]) if len(every) == 1 else None)
+        m._combo = combo
+        m.__dict__["_order_rows"] = (token, rows)
+        lv.parts.append((m, None if s.is_set("color") else ("of", s) if color is None
+                         else ("axis", color, combo[every.index(color)]), False))
+    for ax in every if len(every) > 1 or items else ():     # legend sections
+        for k, level in enumerate(ax.present):
+            if items:
+                one = array.array("q", [ax.codes.index(ax.levels.index(level))])
+                got = _rows(cols, pos, kw, one, n)
+            else:
+                m = next(p for p, _, only in lv.parts
+                         if not only and p._combo[every.index(ax)] == level)
+                got = (m.cols, m._pos, m._given)
+            m = _part(s, *got, {ax: level}, str(level))
+            lv.parts.append((m, ("axis", ax, level) if ax is color else ("text",)
+                             if color is not None else None if s.is_set("color")
+                             else ("of", s), True))
+            if k == 0 and len(every) > 1:
+                lv.headers[id(m)] = Section(ax.title if ax.title is not None
+                                            else ax.aesthetics[0])
+    return s
+
+
+def _rows(cols: Any, pos: dict[str, Any], kw: dict[str, Any], rows: Any, n: int
+          ) -> tuple[Any, dict[str, Any], dict[str, Any]]:
+    """The columns, data arguments and per-point keywords of ``rows`` (of ``n``)."""
+    from .layers.base import SPLIT_KEYS
+    from .tables import take
+    ck = cols.take(rows, n)
+    pk = {k: ck.args[k] if k in ck.args else (take(v, rows) if _length(v) == n else v)
+          for k, v in pos.items()}
+    kk = {k: (take(v, rows) if k in SPLIT_KEYS and _length(v) == n and not (
+        isinstance(v, tuple) and len(v) in (3, 4)) else v) for k, v in kw.items()}
+    return ck, pk, kk
+
+
+class _Probe:
+    """The settings of a call before its series exists (level values at intake)."""
+
+    def __init__(self, cls: Any, kw: dict[str, Any]) -> None:
+        self.SETTINGS = cls.SETTINGS
+        self.kw = kw
+
+    def resolve(self, name: str) -> Any:
+        v = self.kw.get(name)
+        return None if v is None else self.SETTINGS[name].check(v)
+
+
+def _combos(axes: list[LevelAxis], n: int) -> list[tuple[Any, tuple[Any, ...]]]:
+    """``(rows, levels)`` of each level combination with rows, in level order (rows by
+    a stable argsort of the combined codes)."""
+    from bisect import bisect_left, bisect_right
+    sizes = [len(ax.levels) for ax in axes]
+    code = array.array("d", axes[-1].codes)
+    stride = sizes[-1]
+    for ax, size in reversed(list(zip(axes[:-1], sizes[:-1]))):
+        c = ax.codes
+        for i in range(n):
+            code[i] += c[i] * stride
+        stride *= size
+    rows = kernels.argsort(code)
+    ordered = kernels.take(code, rows) if n else array.array("d")
+    out = []
+    for k in sorted(set(code)):
+        lo = bisect_left(ordered, k)
+        combo, rest = [], int(k)
+        for size in reversed(sizes):
+            rest, j = divmod(rest, size)
+            combo.append(j)
+        out.append((rows[lo:bisect_right(ordered, k, lo)],
+                    tuple(ax.levels[j] for ax, j in zip(axes, reversed(combo)))))
+    return out
+
+
+def _upward(name: str) -> bool:
+    """Whether ``name`` is a setting of the plot or the figure (a call's keyword that
+    went to them)."""
+    from .figure import Figure
+    from .plot import Plot
+    from .settings import canonical
+    return (name in Plot.CALL_EXTRA or canonical(name, Plot.SETTINGS) in Plot.SETTINGS
+            or canonical(name, Figure.SETTINGS) in Figure.SETTINGS)
+
+
+def _part(s: Any, ck: Any, pk: dict[str, Any], kw: dict[str, Any],
+          levels: dict[LevelAxis, Any], name: str | None) -> Any:
+    """A call of ``s`` drawn apart (not in ``plot.series``): a level member, or a legend
+    section's entry (the axes not in ``levels`` at their defaults)."""
+    from .settings import canonical
+    own = type(s).SETTINGS
+    kk = {k: v for k, v in kw.items()               # the plot's and figure's went to them
+          if canonical(k, own) in own or not _upward(k)}
+    for ax in s._lv.axes:
+        for a in ax.aesthetics:
+            if a != "color":
+                kk.pop(a, None)
+                if ax in levels:
+                    kk[a] = ax.value(s, a, levels[ax])
+    if name is not None:
+        kk["name"] = name
+    m = object.__new__(type(s))
+    m.cols, m._of, m._pos, m._given = ck, s, pk, kk
+    m.__init__(**pk, **{**kk, "plot": s.plot})
+    return m
+
+
+# -- render ---------------------------------------------------------------------------
+
+def calls_of(series: Any) -> list[Any]:
+    """The calls a series is drawn as: its own, or its level members' and legend
+    sections'."""
+    lv = getattr(series, "_lv", None)
+    if lv is None:
+        return [series.layers()]
+    out = []
+    for part, spec, legend_only in lv.parts:
+        c = part.layers()
+        if legend_only:
+            keep = _key_call()(part)
+            keep.entries = c.entries
+            c = keep
+        head = lv.headers.get(id(part))
+        if head is not None:
+            c.entries = [head, *c.entries]
+        c.level = spec
+        if spec is not None:
+            c.color_count = 0
+        out.append(c)
+    return out
+
+
+@functools.cache
+def _key_call() -> Any:
+    from .layers.core import Call
+
+    class Key(Call):
+        """A legend section's entry: a call on no axis."""
+
+        def has_axis(self, role: str) -> bool:
+            return False
+    return Key
+
+
+def level_color_count(calls: list[Any]) -> int:
+    """The plot's colours the level axes of ``calls`` take at most."""
+    seen: set[Any] = set()
+    n = 0
+    for c in calls:
+        spec = getattr(c, "level", None)
+        if spec is None:
+            continue
+        if spec[0] in ("axis", "items") and spec[1].key not in seen:
+            seen.add(spec[1].key)
+            n += len(spec[1].levels)
+        elif spec[0] == "of" and id(spec[1]) not in seen and not any(
+                d.series is spec[1] for d in calls):
+            seen.add(id(spec[1]))
+            n += 1
+    return n
+
+
+def assign(plot: Any, c: Any, cycle: Any, i: int, done: dict[Any, Any]) -> int:
+    """The colours of a call with a colour spec (``c.level``) into the render; ``cycle``:
+    the plot's colours (in the series' colour variant); ``i``: the plot's next colour
+    (returned, advanced by the colours taken); ``done``: the series colours given in this
+    pass."""
+    from .spec import current
+    r = current()
+    assert r is not None
+    spec = c.level
+    kind = spec[0]
+    if kind == "text":
+        lg = getattr(plot, "legend", None)
+        col = lg.resolve("color") if lg is not None else None
+        r.colors[id(c.series)] = [col if col is not None else plot.resolve("text_color")]
+        return i
+    if kind == "of":
+        s = spec[1]
+        got = done.get(id(s))
+        if got is None:
+            got = done[id(s)] = [cycle[i % len(cycle)]]
+            i += 1
+        r.colors[id(c.series)] = got
+        return i
+    ax = spec[1]
+    owner = c.series._of if "_of" in c.series.__dict__ else c.series
+    group = r.levels_group.get(id(plot), id(plot))
+    store = r.levels.get((group, ax.key))
+    if store is None or (store[0] == id(plot) and (group, ax.key) not in done):
+        store = r.levels[(group, ax.key)] = (id(plot), dict[Any, Any]())
+        done[(group, ax.key)] = True
+    colors = store[1]
+    from .layers.pipeline import own_map
+    cm = own_map(owner)
+    by_level = cm if isinstance(cm, dict) else {}
+    own = None if cm is None or isinstance(cm, dict) else cm.colors(len(ax.levels))
+    for k, lv in enumerate(ax.levels):
+        if lv in colors:
+            continue
+        if lv in by_level:
+            colors[lv] = by_level[lv]
+        elif own is not None:
+            colors[lv] = own[k % len(own)]
+        else:
+            colors[lv] = cycle[i % len(cycle)]
+            i += 1
+    if kind == "items":
+        r.colors[id(c.series)] = [colors[lv] for lv in ax.levels]
+    else:
+        r.colors[id(c.series)] = [colors[spec[2]]]
+    return i
+
+
+def facet_orders(data: Any, kw: dict[str, Any]) -> None:
+    """The ``level_order`` of a facet call: the levels of each level column over the
+    whole table, so that a level has one colour, marker… in every panel."""
+    from .tables import column, has_column
+    given = kw.get("level_order")
+    if given is not None and not isinstance(given, dict):
+        return
+    out = dict(given or {})
+    for name in AESTHETICS:
+        v = kw.get(name)
+        if not isinstance(v, str) or v in out or not has_column(data, v):
+            continue
+        values, order = column(data, v)
+        items = _items(values)
+        if order is None and not (items and any(isinstance(x, (str, bool)) for x in items)):
+            continue
+        ax = LevelAxis(name, values, v, order, None, kw.get("level_missing", "keep"))
+        out[v] = ax.levels
+    if out:
+        kw["level_order"] = out

plot_io/limits.py

@@ -0,0 +1,124 @@
+"""Limits: ``"auto"``, ``"lo/hi"`` strings (``min``, ``max``, numbers, ``q:F``), ``"-m/m"``
+or pairs."""
+
+import math
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from .times import axis_value
+from .validators import typed
+
+__all__ = ["check_limits", "resolve_limits", "symmetric", "SYMMETRIC"]
+
+#: ``"-m/m"``: limits symmetric about the axis' ``center`` (or 0), ``m`` the farthest value
+SYMMETRIC = (("m", -1.0), ("m", 1.0))
+
+
+def symmetric(spec: Any) -> bool:
+    """Whether the limits ``spec`` is :data:`SYMMETRIC`."""
+    return isinstance(spec, tuple) and len(spec) == 2 and all(
+        isinstance(s, tuple) and len(s) == 2 and isinstance(s[0], str) and s[0] == "m"
+        for s in spec)
+
+
+def _side(token: str) -> Any:
+    """One side of a limits string: a keyword (any case), a number or an ISO date."""
+    t = token.strip().lower()
+    if t in ("min", "max", "auto", ""):
+        return "auto" if t in ("auto", "") else t
+    if t in ("m", "-m"):
+        raise ValueError(f"invalid limit {token!r}: `m` is only in \"-m/m\" (symmetric "
+                         f"about the centre)")
+    if t.startswith("q:"):
+        try:
+            q = float(t[2:])
+        except ValueError:
+            q = math.nan
+        if not 0 <= q <= 1:
+            raise ValueError(f"invalid limit {token!r}: `q:` takes a quantile from 0 to 1")
+        return ("q", q)
+    try:
+        v = float(t)
+    except ValueError:
+        try:
+            v = axis_value(token.strip())
+        except ValueError:
+            raise ValueError(f"invalid limit {token!r}") from None
+    if not math.isfinite(v):
+        raise ValueError(f"invalid limit {token!r}")
+    return v
+
+
+@typed("str | Sequence[Any]")
+def check_limits(v: Any) -> Any:
+    """Normalize a limits value to ``"auto"``, :data:`SYMMETRIC` (``"-m/m"``) or a pair of
+    sides (``None``/``"auto"``, a number, ``"min"``, ``"max"``, ``("q", F)``, or in a pair a
+    category ``("name", N)``)."""
+    if isinstance(v, str):
+        s = v.strip()
+        if s.lower() == "auto":
+            return "auto"
+        if "".join(s.lower().split()) == "-m/m":
+            return SYMMETRIC
+        parts = s.split("/")
+        if len(parts) != 2:
+            raise ValueError(f"expected 'lo/hi', got {v!r}")
+        return (_side(parts[0]), _side(parts[1]))
+    if symmetric(v):
+        return SYMMETRIC
+    if isinstance(v, (tuple, list)) and len(v) == 2:
+        out: list[Any] = []
+        for side in v:
+            if side is None:
+                out.append("auto")
+            elif isinstance(side, str):
+                try:
+                    out.append(_side(side))
+                except ValueError:           # a category name, read by the axis
+                    out.append(("name", side))
+            elif isinstance(side, tuple) and len(side) == 2 and side[0] == "q":
+                out.append(_side(f"q:{side[1]!r}"))          # already checked
+            else:
+                try:
+                    x = axis_value(side)                 # a number or a date
+                except ValueError:
+                    x = math.nan
+                if not math.isfinite(x):
+                    raise ValueError(f"invalid limit {side!r}")
+                out.append(x)
+        return tuple(out)
+    raise ValueError(f"expected 'auto', 'lo/hi' or (lo, hi), got {v!r}")
+
+
+def resolve_limits(spec: Any, lo: float, hi: float,
+                   quantile: Callable[[float], float] | None = None) -> tuple[Any, Any, bool, bool]:
+    """``(lo, hi, lo_auto, hi_auto)`` from a limits spec and the data range; ``*_auto``
+    tells whether that side follows the data (and takes padding)."""
+    if symmetric(spec):
+        return lo, hi, False, False
+    sides = ("auto", "auto") if spec == "auto" else spec
+    out: list[Any] = []
+    autos: list[bool] = []
+    for side, data in zip(sides, (lo, hi)):
+        if side == "auto":
+            out.append(data)
+            autos.append(True)
+        elif side == "min":
+            out.append(lo)
+            autos.append(False)
+        elif side == "max":
+            out.append(hi)
+            autos.append(False)
+        elif isinstance(side, tuple):
+            out.append(quantile(side[1]) if quantile is not None else data)
+            autos.append(False)
+        else:
+            out.append(float(side))
+            autos.append(False)
+    return out[0], out[1], autos[0], autos[1]
+
+
+def needs_quantiles(spec: Any) -> Sequence[float]:
+    if spec == "auto":
+        return ()
+    return [s[1] for s in spec if isinstance(s, tuple) and s[0] == "q"]

plot_io/lines.py

@@ -0,0 +1,42 @@
+"""Line styles: named dash patterns or dash lengths."""
+
+from typing import Any
+
+from .validators import Custom, length, one_of, typed
+
+__all__ = ["line_style", "dash_of"]
+
+
+_DASH_LENGTH = length(lo=0)
+
+
+_STYLES = one_of("solid", "dashed", "dotted", "dashdot")
+
+
+@typed("Literal['solid', 'dashed', 'dotted', 'dashdot'] | list[SupportsFloat | str] | "
+       "tuple[SupportsFloat | str, ...]")
+def _line_style(v: Any) -> Any:
+    if isinstance(v, (list, tuple)):
+        return [_DASH_LENGTH(x) for x in v]
+    return _STYLES(v)
+
+
+#: A line style: `solid`, `dashed`, `dotted`, `dashdot`, or dash lengths (px or any length
+#: unit), alternately on and off.
+line_style = Custom(_line_style, inner=_DASH_LENGTH)
+
+_DASHES = {"solid": None, "dashed": (3.7, 1.6), "dotted": (1.0, 1.65),
+           "dashdot": (6.4, 1.6, 1.0, 1.6)}
+
+
+def dash_of(style: Any, width: float) -> list[float] | None:
+    """Dash lengths (px) of a line style, scaled by the line width."""
+    if style is None:
+        return None
+    if isinstance(style, (list, tuple)):
+        return [float(x) for x in style] or None
+    pattern = _DASHES[style]
+    if pattern is None:
+        return None
+    w = max(width, 0.75)
+    return [x * w for x in pattern]