plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/helpers/volcano.py

@@ -0,0 +1,505 @@
+"""Volcano, MA and Manhattan plots: scatters of differential or association results, with
+classes by thresholds, threshold rules and the top hits labelled by Scatter's point
+label placer."""
+
+import array
+import math
+import re
+from collections import Counter
+from typing import Any
+
+from .. import DEFAULTS, Scatter, ext, kernels
+from .._methods import MaMixin, ManhattanMixin, VolcanoMixin
+
+__all__ = ["Volcano", "Ma", "Manhattan"]
+
+#: The classes of a volcano or MA plot, in legend order.
+CLASSES = ("up", "down", "n.s.")
+#: Title of a −log10 p axis.
+LOG_P = "-log<sub>10</sub>(p)"
+
+
+def _floats(v: Any) -> Any:
+    if v is None or isinstance(v, str):
+        return None
+    try:
+        return kernels.doubles(v)
+    except (TypeError, ValueError):
+        return [math.nan if x is None else float(x) for x in
+                (v.tolist() if hasattr(v, "tolist") else v)]
+
+
+def _setting(cls: Any, kw: dict[str, Any], name: str) -> Any:
+    """A setting read at the call: given, else the class' default."""
+    if name in kw:
+        return cls.SETTINGS[name].check(kw[name])
+    for c in cls.__mro__:
+        key = f"{c.__name__}.{name}"
+        if key in DEFAULTS:
+            return cls.SETTINGS[name].check(DEFAULTS[key])
+    raise KeyError(name)
+
+
+def classify(fc: list[float], p: list[float] | None, fc_threshold: float,
+             p_threshold: float) -> list[str | None]:
+    """``"up"``, ``"down"`` or ``"n.s."`` per point (``None``: fold change or p not a
+    number): significant when ``p < p_threshold`` (always without ``p``), up or down when
+    also ``|fc| ≥ fc_threshold``."""
+    out: list[str | None] = []
+    for i, f in enumerate(fc):
+        q = p[i] if p is not None else 0.0
+        if f != f or q != q:
+            out.append(None)
+        elif q < p_threshold and f >= fc_threshold:
+            out.append("up")
+        elif q < p_threshold and f <= -fc_threshold:
+            out.append("down")
+        else:
+            out.append("n.s.")
+    return out
+
+
+def _levels(cls: Any, kw: dict[str, Any], fc: list[float], p: list[float] | None
+            ) -> dict[str, Any]:
+    classes = classify(fc, p, _setting(cls, kw, "fold_change_threshold"),
+                       _setting(cls, kw, "p_threshold"))
+    colors = {**dict(zip(CLASSES, (DEFAULTS["Volcano.colors"][k] for k in CLASSES))),
+              **_setting(cls, kw, "colors")}
+    counts = _setting(cls, kw, "counts")
+    n = Counter(classes)
+    names = {k: f"{k} ({n[k]})" if counts else k for k in CLASSES}
+    present = [names[k] for k in CLASSES if k in classes]
+    return {"color": [names["n.s."] if c is None else names[c] for c in classes],
+            "color_map": {names[k]: colors[k] for k in CLASSES},
+            "level_order": present or [names["n.s."]]}
+
+
+def _colors(v: Any) -> dict[str, Any]:
+    if not isinstance(v, dict):
+        raise ValueError(f"expected a dict class → color, got {v!r}")
+    bad = sorted(set(v) - set(CLASSES))
+    if bad:
+        raise ValueError(f"no class {bad[0]!r} (classes: {', '.join(CLASSES)})")
+    return {k: ext.color(c) for k, c in v.items()}
+
+
+def _label(v: Any) -> Any:
+    if v is None or v is False:
+        return None
+    if isinstance(v, str):
+        return ext.one_of("top")(v)
+    return list(v)
+
+
+def _neg_log10(p: Any) -> Any:
+    """−log10 of p-values, 0 at the smallest positive p (NaN, negatives: NaN)."""
+    v = kernels.doubles(p)
+    if kernels.extent(v)[1] <= 0:
+        tiny = min((q for q in v if q > 0), default=1.0)
+        v = [tiny if q == 0 else (q if q > 0 else math.nan) for q in v]
+    return kernels.scaled(v, -1.0, 0.0, "log10")
+
+
+_READ_AT_CALL = ("fold_change_threshold", "p_threshold", "colors", "counts")
+
+_COMMON = dict(
+    fold_change_threshold=ext.Setting(ext.number(0), doc="Smallest |log2 fold change| "
+                                                         "of the up and down classes."),
+    p_threshold=ext.Setting(ext.number(0, 1), doc="p below which a point is significant."),
+    colors=ext.Setting(_colors, doc="Colors of the classes `up`, `down`, `n.s.` (a dict; "
+                                    "classes not given keep theirs)."),
+    counts=ext.Setting(ext.boolean, doc="Counts in the legend entries (`up (123)`)."),
+    thresholds=ext.Setting(ext.boolean, doc="Dashed rules at the thresholds."),
+    threshold_color=ext.Setting(ext.color, doc="Color of the threshold rules."),
+    threshold_width=ext.Setting(ext.length(lo=0), doc="Width of the threshold rules."),
+    label=ext.Setting(_label, doc="Points labelled with their `labels` text: `top` (the "
+                                  "`label_count` most significant beyond both thresholds), "
+                                  "a list of texts (those points), `None`."),
+    label_count=ext.Setting(ext.number(0, integer=True), doc="Points `label=\"top\"` labels."),
+)
+
+
+def _settings(**extra: Any) -> Any:
+    return ext.table(
+        **{k: v for k, v in Scatter.SETTINGS.items()
+           if k not in ("x_error", "y_error", "orientation")},
+        **extra)
+
+
+def _rules(s: Any, xs: list[float], ys: list[float], solid: int = -1) -> Any:
+    """A table of dashed rules across the axes: vertical at ``xs``, horizontal at ``ys``
+    (the ``solid``-th one solid)."""
+    if not s.resolve("thresholds") or not (xs or ys):
+        return None
+    t = ext.Table()
+    t.lazy["x0"] = lambda ctx: [*xs, *(ctx.x.lo for _ in ys)]
+    t.lazy["x1"] = lambda ctx: [*xs, *(ctx.x.hi for _ in ys)]
+    t.lazy["y0"] = lambda ctx: [*(ctx.y.lo for _ in xs), *ys]
+    t.lazy["y1"] = lambda ctx: [*(ctx.y.hi for _ in xs), *ys]
+    t["dash"] = [None if k == solid else "dashed" for k in range(len(xs) + len(ys))]
+    return t
+
+
+def _rule_layer() -> Any:
+    return ext.Lay("segments", ("stroke", {"color": "threshold_color",
+                                           "width": "threshold_width",
+                                           "fixed": lambda s: {"dash": _dashes(s)}}),
+                   table="rules", key=False, occupy=False, bounds=False)
+
+
+def _dashes(s: Any) -> Any:
+    t = s._rule_table()
+    return None if t is None else t["dash"]
+
+
+def _points_layer() -> Any:
+    return ext.Lay("points", ("marker", {"order": True, "once": True,
+                                         "n": lambda s: len(s.cols[s.FOLD])}),
+                   name="points", radius=lambda s: _radius(s.resolve("size")))
+
+
+def _radius(size: Any) -> float:
+    return size / 2 if isinstance(size, (int, float)) else 0.0
+
+
+def _finish(s: Any, b: Any, x_title: str, y_title: str) -> None:
+    labels = Scatter.SPEC.finish                          # Scatter's point labels
+    if labels is not None:
+        labels(s, b)
+    b.call.titles.setdefault("x", x_title)
+    b.call.titles.setdefault("y", y_title)
+
+
+class _Thresholds(Scatter):
+    """What Volcano and Ma share: classes read at the call (``color`` becomes the class of
+    each point, a level axis coloured by ``colors``, with counts), the labels of the top
+    hits."""
+
+    FOLD = "fold_change"
+
+    @classmethod
+    def _at_call(cls, data: dict[str, Any], kw: dict[str, Any]) -> dict[str, Any]:
+        if "color" in kw or "group" in kw:
+            return kw
+        fc, p = _floats(data.get(cls.FOLD)), _floats(data.get("p"))
+        if fc is None or (p is None and data.get("p") is not None):
+            return kw
+        return {**kw, **_levels(cls, kw, fc, p)}
+
+    def set(self, **settings: Any) -> Any:
+        if hasattr(self, "cols"):
+            late = [k for k in settings if k in _READ_AT_CALL]
+            if late and getattr(self, "_classified", False):
+                raise ValueError(f"{type(self).__name__}: {late[0]} is read at the call: "
+                                 f"pass it to plt.{type(self).__name__}(…)")
+        return super().set(**settings)
+
+    def _p(self) -> list[float] | None:
+        return _floats(self.cols["p"])
+
+    def _ranked(self, fc: Any, p: list[float] | None) -> Any:
+        """Point indices, most significant first (NaN first: skipped by the caller)."""
+        return kernels.argsort(p) if p is not None else _by_fold(fc)
+
+    def _label_picks(self) -> list[tuple[int, Any]]:
+        texts = self.resolve("labels")
+        which = self.resolve("label")
+        if not texts or which is None:
+            return []
+        if which != "top":
+            want = set(map(str, which))
+            return [(i, str(t)) for i, t in enumerate(texts) if t is not None
+                    and str(t) in want]
+        fc = kernels.doubles(self.cols[self.FOLD])
+        p = self._p()
+        t_fc, t_p = self.resolve("fold_change_threshold"), self.resolve("p_threshold")
+        count = self.resolve("label_count")
+        out: list[tuple[int, Any]] = []
+        for i in self._ranked(fc, p):
+            if len(out) >= count:
+                break
+            if i >= len(texts) or texts[i] is None or texts[i] == "":
+                continue
+            c = classify([fc[i]], None if p is None else [p[i]], t_fc, t_p)[0]
+            if c in ("up", "down"):
+                out.append((i, str(texts[i])))
+        return out
+
+
+def _by_fold(fc: Any) -> Any:
+    return kernels.argsort([-abs(f) for f in fc])
+
+
+class Volcano(VolcanoMixin, _Thresholds):
+    """Differential results: log2 ``fold_change`` (x) against −log10 ``p`` (y; p = 0 at
+    the smallest positive p, NaN left out).  Points are ``up``, ``down`` or ``n.s.``: up
+    or down when ``p < p_threshold`` and |fold change| ≥ ``fold_change_threshold``,
+    coloured by ``colors`` as a level axis on ``color`` (the legend counts them), dashed
+    rules at the thresholds.  ``labels`` gives a text per point, ``label`` which are drawn
+    (placed as Scatter's).  The classification settings are read at the call.
+
+    :class:`Scatter`'s settings apply; a later ``set`` of the classification settings
+    (``fold_change_threshold``, ``p_threshold``, ``colors``, ``counts``) raises.
+
+    The class colors are ``colors`` (up ``#d6604d``, down ``#4393c3``, n.s. ``#bdbdbd``; the
+    plot's colors are not used), with their counts in the legend (``up (123)``; ``counts=False``).
+    ``thresholds=False`` leaves the rules out.  ``label="top"`` (default) labels the
+    ``label_count`` (10) most significant points beyond both thresholds, a list of texts
+    labels those points, ``None`` none.  ``color=`` or ``group=`` given replaces the
+    classes.  Uses::
+
+        p.volcano("log2FC", "pvalue", data=res, labels="gene")      # top 10 hits labelled
+        p.volcano(fc, pv, labels=names, label=["TP53", "MYC"])      # these labelled
+
+    Example::
+
+        rng = random.Random(1)
+        fc = [rng.gauss(0, 1.5) for _ in range(300)]
+        p = plt.Plot(width=240, height=160)
+        p.volcano(fc, [min(1, rng.random() * 2 ** -abs(v * 4)) for v in fc])
+    """
+
+    SETTINGS = _settings(**_COMMON)
+    DATA = {"fold_change": "numbers", "p": "numbers"}
+
+    def __init__(self, fold_change: Any, p: Any, plot: Any = None,
+                 **settings: Any) -> None:
+        ext.Series.__init__(self, plot=plot, **settings)
+        self.__dict__["_classified"] = True
+
+    def density_points(self) -> tuple[Any, Any]:
+        return kernels.doubles(self.cols["fold_change"]), _y(self)
+
+    def _rule_table(self) -> Any:
+        t, p = self.resolve("fold_change_threshold"), self.resolve("p_threshold")
+        return _rules(self, [-t, t] if t else [0.0], [-math.log10(p)] if p > 0 else [])
+
+
+def _volcano_data(s: Any, b: Any) -> Any:
+    return ext.Table(x=kernels.doubles(s.cols["fold_change"]), y=_y(s))
+
+
+def _y(s: Any) -> Any:
+    """−log10 p of a series' points (once)."""
+    return s.cached("neg_log10_p", lambda: _neg_log10(s.cols["p"]))
+
+
+Volcano.SPEC = ext.Spec(
+    [_rule_layer(), _points_layer()],
+    tables={"data": _volcano_data, "rules": lambda s, b: s._rule_table()},
+    key={"fill": "marker", "stroke": "marker", "marker": "@points"},
+    titles={"fold_change": "x"}, color_sources=True, size_sources=True,
+    finish=lambda s, b: _finish(s, b, "log<sub>2</sub> fold change", LOG_P))
+
+
+class Ma(MaMixin, _Thresholds):
+    """An MA plot: mean expression ``mean`` (x, on a log10 axis unless the axis has a scale)
+    against log2 ``fold_change`` (y), a rule at 0 and dashed ones at ±
+    ``fold_change_threshold``.  Classes, colors and labels as `Volcano`'s (by fold change
+    alone without ``p``; ``label="top"``: the largest |fold change| among the
+    significant).
+
+    :class:`Scatter`'s settings apply.  The classification settings (``fold_change_threshold``,
+    ``p_threshold``, ``colors``, ``counts``) are read at the call: set them there (a later
+    ``set`` of them raises).  Use::
+
+        p.ma("baseMean", "log2FC", "padj", data=res)
+
+    Example::
+
+        rng = random.Random(1)
+        fc = [rng.gauss(0, 1.5) for _ in range(300)]
+        p = plt.Plot(width=240, height=160)
+        p.ma([10 ** rng.uniform(0, 4) for _ in fc], fc, [min(1, rng.random() * 2 ** -abs(v * 4)) for v in fc])
+    """
+
+    SETTINGS = _settings(**_COMMON)
+    DATA = {"mean": "numbers", "fold_change": "numbers", "p": "raw"}
+
+    def __init__(self, mean: Any, fold_change: Any, p: Any = None, plot: Any = None,
+                 **settings: Any) -> None:
+        ext.Series.__init__(self, plot=plot, **settings)
+        self.__dict__["_classified"] = True
+        axis = self.plot.x_axis
+        if not axis.is_set("scale"):
+            axis.set(scale="log10")
+
+    def _ranked(self, fc: Any, p: list[float] | None) -> Any:
+        return _by_fold(fc)
+
+    def density_points(self) -> tuple[Any, Any]:
+        return kernels.doubles(self.cols["mean"]), kernels.doubles(self.cols["fold_change"])
+
+    def _rule_table(self) -> Any:
+        t = self.resolve("fold_change_threshold")
+        return _rules(self, [], [0.0, -t, t] if t else [0.0], solid=0)
+
+
+def _ma_data(s: Any, b: Any) -> Any:
+    return ext.Table(x=kernels.doubles(s.cols["mean"]), y=kernels.doubles(s.cols["fold_change"]))
+
+
+Ma.SPEC = ext.Spec(
+    [_rule_layer(), _points_layer()],
+    tables={"data": _ma_data, "rules": lambda s, b: s._rule_table()},
+    key={"fill": "marker", "stroke": "marker", "marker": "@points"},
+    titles={"mean": "x", "fold_change": "y"}, color_sources=True, size_sources=True,
+    finish=lambda s, b: _finish(s, b, "mean", "log<sub>2</sub> fold change"))
+
+
+# -- Manhattan -----------------------------------------------------------------------
+
+def _chrom_key(name: str) -> tuple[int, int, str]:
+    """Natural order of chromosome names: numbered ones by number, then X, Y, M, others."""
+    bare = re.sub(r"^chr", "", name, flags=re.IGNORECASE)
+    if bare.isdigit():
+        return 0, int(bare), ""
+    rank = {"X": 1, "Y": 2, "M": 3, "MT": 3}.get(bare.upper(), 4)
+    return 1, rank, bare
+
+
+def _sizes(v: Any) -> Any:
+    if not isinstance(v, dict):
+        raise ValueError(f"expected a dict chromosome → size, got {v!r}")
+    return {str(k): ext.number(0)(n) for k, n in v.items()}
+
+
+def _pair(v: Any) -> Any:
+    if isinstance(v, str) or len(v) != 2:
+        raise ValueError(f"expected two colors, got {v!r}")
+    return tuple(ext.color(c) for c in v)
+
+
+def _p_line(v: Any) -> Any:
+    return None if v is None or v is False else ext.number(0, 1)(v)
+
+
+class Manhattan(ManhattanMixin, Scatter):
+    """Genome-wide association results: −log10 ``p`` (y) at ``positions`` (bp) of
+    ``chromosomes`` laid end to end (x) in natural order (chr1 … chr22, X, Y, M), each
+    ``chr_sizes`` long (unset: to its last position), its points in the next of the two
+    ``colors``, its name as the tick at its middle (left to right, a name that would
+    overlap the last one shown is left out), the x axis from the first chromosome's start
+    to the last one's end; a dashed rule at ``threshold`` (genome-wide significance).
+    ``labels``/``label``/``label_count`` as `Volcano`'s (``top``: the most significant
+    beyond ``threshold``).
+
+    :class:`Scatter`'s settings apply.  The classification settings (``fold_change_threshold``,
+    ``p_threshold``, ``colors``, ``counts``) are read at the call: set them there (a later
+    ``set`` of them raises).  Use::
+
+        p.manhattan("chr", "pos", "p", data=gwas, labels="snp", label="top")
+
+    Example::
+
+        rng = random.Random(1)
+        chrs = [str(c) for c in range(1, 7) for _ in range(100)]
+        p = plt.Plot(width=300, height=160)
+        p.manhattan(chrs, [rng.randrange(50_000_000) for _ in chrs],
+                    [rng.random() ** 6 for _ in chrs], threshold=1e-5)
+    """
+
+    SETTINGS = _settings(
+        chr_sizes=ext.Setting(_sizes, doc="Chromosome sizes (bp), a dict."),
+        colors=ext.Setting(_pair, doc="The two colors chromosomes alternate."),
+        threshold=ext.Setting(_p_line, doc="p of the dashed rule (`None`: none)."),
+        **{k: _COMMON[k] for k in ("threshold_color", "threshold_width", "label",
+                                    "label_count")},
+    )
+    DATA = {"chromosomes": "raw", "positions": "numbers", "p": "numbers"}
+
+    def __init__(self, chromosomes: Any, positions: Any, p: Any, plot: Any = None,
+                 **settings: Any) -> None:
+        ext.Series.__init__(self, plot=plot, **settings)
+
+    def layout(self) -> tuple[list[float], list[tuple[str, float, float]]]:
+        """x of each point and ``(chromosome, start, end)`` of each chromosome on x."""
+        def compute() -> Any:
+            names = [str(c) for c in self._column("chromosomes")]
+            pos = list(kernels.doubles(self.cols["positions"]))
+            last: dict[str, float] = {}
+            for c, x in zip(names, pos):
+                if x == x and x > last.get(c, -math.inf):
+                    last[c] = x
+            sizes = self.resolve("chr_sizes") or {}
+            spans, at, start = [], {}, 0.0
+            for c in sorted(set(names), key=_chrom_key):
+                size = float(sizes.get(c, last.get(c, 0.0)))
+                spans.append((c, start, start + size))
+                at[c] = start
+                start += size
+            return [at[c] + x for c, x in zip(names, pos)], spans
+        return self.cached("manhattan_layout", compute, ("chr_sizes",))
+
+    def _column(self, name: str) -> list[Any]:
+        v = self.cols[name]
+        return list(v.tolist() if hasattr(v, "tolist") else v)
+
+    def density_points(self) -> tuple[Any, Any]:
+        return self.layout()[0], _y(self)
+
+    def _point_colors(self, ctx: Any) -> Any:
+        a, b = self.resolve("colors")
+        names = [str(c) for c in self._column("chromosomes")]
+        order = {c: k for k, (c, _, _) in enumerate(self.layout()[1])}
+        return [a if order[c] % 2 == 0 else b for c in names]
+
+    def _rule_table(self) -> Any:
+        t = self.resolve("threshold")
+        if t is None or t <= 0:
+            return None
+        tab = ext.Table(y0=[-math.log10(t)], y1=[-math.log10(t)])
+        tab.lazy["x0"] = lambda ctx: [ctx.x.lo]
+        tab.lazy["x1"] = lambda ctx: [ctx.x.hi]
+        tab["dash"] = ["dashed"]
+        return tab
+
+    def _label_picks(self) -> list[tuple[int, Any]]:
+        texts = self.resolve("labels")
+        which = self.resolve("label")
+        if not texts or which is None:
+            return []
+        named = [(i, str(t)) for i, t in enumerate(texts) if t is not None and t != ""]
+        if which != "top":
+            want = set(map(str, which))
+            return [(i, t) for i, t in named if t in want]
+        p = list(kernels.doubles(self.cols["p"]))
+        t = self.resolve("threshold")
+        hits = [(i, s) for i, s in named if i < len(p) and p[i] == p[i]
+                and (t is None or p[i] < t)]
+        hits.sort(key=lambda it: (p[it[0]], it[0]))
+        return hits[:self.resolve("label_count")]
+
+
+def _manhattan_data(s: Any, b: Any) -> Any:
+    return ext.Table(x=s.layout()[0], y=_y(s))
+
+
+def _manhattan_finish(s: Any, b: Any) -> None:
+    _finish(s, b, "chromosome", LOG_P)
+    spans = s.layout()[1]
+    b.call.ticks["x"] = [((a + e) / 2, re.sub(r"^chr", "", c, flags=re.IGNORECASE))
+                         for c, a, e in spans]
+    b.call.thin.add("x")
+    if spans:                       # the axis spans the chromosomes, unpadded
+        b.call.extra["x"] = array.array("d", [spans[0][1], spans[-1][2]])
+        b.call.exact.add("x")
+
+
+Manhattan.SPEC = ext.Spec(
+    [ext.Lay("segments", ("stroke", {"color": "threshold_color", "width": "threshold_width",
+                                     "fixed": {"dash": ["dashed"]}}),
+             table="rules", key=False, occupy=False, bounds=False),
+     ext.Lay("points", ("marker", {"order": True, "once": True,
+                                   "n": lambda s: len(s.cols["positions"]),
+                                   "color": lambda s: "base" if s.is_set("color")
+                                   else "_point_colors()"}),
+             name="points", radius=lambda s: _radius(s.resolve("size")))],
+    tables={"data": _manhattan_data, "rules": lambda s, b: s._rule_table()},
+    key={"fill": "marker", "stroke": "marker", "marker": "@points"},
+    color_sources=True, size_sources=True, finish=_manhattan_finish)
+
+
+ext.register("volcano", Volcano)
+ext.register("ma", Ma)
+ext.register("manhattan", Manhattan)

plot_io/hints.py

@@ -0,0 +1,125 @@
+"""matplotlib names and their plot_io forms, read by the error messages and by the
+"coming from matplotlib" page.  Hints only: the matplotlib names are not accepted (but
+those that are plot_io's own shorthands, ``settings.ALIASES``)."""
+
+import re
+from typing import Any, Iterable
+
+#: matplotlib keyword → the plot_io settings meaning the same, the first one the class has
+#: is suggested ("width and height": both).
+MATPLOTLIB: dict[str, tuple[str, ...]] = {
+    "lw": ("line_width", "edge_width", "border_width"),
+    "linewidth": ("line_width", "edge_width", "border_width"),
+    "linewidths": ("edge_width", "line_width"),
+    "ls": ("line_style",),
+    "linestyle": ("line_style",),
+    "c": ("color",),
+    "s": ("size",),
+    "ms": ("marker_size", "size"),
+    "markersize": ("marker_size", "size"),
+    "mec": ("marker_edge_color", "edge_color"),
+    "markeredgecolor": ("marker_edge_color", "edge_color"),
+    "mew": ("marker_edge_width", "edge_width"),
+    "markeredgewidth": ("marker_edge_width", "edge_width"),
+    "mfc": ("marker_color", "color"),
+    "markerfacecolor": ("marker_color", "color"),
+    "ec": ("edge_color", "border_color"),
+    "edgecolor": ("edge_color", "border_color"),
+    "edgecolors": ("edge_color",),
+    "fc": ("color",),
+    "facecolor": ("color",),
+    "facecolors": ("color",),
+    "ecolor": ("error_color", "color"),
+    "elinewidth": ("error_width", "line_width"),
+    "capsize": ("cap_length",),
+    "capstyle": ("cap",),
+    "joinstyle": ("join",),
+    "cmap": ("color_map",),
+    "palette": ("qualitative_map", "color_map"),
+    "vmin": ("color_limits",),
+    "vmax": ("color_limits",),
+    "zorder": ("z",),
+    "rasterized": ("rasterize",),
+    "fontsize": ("font_size",),
+    "fontweight": ("font_weight",),
+    "figsize": ("width and height",),
+    "dpi": ("default_dpi",),
+    "nrows": ("rows",),
+    "ncols": ("cols",),
+    "sharex": ("share_x",),
+    "sharey": ("share_y",),
+    "aspect": ("aspect_ratio", "data_ratio"),
+}
+
+#: matplotlib axis keyword suffix → the plot_io axis setting (``xlim`` → ``x_axis``'s
+#: ``limits``).
+AXIS = {"lim": "limits", "label": "label", "scale": "scale", "ticks": "ticks"}
+
+
+def axis_setting(name: str) -> str | None:
+    """The plot_io form of the matplotlib axis keyword ``name`` (``xlim``:
+    ``x_axis={"limits": …}``), or ``None``."""
+    m = re.fullmatch(r"([xy])(lim|label|scale|ticks)", name)
+    if m is None:
+        return None
+    axis, key = m.group(1), AXIS[m.group(2)]
+    return f'{axis}_axis={{"{key}": …}} on the plot, or plot.{axis}_axis({key}=…)'
+
+
+_TAB = ("blue", "orange", "green", "red", "purple", "brown", "pink", "gray", "olive", "cyan")
+
+#: matplotlib color → the plot_io color.
+COLORS: dict[str, str] = {
+    "k": "black", "w": "white", "r": "red", "g": "green", "b": "blue", "c": "cyan",
+    "m": "magenta", "y": "yellow",
+    **{f"tab:{n}": f'C{i} with qualitative_map="tab10"' for i, n in enumerate(_TAB)},
+    "tab:grey": 'C7 with qualitative_map="tab10"',
+}
+
+
+def setting(name: str, candidates: Iterable[str]) -> str | None:
+    """The plot_io form of the matplotlib keyword ``name`` among ``candidates``
+    (``"line_width="``), or ``None``."""
+    have = set(candidates)
+    for choice in MATPLOTLIB.get(name, ()):
+        names = choice.split(" and ")
+        if all(n in have for n in names):
+            return " and ".join(n + "=" for n in names)
+    return None
+
+
+def _variant(key: str) -> str:
+    """A hint for a color with a variant word (``"pastel navy"``, ``"red pastel"``)."""
+    from .color.variants import VARIANTS
+    words = key.split()
+    at = [i for i, w in enumerate(words) if w in VARIANTS]
+    if not at:
+        return ""
+    w = words[at[0]]
+    rest = " ".join(words[:at[0]] + words[at[0] + 1:])
+    if not rest:
+        return f" ({w!r} is a color variant: before a scale name, \"{w} red\", or as " \
+               f"color_variant=\"{w}\")"
+    if at[0] > 0:
+        return f" (the variant word comes first: \"{w} {rest}\")"
+    return f" (a variant applies to the named scales, \"{w} red\"; {rest!r} is not one)"
+
+
+def color(v: Any) -> str:
+    """A hint for the invalid color ``v`` (``" (matplotlib's 'k' is \"black\")"``), or ``""``."""
+    if isinstance(v, str):
+        key = v.strip().lower()
+        if key in COLORS:
+            want = COLORS[key]
+            want = want if " with " in want else f'"{want}"'
+            return f" (matplotlib's {v!r} is {want})"
+        variant = _variant(key)
+        if variant:
+            return variant
+        if re.fullmatch(r"0?\.\d+|[01](\.0*)?", key):
+            pct = f"{float(key) * 100:g}%"
+            return f" (matplotlib's {v!r} is a gray: \"rgb({pct} {pct} {pct})\")"
+    elif isinstance(v, (tuple, list)) and 3 <= len(v) <= 4 and all(
+            isinstance(x, (int, float)) for x in v) and any(x > 1 for x in v):
+        return ' (components are 0–1; or "rgb(255 0 0)")'
+    return ""