plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/presets/box.py

@@ -0,0 +1,400 @@
+"""Box plots (stat ``box``): bodies (``Rects``), whiskers, caps and medians
+(``Segments``), outliers and means (``Points``), dodged per category."""
+
+import array
+from typing import Any
+
+from .._methods import BoxMixin
+from .. import columns, groups
+from ..color.values import color
+from ..layers import stats
+from ..layers.base import Series, common
+from ..layers.core import Table
+from ..layers.geoms import Marks
+from ..layers.grammar import Lay, Spec
+from ..layers.paint import MarkerStyle, base_colors, role
+from ..layers.positions import Dodge, placed
+from ..markers import check_marker, resolve
+from ..settings import Setting, boolean, either, literal, number, one_of, pair, table
+from ..transform import settings_both as coord_settings
+from ..validators import length, typed
+from ..values import Values, category_paint
+from ._util import fill_colors, memo
+
+__all__ = ["Box"]
+
+
+def _outlier_paint(name: str) -> Any:
+    """``marker_color``/``marker_edge_color``: colors only (outliers are computed, so there
+    are no values per point to map)."""
+    def check(v: Any) -> Any:
+        from ..values import is_computed, paint
+        if name == "marker_edge_color" and v == "auto":
+            return v
+        out = paint(v, name)
+        if isinstance(out, Values) or is_computed(out):
+            raise ValueError("a color, or colors per outlier: outliers are computed, so "
+                             "numbers or a density are not mapped here")
+        return out
+    return check
+
+
+def _whiskers(v: Any) -> Any:
+    if v == "range":
+        return "range"
+    if isinstance(v, (tuple, list)):
+        lo, hi = pair(number(0, 100))(v)
+        if not lo < hi:
+            raise ValueError("whisker percentiles must increase")
+        return (lo, hi)
+    return number(lo=0)(v)
+
+
+@typed("ColorLike")
+def _line_color(v: Any) -> Any:
+    if v in ("series", "auto"):
+        return v
+    return color(v)
+
+
+class Box(BoxMixin, Series):
+    """Box plots of ``values``: a dict ``{category: values}``, a list of arrays
+    (categories ``0, 1, …`` or ``categories=``), or one array.
+
+    ``values`` may also be a data frame (categories by column) or a 2-D buffer;
+    ``positions`` places the boxes on a numeric axis instead.  Quartiles interpolate
+    linearly (numpy's default; with ``weights``, Hmisc's ``wtd.quantile`` on the cumulative
+    weights); whiskers reach the furthest data within ``whiskers`` × IQR, or the range, or
+    percentiles; points beyond are outliers.  Box series of a plot share each category's
+    slot side by side, in call order, among those having that category.  ``offset`` moves
+    the boxes within their slot (``"-20%"``: a fifth of the slot toward lower positions), as
+    on strip and swarm series.  ``box.stats``: ``{category: BoxStats(count, mean, q1,
+    median, q3, low, high, outliers)}``.
+
+    Example::
+
+        rng = random.Random(1)
+        p = plt.Plot(width=240, height=160)
+        p.box({k: [rng.gauss(m, 1) for _ in range(50)] for k, m in (("A", 0), ("B", 1), ("C", 0.5))})
+    """
+
+    SETTINGS = table(
+        **coord_settings(),
+        color=Setting(category_paint,
+                      doc="Box fill: a color, one per box (list or dict by category), or "
+                          "numbers per box (list or dict) mapped through `color_map`; "
+                          "default: the plot's next color."),
+        **common("color_map"),
+        **groups.Stroke.embed("edge_",
+                              only=("color", "line_width"),
+                              checks={"color": _line_color},
+                              docs={"color": "Box outline, whiskers, caps and median: a "
+                                             "color, `\"series\"` (each box's own color) or "
+                                             "`\"auto\"` (a grey 0.6 × as light as the "
+                                             "series' lightest color, as seaborn).",
+                                    "line_width": "Outline width."}),
+        **groups.Stroke.embed("whisker_",
+                              only=("color", "line_width", "line_style"),
+                              checks={"color": _line_color},
+                              docs={"color": "Whisker and cap color; default `edge_color`.",
+                                    "line_width": "Whisker and cap width; default "
+                                                  "`edge_width`.",
+                                    "line_style": "Whisker line style: `solid`, `dashed`, "
+                                                  "`dotted`, `dashdot` or a dash list (caps "
+                                                  "stay solid)."}),
+        **groups.Stroke.embed("median_",
+                              only=("color", "line_width"),
+                              checks={"color": _line_color},
+                              docs={"color": "Median line color; default `edge_color`.",
+                                    "line_width": "Median line width."}),
+        max_width=Setting(length(positive=True, data=True, percent="slot"),
+                          doc="Largest width of the series' part of a slot (as `width`)."),
+        width=Setting(length(positive=True, data=True, percent="slot"),
+                      doc="Box width: `%` of the slot, a length (bare numbers: px), `d` "
+                          "data units, or a duration on time axes."),
+        offset=Setting(length(data=True, percent="slot"),
+                       doc="Shift within the slot, toward higher positions: `%` of the slot, "
+                           "a length (bare numbers: px) or `d` data units."),
+        cap_length=Setting(length(lo=0, percent="box_width"),
+                          doc="Whisker cap width (`%` of the box width)."),
+        whiskers=Setting(_whiskers,
+                         doc="Whisker reach: a multiple of the IQR, `\"range\"`, or "
+                             "percentiles `(lo, hi)`."),
+        weights=Setting(columns.weights,
+                        doc="A weight per value, counted as repeated values (a dict or a list "
+                            "per category, as the values; long data: a weight per row)."),
+        outliers=Setting(boolean, doc="Draw points beyond the whiskers."),
+        saturation=Setting(number(0, 1),
+                           doc="Saturation of the box fills (1: the colors as given; seaborn "
+                               "uses 0.75)."),
+        **groups.FillStyle.embed(docs={"fill": "Fill: `True` (the box's color), a color, or "
+                                               "`False`.",
+                                       "fill_opacity": "Opacity of the fill, times `opacity` "
+                                                       "(lines keep `opacity`)."}),
+        mean=Setting(boolean, doc="Draw the mean as a marker."),
+        mean_marker=Setting(check_marker, doc="Marker of the mean."),
+        mean_color=Setting(color, doc="Fill of the mean marker (outline: "
+                                               "`edge_color`)."),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (categories on x) or `horizontal`."),
+        dodge=Setting(boolean, doc="Box and violin series sharing a category share its "
+                                         "slot side by side; `False` overlays them."),
+        gap=Setting(length(lo=0, percent="slot_part"), doc="Fraction of each box's part of a shared slot left "
+                                           "empty."),
+        categories=Setting(either(literal(None), lambda v: list(v)),
+                           doc="Category names of a list of arrays."),
+        **groups.Marker.embed("marker_",
+                              checks={"color": _outlier_paint("marker_color"),
+                                      "edge_color": _outlier_paint("marker_edge_color")},
+                              docs={"color": "Outlier fill: a color, or colors per outlier.",
+                                    "edge_color": "Outlier outline: as the fill, or `\"auto\"` "
+                                                  "(white around filled markers; hollow ones "
+                                                  "outlined in their color)."}),
+        **common("name", "opacity", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    DATA = {"values": "categories", "positions": "slots"}
+    ITEMS = "boxes"
+
+    def __init__(self, values: Any, positions: Any = None, plot: Any = None,
+                 **settings: Any) -> None:
+        super().__init__(plot=plot, **settings)
+
+    @property
+    def cats(self) -> list[Any]:
+        """The category of each box."""
+        return self.cols.categories
+
+    @property
+    def stats(self) -> dict[Any, Any]:
+        """``{category: BoxStats}``: count, mean, q1, median, q3, low, high, outliers."""
+        return stats.run(self, "box")
+
+    # -- paint -----------------------------------------------------------------------
+
+    def _base_colors(self, ctx: Any) -> list[Any]:
+        return base_colors(self, ctx, self.cols.categories, "boxes", items=True,
+                           saturation=False)
+
+    def _fills(self, ctx: Any) -> list[Any]:
+        return fill_colors(self, ctx, self._base_colors(ctx))
+
+    def _lines(self, ctx: Any, setting: str, fallback: list[Any] | None = None) -> list[Any]:
+        """Per-box colors of a line setting (`edge_color`, `whisker_color`, `median_color`)."""
+        v = self.resolve(setting)
+        n = len(self.cols.categories)
+        if v is None:
+            return list(fallback) if fallback is not None else [None] * n
+        if v == "series":
+            return self._base_colors(ctx)
+        if v == "auto":
+            import colorsys
+            from ..color.values import rgba_of
+            rgbas = [rgba_of(c) for c in self._base_colors(ctx) if c is not None]
+            light = [colorsys.rgb_to_hls(r[0], r[1], r[2])[1] for r in rgbas if r is not None]
+            g = 0.6 * min(light) if light else 0.25
+            return [(g, g, g)] * n
+        return [ctx.color(v)] * n
+
+    SPEC = Spec(
+        [Lay("rects", ("box.bodies", {"table": "#body"}), table="body", name="bodies",
+             stat="box", position="dodge", occupy_aes={"y0": "low", "y1": "high"},
+             each=True),
+         Lay("segments", ("box.lines", {"table": "#whisk"}), table="whisk", stat="box",
+             key=False, occupy=False),
+         Lay("points", ("box.outliers", {"table": "#outs"}), table="outs", stat="box",
+             key=False, when="outliers"),
+         Lay("points", ("box.mean", {"table": "#means"}), table="means", stat="box",
+             key=False, occupy=False, when="mean")],
+        tables={"body": lambda s, b: _body(s, b), "whisk": lambda s, b: _whisker_table(s, b),
+                "outs": lambda s, b: _outliers(s, b), "means": lambda s, b: _means(s, b)},
+        key={"fill": "symbol", "stroke": "symbol", "marker": "@bodies"},
+        zero=("y",), titles={"values": "y", "categories": "x"}, slots="positions",
+        color_sources="items", finish=lambda s, b: _finish(s, b))
+
+
+def _colors(s: Box, ctx: Any) -> tuple[list[Any], list[Any], list[Any], list[Any]]:
+    """Fills, outline, whisker and median colors of each box."""
+    def get() -> Any:
+        lcs = s._lines(ctx, "edge_color")
+        wcs = s._lines(ctx, "whisker_color", lcs)
+        mcs = [m if m is not None else lc
+               for m, lc in zip(s._lines(ctx, "median_color", lcs), lcs)]
+        return s._fills(ctx), lcs, wcs, mcs
+    return memo(ctx, (id(s), "colors"), get)
+
+
+def _geo(ctx: Any, body: Any) -> list[tuple[float, float]]:
+    """``(centre, width)`` of each drawn box, in slot space."""
+    sl = placed(body.dodge, ctx).geo
+    return [sl[i] for i in body.drawn]
+
+
+def _cap_half(s: Box, ctx: Any, body: Any, w: float) -> float:
+    """Half a cap in slot units (``cap_length`` is px + `%` of the box width)."""
+    c0, c1 = memo(ctx, (id(s), "cap"), lambda: s.resolve_linear("cap_length"))
+    pl = placed(body.dodge, ctx)
+    px = abs(pl.px(w) - pl.px(0.0))
+    return (c0 + px * c1) / 2 / (abs(pl.map.a) or 1.0)
+
+
+def _body(s: Box, b: Any) -> Table:
+    """The boxes (quartiles, whisker ends) in slots shared with the plot's dodged boxes
+    and violins; ``drawn``: the categories with values, ``sts`` their stats."""
+    bs = s.stats
+    cats = s.cols.categories
+    drawn = [i for i, k in enumerate(cats) if bs[k].count]
+    d = Dodge(s, "box", b.flip, list(cats), s.cols["positions"], None)
+    sts = [bs[cats[i]] for i in drawn]
+    t: Any = Table(y0=[st.q1 for st in sts], y1=[st.q3 for st in sts],
+              low=[st.low for st in sts], high=[st.high for st in sts])
+    t.dodge, t.drawn, t.sts = d, drawn, sts
+    t.lazy["x0"] = lambda ctx: placed(d, ctx).back([c - w / 2 for c, w in _geo(ctx, t)])
+    t.lazy["x1"] = lambda ctx: placed(d, ctx).back([c + w / 2 for c, w in _geo(ctx, t)])
+    return t
+
+
+def _whisker_table(s: Box, b: Any) -> Table:
+    """Whiskers (with caps) and medians, per box in drawing order (``order``: ``(box,
+    kind)``)."""
+    body = b.tables["body"]
+    t: Any = Table()
+    order = []
+    b0, b1 = [], []
+    for j, st in enumerate(body.sts):
+        for q, end in ((st.q1, st.low), (st.q3, st.high)):
+            order.append((j, "whisker"))
+            b0.append(q)
+            b1.append(end)
+            order.append((j, "cap"))
+            b0.append(end)
+            b1.append(end)
+        order.append((j, "median"))
+        b0.append(st.median)
+        b1.append(st.median)
+    t["y0"], t["y1"] = b0, b1
+    t.order, t.body = order, body
+
+    def ends(ctx: Any, side: int) -> list[float]:
+        geo = _geo(ctx, body)
+        out = []
+        for j, kind in order:
+            c, w = geo[j]
+            if kind == "whisker":
+                out.append(c)
+            elif kind == "cap":
+                out.append(c + side * _cap_half(s, ctx, body, w))
+            else:
+                out.append(c + side * w / 2)
+        return placed(body.dodge, ctx).back(out)
+
+    t.lazy["x0"] = lambda ctx: ends(ctx, -1)
+    t.lazy["x1"] = lambda ctx: ends(ctx, 1)
+    return t
+
+
+def _outliers(s: Box, b: Any) -> Table | None:
+    body = b.tables["body"]
+    if not sum(len(st.outliers) for st in body.sts):
+        return None
+    values = array.array("d")
+    for st in body.sts:
+        values.extend(st.outliers)
+    t: Any = Table(y=values)
+    t.body = body
+
+    def centres(ctx: Any) -> Any:
+        out = array.array("d")
+        for (c, _), st in zip(_geo(ctx, body), body.sts):
+            out.extend([c] * len(st.outliers))
+        return placed(body.dodge, ctx).back(out)
+    t.lazy["x"] = centres
+    return t
+
+
+def _means(s: Box, b: Any) -> Table | None:
+    body = b.tables["body"]
+    if not body.sts:
+        return None
+    t: Any = Table(y=[st.mean for st in body.sts])
+    t.body = body
+    t.lazy["x"] = lambda ctx: placed(body.dodge, ctx).back([c for c, _ in _geo(ctx, body)])
+    return t
+
+
+@role("box.bodies")
+def _bodies_paint(s: Box, ctx: Any, glyph: bool, table: Any = None) -> dict[str, Any]:
+    fills, lcs, _, _ = _colors(s, ctx)
+    lw = s.resolve("edge_width")
+    if glyph:
+        return {"fill": fills[0] if fills else None,
+                "stroke": lcs[0] if lcs else None, "line_width": lw}
+    return {"fill": [fills[i] for i in table.drawn],
+            "stroke": [lcs[i] for i in table.drawn] if lw else None,
+            "line_width": lw if lw else None}
+
+
+@role("box.lines")
+def _lines_paint(s: Box, ctx: Any, glyph: bool, table: Any = None) -> dict[str, Any]:
+    _, _, wcs, mcs = _colors(s, ctx)
+    body = table.body
+    ww, mw = s.resolve("whisker_width"), s.resolve("median_width")
+    wstyle = s.resolve("whisker_style")
+    geo = _geo(ctx, body)
+    cols: list[Any] = []
+    widths: list[Any] = []
+    dashes: list[Any] = []
+    for j, kind in table.order:
+        i = body.drawn[j]
+        if kind == "median":
+            cols.append(mcs[i])
+            widths.append(mw)
+            dashes.append(None)
+        else:
+            # a box without caps (none drawn when they have no length)
+            no_cap = kind == "cap" and not _cap_half(s, ctx, body, geo[j][1])
+            cols.append(None if no_cap else wcs[i])
+            widths.append(ww)
+            dashes.append(wstyle if kind == "whisker" and wstyle != "solid" else None)
+    return {"color": cols, "width": widths, "dash": dashes, "cap": "butt"}
+
+
+@role("box.outliers")
+def _outliers_paint(s: Box, ctx: Any, glyph: bool, table: Any = None) -> MarkerStyle:
+    _, lcs, _, _ = _colors(s, ctx)
+    body = table.body
+    edges = []                                   # the edge color of its box
+    for j, st in enumerate(body.sts):
+        edges.extend([lcs[body.drawn[j]]] * len(st.outliers))
+    style = MarkerStyle(s, ctx, "marker_", None, len(table["y"]), glyph)
+    if style.fill is None and style.stroke is None:
+        if edges and len(set(edges)) > 1 and None not in edges:
+            style.stroke = edges
+        else:
+            style.stroke = lcs[0] if s.cols.categories else None
+        style.line_width = s.resolve("marker_edge_width")
+    style.simplify = s.resolve("simplify")
+    return style
+
+
+@role("box.mean")
+def _mean_paint(s: Box, ctx: Any, glyph: bool, table: Any = None) -> Marks:
+    _, lcs, _, _ = _colors(s, ctx)
+    body = table.body
+    edges = [lcs[i] or "black" for i in body.drawn]
+    n_out = sum(len(st.outliers) for st in body.sts) if s.resolve("outliers") else 0
+    style = MarkerStyle(s, ctx, "marker_", None, n_out, False)
+    return Marks(resolve(s.resolve("mean_marker"))[0],
+                 style.size if isinstance(style.size, float) else 4.0,
+                 ctx.color(s.resolve("mean_color")),
+                 edges[0] if len(set(edges)) == 1 else edges,
+                 s.resolve("marker_edge_width"))
+
+
+def _finish(s: Box, b: Any) -> None:
+    """Dates on the category axis; exact limits at numeric positions."""
+    cat = b.role("x")
+    b.tables["body"].dodge.time = cat in b.call.times
+    if s.cols["positions"] is not None:
+        b.call.exact = {cat}

plot_io/presets/catpoints.py

@@ -0,0 +1,177 @@
+"""Points per category (``Points``): jittered (position ``jitter``: strip) or side by side
+without overlaps (position ``swarm``), dodged per category."""
+
+import array
+from typing import Any
+
+from .._methods import StripMixin, SwarmMixin
+from .. import groups
+from ..layers.base import Series, common
+from ..layers.core import Table
+from ..layers.grammar import Lay, Spec, flipped
+from ..layers.paint import (MarkerStyle, base_color, density_points, density_stats,
+                            order_settings)
+from ..layers.positions import Dodge, jitter, placed, swarm_offsets
+from ..settings import Setting, boolean, either, literal, number, one_of, table
+from ..transform import settings_both as coord_settings
+from ..validators import length
+from .scatter import _radius
+
+__all__ = ["Strip", "Swarm"]
+
+
+class _CatPoints(Series):
+    SETTINGS: dict[str, Setting] = {}
+    DATA = {"values": "categories", "positions": "slots"}
+    POSITION = "jitter"
+
+    def __init__(self, values: Any, positions: Any = None, plot: Any = None,
+                 **settings: Any) -> None:
+        super().__init__(plot=plot, **settings)
+
+    def _flat(self) -> tuple[list[int], array.array]:
+        cat_index, vals = [], array.array("d")
+        for k, d in enumerate(self.cols.values):
+            cat_index.extend([k] * len(d))
+            vals.extend(d)
+        return cat_index, vals
+
+    def offsets(self, ctx: Any, d: Dodge, widths: list[float], t: Table) -> array.array:
+        raise NotImplementedError
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        """Derived data: ``{"density": values}`` when the series maps a density."""
+        return density_stats(self)
+
+    def density_points(self) -> tuple[Any, Any]:
+        idx, vals = self._flat()
+        pos = self.cols["positions"] or [float(i) for i in range(len(self.cols.categories))]
+        cat = array.array("d", (pos[k] for k in idx))
+        if flipped(self):
+            return density_points(self, vals, cat)
+        return density_points(self, cat, vals)
+
+    SPEC = Spec(
+        [Lay("points", ("marker", {"order": True,
+                                    "n": lambda s: sum(map(len, s.cols.values))}),
+             table="points", name="points", position=lambda s: s.POSITION,
+             occupy_aes={"x": "x_center"}, radius=lambda s: _radius(s.resolve("size")))],
+        tables={"points": lambda s, b: _points(s, b)},
+        key={"fill": "marker", "stroke": "marker", "marker": "@points"},
+        titles={"values": "y", "categories": "x"}, slots="positions", color_sources=True,
+        size_sources=True, finish=lambda s, b: _finish(s, b))
+
+    def _prepare(self, t: Table, n: int) -> None:
+        """Position columns drawn before the axes are placed."""
+
+
+def _points(s: _CatPoints, b: Any) -> Table:
+    """The points by category, placed in slots shared with the plot's dodged points."""
+    d = Dodge(s, "points", b.flip, list(s.cols.categories), s.cols["positions"], None)
+    idx, vals = s._flat()
+    t = Table(y=vals)
+    t.dodge = d
+    s._prepare(t, len(vals))
+
+    def x(ctx: Any) -> Any:
+        pl = placed(d, ctx)
+        sl = pl.geo
+        offs = s.offsets(ctx, d, [w for _, w in sl], t)
+        return pl.back(array.array("d", (sl[k][0] + o for k, o in zip(idx, offs))))
+
+    def centres(ctx: Any) -> Any:
+        pl = placed(d, ctx)
+        return pl.back([pl.geo[k][0] for k in idx])
+
+    t.lazy["x"] = x
+    t.lazy["x_center"] = centres
+    return t
+
+
+def _finish(s: _CatPoints, b: Any) -> None:
+    b.tables["points"].dodge.time = b.role("x") in b.call.times
+
+
+def _settings(extra: dict[str, Setting]) -> dict[str, Setting]:
+    return table(
+        **coord_settings(),
+        **groups.Marker.embed(),
+        **common("color_map", "size_map", "size_key"),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (categories on x) or `horizontal`."),
+        max_width=Setting(length(positive=True, data=True, percent="slot"),
+                          doc="Largest width of the series' part of a slot (as `width`); "
+                              "default none."),
+        width=Setting(length(positive=True, data=True, percent="slot"),
+                      doc="Width the points spread over: `%` of the slot, a length (bare "
+                          "numbers: px), `d` data units, or a duration on time axes."),
+        offset=Setting(length(data=True, percent="slot"),
+                       doc="Shift within the slot, toward higher positions: `%` of the slot, "
+                           "a length (bare numbers: px) or `d` data units."),
+        dodge=Setting(boolean, doc="Point series sharing a category share its slot "
+                                         "side by side; `False` overlays them."),
+        gap=Setting(length(lo=0, percent="slot_part"), doc="Fraction of each part of a shared slot left "
+                                           "empty."),
+        categories=Setting(either(literal(None), lambda v: list(v)),
+                           doc="Category names of a list of arrays."),
+        **extra,
+        **order_settings(),
+        **common("name", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+
+class Strip(StripMixin, _CatPoints):
+    """Points of each category's values, spread across the slot by random jitter (from a
+    fixed seed, so output is reproducible).
+
+    ``values`` as :class:`Box` takes them.  Jitter is uniform, ± ``jitter`` (``%`` of the
+    slot width), from ``seed``.  Marker settings as :class:`Scatter`'s.  ``offset`` moves the
+    points within their slot (``%`` of the slot, toward higher positions).
+
+    Example::
+
+        rng = random.Random(1)
+        p = plt.Plot(width=240, height=160)
+        p.strip({k: [rng.gauss(m, 1) for _ in range(30)] for k, m in (("A", 0), ("B", 1), ("C", 0.5))})
+    """
+
+    SETTINGS = _settings(dict(
+        jitter=Setting(length(lo=0, percent="slot"),
+                       doc="Half-width of the jitter (`%` of the slot width)."),
+        seed=Setting(number(integer=True), doc="Seed of the jitter."),
+    ))
+
+    def _prepare(self, t: Table, n: int) -> None:
+        t["jitter_u"] = jitter(n, self.resolve("seed"))
+
+    def offsets(self, ctx: Any, d: Dodge, widths: list[float], t: Table) -> array.array:
+        scale = abs((ctx.ymap if d.flip else ctx.xmap).a) or None
+        ja, jb = self.resolve_linear("jitter", scale=scale, unit="data")
+        idx, _ = self._flat()
+        return array.array("d", (r * (ja + jb * widths[k]) for k, r in zip(idx, t["jitter_u"])))
+
+
+class Swarm(SwarmMixin, _CatPoints):
+    """Points of each category's values, side by side so that they do not overlap
+    (points that do not fit go to the slot's edge, with a warning; above 100,000 points,
+    jittered across the width as a strip, with a warning).
+
+    ``values`` as :class:`Box` takes them.  The settings are :class:`Strip`'s but ``jitter``
+    and ``seed``.
+
+    Example::
+
+        rng = random.Random(1)
+        p = plt.Plot(width=240, height=160)
+        p.swarm({k: [rng.gauss(m, 1) for _ in range(30)] for k, m in (("A", 0), ("B", 1), ("C", 0.5))})
+    """
+
+    SETTINGS = _settings({})
+    POSITION = "swarm"
+
+    def offsets(self, ctx: Any, d: Dodge, widths: list[float], t: Table) -> array.array:
+        style = MarkerStyle(self, ctx, "", base_color(self, ctx),
+                            sum(len(v) for v in self.cols.values))
+        return swarm_offsets(ctx, d, self.cols.values, style.size, widths)