plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/layers/pipeline.py

@@ -0,0 +1,170 @@
+"""The stages between the model and the drawing: compute, positions, train.
+
+* :func:`plot_calls`: each call of a plot through its preset (stats computed, layers
+  built), then the plot's positions (:func:`~plot_io.layers.positions.run`); cached in
+  the render in progress.
+* :func:`train_colors`: the colors of the calls without a color of their own, from the
+  plot's ``qualitative_map`` in call order (a series' own ``color_map``: its sets, group
+  members and levels), continued across twin plots (a call that needs no hue takes
+  ``plain_color`` when set: :func:`plain_of`); kept in the render (``Render.colors``).
+* :func:`drawn_layers`: a plot's layers in drawing order (``z``, then call order).
+"""
+
+from typing import Any
+
+from ..spec import current
+
+__all__ = ["plot_calls", "call_of", "drawn_layers", "train_colors", "plain_of", "own_map", "z_of",
+           "render_of"]
+
+
+def render_of(plot: Any) -> Any:
+    """The render in progress of ``plot``'s figure, if any."""
+    r = current()
+    return r if r is not None and r.root is getattr(plot, "figure", None) else None
+
+
+def plot_calls(plot: Any) -> list[Any]:
+    """The calls of ``plot``'s series, positions applied (one per series, in call order)."""
+    r = render_of(plot)
+    if r is not None:
+        got = r.plots.get(id(plot))
+        if got is not None:
+            return got
+    from . import positions
+    from ..levels import calls_of
+    made = [(s, calls_of(s)) for s in plot.series]
+    calls = [c for _, cs in made for c in cs]
+    positions.run(plot, calls)
+    if r is not None:
+        r.plots[id(plot)] = calls
+        for s, cs in made:
+            for c in cs:
+                r.calls.setdefault(id(c.series), c)
+            r.calls[id(s)] = cs[0]
+    return calls
+
+
+def call_of(series: Any) -> Any:
+    """The call of one series (its plot's calls are computed together)."""
+    r = render_of(series.plot)
+    if r is not None:
+        got = r.calls.get(id(series))
+        if got is not None:
+            return got
+    calls = plot_calls(series.plot)
+    return next(c for c in calls if c.series is series or c.series.__dict__.get("_of") is series)
+
+
+def z_of(item: Any) -> float:
+    """Drawing order key: ``z``, unset (call order) counting as 0 (sorting is stable)."""
+    z = item.resolve("z")
+    return 0.0 if z is None else z
+
+
+def drawn_layers(plot: Any) -> list[tuple[Any, Any]]:
+    """``(call, layer)`` of the plot's layers drawn inside the axes, in drawing order."""
+    calls = sorted(plot_calls(plot), key=lambda c: z_of(c.series))
+    return [(c, layer) for c in calls for layer in c.layers if not layer.overlay]
+
+
+def _refs(series: Any) -> list[int]:
+    """References to the plot's colors (``"C1"``…) among a series' settings: the plot's
+    colors must hold them."""
+    from ..units import given
+    vals = (given(v) for v in series._values.values() if not isinstance(v, (list, tuple, dict)))
+    return [int(v[1:]) + 1 for v in vals
+            if isinstance(v, str) and v[:1] == "C" and v[1:].isascii() and v[1:].isdigit()]
+
+
+def plain_of(call: Any) -> Any:
+    """The ``plain_color`` of a call that needs no hue (no levels, one color of the plot's,
+    no name: nothing in the legend tells it apart), else ``None``."""
+    s = call.series
+    if call.level is not None or call.color_count != 1 or "plain_color" not in s.SETTINGS:
+        return None
+    if "name" in s.SETTINGS and s.resolve("name") not in (None, ""):
+        return None
+    return s.resolve("plain_color")
+
+
+def own_map(series: Any) -> Any:
+    """The colors a series' own ``color_map`` gives its sets, group members and levels: a
+    ``ColorMap`` (in the series' color variant), a dict level → color, or ``None`` (none set,
+    or ``"auto"``: the plot's colors)."""
+    from ..color.maps import chosen_map
+    if "color_map" not in series.SETTINGS or not series.is_set("color_map"):
+        return None
+    v = series.resolve("color_map")
+    if isinstance(v, dict):
+        return v
+    if v == "auto":
+        return None
+    return chosen_map(series, v, "qualitative")
+
+
+def train_colors(plot: Any, calls: list[Any], twin_calls: list[Any], cycle: Any) -> Any:
+    """Colors for the calls without their own (``Call.color_count`` each), in call order,
+    continued in the twins' calls; ``cycle``: the main plot's colors (twins use them).  The
+    colors are the plot's ``qualitative_map``'s, in each series' color variant; a series'
+    own ``color_map`` colors its sets and its group's members (:func:`own_map`).  A call
+    that needs no hue takes its ``plain_color`` when set (:func:`plain_of`) and leaves the
+    plot's turn where it is.  Returns the plot's colors (``"C<n>"`` refer to them)."""
+    from ..color.maps import cycle_of, map_of
+    from ..color.values import resolve_color, variant_of
+    from ..levels import assign, level_color_count
+    colored = calls + twin_calls
+    plain = {id(c): v for c in colored if (v := plain_of(c)) is not None}
+    if cycle is not None and getattr(plot, "twin_of", None):
+        return cycle
+    n_auto = sum(c.color_count for c in colored if id(c) not in plain) + \
+        level_color_count(colored)
+    n = max([n_auto] + [k for c in colored for k in _refs(c.series)])
+    base = map_of(plot, "qualitative", "base")
+    variants: dict[str, Any] = {}
+
+    def cycle_in(series: Any) -> Any:
+        v = variant_of(series)
+        got = variants.get(v)
+        if got is None:
+            got = variants[v] = cycle_of(base.in_variant(v), n)
+        return got
+    cycle = cycle_in(plot)
+    r = current()
+    assert r is not None
+    i = 0
+    done: dict[Any, Any] = {}
+    for c in colored:
+        s = c.series
+        if c.level is not None:
+            i = assign(plot, c, cycle_in(s), i, done)
+        elif id(c) in plain:
+            r.colors[id(s)] = [resolve_color(plain[id(c)], cycle)]
+            done[id(s)] = r.colors[id(s)]
+        elif c.color_count:
+            own = _own_colors(s, c.color_count)
+            if own is not None:
+                r.colors[id(s)] = own
+            else:
+                pal = cycle_in(s)
+                r.colors[id(s)] = [pal[(i + j) % len(pal)] for j in range(c.color_count)]
+                i += c.color_count
+            done[id(s)] = r.colors[id(s)]
+        else:
+            r.colors[id(s)] = None
+    return cycle
+
+
+def _own_colors(series: Any, count: int) -> list[Any] | None:
+    """The colors of a series' own map for its ``count`` sets, or for its place among the
+    members of its ``group=`` call; ``None``: the plot's colors."""
+    member = series.__dict__.get("_member")
+    if count == 1 and member is None:
+        return None
+    cm = own_map(series)
+    if cm is None or isinstance(cm, dict):
+        return None
+    if member is not None:
+        k, total = member
+        return [cm.colors(total)[k]]
+    return list(cm.colors(count))

plot_io/layers/positions.py

@@ -0,0 +1,431 @@
+"""Positions: what places a layer's items among the other layers of its plot.
+
+They run once per plot, over all its calls, after the stats and before training
+(:func:`run`):
+
+* **stack** (:func:`stack`): tables with ``stack`` set, ``(group, mode[, baseline])``,
+  pile on the previous stacked tables of their group (family and orientation, or one
+  call), per key (a category, a bin, a grid point); positive and negative values pile
+  apart; ``"normalize"`` on any of them divides each key by its total (of absolute
+  values).  With a ``baseline`` (``zero``, ``sym``, ``wiggle``, ``weighted_wiggle``: areas)
+  the tables' values at each index pile in order from the baseline, signs together.
+  Writes ``bottom`` and ``top``.
+* **dodge**: tables of one family (categorical calls: box and violin, bar, points; the sets
+  of a histogram) with the same orientation share each slot (a category, or a bin) side
+  by side, in call order (stacked tables count as one, and so do split violins).  Sets
+  ``parts``: per slot, the part ``(j, m)`` the table takes (``None``: the whole slot).  The
+  slots' centres and widths need the axis scale (widths in px, `%` of the slot):
+  :func:`slots` computes them when the axes are placed, :func:`bin_parts` the parts of
+  bins.
+* **jitter**: a uniform draw in [-1, 1] per point from the call's seed (``jitter_u``),
+  scaled by the jitter width once it is known.
+* **swarm** places points side by side once marker sizes and the axes are known
+  (:func:`swarm_offsets`, a lazy column).
+"""
+
+import array
+import math
+import random
+import warnings
+from typing import Any
+
+from ..units import NeedsScale
+from ..validators import typed
+
+__all__ = ["NAMES", "run", "register", "check_stack", "stack", "slots", "bin_parts", "Dodge",
+           "Placed", "placed", "swarm_offsets"]
+
+#: Positions of plot types registered with :func:`register` (genome signal bands).
+_EXTRA: list[Any] = []
+
+#: The position names a layer may declare (:func:`register` adds more).
+NAMES: list[str] = ["identity", "stack", "dodge", "jitter", "swarm", "pack"]
+
+
+def register(position: Any, name: str | None = None) -> None:
+    """Add a position: ``position(plot, calls)`` runs after the built-in ones, before the
+    presets' steps that need them; ``name``: the name layers declare it by."""
+    if position not in _EXTRA:
+        _EXTRA.append(position)
+    if name is not None and name not in NAMES:
+        NAMES.append(name)
+
+
+@typed("bool | Literal['normalize']")
+def check_stack(v: Any) -> Any:
+    if v == "normalize":
+        return "normalize"
+    if isinstance(v, bool):
+        return v
+    raise ValueError(f"expected True, False or 'normalize', got {v!r}")
+
+
+class Dodge:
+    """A table's place in a dodge family: the series (its ``width``, ``gap``,
+    ``max_width`` and ``dodge`` settings), its categories, numeric ``positions`` (not
+    dodged), and the token it shares a part with (``"stack"``, ``"split"``, or itself)."""
+
+    __slots__ = ("series", "family", "flip", "cats", "positions", "token", "time", "parts",
+                 "side")
+
+    def __init__(self, series: Any, family: Any, flip: bool, cats: list[Any],
+                 positions: Any = None, token: Any = None, time: bool = False) -> None:
+        self.series = series
+        self.family = family
+        self.flip = flip
+        self.cats = cats
+        self.positions = positions
+        self.token = series if token is None else token
+        self.time = time
+        self.parts: list[Any] = []
+        #: split halves (``token="split"``): -1 the lower half, 1 the upper, 0 both
+        self.side = 0
+
+
+def _tables(calls: list[Any]) -> list[Any]:
+    seen: set[int] = set()
+    out = []
+    for call in calls:
+        for layer in call.layers:
+            t = layer.table
+            if id(t) not in seen:
+                seen.add(id(t))
+                out.append(t)
+        for t in getattr(call, "tables", ()):
+            if id(t) not in seen:
+                seen.add(id(t))
+                out.append(t)
+    return out
+
+
+def run(plot: Any, calls: list[Any]) -> None:
+    """The positions of a plot's calls (in call order)."""
+    tables = _tables(calls)
+    _stack(tables)
+    _dodge(tables)
+    for extra in _EXTRA:
+        extra(plot, calls)
+    for call in calls:
+        for step in call.after:
+            step()
+
+
+def _stack(tables: list[Any]) -> None:
+    groups: dict[Any, list[Any]] = {}
+    for t in tables:
+        st = getattr(t, "stack", None)
+        if st:
+            groups.setdefault(st[0], []).append(t)
+    for members in groups.values():
+        normalize = any(t.stack[1] == "normalize" for t in members)
+        baseline = next((t.stack[2] for t in members if len(t.stack) > 2), None)
+        stack(members, normalize, baseline)
+
+
+def stack(members: list[Any], normalize: bool = False, baseline: str | None = None) -> None:
+    """Pile ``members`` (tables with ``heights``, and ``keys`` without a ``baseline``) in
+    order: writes their ``bottom`` and ``top`` (see the module docstring)."""
+    if baseline is not None:
+        _pile(members, baseline)
+        return
+    totals: dict[Any, float] = {}
+    if normalize:
+        for t in members:
+            for k, v in zip(t["keys"], t["heights"]):
+                if math.isfinite(v):
+                    totals[k] = totals.get(k, 0.0) + abs(v)
+    pos: dict[Any, float] = {}
+    neg: dict[Any, float] = {}
+    for t in members:
+        bottoms, tops = [], []
+        for k, v in zip(t["keys"], t["heights"]):
+            if not math.isfinite(v):
+                bottoms.append(math.nan)
+                tops.append(math.nan)
+                continue
+            if normalize:
+                tot = totals.get(k, 0.0)
+                v = v / tot if tot else 0.0
+            acc = pos if v >= 0 else neg
+            b = acc.get(k, 0.0)
+            acc[k] = b + v
+            bottoms.append(b)
+            tops.append(b + v)
+        t["bottom"], t["top"] = bottoms, tops
+
+
+def _pile(members: list[Any], baseline: str) -> None:
+    """The values at each index piled from ``baseline`` (missing values count 0; their
+    tops are NaN): ``zero``, ``sym`` (symmetric around 0), ``wiggle`` or
+    ``weighted_wiggle`` (streamgraphs, as matplotlib's stackplot)."""
+    raws = [t["heights"] for t in members]
+    n = len(raws[0]) if raws else 0
+    ys = [[v if math.isfinite(v) else 0.0 for v in r] for r in raws]
+    m = len(ys)
+    total = [math.fsum(r[j] for r in ys) for j in range(n)]
+    if baseline == "zero":
+        first = [0.0] * n
+    elif baseline == "sym":
+        first = [-t / 2 for t in total]
+    elif baseline == "wiggle":
+        first = [-math.fsum(ys[i][j] * (m - 0.5 - i) for i in range(m)) / m
+                 for j in range(n)]
+    else:
+        inv = [1.0 / t if t else 0.0 for t in total]
+        center = [0.0] * n
+        acc = 0.0
+        for j in range(n):
+            s = 0.0
+            cum = 0.0
+            for i in range(m):
+                cum += ys[i][j]
+                inc = ys[i][j] - (ys[i][j - 1] if j else 0.0) if j else ys[i][j]
+                below = total[j] - cum + 0.5 * ys[i][j]
+                move_up = 0.5 if j == 0 else below * inv[j]
+                s += (move_up - 0.5) * inc
+            acc += s
+            center[j] = acc
+        first = [c - 0.5 * t for c, t in zip(center, total)]
+    cur = first
+    for t, r, raw in zip(members, ys, raws):
+        top = [a + b for a, b in zip(cur, r)]
+        t["bottom"] = array.array("d", cur)
+        t["top"] = array.array("d", (v if math.isfinite(h) else math.nan
+                                     for v, h in zip(top, raw)))
+        cur = top
+
+
+def _dodge(tables: list[Any]) -> None:
+    infos = [t.dodge for t in tables if getattr(t, "dodge", None) is not None]
+    for flip in (False, True):                   # split halves alternate, in call order
+        halves = [d for d in infos if d.token == "split" and d.flip == flip]
+        for i, d in enumerate(halves):
+            d.side = -1 if i % 2 == 0 else 1
+    families: dict[Any, list[Dodge]] = {}
+    for d in infos:
+        if d.positions is not None:
+            d.parts = [None] * len(d.cats)
+        else:
+            families.setdefault((d.family, d.flip), []).append(d)
+    for peers in families.values():
+        # per category, the tokens of the dodging tables that have it, in call order
+        members: dict[Any, dict[Any, int]] = {}
+        dodging = [bool(e.series.resolve("dodge")) for e in peers]
+        for e, on in zip(peers, dodging):
+            if not on:
+                continue
+            for k in e.cats:
+                toks = members.setdefault(k, {})
+                if e.token not in toks:
+                    toks[e.token] = len(toks)
+        for d, on in zip(peers, dodging):
+            if not on:
+                d.parts = [None] * len(d.cats)
+                continue
+            d.parts = [(members[k][d.token], len(members[k])) for k in d.cats]
+
+
+def bin_parts(d: Dodge, lo: Any, hi: Any, scale: Any) -> tuple[list[float], list[float]]:
+    """``(x0, x1)`` of the bins ``lo``–``hi`` (one per of ``d.cats``) for the table's
+    parts: even in the space of the axis ``scale``."""
+    x0, x1 = [], []
+    for a, b, part in zip(lo, hi, d.parts):
+        if part is None:
+            x0.append(a)
+            x1.append(b)
+            continue
+        j, m = part
+        fa = scale.f(a)
+        fd = (scale.f(b) - fa) / m
+        x0.append(scale.inverse(fa + j * fd))
+        x1.append(scale.inverse(fa + (j + 1) * fd))
+    return x0, x1
+
+
+def slots(d: Dodge, ctx: Any) -> list[tuple[float, float]]:
+    """``(center, width)`` of each of ``d.cats`` in category units (data units on a
+    numeric axis), for the axes of ``ctx``."""
+    from .base import slot_width
+    s = d.series
+    state = ctx.y if d.flip else ctx.x
+    scale = abs((ctx.ymap if d.flip else ctx.xmap).a) or None
+    width = slot_width(s, d.positions, d.time, scale)
+    cap = math.inf
+    if "max_width" in s.SETTINGS and s.get("max_width") is not None:
+        cap = slot_width(s, d.positions, d.time, scale, "max_width") or math.inf
+    if d.positions is not None:
+        return [(p, min(width, cap)) for p in d.positions]
+    gap = (0.0, 0.0)
+    if "gap" in s.SETTINGS:
+        try:
+            gap = s.resolve_linear("gap", scale=scale, unit="data")
+        except NeedsScale:
+            pass
+    index: dict[Any, int] = {}
+    for i, c in enumerate(state.categories):
+        index.setdefault(c, i)
+    out = []
+    for k, part in zip(d.cats, d.parts):
+        i = index[k]
+        if part is None:
+            out.append((float(i), min(width, cap)))
+            continue
+        j, m = part
+        share = width / m
+        p = max(share - gap[0] - gap[1] * share, 0.0) if m > 1 else share
+        out.append((i - width / 2 + (j + 0.5) * share, min(p, cap)))
+    return out
+
+
+class Placed:
+    """The slots of a dodged table placed in a drawing context: ``geo``, per category
+    ``(centre, width)`` in slot space (category units, data units on a numeric axis; at
+    numeric positions on an axis with a scale function, the scale's space, as
+    :func:`slot_edges`); :meth:`back` maps slot-space values to data, ``map`` is the
+    category axis' mapper and :meth:`px` its page coordinate of a slot-space value."""
+
+    __slots__ = ("geo", "inverse", "map")
+
+    def __init__(self, d: Dodge, ctx: Any) -> None:
+        self.map = ctx.ymap if d.flip else ctx.xmap
+        sc = (ctx.y if d.flip else ctx.x).scale
+        self.inverse = None
+        if d.positions is None or sc is None or sc.function is None:
+            self.geo = slots(d, ctx)
+        else:
+            self.inverse = sc.inverse
+            fw, dw = _scale_width(d, ctx, sc)
+            self.geo = []
+            for p in d.positions:
+                fp = sc.f(float(p))
+                a, b = _edges(sc, float(p), fw, dw)
+                fa, fb = sc.f(a), sc.f(b)
+                self.geo.append(((fa + fb) / 2, fb - fa) if dw and math.isfinite(fa) and
+                                math.isfinite(fb) else (fp, fw))
+        off = _offset(d, ctx, sc)
+        if off:
+            self.geo = [(c + off, w) for c, w in self.geo]
+
+    def back(self, v: Any) -> Any:
+        if self.inverse is None:
+            return v
+        if isinstance(v, array.array):
+            return array.array("d", map(self.inverse, v))
+        return [self.inverse(x) for x in v]
+
+    def px(self, v: float) -> float:
+        return self.map.position(v)
+
+
+def _offset(d: Dodge, ctx: Any, sc: Any) -> float:
+    """The series' ``offset`` within the slot, in slot space (0 without one)."""
+    from .base import slot_parts, slot_width
+    s = d.series
+    if "offset" not in s.SETTINGS or s.get("offset") in (None, 0):
+        return 0.0
+    px = abs((ctx.ymap if d.flip else ctx.xmap).a) or None
+    if d.positions is None or sc is None or sc.function is None:
+        return slot_width(s, d.positions, d.time, px, "offset")
+    return slot_parts(s, d.positions, d.time, sc, px, "offset")[0]
+
+
+def placed(d: Dodge, ctx: Any) -> Placed:
+    """The :class:`Placed` slots of ``d`` for ``ctx`` (once per drawing context)."""
+    from .paint import memo
+    return memo(ctx, (id(d), "placed"), lambda: Placed(d, ctx))
+
+
+def _scale_width(d: Dodge, ctx: Any, sc: Any) -> tuple[float, float]:
+    """The slot width of ``d``'s series at its positions in the space of scale ``sc`` and
+    in data units (:func:`~plot_io.layers.base.slot_parts`, ``max_width`` applied)."""
+    from .base import slot_parts
+    s = d.series
+    px = abs((ctx.ymap if d.flip else ctx.xmap).a) or None
+    fw, dw = slot_parts(s, d.positions, d.time, sc, px)
+    if "max_width" in s.SETTINGS and s.get("max_width") is not None:
+        cf, cd = slot_parts(s, d.positions, d.time, sc, px, "max_width")
+        fw, dw = (min(fw, cf) if cf else fw), (min(dw, cd) if cd else dw)
+    return fw, dw
+
+
+def slot_edges(d: Dodge, ctx: Any) -> list[tuple[float, float]]:
+    """``(x0, x1)`` of each of ``d.cats`` (as :func:`slots`).  At numeric positions on an
+    axis with a scale function, the slot and the ``%`` and px parts of the width are in the
+    scale's space (edges at ``f⁻¹(f(p) ± w/2)``); a width in data units stays in data
+    units (ends outside the scale's domain are drawn at the axes' edge)."""
+    sc = (ctx.y if d.flip else ctx.x).scale
+    if d.positions is None or sc is None or sc.function is None:
+        return [(c - w / 2, c + w / 2) for c, w in slots(d, ctx)]
+    fw, dw = _scale_width(d, ctx, sc)
+    return [_edges(sc, float(p), fw, dw) for p in d.positions]
+
+
+def _edges(sc: Any, p: float, fw: float, dw: float) -> tuple[float, float]:
+    """Edges of a slot of ``fw`` in the scale's space and ``dw`` in data units at ``p``."""
+    fp = sc.f(p)
+    a = b = p
+    if fw and math.isfinite(fp):
+        a, b = sc.inverse(fp - fw / 2), sc.inverse(fp + fw / 2)
+    return a - dw / 2, b + dw / 2
+
+
+def slot_extent(s: Any, positions: Any, time: bool, scale: Any) -> tuple[int, float, float]:
+    """``(count, lo, hi)`` of numeric ``positions`` widened by half a slot (``width`` of
+    ``s``), for the limits: on an axis with a scale function as :func:`slot_edges` does,
+    without the parts outside the scale's domain."""
+    from .. import kernels
+    from .base import slot_parts, slot_width
+    n, lo, hi = kernels.extent(positions, scale.function)
+    if scale.function is None:
+        w = slot_width(s, positions, time) / 2
+        return n, lo - w, hi + w
+    if not n:
+        return n, lo, hi
+    fw, dw = slot_parts(s, positions, time, scale)
+    a, b = _edges(scale, lo, fw, dw)[0], _edges(scale, hi, fw, dw)[1]
+    return n, (a if scale.contains(a) else lo), (b if scale.contains(b) else hi)
+
+
+def jitter(n: int, seed: Any) -> list[float]:
+    """``n`` uniform draws in [-1, 1] from ``seed``."""
+    rng = random.Random(seed)
+    return [rng.uniform(-1.0, 1.0) for _ in range(n)]
+
+
+#: Most points of one swarm series; above, its points are jittered across the width, as a
+#: strip, with a warning.
+SWARM_MAX = 100_000
+
+
+def swarm_offsets(ctx: Any, d: Dodge, data: list[Any], size: Any,
+                  widths: list[float]) -> Any:
+    """Offsets (category units) that put each category's points side by side without
+    overlaps; points that do not fit go to the slot's edge, with a warning.  Above
+    :data:`SWARM_MAX` points, uniform jitter over the width (seed 0), with a warning."""
+    import array
+    from .. import kernels
+    total = sum(len(v) for v in data)
+    if total > SWARM_MAX:
+        warnings.warn(f"swarm of {total:,} points (more than {SWARM_MAX:,}): drawn as a "
+                      "strip, jittered across the width", stacklevel=2)
+        r = jitter(total, 0)
+        k_of = [k for k, v in enumerate(data) for _ in range(len(v))]
+        return array.array("d", (u * widths[k] / 2 for u, k in zip(r, k_of)))
+    cmap, vmap = (ctx.ymap, ctx.xmap) if d.flip else (ctx.xmap, ctx.ymap)
+    unit = abs(cmap.position(1.0) - cmap.position(0.0)) or 1.0   # page units per slot unit
+    out = array.array("d")
+    gutter = 0
+    start = 0
+    for k, v in enumerate(data):
+        n = len(v)
+        sz = size if isinstance(size, float) else array.array("d", size[start:start + n])
+        start += n
+        pos = vmap.many(v)
+        offs, g = kernels.swarm(pos, sz, widths[k] * unit)
+        gutter += g
+        sign = 1.0 if cmap.position(1.0) > cmap.position(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