plot-io 0.1.0__py3-none-any.whl

plot_io/series/box.py

@@ -0,0 +1,401 @@
+"""Box plots: quartiles, whiskers and outliers per category."""
+
+import array
+from typing import Any
+
+from .. import _backend
+from ..markers import check_marker, resolve
+from ..settings import Setting, boolean, color, either, literal, number, one_of, pair, table
+from ..style import desaturate, with_alpha
+from . import Series, common
+from .points import MarkerStyle, marker_settings
+from ..values import Values, category_paint
+from ..slots import slots
+
+__all__ = ["Box"]
+
+
+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)
+
+
+def _line_color(v: Any) -> Any:
+    if v in ("series", "auto"):
+        return v
+    return color(v)
+
+
+def _dash(v: Any) -> Any:
+    if isinstance(v, (list, tuple)):
+        return [number(lo=0)(x) for x in v]
+    return one_of("solid", "dashed", "dotted", "dashdot")(v)
+
+
+class Box(Series):
+    """Box plots of ``values``: a dict ``{category: values}``, a list of arrays
+    (categories ``0, 1, …`` or ``categories=``), or one array."""
+
+    SETTINGS = table(
+        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 next palette color."),
+        **common("color_map"),
+        line_color=Setting(_line_color,
+                           doc="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)."),
+        whisker_color=Setting(_line_color, doc="Whisker and cap color; default `line_color`."),
+        whisker_style=Setting(_dash,
+                              doc="Whisker line style: `solid`, `dashed`, `dotted`, `dashdot` or "
+                                  "a dash list (caps stay solid)."),
+        line_width=Setting(number(lo=0), doc="Outline and whisker width (pt).", length=True),
+        median_color=Setting(_line_color, doc="Median line color; default `line_color`."),
+        median_width=Setting(number(lo=0), doc="Median line width (pt).", length=True),
+        width=Setting(number(positive=True),
+                      doc="Width of a category's slot (category units)."),
+        cap_width=Setting(number(lo=0), doc="Whisker cap width, as a fraction of the box."),
+        whiskers=Setting(_whiskers,
+                         doc="Whisker reach: a multiple of the IQR, `\"range\"`, or "
+                             "percentiles `(lo, hi)`."),
+        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)."),
+        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: "
+                                               "`line_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(number(0, 1), 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."),
+        **marker_settings("marker_"),
+        **common("name", "alpha", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    DODGE_GROUP = "box"
+    LONG_FORM = True
+
+    def __init__(self, values: Any, positions: Any = None, plot: Any = None,
+                 **settings: Any) -> None:
+        cats = settings.get("categories")
+        if isinstance(values, dict):
+            items = list(values.items())
+        elif _is_sequence_of_arrays(values):
+            names = list(cats) if cats is not None else list(range(len(values)))
+            if len(names) != len(values):
+                raise ValueError(f"{len(names)} categories for {len(values)} boxes")
+            items = list(zip(names, values))
+        else:
+            items = [(cats[0] if cats else 0, values)]
+        self.cats = [k for k, _ in items]
+        self.data = [_backend.doubles(v) for _, v in items]
+        self.positions = None if positions is None else [float(p) for p in positions]
+        if self.positions is not None and len(self.positions) != len(self.cats):
+            raise ValueError(f"{len(self.positions)} positions for {len(self.cats)} boxes")
+        self._stats: dict[Any, Any] = {}
+        self._stats_key: Any = None
+        self._drawn: list[tuple[float, Any]] = []
+        super().__init__(plot=plot, **settings)
+
+    # -- statistics -------------------------------------------------------------------
+
+    @property
+    def stats(self) -> dict[Any, Any]:
+        """``{category: BoxStats}``: count, mean, q1, median, q3, low, high, outliers."""
+        key = self.get("whiskers")
+        if self._stats_key != key or not self._stats:
+            self._stats = {k: _backend.box_stats(v, key) for k, v in zip(self.cats, self.data)}
+            self._stats_key = key
+        return self._stats
+
+    def _horizontal(self) -> bool:
+        return self.get("orientation") == "horizontal"
+
+    def _cat_role(self) -> str:
+        return "y" if self._horizontal() else "x"
+
+    def categories(self, role: str) -> list[Any] | None:
+        if role == self._cat_role() and self.positions is None:
+            return list(self.cats)
+        return None
+
+    def values(self, role: str) -> Any:
+        if role == self._cat_role():
+            return array.array("d", self.positions or [])
+        out = array.array("d")
+        show_out = self.get("outliers")
+        for st in self.stats.values():
+            if st.count:
+                out.extend((st.low, st.high, st.q1, st.q3))
+                if show_out:
+                    out.extend(st.outliers)
+                if self.get("mean"):
+                    out.append(st.mean)
+        return out
+
+    def extent(self, role: str, scale: Any) -> tuple[int, float, float]:
+        if role == self._cat_role() and self.positions is not None:
+            w = self.get("width") / 2
+            n, lo, hi = _backend.extent(self.positions, scale.function)
+            return n, lo - w, hi + w
+        return super().extent(role, scale)
+
+    def zero_default(self, role: str) -> bool:
+        return role != self._cat_role()
+
+    def zero_padding(self, role: str) -> bool:
+        return role == self._cat_role() and self.positions is not None
+
+    def color_sources(self) -> list[tuple[Any, Any]]:
+        c = self.get("color")
+        if isinstance(c, Values):
+            return [(self.color_map_obj(), array.array("d", self._per_box(c.data)))]
+        return []
+
+    def _per_box(self, v: Any) -> list[Any]:
+        if isinstance(v, dict):
+            return [v.get(k, float("nan")) for k in self.cats]
+        if len(v) != len(self.cats):
+            raise ValueError(f"{len(v)} values for {len(self.cats)} boxes")
+        return list(v)
+
+    # -- geometry ---------------------------------------------------------------------
+
+    def _slots(self, ctx: Any) -> list[tuple[float, float]]:
+        """``(center, width)`` of each box, in category units."""
+        return slots(self, ctx)
+
+    def _fills(self, ctx: Any) -> list[Any]:
+        alpha = self.get("alpha")
+        alpha = 1.0 if alpha is None else alpha
+        cols = self._base_colors(ctx)
+        sat = self.get("saturation")
+        if sat != 1.0:
+            cols = [desaturate(x, sat) if x is not None else None for x in cols]
+        return [with_alpha(x, alpha) if x is not None else None for x in cols]
+
+    def _lines(self, ctx: Any, setting: str, fallback: list[Any] | None = None) -> list[Any]:
+        """Per-box colors of a line setting (`line_color`, `whisker_color`, `median_color`)."""
+        v = self.get(setting)
+        n = len(self.cats)
+        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 pdf_io.colors import to_rgba
+            rgbas = [to_rgba(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
+
+    def _base_colors(self, ctx: Any) -> list[Any]:
+        """Each box's color before saturation and opacity."""
+        c = self.get("color")
+        n = len(self.cats)
+        if isinstance(c, Values):
+            cm = self.color_map_obj()
+            limits = ctx.maps[id(cm)]
+            from ..scales import get_scale
+            f = get_scale(cm.scale).f
+            vals = self._per_box(c.data)
+            span = (limits[1] - limits[0]) or 1.0
+            cols = [cm((f(v) - limits[0]) / span) for v in vals]
+        elif isinstance(c, dict):
+            cols = [ctx.color(c[k]) if c.get(k) is not None else None for k in self.cats]
+        elif isinstance(c, list):
+            if len(c) != n:
+                raise ValueError(f"{len(c)} colors for {n} boxes")
+            cols = [ctx.color(x) for x in c]
+        else:
+            cols = [self.base_color(ctx)] * n
+        return cols
+
+    def draw(self, ctx: Any) -> None:
+        canvas = ctx.canvas
+        horiz = self._horizontal()
+        cmap, vmap = (ctx.ymap, ctx.xmap) if horiz else (ctx.xmap, ctx.ymap)
+        lcs = self._lines(ctx, "line_color")
+        wcs = self._lines(ctx, "whisker_color", lcs)
+        mcs = [m if m is not None else lc
+               for m, lc in zip(self._lines(ctx, "median_color", lcs), lcs)]
+        lw = self.get("line_width")
+        mw = self.get("median_width")
+        wstyle = self.get("whisker_style")
+        dashed: dict[Any, tuple[list[float], list[float]]] = {}
+        fills = self._fills(ctx)
+        cap = self.get("cap_width")
+        # a0, b0, a1, b1, color, width of segments (a: across the boxes, b: along values)
+        seg: tuple[list[Any], ...] = ([], [], [], [], [], [])
+        outs_a = array.array("d")
+        outs_b = array.array("d")
+        means: list[tuple[float, float]] = []
+        self._drawn = []
+        stats = self.stats
+        lc = lcs[0] if lcs else None
+        for (center, width), k, fill, lc, wc, mc in zip(self._slots(ctx), self.cats, fills,
+                                                         lcs, wcs, mcs):
+            st = stats[k]
+            if not st.count:
+                continue
+            a0, a1 = cmap(center - width / 2), cmap(center + width / 2)
+            ac = cmap(center)
+            q1, q3, med = vmap(st.q1), vmap(st.q3), vmap(st.median)
+            lo, hi = vmap(st.low), vmap(st.high)
+            self._drawn.append((center, st))
+            canvas.begin_path()
+            if horiz:
+                canvas.rect(min(q1, q3), min(a0, a1), abs(q3 - q1), abs(a1 - a0))
+            else:
+                canvas.rect(min(a0, a1), min(q1, q3), abs(a1 - a0), abs(q3 - q1))
+            if fill is not None:
+                canvas.fill(fill)
+            if lc is not None and lw:
+                canvas.line_width = lw
+                canvas.stroke(lc)
+            half = abs(a1 - a0) * cap / 2
+            for b0, b1 in ((q1, lo), (q3, hi)):
+                if wstyle == "solid":
+                    seg[0].append(ac)
+                    seg[1].append(b0)
+                    seg[2].append(ac)
+                    seg[3].append(b1)
+                    seg[4].append(wc)
+                    seg[5].append(lw)
+                elif wc is not None and lw:
+                    xs_, ys_ = dashed.setdefault(wc, ([], []))
+                    a_, b_ = (ys_, xs_) if horiz else (xs_, ys_)
+                    a_ += [ac, ac, float("nan")]
+                    b_ += [b0, b1, float("nan")]
+                if half:
+                    seg[0].append(ac - half)
+                    seg[1].append(b1)
+                    seg[2].append(ac + half)
+                    seg[3].append(b1)
+                    seg[4].append(wc)
+                    seg[5].append(lw)
+            seg[0].append(a0)
+            seg[1].append(med)
+            seg[2].append(a1)
+            seg[3].append(med)
+            seg[4].append(mc)
+            seg[5].append(mw)
+            if self.get("outliers") and len(st.outliers):
+                outs_a.extend([ac] * len(st.outliers))
+                outs_b.extend(vmap.many(st.outliers))
+            if self.get("mean"):
+                means.append((ac, vmap(st.mean)))
+        keep = [i for i in range(len(seg[0])) if seg[4][i] is not None and seg[5][i]]
+        if keep:
+            cols = [seg[i] for i in range(6)]
+            pick = [[c[i] for i in keep] for c in cols]
+            a0s, b0s, a1s, b1s, colors, widths = pick
+            if horiz:
+                canvas.draw_segments(b0s, a0s, b1s, a1s, color=colors, width=widths,
+                                     cap="butt")
+            else:
+                canvas.draw_segments(a0s, b0s, a1s, b1s, color=colors, width=widths,
+                                     cap="butt")
+        from ..style import dash_of
+        for wc, (xs_, ys_) in dashed.items():
+            canvas.draw_lines(xs_, ys_, color=wc, width=lw, dash=dash_of(wstyle, lw), cap="butt")
+        style = self._marker_style(ctx, len(outs_a))
+        if len(outs_a):
+            xs, ys = (outs_b, outs_a) if horiz else (outs_a, outs_b)
+            style.draw(canvas, xs, ys, self.simplify_arg())
+        if means:
+            mx = [b if horiz else a for a, b in means]
+            my = [a if horiz else b for a, b in means]
+            canvas.draw_markers(mx, my, marker=resolve(self.get("mean_marker"))[0],
+                                size=style.size if isinstance(style.size, float) else 3.0,
+                                fill=ctx.color(self.get("mean_color")), stroke=lc or "black",
+                                line_width=self.get("marker_line_width"))
+
+    def _marker_style(self, ctx: Any, n: int, glyph: bool = False) -> MarkerStyle:
+        style = MarkerStyle(self, ctx, "marker_", None, n, glyph)
+        if style.fill is None and style.stroke is None:
+            style.stroke = self._lines(ctx, "line_color")[0] if self.cats else None
+            style.line_width = self.get("marker_line_width")
+        return style
+
+    def occupy(self, ctx: Any, occ: Any) -> None:
+        lo, hi, c0, c1, ox, oy = [], [], [], [], [], []
+        stats = self.stats
+        for (center, width), k in zip(self._slots(ctx), self.cats):
+            st = stats.get(k)
+            if st is None or not st.count:
+                continue
+            lo.append(st.low)
+            hi.append(st.high)
+            c0.append(center - width / 2)
+            c1.append(center + width / 2)
+            ox.extend([center] * len(st.outliers))
+            oy.extend(st.outliers)
+        if self._horizontal():
+            occ.rects(ctx.xmap.many(lo), ctx.ymap.many(c0), ctx.xmap.many(hi), ctx.ymap.many(c1))
+            occ.points(ctx.xmap.many(oy), ctx.ymap.many(ox))
+        else:
+            occ.rects(ctx.xmap.many(c0), ctx.ymap.many(lo), ctx.xmap.many(c1), ctx.ymap.many(hi))
+            occ.points(ctx.xmap.many(ox), ctx.ymap.many(oy))
+
+    def legend_points(self) -> tuple[Any, Any] | None:
+        xs, ys = array.array("d"), array.array("d")
+        for center, st in self._drawn:
+            for v in (st.low, st.q1, st.median, st.q3, st.high):
+                xs.append(center)
+                ys.append(v)
+        return (ys, xs) if self._horizontal() else (xs, ys)
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        fills = self._fills(ctx)
+        lines = self._lines(ctx, "line_color")
+        return (fills[0] if fills else None), (lines[0] if lines else None)
+
+    def legend_glyph(self, ctx: Any, x: float, y: float, w: float, h: float) -> None:
+        canvas = ctx.canvas
+        fills = self._fills(ctx)
+        fill = fills[0] if fills else None
+        lcs = self._lines(ctx, "line_color")
+        lc = lcs[0] if lcs else None
+        bw = min(w, 1.6 * h)
+        bx = x + (w - bw) / 2
+        canvas.begin_path()
+        canvas.rect(bx, y, bw, h)
+        if fill is not None:
+            canvas.fill(fill)
+        if lc is not None:
+            canvas.line_width = self.get("line_width")
+            canvas.stroke(lc)
+            mcs = self._lines(ctx, "median_color", lcs)
+            mc = mcs[0] if mcs and mcs[0] is not None else lc
+            canvas.draw_segments([bx], [y + h / 2], [bx + bw], [y + h / 2], color=mc,
+                                 width=min(self.get("median_width"), h / 3))
+
+
+def _is_sequence_of_arrays(v: Any) -> bool:
+    if isinstance(v, (str, bytes)) or _backend.doubles is None:
+        return False
+    try:
+        mv = memoryview(v)
+        return mv.ndim == 2
+    except TypeError:
+        pass
+    if not isinstance(v, (list, tuple)) or not v:
+        return False
+    return all(hasattr(x, "__len__") and not isinstance(x, str) for x in v)

plot_io/series/catdata.py

@@ -0,0 +1,23 @@
+"""Per-category values of violin, strip and swarm series (the forms box plots take)."""
+
+from typing import Any
+
+from .. import _backend
+
+__all__ = ["category_values"]
+
+
+def category_values(values: Any, categories: Any = None) -> tuple[list[Any], list[Any]]:
+    """``(categories, arrays)`` of a dict ``{category: values}``, a list of arrays
+    (categories ``0, 1, …`` or ``categories``), or one array."""
+    from .box import _is_sequence_of_arrays
+    if isinstance(values, dict):
+        items = list(values.items())
+    elif _is_sequence_of_arrays(values):
+        names = list(categories) if categories is not None else list(range(len(values)))
+        if len(names) != len(values):
+            raise ValueError(f"{len(names)} categories for {len(values)} value sets")
+        items = list(zip(names, values))
+    else:
+        items = [(categories[0] if categories else 0, values)]
+    return [k for k, _ in items], [_backend.doubles(v) for _, v in items]

plot_io/series/catpoints.py

@@ -0,0 +1,182 @@
+"""Points per category: jittered (strip) or side by side without overlaps (swarm)."""
+
+import array
+import math
+import random
+import warnings
+from typing import Any
+
+from .. import stats
+from ..settings import Setting, boolean, either, literal, number, one_of, table
+from ..slots import slots
+from . import Series, common
+from .catdata import category_values
+from .points import (MarkerStyle, density_points, marker_settings, order_index,
+                     order_settings, permuted)
+
+__all__ = ["Strip", "Swarm"]
+
+
+class _CatPoints(Series):
+    SETTINGS: dict[str, Setting] = {}
+    DODGE_GROUP = "points"
+    LONG_FORM = True
+
+    def __init__(self, values: Any, positions: Any = None, plot: Any = None,
+                 **settings: Any) -> None:
+        self.cats, self.data = category_values(values, settings.get("categories"))
+        self.positions = None if positions is None else [float(p) for p in positions]
+        if self.positions is not None and len(self.positions) != len(self.cats):
+            raise ValueError(f"{len(self.positions)} positions for {len(self.cats)} sets")
+        super().__init__(plot=plot, **settings)
+
+    def _horizontal(self) -> bool:
+        return self.get("orientation") == "horizontal"
+
+    def _cat_role(self) -> str:
+        return "y" if self._horizontal() else "x"
+
+    def categories(self, role: str) -> list[Any] | None:
+        if role == self._cat_role() and self.positions is None:
+            return list(self.cats)
+        return None
+
+    def values(self, role: str) -> Any:
+        if role == self._cat_role():
+            return array.array("d", self.positions or [])
+        out = array.array("d")
+        for d in self.data:
+            out.extend(d)
+        return out
+
+    def extent(self, role: str, scale: Any) -> tuple[int, float, float]:
+        if role == self._cat_role() and self.positions is not None:
+            from .. import _backend
+            w = self.get("width") / 2
+            n, lo, hi = _backend.extent(self.positions, scale.function)
+            return n, lo - w, hi + w
+        return super().extent(role, scale)
+
+    def _flat(self) -> tuple[list[int], array.array]:
+        cat_index, vals = [], array.array("d")
+        for k, d in enumerate(self.data):
+            cat_index.extend([k] * len(d))
+            vals.extend(d)
+        return cat_index, vals
+
+    def offsets(self, ctx: Any, centers: list[float], widths: list[float]) -> array.array:
+        raise NotImplementedError
+
+    def positions_page(self, ctx: Any) -> tuple[array.array, array.array]:
+        sl = slots(self, ctx)
+        centers = [c for c, _ in sl]
+        widths = [w for _, w in sl]
+        idx, vals = self._flat()
+        offs = self.offsets(ctx, centers, widths)
+        cat = array.array("d", (centers[k] + o for k, o in zip(idx, offs)))
+        return (vals, cat) if self._horizontal() else (cat, vals)
+
+    def legend_points(self) -> tuple[Any, Any] | None:
+        idx, vals = self._flat()
+        pos = self.positions or [float(i) for i in range(len(self.cats))]
+        cat = array.array("d", (pos[k] for k in idx))
+        return (vals, cat) if self._horizontal() else (cat, vals)
+
+    def _style(self, ctx: Any, n: int, glyph: bool = False) -> MarkerStyle:
+        return MarkerStyle(self, ctx, "", self.base_color(ctx), n, glyph)
+
+    def draw(self, ctx: Any) -> None:
+        xs, ys = self.positions_page(ctx)
+        idx = order_index(self, len(xs))
+        style = MarkerStyle(self, ctx, "", self.base_color(ctx), len(xs), False, idx)
+        px, py = ctx.xmap.many(xs), ctx.ymap.many(ys)
+        if idx is not None:
+            px, py = permuted(px, idx), permuted(py, idx)
+        style.draw(ctx.canvas, px, py, self.simplify_arg())
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        """Derived data: ``{"density": values}`` when the series maps a density."""
+        from .points import density_stats
+        return density_stats(self)
+
+    def density_points(self) -> tuple[Any, Any]:
+        pts: Any = self.legend_points()
+        return density_points(self, pts[0], pts[1])
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        style = self._style(ctx, 1, True)
+        return style.first_color("fill"), style.first_color("stroke")
+
+    def legend_glyph(self, ctx: Any, x: float, y: float, w: float, h: float) -> None:
+        self._style(ctx, 1, True).glyph(ctx.canvas, x + w / 2, y + h / 2, h * 1.1)
+
+
+def _settings(extra: dict[str, Setting]) -> dict[str, Setting]:
+    return table(
+        **marker_settings(),
+        **common("color_map", "size_map", "size_legend"),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (categories on x) or `horizontal`."),
+        width=Setting(number(positive=True), doc="Width of a category's slot."),
+        dodge=Setting(boolean, doc="Point series sharing a category share its slot "
+                                         "side by side; `False` overlays them."),
+        gap=Setting(number(0, 1), 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(_CatPoints):
+    """Points of each category's values, spread across the slot by random jitter (from a
+    fixed seed, so output is reproducible)."""
+
+    SETTINGS = _settings(dict(
+        jitter=Setting(number(lo=0),
+                       doc="Half-width of the jitter, as a fraction of the slot width."),
+        seed=Setting(number(integer=True), doc="Seed of the jitter."),
+    ))
+
+    def offsets(self, ctx: Any, centers: list[float], widths: list[float]) -> array.array:
+        rng = random.Random(self.get("seed"))
+        j = self.get("jitter")
+        idx, _ = self._flat()
+        return array.array("d", (rng.uniform(-j, j) * widths[k] for k in idx))
+
+
+class Swarm(_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)."""
+
+    SETTINGS = _settings({})
+
+    def offsets(self, ctx: Any, centers: list[float], widths: list[float]) -> array.array:
+        horiz = self._horizontal()
+        cmap, vmap = (ctx.ymap, ctx.xmap) if horiz else (ctx.xmap, ctx.ymap)
+        unit = abs(cmap(1.0) - cmap(0.0)) or 1.0         # page units per category unit
+        style = self._style(ctx, sum(len(d) for d in self.data))
+        size = style.size
+        out = array.array("d")
+        gutter = 0
+        start = 0
+        for k, d in enumerate(self.data):
+            n = len(d)
+            sz = size if isinstance(size, float) else array.array("d", size[start:start + n])
+            start += n
+            pos = vmap.many(d)
+            offs, g = stats.swarm(pos, sz, widths[k] * unit)
+            gutter += g
+            sign = 1.0 if cmap(1.0) > cmap(0.0) else -1.0
+            out.extend(o / unit * sign for o in offs)
+        if gutter:
+            warnings.warn(f"{gutter} swarm points did not fit their slot and were placed at "
+                          "its edge", stacklevel=2)
+        return out
+
+
+del math