plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/layers/base.py

@@ -0,0 +1,630 @@
+"""The model of a plot type's call: data plus settings (:class:`Series`).
+
+A series is what ``p.scatter(…)`` or ``plt.Box(…)`` returns.  It holds the data (its
+:class:`~plot_io.columns.Columns`, ``cols``) and the settings, and one method,
+:meth:`Series.layers`: the preset that turns it into a :class:`~plot_io.layers.core.Call`
+(its layers, legend entries and what the axes and color maps need) in each render.
+:class:`SeriesMeta` resolves ``data=`` columns, reads the data arguments into the
+``Columns`` and splits ``group=`` calls before a series is made.
+"""
+
+import math
+from typing import Any
+
+from .. import groups
+from ..color.values import color as _color  # noqa: F401  (re-exported for presets)
+from ..color.values import VARIANT_DOC, check_variant
+from ..levels import level_order
+from .stats import check_estimate, check_interval
+from ..limits import check_limits
+from ..scales import NUMERIC_SCALES
+from ..settings import (Setting, Settings, dpi_or_bool, number, one_of, route, simplify_value,
+                        table, text)
+from ..units import NeedsScale
+from ..validators import length, typed
+from ..values import lazy
+
+__all__ = ["Series", "SeriesMeta", "column", "COMMON", "common", "upward_message",
+           "slot_width", "slot_parts"]
+
+_check_color_map = lazy("color.maps", "check_series_map")
+_check_size_map = lazy("values", "check_size_map")
+_check_color_axis = lazy("mapped", "check_color_axis")
+_check_size_axis = lazy("mapped", "check_size_axis")
+
+
+@typed("bool | str | Mapping[str, Any]")
+def colorbar_value(v: Any) -> Any:
+    """A ``colorbar=`` value: ``True``, ``False``, a place, or a dict of colorbar
+    settings."""
+    from ..guides import where_of
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, dict):
+        return dict(v)
+    if isinstance(v, str) and "visible" not in where_of(v):
+        return v
+    raise ValueError(f"expected True, False, a place or a dict of colorbar settings, "
+                     f"got {v!r}")
+
+
+@typed("Literal['key', 'legend', False] | Sequence[SupportsFloat]")
+def _size_key(v: Any) -> Any:
+    if v is False:
+        return v
+    if isinstance(v, str) and v.strip().lower() in ("key", "legend"):
+        return v.strip().lower()
+    if isinstance(v, (list, tuple)) and v:
+        return [float(x) for x in v]
+    raise ValueError(f"expected 'key', 'legend', False or a list of values, got {v!r}")
+
+
+COMMON = dict(
+    name=lambda: Setting(text, doc="Legend entry; unset: not in the legend."),
+    opacity=lambda: Setting(number(0, 1), inherited=True,
+                            doc="Opacity, multiplying the colors' own."),
+    z=lambda: Setting(number(), doc="Drawing order (higher on top); default: call order."),
+    rasterize=lambda: Setting(dpi_or_bool, inherited=True,
+                              doc="`True` or a dpi: drawn as an image inside the PDF."),
+    simplify=lambda: Setting(simplify_value, inherited=True,
+                             doc="`\"auto\"`, `True`, a dpi, `False`, or a `Simplify` (or "
+                                 "a dict of its fields): vec_io's `simplify`."),
+    text_color=lambda: Setting(_color, inherited=True, doc="Text color."),
+    plain_color=lambda: Setting(_color, inherited=True,
+                                doc="Color when the series needs no hue (no levels, one "
+                                    "color, no `name`), the plot's turn kept; unset: the "
+                                    "plot's next color."),
+    line_width=lambda: Setting(length(lo=0), inherited=True, doc="Line width."),
+    color_variant=lambda: Setting(check_variant, inherited=True, doc=VARIANT_DOC),
+    color_map=lambda: Setting(_check_color_map,
+                              doc="The colors of numbers given as colors, and of the series' "
+                                  "levels, sets and group members: a `ColorMap`, a map name "
+                                  "or colors (alias `cmap`), a dict level → color, `\"auto\"` "
+                                  "(numbers: `sequential_map`, or `diverging_map` about a "
+                                  "`center`; levels: the plot's `qualitative_map` colors) "
+                                  "or a kind (`\"sequential\"`…: that kind's map)."),
+    center=lambda: Setting(number(),
+                           doc="Numbers given as colors: the value at the color map's "
+                               "middle (`color_map=\"auto\"`: `diverging_map`); the "
+                               "limits symmetric about it unless given."),
+    color_limits=lambda: Setting(check_limits,
+                                 doc="Limits of the series' color axis, as an axis' `limits`: "
+                                     "`\"-2/2\"`, `\"0/max\"`, `\"q:0.01/q:0.99\"`, "
+                                     "`\"-m/m\"` (symmetric about the `center`, or 0, `m` "
+                                     "the farthest value); unset: `\"auto\"`, the values' "
+                                     "range."),
+    color_scale=lambda: Setting(one_of(*NUMERIC_SCALES),
+                                doc="Scale of the series' color axis (`log`, `sqrt`, …); "
+                                    "unset: `linear`."),
+    color_axis=lambda: Setting(_check_color_axis, expr=False,
+                               doc="A shared `ColorAxis` (`figure.color_axis(…)`) in place of "
+                                   "the series' own: it holds the map, limits and scale."),
+    colorbar=lambda: Setting(colorbar_value, expr=False,
+                             doc="A colorbar of the series' color axis attached to the plot "
+                                 "(once): `True`, a place (a side or a place inside the "
+                                 "axes) or a dict of colorbar settings; `False`: none."),
+    size_key=lambda: Setting(_size_key,
+                             doc="With mapped sizes: a key attached to the plot, as a "
+                                 "colorbar's (`\"key\"`), sample rows in the legend "
+                                 "(`\"legend\"`), none (`False`), or the values to show (a "
+                                 "list: a key with a marker at each)."),
+    size_map=lambda: Setting(_check_size_map,
+                             doc="The sizes numbers in `size` are drawn with: a `SizeMap` "
+                                 "(alias `smap`); without it (or `size_axis`), numbers are "
+                                 "sizes in px."),
+    size_limits=lambda: Setting(check_limits,
+                                doc="Limits of the series' size axis, as an axis' `limits`; "
+                                    "unset: `\"auto\"`."),
+    size_scale=lambda: Setting(one_of(*NUMERIC_SCALES),
+                               doc="Scale of the series' size axis; unset: `linear`."),
+    size_axis=lambda: Setting(_check_size_axis, expr=False,
+                              doc="A shared `SizeAxis` (`figure.size_axis(…)`) in place of "
+                                  "the series' own: it holds the sizes, limits and scale."),
+    markers=lambda: Setting(level_order,
+                            doc="Markers of marker levels: a list taken in turn, or a dict "
+                                "level → marker; default: circle, square, triangle_up…"),
+    line_styles=lambda: Setting(level_order,
+                                doc="Line styles of line_style levels: a list taken in turn, "
+                                    "or a dict level → style; default: solid, dashed, dotted, "
+                                    "dashdot."),
+    level_order=lambda: Setting(level_order,
+                                doc="Levels first, in order (kept when absent): a list, or a "
+                                    "dict of lists by column."),
+    estimate=lambda: Setting(check_estimate,
+                             doc="Replicates summarized per position (and set, and level): "
+                                 "`\"mean\"`, `\"median\"` or a function of an array; "
+                                 "default none (each value drawn)."),
+    interval=lambda: Setting(check_interval,
+                             doc="With `estimate`, the interval drawn as error bars: "
+                                 "`\"ci\"` (95 % t interval of the mean; `(\"ci\", 0.9)`), "
+                                 "`\"se\"`, `\"sd\"`, `\"pi\"` (95 % percentile interval "
+                                 "of the values; `(\"pi\", 0.5)`); default none."),
+    level_missing=lambda: Setting(one_of("keep", "drop"),
+                                  doc="Missing values of a level column: `\"keep\"` (a "
+                                      "level `\"nan\"`) or `\"drop\"` (their rows left "
+                                      "out)."),
+)
+
+#: Settings a name of :func:`common` brings along: the color of a series without a legend
+#: entry, the color variant (every series has ``z``), the series' color and size axes, the
+#: settings of level axes.
+BUNDLES = {"name": ("plain_color",), "z": ("color_variant",),
+           "color_map": ("color_limits", "color_scale", "center", "color_axis", "colorbar"),
+           "size_map": ("size_limits", "size_scale", "size_axis"),
+           "level_order": ("level_missing", "color_map"),
+           "estimate": ("interval",)}
+
+
+#: Data arguments whose strings name columns when ``data`` is given (others than the
+#: positional ones).
+DATA_KEYS = ("color", "edge_color", "marker_color", "marker_edge_color", "size", "opacity",
+             "group", "draw_order", "x_error", "y_error", "weights", "positions", "x", "y",
+             "names", "marker", "line_style", "labels")
+#: Of those, the ones whose strings must be columns.
+MUST_BE_COLUMNS = ("group", "weights", "positions")
+#: Per-point keyword arguments split among the members of a group.
+SPLIT_KEYS = ("color", "edge_color", "marker_color", "marker_edge_color", "size", "opacity",
+              "marker", "x_error", "y_error", "draw_order", "weights", "x", "y", "names",
+              "labels")
+
+
+def call_signature(fn: Any, drop: tuple[str, ...] = (), first: tuple[str, ...] = ()) -> Any:
+    """The signature of ``fn`` without annotations and the parameters in ``drop``, after
+    positional parameters named ``first``."""
+    import inspect
+    sig = inspect.signature(fn)
+    params = [inspect.Parameter(n, inspect.Parameter.POSITIONAL_OR_KEYWORD) for n in first]
+    params += [p.replace(annotation=p.empty) for n, p in sig.parameters.items()
+               if n not in drop]
+    return inspect.Signature(params)
+
+
+def _positional(cls: type) -> list[str]:
+    import inspect
+    names = cls.__dict__.get("_POSITIONAL")
+    if names is None:
+        sig = inspect.signature(getattr(cls, "__init__"))
+        names = [n for n, p in sig.parameters.items()
+                 if n not in ("self", "plot") and p.kind in (p.POSITIONAL_ONLY,
+                                                             p.POSITIONAL_OR_KEYWORD)]
+        setattr(cls, "_POSITIONAL", names)
+    return names
+
+
+_REQUIRED = object()
+
+
+def _defaults(cls: type) -> dict[str, Any]:
+    """The defaults of ``cls.__init__``'s parameters (:data:`_REQUIRED`: none)."""
+    import inspect
+    out = cls.__dict__.get("_DEFAULTS")
+    if out is None:
+        sig = inspect.signature(getattr(cls, "__init__"))
+        out = {n: (_REQUIRED if p.default is p.empty else p.default)
+               for n, p in sig.parameters.items()}
+        setattr(cls, "_DEFAULTS", out)
+    return out
+
+
+def _length(v: Any) -> int | None:
+    if v is None or isinstance(v, (str, bytes, dict, int, float)):
+        return None
+    try:
+        return len(v)
+    except TypeError:
+        return None
+
+
+class SeriesMeta(type):
+    """Resolves ``data`` columns, reads the data arguments (the type's ``DATA``) into a
+    :class:`~plot_io.columns.Columns` and splits ``group`` calls before a series is made."""
+
+    @property
+    def __signature__(cls) -> Any:
+        """The parameters of ``__init__`` (without ``self``; ``plot`` keyword-only, as
+        :meth:`__call__` takes it; ``y=None`` after the first when a ``y`` makes another
+        type), for :func:`inspect.signature`."""
+        import inspect
+        sig = call_signature(getattr(cls, "__init__"), drop=("self",))
+        params = [p.replace(kind=p.KEYWORD_ONLY) if n == "plot" else p
+                  for n, p in sig.parameters.items()]
+        if getattr(cls, "with_y", None) is not None and "y" not in sig.parameters:
+            params.insert(1, inspect.Parameter("y", inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                                               default=None))
+        return sig.replace(parameters=sorted(params, key=lambda p: p.kind))
+
+    def __call__(cls, *args: Any, **kw: Any) -> Any:
+        from .. import tables
+        from ..settings import canonical_kwargs
+        with_y = getattr(cls, "with_y", None)
+        if with_y is not None and (len(args) == 2 or "y" in kw):
+            return with_y()(*args, **kw)
+        names = _positional(cls)
+        kw = canonical_kwargs(kw, getattr(cls, "SETTINGS", {}), cls.__name__)
+        if len(args) > len(names):
+            raise TypeError(f"{cls.__name__}() takes {len(names)} positional arguments")
+        pos = dict(zip(names, args))
+        for n in names:
+            if n in kw:
+                if n in pos:
+                    raise TypeError(f"{cls.__name__}() got two values for {n!r}")
+                pos[n] = kw.pop(n)
+        plot = kw.get("plot")
+        data = kw.pop("data", None)
+        if data is None and plot is not None:
+            data = plot.resolve("data")
+        columns: dict[str, Any] = {}
+        orders: dict[str, Any] = {}
+        if data is not None:
+            for n, v in list(pos.items()):
+                if isinstance(v, str):
+                    pos[n], orders[n] = tables.column(data, v)
+                    columns[n] = v
+            for n in DATA_KEYS:
+                v = kw.get(n)
+                if isinstance(v, str) and n not in pos:
+                    if tables.has_column(data, v):
+                        if n in ("color", "edge_color", "marker_color", "marker_edge_color"):
+                            from ..color.values import color
+                            try:
+                                color(v)
+                                tables.color_name_warning(v)
+                            except ValueError:
+                                pass
+                        kw[n], orders[n] = tables.column(data, v)
+                        columns[n] = v
+                    elif n in MUST_BE_COLUMNS:
+                        raise ValueError(f"no column {v!r} in data")
+        from ..columns import Columns, Keys
+        kinds: dict[str, str] = getattr(cls, "DATA", {})
+        if "categories" not in kinds.values():
+            for store in (pos, kw):
+                for n in ("x", "y"):
+                    if orders.get(n) is not None and n in store and kinds.get(n) != "cells":
+                        store[n] = Keys(store[n], orders[n])
+        from .. import times as _times
+        names = list(kinds)
+        if len(names) > 1 and names[0] == "x" and pos.get(names[1]) is None \
+                and kinds[names[1]] in ("numbers", "sets"):
+            index: Any = getattr(pos.get("x"), "index", None)       # a pandas date index
+            if getattr(getattr(index, "dtype", None), "kind", None) == "M":
+                pos[names[1]] = pos["x"]
+                pos["x"] = index if getattr(index, "tz", None) is None else list(index)
+        time_params: dict[str, Any] = {}
+        for store in (pos, kw):
+            for n in ("x", "y", "positions"):
+                v = store.get(n)
+                if v is not None and _times.is_time_like(v):
+                    store[n], time_params[n] = _times.to_seconds(v)
+        kw = cls._at_call(pos, kw)                  # type: ignore[attr-defined]
+        defaults = _defaults(cls)
+        if any(n not in pos and defaults.get(n, 0) is _REQUIRED for n in kinds):
+            from ..settings import SAME_IDEA
+            for k in kw:
+                if SAME_IDEA.get(k) in kinds and SAME_IDEA[k] not in pos:
+                    raise TypeError(f"{cls.__name__}: unknown argument {k!r} (did you mean "
+                                    f"{SAME_IDEA[k]!r}?)")
+            return super().__call__(**pos, **kw)            # the missing argument's error
+        kind = getattr(cls, "LEVELS", None)
+        if kind == "grid" and "group" in kw:
+            raise ValueError(f"{cls.__name__}: group= splits points, not grids; use plt.facet")
+        from .. import levels
+        found = levels.detect(cls, kw, columns, orders)
+        given = {n: pos[n] if n in pos else defaults.get(n) for n in kinds}
+        split = "group" in kw and getattr(cls, "SPLITS_GROUPS", True) and not found
+        cols = Columns.build(kinds, given, kw, columns, orders, time_params,
+                             getattr(cls, "ITEMS", "sets"),
+                             read=not split and not (found and kind == "split"))
+        if split:
+            return cls._grouped(cols, pos, kw)
+        for k in ("group_order", "group_missing", "group_colors"):
+            if k in kw:
+                raise ValueError(f"{k} applies with group=")
+        if found:
+            return levels.make(cls, cols, pos, kw, found)
+        return cls._make(cols, pos, kw)
+
+    def _make(cls, cols: Any, pos: dict[str, Any], kw: dict[str, Any]) -> Any:
+        """A series of ``cls`` reading ``cols`` (``pos``: its data arguments as given)."""
+        s: Any = object.__new__(cls)  # type: ignore[arg-type]
+        s.cols = cols
+        s.__init__(**pos, **kw)
+        return s
+
+    def _grouped(cls, cols: Any, pos: dict[str, Any], kw: dict[str, Any]) -> Any:
+        from .. import tables
+        labels = kw.pop("group")
+        given = kw.pop("group_order", None)
+        missing = kw.pop("group_missing", "keep")
+        if missing not in ("keep", "drop"):
+            raise ValueError("group_missing is 'keep' or 'drop'")
+        colors = kw.pop("group_colors", None) or {}
+        from ..mapped import group_axes
+        group_axes(cls, kw)
+        bar = kw.pop("colorbar", None)            # one colorbar of the shared color axis
+        n = _length(labels)
+        if n is None:
+            raise ValueError("group needs one label per point")
+        if hasattr(labels, "tolist"):
+            labels = labels.tolist()
+        keys, rows = tables.group_keys(labels, cols.orders.get("group"), given, missing)
+        auto_marker = kw.get("marker") == "auto"
+        auto_style = kw.get("line_style") == "auto"
+        title = cols.titles.get("group")
+        members: list[Any] = []
+        token = object()                               # the members drawn in data order
+        for k, (key, idx) in enumerate(zip(keys, rows)):
+            ck = cols.take(idx, n)
+            kk = {}
+            for nm, v in kw.items():
+                if nm in SPLIT_KEYS and _length(v) == n and not (
+                        isinstance(v, tuple) and len(v) in (3, 4)):
+                    v = tables.take(v, idx)
+                kk[nm] = v
+            if auto_marker:
+                kk["marker"] = tables.MARKER_CYCLE[k % len(tables.MARKER_CYCLE)]
+            if auto_style:
+                kk["line_style"] = tables.LINE_STYLE_CYCLE[k % len(tables.LINE_STYLE_CYCLE)]
+            if key in colors:
+                kk["color"] = colors[key]
+            kk.setdefault("name", str(key))
+            if k > 0 and kk.get("plot") is None and members:
+                kk["plot"] = members[0].plot
+            pk = {nm: ck.args[nm] if nm in ck.args else (
+                tables.take(v, idx) if _length(v) == n else v) for nm, v in pos.items()}
+            m = cls._make(ck, pk, kk)
+            m.__dict__["_member"] = (k, len(keys))     # its color of an own color_map
+            m.__dict__["_order_rows"] = (token, idx)
+            members.append(m)
+        if bar is not None and members:
+            members[-1].set(colorbar=bar)
+        group = tables.SeriesGroup(members, keys, title)
+        if members and title is not None:
+            members[0].plot._legend_title = title
+        return group
+
+
+def common(*names: str, docs: dict[str, str] | None = None) -> dict[str, Setting]:
+    """The ``COMMON`` settings ``names``, and members of the :class:`~plot_io.groups.Font`
+    group (``font_family`` brings the whole face along; ``color_map`` and ``size_map``
+    bring the settings of the series' color and size axes, :data:`BUNDLES`); ``docs``:
+    the type's own doc of some of them."""
+    font = [n for n in groups.Font.MEMBERS if n in names
+            or (n in groups.Font.FACE and "font_family" in names)]
+    names = tuple(m for n in names for m in (n, *BUNDLES.get(n, ())))
+    out = {n: COMMON[n]() for n in names if n not in groups.Font.MEMBERS}
+    for n, doc in (docs or {}).items():
+        out[n].doc = doc
+    return {**out, **groups.Font.embed(only=font)}
+
+
+def upward_message(kind: str, levels: list[tuple[str, str, dict[str, Any]]]) -> str:
+    """The error of keywords that belong to levels above an object that already exist:
+    keywords set the levels above only when the call creates them.  ``levels``:
+    ``(level, how to reach it, keywords)``."""
+    parts = []
+    for level, target, kw in levels:
+        if kw:
+            names = ", ".join(f"{k}=" for k in kw)
+            args = ", ".join(f"{k}=…" for k in kw)
+            parts.append(f"{names} of the existing {level}: use {target}.set({args})")
+    return f"{kind}: " + "; ".join(parts)
+
+
+class Series(Settings, metaclass=SeriesMeta):
+    """Base of every plot type's model.  ``plot=None`` creates a plot (and its figure).
+
+    A subclass declares its ``DATA`` and ``SETTINGS`` and implements :meth:`layers`."""
+
+    SETTINGS: dict[str, Setting] = table(**common("name", "opacity", "z", "rasterize",
+                                                  "simplify"))
+
+    #: The data arguments and their slot kinds (:data:`plot_io.columns.KINDS`), read into
+    #: :attr:`cols` once per call.
+    DATA: dict[str, str] = {}
+    #: The data of the call (:class:`~plot_io.columns.Columns`).
+    cols: Any
+    #: Whether ``group=`` makes one series per group (else the series takes it).
+    SPLITS_GROUPS = True
+
+    def __init__(self, *, plot: Any = None, **settings: Any) -> None:
+        from ..figure import Figure
+        from ..plot import Plot
+
+        own, plot_kw, fig_kw = route(settings, [type(self), Plot, Figure],
+                                     extra={1: Plot.CALL_EXTRA})
+        if plot is None:
+            plot = Plot(**plot_kw, **fig_kw)
+        elif plot_kw or fig_kw:
+            raise ValueError(upward_message(self.kind, [("plot", "plot", plot_kw),
+                                                        ("figure", "plot.figure", fig_kw)]))
+        self.plot = plot
+        super().__init__(**own)
+        if "_of" not in self.__dict__:          # a level member is drawn by its series
+            plot._add_series(self)
+        self._ready = True
+        self._attach_bar()
+
+    def _parent(self) -> Settings:
+        return self.plot
+
+    @property
+    def columns(self) -> dict[str, Any]:
+        """The ``data=`` column name of each data argument."""
+        return self.cols.titles
+
+    @classmethod
+    def _at_call(cls, data: dict[str, Any], kw: dict[str, Any]) -> dict[str, Any]:
+        """The keywords of a call given its data arguments (``data=`` columns read): a type
+        deriving settings from its data at the call overrides it."""
+        return kw
+
+    #: How the type draws levels in its aesthetics (:mod:`plot_io.levels`): ``"items"``,
+    #: ``"split"``; ``"grid"`` refuses them and ``group=``; ``None``: not read as levels.
+    LEVELS: str | None = None
+    #: The level axes and calls of a series with levels (:class:`plot_io.levels.Levels`).
+    _lv: Any = None
+
+    def set(self, **settings: Any) -> Any:
+        if self._lv is not None and "name" in settings:   # with levels: the legend's title
+            self.plot._legend_title = settings.pop("name")
+        super().set(**settings)
+        self._cache: dict[Any, Any] = {}
+        if self._lv is not None:
+            for part, _, _ in self._lv.parts:
+                if part is not self:
+                    part.set(**settings)
+        for name in ("color_axis", "size_axis"):
+            axis = self._values.get(name)
+            if axis is not None and axis._parent() is None:
+                self.plot.figure.adopt_axis(axis)      # a shared axis made on its own
+        if "colorbar" in settings and self._ready:
+            self._attach_bar()
+        return self
+
+    #: Whether the series is made (its ``__init__`` done).
+    _ready = False
+    #: The colorbar ``colorbar=`` attached, once.
+    _bar: Any = None
+
+    def _attach_bar(self) -> None:
+        """``colorbar=``: a colorbar of :meth:`_bar_source` attached to the plot, once (and
+        not twice for one source)."""
+        v = self.resolve("colorbar") if "colorbar" in self.SETTINGS else False
+        if not v or self._bar is not None or "_of" in self.__dict__:
+            return
+        source = self._bar_source()
+        if source is None or any(cb.source is source for cb in self.plot.colorbars):
+            return
+        if isinstance(v, dict):
+            self._bar = self.plot.add_colorbar(source, **v)
+        else:
+            self._bar = self.plot.add_colorbar(source, None if v is True else v)
+
+    def _bar_source(self) -> Any:
+        """What ``colorbar=`` shows: the series when it maps numbers in ``color`` (or in a
+        marker or edge color); else ``None`` (a ``colorbar=`` of the series' own raises)."""
+        from ..values import Values, is_computed
+        for name in ("color", "marker_color", "edge_color", "marker_edge_color"):
+            v = self.resolve(name) if name in self.SETTINGS else None
+            if isinstance(v, Values) or is_computed(v):
+                return self
+        if self.is_set("colorbar"):
+            raise ValueError(f"{self.kind}: colorbar= needs numbers in color (or in a "
+                             f"marker or edge color)")
+        return None
+
+    def _children(self) -> list[Settings]:
+        return [a for a in (self.__dict__.get("_color_axis"),
+                            self.__dict__.get("_size_axis")) if a is not None]
+
+    @property
+    def color_axis(self) -> Any:
+        """The color axis numbers in ``color`` go through: the shared one given as
+        ``color_axis=``, else the series' own (its scale and limits are the series'
+        ``color_scale`` and ``color_limits``); its guide is a colorbar."""
+        from ..mapped import color_axis_of
+        if "color_map" not in self.SETTINGS:
+            raise AttributeError(f"{self.kind} maps no colors")
+        return color_axis_of(self)
+
+    @property
+    def size_axis(self) -> Any:
+        """The size axis numbers in ``size`` go through (as :attr:`color_axis`); its guide
+        is a size key."""
+        from ..mapped import SizeAxis, own_axis, shared_axis
+        if "size_map" not in self.SETTINGS:
+            raise AttributeError(f"{self.kind} maps no sizes")
+        shared = shared_axis(self, "size")
+        return shared if shared is not None else own_axis(self, SizeAxis)
+
+    def cached(self, key: Any, compute: Any, reads: tuple[str, ...] = (),
+               kind: Any = None) -> Any:
+        """``compute()`` once per ``key`` and resolved values of the settings it ``reads``
+        (from the series, its parents or the style), until a setting of the series changes
+        (derived data: bins, densities…).  One result is kept per ``kind`` (default: the
+        key): a new key of a kind replaces the previous."""
+        cache = self.__dict__.setdefault("_cache", {})
+        full = (key, tuple(_token(self.resolve(n)) for n in reads if n in self.SETTINGS))
+        slot = key if kind is None else kind
+        hit = cache.get(slot)
+        if hit is None or hit[0] != full:
+            hit = cache[slot] = (full, compute())
+        return hit[1]
+
+    def __repr__(self) -> str:
+        name = self.get("name")
+        return f"{self.kind}({name!r})" if name else f"{self.kind}()"
+
+    #: the type as a declaration (:class:`~plot_io.layers.grammar.Spec`), run by
+    #: :meth:`layers`; ``None``: the type implements :meth:`layers`
+    SPEC: Any = None
+
+    def layers(self) -> Any:
+        """The preset: this call's :class:`~plot_io.layers.core.Call` (layers, legend
+        entries, what the axes and color maps need), built in each render (by the
+        type's ``SPEC`` when it has one)."""
+        if self.SPEC is not None:
+            from .grammar import build
+            return build(self)
+        raise NotImplementedError
+
+
+def column(name: str, doc: str) -> Any:
+    """A read-only property: the series' column ``name`` (``cols[name]``)."""
+    return property(lambda self: self.cols[name], doc=doc)
+
+
+def _token(v: Any) -> Any:
+    """A setting value as a hashable part of a cache key (containers by content, other
+    unhashable values by identity)."""
+    if isinstance(v, (list, tuple)):
+        return (type(v).__name__, tuple(_token(x) for x in v))
+    if isinstance(v, dict):
+        return ("dict", tuple((k, _token(x)) for k, x in v.items()))
+    try:
+        hash(v)
+    except TypeError:
+        return ("id", id(v))
+    return v
+
+
+def slot_width(series: Any, positions: Any, time: bool, scale: float | None = None,
+               name: str = "width") -> float:
+    """``width`` (or ``name``) of a categorical series in data units: `%` of the slot (one
+    category, or the smallest gap between ``positions``), lengths through ``scale`` (px per
+    data unit; 0 while it is unknown)."""
+    unit = 1.0
+    if positions is not None:
+        ps = sorted({float(p) for p in positions})
+        gaps = [b - a for a, b in zip(ps, ps[1:]) if b > a]
+        unit = min(gaps) if gaps else 1.0
+    else:
+        time = False
+    try:
+        return series.resolve(name, of=unit, scale=abs(scale) if scale else None,
+                              time=time, unit="data")
+    except NeedsScale:
+        return 0.0
+
+
+def slot_parts(series: Any, positions: Any, time: bool, axis_scale: Any,
+               scale: float | None = None, name: str = "width") -> tuple[float, float]:
+    """``width`` (or ``name``) of a series at numeric ``positions`` on an axis with a scale
+    function, in two parts: ``%`` of the slot (the smallest gap between the positions
+    through the function) and lengths in the scale's space (``scale``: px per unit of it;
+    0 while it is unknown), and lengths in data units (``data``, ``d``), which stay data
+    units."""
+    fs = sorted({v for v in (axis_scale.f(float(p)) for p in positions) if math.isfinite(v)})
+    gaps = [b - a for a, b in zip(fs, fs[1:]) if b > a]
+    unit = min(gaps) if gaps else 1.0
+    try:
+        data = series.resolve(name, of=0.0, scale=math.inf, time=time, unit="data")
+    except ValueError:                  # no data part (a % or px width alone)
+        data = 0.0
+    try:
+        total = series.resolve(name, of=unit, scale=abs(scale) if scale else None,
+                               time=time, unit="data")
+    except NeedsScale:
+        return 0.0, data
+    return max(total - data, 0.0), data