plot-io 0.1.0__py3-none-any.whl

plot_io/numbers.py

@@ -0,0 +1,289 @@
+"""Numbers as text: one formatter for tick labels, colorbars and heatmap cell labels.
+
+``fmt`` is ``"auto"``, a format string, a callable, or a preset (``"percent"``,
+``"sci"``, ``"eng"``, ``"si"``, ``"int"``).  A :class:`NumberStyle` carries the decimal
+and thousands separators, the minus sign, a prefix and suffix, and the precision.
+"""
+
+import decimal
+import math
+import re
+from collections.abc import Callable, Sequence
+from typing import Any
+
+__all__ = ["NumberStyle", "format_numbers", "format_axis", "PRESETS", "check_format",
+           "NUMBER_SETTINGS"]
+
+PRESETS = ("auto", "percent", "sci", "eng", "si", "int")
+_SI = {-24: "y", -21: "z", -18: "a", -15: "f", -12: "p", -9: "n", -6: "µ", -3: "m",
+       0: "", 3: "k", 6: "M", 9: "G", 12: "T", 15: "P", 18: "E", 21: "Z", 24: "Y"}
+_MINUS = {"hyphen": "-", "minus": "−"}
+
+
+def check_format(v: Any) -> Any:
+    if callable(v):
+        return v
+    if isinstance(v, str):
+        key = v.strip().lower()
+        if key in PRESETS:
+            return key
+        if "%" in v and "{" not in v:            # strftime pattern (time axes)
+            return v
+        if "{" in v:
+            try:
+                v.format(1.5)
+            except (IndexError, KeyError, ValueError) as e:
+                raise ValueError(f"invalid format string {v!r}: {e}") from None
+            return v
+    raise ValueError(f"expected 'auto', a preset ({', '.join(PRESETS[1:])}), a format "
+                     f"string or a function, got {v!r}")
+
+
+class NumberStyle:
+    """Separators, minus sign, affixes and precision of formatted numbers."""
+
+    __slots__ = ("decimal", "thousands", "minus", "prefix", "suffix", "precision")
+
+    def __init__(self, decimal_separator: str = ".", thousands_separator: str = "",
+                 minus: str = "hyphen", prefix: str = "", suffix: str = "",
+                 precision: int | None = None) -> None:
+        self.decimal = decimal_separator
+        self.thousands = thousands_separator
+        self.minus = _MINUS[minus]
+        self.prefix = prefix
+        self.suffix = suffix
+        self.precision = precision
+
+    @classmethod
+    def of(cls, obj: Any) -> "NumberStyle":
+        """The style from an object's (inherited) settings."""
+        return cls(obj.get("decimal_separator"), obj.get("thousands_separator"),
+                   obj.get("minus"), obj.get("prefix"), obj.get("suffix"),
+                   obj.get("precision"))
+
+    def digits(self, s: str) -> str:
+        """A plain decimal string (``-1234.5``) with this style's signs and separators."""
+        neg = s.startswith("-")
+        if neg:
+            s = s[1:]
+        whole, _, frac = s.partition(".")
+        if self.thousands and len(whole) > 3:
+            groups = []
+            while len(whole) > 3:
+                groups.append(whole[-3:])
+                whole = whole[:-3]
+            groups.append(whole)
+            whole = self.thousands.join(reversed(groups))
+        out = whole + (self.decimal + frac if frac else "")
+        return (self.minus if neg else "") + out
+
+    def exponent(self, k: int) -> str:
+        return (self.minus if k < 0 else "") + str(abs(k))
+
+    def wrap(self, label: Any) -> Any:
+        if not (self.prefix or self.suffix):
+            return label
+        if isinstance(label, str):
+            return self.prefix + label + self.suffix
+        return [self.prefix] + list(label) + [self.suffix]
+
+
+def _fixed(v: float, d: int) -> str:
+    """``v`` with ``d`` decimals, rounding halves away from zero on the shortest decimal
+    form (1234.5 → 1235, 2.675 → 2.68)."""
+    if not math.isfinite(v):
+        return str(v)
+    q = decimal.Decimal(repr(float(v))).quantize(decimal.Decimal(1).scaleb(-d),
+                                                 rounding=decimal.ROUND_HALF_UP)
+    s = f"{q:f}"
+    if s.startswith("-") and float(s) == 0:
+        s = s[1:]
+    return s
+
+
+def _decimals(values: Sequence[float], precision: int | None, cap: int = 12) -> int:
+    """The fewest decimals telling the values apart and representing them (or giving
+    ``precision`` significant digits to the largest)."""
+    finite = [v for v in values if math.isfinite(v)]
+    if not finite:
+        return 0
+    big = max(abs(v) for v in finite)
+    if precision is not None:
+        if big == 0:
+            return 0
+        e = math.floor(math.log10(big))
+        d = precision - 1 - e
+        if abs(float(_fixed(big, max(0, d)))) >= 10.0 ** (e + 1):
+            d -= 1                          # rounding reached the next power (9.96 → 10)
+        return max(0, min(cap, d))
+    span = max(finite) - min(finite)
+    tol = max(1e-12, 1e-9 * big, span * 1e-6)
+    for d in range(cap + 1):
+        labels = [_fixed(v, d) for v in finite]
+        if len(set(labels)) == len(set(finite)) and all(abs(float(s) - v) <= tol
+                                                        for s, v in zip(labels, finite)):
+            return d
+    return cap
+
+
+def _superscript(text: str) -> Any:
+    from .text import superscript
+    return superscript(text)
+
+
+def _exp_form(values: Sequence[float], style: NumberStyle, step: int,
+              si: bool = False) -> list[Any]:
+    """Mantissa × 10ᵏ labels (``step`` 1: sci, 3: eng) or SI prefixes."""
+    parts: list[tuple[float, int] | None] = []
+    for v in values:
+        if not math.isfinite(v):
+            parts.append(None)
+        elif v == 0:
+            parts.append((0.0, 0))
+        else:
+            k = math.floor(math.log10(abs(v)) / step) * step
+            parts.append((v / 10.0 ** k, k))
+    mants = [p[0] for p in parts if p is not None]
+    prec = style.precision
+    if prec is None:
+        d = _decimals(mants, None, 10)
+    elif step == 1:
+        d = prec - 1
+    else:
+        bigm = max((abs(m) for m in mants), default=0.0)
+        d = max(0, prec - 1 - math.floor(math.log10(bigm))) if bigm else 0
+    out: list[Any] = []
+    for p in parts:
+        if p is None:
+            out.append("")
+            continue
+        m, k = p
+        dd = d
+        s = _fixed(m, dd)
+        if abs(float(s)) >= 10 ** step and m:      # rounding reached the next power
+            m, k = m / 10 ** step, k + step
+            if prec is not None and step == 3:
+                dd = prec - 1                     # the rounded mantissa is 1
+            s = _fixed(m, dd)
+        if si and k in _SI:
+            out.append(style.wrap(style.digits(s) + _SI[k]))
+        elif k == 0 or float(s) == 0:
+            out.append(style.wrap(style.digits(s)))
+        else:
+            out.append(style.wrap([style.digits(s) + "×10", _superscript(style.exponent(k))]))
+    return out
+
+
+_NUMBER = re.compile(r"(-?)(\d{1,3}(?:,\d{3})+|\d+)(?:\.(\d+))?")
+
+
+def _restyle(text: str, style: NumberStyle) -> str:
+    """Separators and minus applied to the numbers inside a formatted string."""
+    def sub(m: re.Match) -> str:
+        whole = m.group(2)
+        commas = "," in whole
+        whole = whole.replace(",", "")
+        s = (m.group(1) or "") + whole + ("." + m.group(3) if m.group(3) else "")
+        if commas and not style.thousands:
+            return NumberStyle(style.decimal, ",", "hyphen" if style.minus == "-" else "minus"
+                               ).digits(s)
+        return style.digits(s)
+    return _NUMBER.sub(sub, text)
+
+
+def format_axis(values: Sequence[float], fmt: Any = "auto", style: NumberStyle | None = None,
+                sci_limits: tuple[int, int] | None = (-4, 5)) -> tuple[list[Any], int]:
+    """Labels of a set of values formatted together, and the exponent of a common ×10ᵏ
+    factor (``"auto"`` beyond ``10^sci_limits``; 0: none).  ``sci_limits=None``: no
+    factor, the labels carry their exponent (``"sci"``) instead."""
+    style = style or NumberStyle()
+    vals = list(values)
+    finite = [v for v in vals if math.isfinite(v)]
+    if callable(fmt):
+        out = []
+        for v in vals:
+            if not math.isfinite(v):
+                out.append("")
+                continue
+            r = fmt(v)
+            out.append(style.wrap(_restyle(r, style)) if isinstance(r, str) else r)
+        return out, 0
+    if fmt not in PRESETS:
+        return [style.wrap(_restyle(fmt.format(v), style)) if math.isfinite(v) else ""
+                for v in vals], 0
+    if fmt == "int":
+        return [style.wrap(style.digits(_fixed(math.copysign(math.floor(abs(v) + 0.5), v), 0)))
+                if math.isfinite(v) else "" for v in vals], 0
+    if fmt == "sci":
+        return _exp_form(vals, style, 1), 0
+    if fmt == "eng":
+        return _exp_form(vals, style, 3), 0
+    if fmt == "si":
+        return _exp_form(vals, style, 3, si=True), 0
+    scale = 100.0 if fmt == "percent" else 1.0
+    exp = 0
+    big = max((abs(v) for v in finite), default=0.0) * scale
+    if fmt == "auto" and big:
+        if sci_limits is None:
+            pass
+        elif big >= 10.0 ** sci_limits[1] or big < 10.0 ** sci_limits[0]:
+            exp = math.floor(math.log10(big))
+    k = scale * 10.0 ** -exp
+    scaled = [v * k for v in vals]
+    d = _decimals(scaled, style.precision)
+    pct = "%" if fmt == "percent" else ""
+    return [style.wrap(style.digits(_fixed(v, d)) + pct) if math.isfinite(v) else ""
+            for v in scaled], exp
+
+
+def format_numbers(values: Sequence[float], fmt: Any = "auto",
+                   settings: Any = None) -> list[Any]:
+    """Labels of values formatted together; ``settings`` is a :class:`NumberStyle` or an
+    object with the number settings.  ``"auto"`` beyond 10⁵ or below 10⁻⁴ writes each
+    label in scientific form (there is no axis to carry a common factor)."""
+    style = settings if isinstance(settings, NumberStyle) or settings is None \
+        else NumberStyle.of(settings)
+    style = style or NumberStyle()
+    labels, exp = format_axis(values, fmt, style)
+    if exp:
+        return _exp_form(list(values), style, 1)
+    return labels
+
+
+def _check_minus(v: Any) -> str:
+    if v not in _MINUS:
+        raise ValueError(f"expected 'hyphen' or 'minus', got {v!r}")
+    return v
+
+
+def _check_precision(v: Any) -> int:
+    if isinstance(v, bool) or not isinstance(v, int) or not 1 <= v <= 15:
+        raise ValueError(f"expected an integer from 1 to 15, got {v!r}")
+    return v
+
+
+def _check_str(v: Any) -> str:
+    if not isinstance(v, str):
+        raise ValueError(f"expected a string, got {v!r}")
+    return v
+
+
+def number_settings() -> dict[str, Any]:
+    """The inherited number settings, for a ``SETTINGS`` table."""
+    from .settings import Setting
+    return {
+        "decimal_separator": Setting(_check_str, inherited=True,
+                                     doc="Decimal separator of numbers (`\".\"`)."),
+        "thousands_separator": Setting(_check_str, inherited=True,
+                                       doc="Thousands separator (`\"\"`: none)."),
+        "minus": Setting(_check_minus, inherited=True,
+                         doc="`hyphen` (`-`) or `minus` (U+2212, from an installed font)."),
+        "prefix": Setting(_check_str, inherited=True, doc="Text before every number."),
+        "suffix": Setting(_check_str, inherited=True, doc="Text after every number."),
+        "precision": Setting(_check_precision, inherited=True,
+                             doc="Significant digits of `auto`, `sci`, `eng`, `si` "
+                                 "(unset: as needed)."),
+    }
+
+
+NUMBER_SETTINGS: Callable[[], dict[str, Any]] = number_settings

plot_io/occupancy.py

@@ -0,0 +1,219 @@
+"""What the series cover inside the axes, on a coarse grid: used to place legends."""
+
+import math
+from typing import Any
+
+from pdf_io import arrays as _arrays
+
+__all__ = ["Occupancy", "thin", "N", "MAX_VERTICES", "MAX_POINTS"]
+
+#: Cells across each side of the axes.
+N = 64
+#: Polylines and curves are thinned to at most this many vertices before they are marked.
+MAX_VERTICES = 4096
+
+
+#: Points beyond this many are sampled (every k-th) before they are marked.
+MAX_POINTS = 50_000
+
+
+def _stride(n: int) -> int:
+    return max(1, -(-n // MAX_VERTICES))
+
+
+def thin(*columns: Any, limit: int = MAX_POINTS) -> tuple[Any, ...]:
+    """Every k-th item of each column, so that at most ``limit`` are left (data are thinned
+    before they are mapped to the page, which keeps legend placement fast)."""
+    n = min(len(c) for c in columns)
+    k = max(1, -(-n // limit))
+    if k == 1:
+        return columns
+    return tuple(c[:n:k] for c in columns)
+
+
+class Occupancy:
+    """An ``N`` × ``N`` grid of cells over the axes rectangle (page units); a cell is
+    occupied when some series draws in it."""
+
+    def __init__(self, rect: tuple[float, float, float, float]) -> None:
+        x0, y0, x1, y1 = rect
+        self.x0, self.y0 = x0, y0
+        self.cw = max(x1 - x0, 1e-9) / N
+        self.ch = max(y1 - y0, 1e-9) / N
+        self.cells = bytearray(N * N)
+        self._xe = [x0 + i * self.cw for i in range(N + 1)]
+        self._ye = [y0 + j * self.ch for j in range(N + 1)]
+
+    # -- marking ---------------------------------------------------------------------
+
+    def _col(self, x: float) -> int:
+        return min(N - 1, max(0, int((x - self.x0) / self.cw)))
+
+    def _row(self, y: float) -> int:
+        return min(N - 1, max(0, int((y - self.y0) / self.ch)))
+
+    def _span(self, r: int, c0: int, c1: int) -> None:
+        if c1 >= c0:
+            self.cells[r * N + c0:r * N + c1 + 1] = b"\x01" * (c1 - c0 + 1)
+
+    def points(self, px: Any, py: Any, radius: float = 0.0) -> None:
+        """Marks the cells holding points (counted in C; points outside are ignored), and
+        the cells within ``radius`` (pt, a marker's half size) of those."""
+        if not len(px):
+            return
+        _, _, counts = _arrays.histogram2d(px, py, self._xe, self._ye)
+        kx = int(radius / self.cw + 0.5)
+        ky = int(radius / self.ch + 0.5)
+        cells = self.cells
+        for k, c in enumerate(counts):
+            if not c:
+                continue
+            if not kx and not ky:
+                cells[k] = 1
+                continue
+            r, col = divmod(k, N)
+            c0, c1 = max(0, col - kx), min(N - 1, col + kx)
+            for rr in range(max(0, r - ky), min(N - 1, r + ky) + 1):
+                self._span(rr, c0, c1)
+
+    def lines(self, px: Any, py: Any) -> None:
+        """Marks the cells a polyline passes through (NaN breaks it); segments are sampled
+        at half a cell, so long segments count along their whole length (at most
+        ``8 · MAX_VERTICES`` samples in all, spread by length)."""
+        n = min(len(px), len(py))
+        if n == 0:
+            return
+        s = _stride(n)
+        verts = [(px[i], py[i]) for i in range(0, n, s)]
+        step = 0.5 * min(self.cw, self.ch)
+        counts = []
+        for (x0, y0), (x1, y1) in zip(verts, verts[1:]):
+            d = max(abs(x1 - x0), abs(y1 - y0))
+            counts.append(int(d / step) if d == d else -1)
+        total = sum(c for c in counts if c > 0)
+        budget = 8 * MAX_VERTICES
+        scale = budget / total if total > budget else 1.0
+        xs, ys = [], []
+        for (x0, y0), (x1, y1), k in zip(verts, verts[1:], counts):
+            if k < 0:
+                continue
+            k = int(k * scale)
+            for j in range(k + 1):
+                t = j / (k + 1)
+                xs.append(x0 + (x1 - x0) * t)
+                ys.append(y0 + (y1 - y0) * t)
+        x, y = verts[-1]
+        if x == x and y == y:
+            xs.append(x)
+            ys.append(y)
+        self.points(xs, ys)
+
+    def rects(self, x0: Any, y0: Any, x1: Any, y1: Any) -> None:
+        """Marks the cells under rectangles (any corner order; NaN rectangles skipped)."""
+        X0, Y0 = self.x0, self.y0
+        X1, Y1 = X0 + N * self.cw, Y0 + N * self.ch
+        for a, b, c, d in zip(x0, y0, x1, y1):
+            if a != a or b != b or c != c or d != d:
+                continue
+            a, c = min(a, c), max(a, c)
+            b, d = min(b, d), max(b, d)
+            if c < X0 or a > X1 or d < Y0 or b > Y1:
+                continue
+            c0, c1 = self._col(a), self._col(c)
+            for r in range(self._row(b), self._row(d) + 1):
+                self._span(r, c0, c1)
+
+    def band(self, t: Any, lo: Any, hi: Any, horizontal: bool = False) -> None:
+        """Marks the region between two curves sharing the coordinate ``t`` (page x, or page
+        y when ``horizontal``): per grid column (row), from the least to the largest value
+        of the samples in it, with samples added at half a cell along ``t``."""
+        n = min(len(t), len(lo), len(hi))
+        if n == 0:
+            return
+        size = self.ch if horizontal else self.cw
+        index = self._row if horizontal else self._col
+        mins = [math.inf] * N
+        maxs = [-math.inf] * N
+        s = _stride(n)
+        prev: tuple[float, float, float] | None = None
+
+        def put(tv: float, a: float, b: float) -> None:
+            k = index(tv)
+            lo_, hi_ = (a, b) if a <= b else (b, a)
+            if lo_ < mins[k]:
+                mins[k] = lo_
+            if hi_ > maxs[k]:
+                maxs[k] = hi_
+
+        for i in range(0, n, s):
+            tv, a, b = t[i], lo[i], hi[i]
+            if tv != tv or a != a or b != b:
+                prev = None
+                continue
+            if prev is not None:
+                k = int(abs(tv - prev[0]) / (0.5 * size))
+                for j in range(1, k + 1):
+                    f = j / (k + 1)
+                    put(prev[0] + (tv - prev[0]) * f, prev[1] + (a - prev[1]) * f,
+                        prev[2] + (b - prev[2]) * f)
+            put(tv, a, b)
+            prev = (tv, a, b)
+        T0 = self.y0 if horizontal else self.x0
+        T1 = T0 + N * size
+        for k in range(N):
+            if mins[k] > maxs[k]:
+                continue
+            centre = T0 + (k + 0.5) * size
+            if not T0 <= centre <= T1:
+                continue
+            if horizontal:
+                self._span(k, self._col(mins[k]), self._col(maxs[k]))
+            else:
+                for r in range(self._row(mins[k]), self._row(maxs[k]) + 1):
+                    self.cells[r * N + k] = 1
+
+    # -- queries ---------------------------------------------------------------------
+
+    def _sums(self) -> list[int]:
+        """Summed-area table: ``s[(r) * (N + 1) + c]`` = occupied cells above and left."""
+        s = [0] * ((N + 1) * (N + 1))
+        cells = self.cells
+        for r in range(N):
+            run = 0
+            base, prev = (r + 1) * (N + 1), r * (N + 1)
+            for c in range(N):
+                run += cells[r * N + c]
+                s[base + c + 1] = s[prev + c + 1] + run
+        return s
+
+    def covered(self, x: float, y: float, w: float, h: float, sums: list[int] | None = None) -> float:
+        """Fraction of the cells whose centres lie in the box ``(x, y, w, h)`` that are
+        occupied (0 when the box holds no cell centre).  ``sums`` (from :meth:`_sums`)
+        makes repeated queries constant time."""
+        c0 = max(0, math.ceil((x - self.x0) / self.cw - 0.5))
+        c1 = min(N - 1, math.floor((x + w - self.x0) / self.cw - 0.5))
+        r0 = max(0, math.ceil((y - self.y0) / self.ch - 0.5))
+        r1 = min(N - 1, math.floor((y + h - self.y0) / self.ch - 0.5))
+        if c1 < c0 or r1 < r0:
+            return 0.0
+        if sums is None:
+            hit = sum(self.cells[r * N + c0:r * N + c1 + 1].count(1) for r in range(r0, r1 + 1))
+        else:
+            M = N + 1
+            hit = (sums[(r1 + 1) * M + c1 + 1] - sums[r0 * M + c1 + 1]
+                   - sums[(r1 + 1) * M + c0] + sums[r0 * M + c0])
+        return hit / ((c1 - c0 + 1) * (r1 - r0 + 1))
+
+    def free_boxes(self, w: float, h: float, pad: float) -> list[tuple[float, float]]:
+        """Top-left corners, one cell apart, of the boxes ``w`` × ``h`` inside the axes
+        (``pad`` from their edges) that cover no occupied cell."""
+        sums = self._sums()
+        x_lo, x_hi = self.x0 + pad, self.x0 + N * self.cw - pad - w
+        y_lo, y_hi = self.y0 + pad, self.y0 + N * self.ch - pad - h
+        if x_hi < x_lo or y_hi < y_lo:
+            return []
+        nx = int((x_hi - x_lo) / self.cw)
+        ny = int((y_hi - y_lo) / self.ch)
+        xs = [x_lo + i * self.cw for i in range(nx + 1)] + [x_hi]
+        ys = [y_lo + j * self.ch for j in range(ny + 1)] + [y_hi]
+        return [(x, y) for y in ys for x in xs if self.covered(x, y, w, h, sums) == 0.0]

plot_io/palettes.py

@@ -0,0 +1,142 @@
+"""Palettes: the colors series take in turn.
+
+A palette is a list of colors, a registered name, or a function ``n -> colors`` called
+with the number of series that need a color (ggplot2's evenly spaced hues depend on it).
+"""
+
+import math
+from collections.abc import Callable
+from typing import Any
+
+__all__ = ["register_palette", "palette_names", "palette_colors", "check_palette", "hue"]
+
+
+def _luv_to_hex(L: float, C: float, H: float) -> str:
+    """CIE LCh(uv) (D65) to sRGB hex, as R's ``hcl()`` (channels clamped)."""
+    h = math.radians(H)
+    U, V = C * math.cos(h), C * math.sin(h)
+    xn, yn, zn = 95.047, 100.0, 108.883
+    un = 4 * xn / (xn + 15 * yn + 3 * zn)
+    vn = 9 * yn / (xn + 15 * yn + 3 * zn)
+    Y = yn * (((L + 16) / 116) ** 3 if L > 8 else L / 903.3)
+    u = U / (13 * L) + un
+    v = V / (13 * L) + vn
+    X = 9.0 * Y * u / (4 * v)
+    Z = -X / 3 - 5 * Y + 3 * Y / v
+    X, Y, Z = X / 100, Y / 100, Z / 100
+    rgb = (3.240479 * X - 1.537150 * Y - 0.498535 * Z,
+           -0.969256 * X + 1.875992 * Y + 0.041556 * Z,
+           0.055648 * X - 0.204043 * Y + 1.057311 * Z)
+
+    def gamma(c: float) -> float:
+        c = 1.055 * c ** (1 / 2.4) - 0.055 if c > 0.0031308 else 12.92 * c
+        return min(1.0, max(0.0, c))
+
+    return "#" + "".join("%02X" % round(255 * gamma(c)) for c in rgb)
+
+
+def hue(n: int, c: float = 100.0, lum: float = 65.0, start: float = 15.0) -> tuple[str, ...]:
+    """ggplot2's default discrete palette (``scales::hue_pal()``): ``n`` hues evenly
+    spaced from ``start`` degrees, at chroma ``c`` and luminance ``lum``."""
+    return tuple(_luv_to_hex(lum, c, start + 360.0 * i / n) for i in range(max(n, 1)))
+
+
+def _rgb(r: float, g: float, b: float) -> str:
+    return "#%02X%02X%02X" % tuple(round(255 * v) for v in (r, g, b))
+
+
+_PALETTES: dict[str, Any] = {
+    # plot_io's default: Okabe–Ito, extended with indigo and dark brown
+    "okabe_ito": ("#0072B2", "#E69F00", "#009E73", "#D55E00", "#CC79A7", "#56B4E9",
+                  "#F0E442", "#000000", "#332288", "#661100"),
+    # matplotlib ≥ 2.0 ("tab10", d3's category10)
+    "tab10": ("#1F77B4", "#FF7F0E", "#2CA02C", "#D62728", "#9467BD", "#8C564B", "#E377C2",
+              "#7F7F7F", "#BCBD22", "#17BECF"),
+    # matplotlib 1.x: b, g, r, c, m, y, k
+    "matplotlib_classic": ("#0000FF", "#008000", "#FF0000", "#00BFBF", "#BF00BF", "#BFBF00",
+                           "#000000"),
+    # Vega-Lite (Tableau 10)
+    "tableau10": ("#4C78A8", "#F58518", "#E45756", "#72B7B2", "#54A24B", "#EECA3B",
+                  "#B279A2", "#FF9DA6", "#9D755D", "#BAB0AC"),
+    # seaborn
+    "deep": ("#4C72B0", "#DD8452", "#55A868", "#C44E52", "#8172B3", "#937860", "#DA8BC3",
+             "#8C8C8C", "#CCB974", "#64B5CD"),
+    "muted": ("#4878D0", "#EE854A", "#6ACC64", "#D65F5F", "#956CB4", "#8C613C", "#DC7EC0",
+              "#797979", "#D5BB67", "#82C6E2"),
+    "pastel": ("#A1C9F4", "#FFB482", "#8DE5A1", "#FF9F9B", "#D0BBFF", "#DEBB9B", "#FAB0E4",
+               "#CFCFCF", "#FFFEA3", "#B9F2F0"),
+    "bright": ("#023EFF", "#FF7C00", "#1AC938", "#E8000B", "#8B2BE2", "#9F4800", "#F14CC1",
+               "#A3A3A3", "#FFC400", "#00D7FF"),
+    "dark": ("#001C7F", "#B1400D", "#12711C", "#8C0800", "#591E71", "#592F0D", "#A23582",
+             "#3C3C3C", "#B8850A", "#006374"),
+    "colorblind": ("#0173B2", "#DE8F05", "#029E73", "#D55E00", "#CC78BC", "#CA9161",
+                   "#FBAFE4", "#949494", "#ECE133", "#56B4E9"),
+    # ggplot2 (n-dependent)
+    "hue": hue,
+    # MATLAB R2014b+ ("lines")
+    "matlab": tuple(_rgb(*c) for c in ((0, 0.4470, 0.7410), (0.8500, 0.3250, 0.0980),
+                                       (0.9290, 0.6940, 0.1250), (0.4940, 0.1840, 0.5560),
+                                       (0.4660, 0.6740, 0.1880), (0.3010, 0.7450, 0.9330),
+                                       (0.6350, 0.0780, 0.1840))),
+    # Chart.js 4 (colors plugin, border colors)
+    "chartjs": ("#36A2EB", "#FF6384", "#FF9F40", "#FFCD56", "#4BC0C0", "#9966FF", "#C9CBCF"),
+    # Observable Plot (d3's observable10)
+    "observable10": ("#4269D0", "#EFB118", "#FF725C", "#6CC5B0", "#3CA951", "#FF8AB7",
+                     "#A463F2", "#97BBF5", "#9C6B4E", "#9498A0"),
+    # Excel 2013+ (Office 2013 theme accents, then their darker shades)
+    "office": ("#4472C4", "#ED7D31", "#A5A5A5", "#FFC000", "#5B9BD5", "#70AD47", "#264478",
+               "#9E480E", "#636363", "#997300"),
+    # The Economist (ggthemes economist_pal, pre-2017 chart colors)
+    "economist": ("#6794A7", "#014D64", "#76C0C1", "#01A2D9", "#7AD2F6", "#00887D",
+                  "#ADADAD", "#7C260B", "#EE8F71", "#A18376"),
+    # FiveThirtyEight (matplotlib's fivethirtyeight style)
+    "fivethirtyeight": ("#008FD5", "#FC4F30", "#E5AE38", "#6D904F", "#8B8B8B", "#810F7C"),
+    # greys, for Tufte's style
+    "greys": ("#000000", "#666666", "#999999", "#CCCCCC"),
+    # plotly ("plotly" template colorway)
+    "plotly": ("#636EFA", "#EF553B", "#00CC96", "#AB63FA", "#FFA15A", "#19D3F3", "#FF6692",
+               "#B6E880", "#FF97FF", "#FECB52"),
+}
+
+
+def palette_names() -> list[str]:
+    return sorted(_PALETTES)
+
+
+def register_palette(name: str, palette: Any) -> None:
+    """Register a list of colors, or a function ``n -> colors``, as ``name``."""
+    _PALETTES[name.strip().lower()] = palette if callable(palette) else _colors(palette)
+
+
+def _colors(v: Any) -> tuple[Any, ...]:
+    from .settings import color
+
+    cols = tuple(color(c) for c in v)
+    if not cols:
+        raise ValueError("a palette needs at least one color")
+    return cols
+
+
+def check_palette(v: Any) -> Any:
+    """A palette name, a function ``n -> colors``, or a list of colors."""
+    if isinstance(v, str):
+        key = v.strip().lower()
+        if key not in _PALETTES:
+            import difflib
+            near = difflib.get_close_matches(key, _PALETTES, n=1)
+            hint = f" (did you mean {near[0]!r}?)" if near else ""
+            raise ValueError(f"unknown palette {v!r}{hint}")
+        return key
+    if callable(v):
+        return v
+    return _colors(v)
+
+
+def palette_colors(value: Any, n: int = 1) -> tuple[Any, ...]:
+    """The colors of a palette for ``n`` series."""
+    if isinstance(value, str):
+        value = _PALETTES[value]
+    if callable(value):
+        f: Callable[[int], Any] = value
+        return _colors(f(max(n, 1)))
+    return tuple(value)