plot-io 0.1.0__py3-none-any.whl

plot_io/series/scatter.py

@@ -0,0 +1,103 @@
+"""Scatter: markers at points."""
+
+import array
+from typing import Any
+
+from .. import _backend
+from ..settings import Setting, table
+from . import Series, common
+from .errors import error_value
+from .points import (MarkerStyle, density_points, marker_settings, order_index,
+                     order_settings, permuted)
+
+__all__ = ["Scatter"]
+
+
+def _check_xy(x: Any, y: Any) -> tuple[array.array, array.array]:
+    xs, ys = _backend.doubles(x), _backend.doubles(y)
+    if len(xs) != len(ys):
+        raise ValueError(f"x has {len(xs)} values and y {len(ys)}")
+    return xs, ys
+
+
+class Scatter(Series):
+    """Markers at points ``(x, y)``.
+
+    ``color``, ``line_color``, ``size``, ``marker`` and ``alpha`` take one value or one per
+    point.  Numbers per point in ``color``/``line_color`` are mapped through ``color_map``;
+    in ``size``, through ``size_map`` when it is set; ``"density"`` maps the points'
+    density.
+    """
+
+    SETTINGS = table(
+        **marker_settings(),
+        **common("color_map", "size_map", "size_legend"),
+        **order_settings(),
+        x_error=Setting(error_value, doc="Horizontal error bars: a value, a sequence, "
+                                         "`(low, high)` or `ErrorBars`."),
+        y_error=Setting(error_value, doc="Vertical error bars."),
+        **common("name", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    def __init__(self, x: Any, y: Any, plot: Any = None, **settings: Any) -> None:
+        self.x, self.y = _check_xy(x, y)
+        super().__init__(plot=plot, **settings)
+
+    def _error(self, role: str) -> Any:
+        e = self.get("x_error" if role == "x" else "y_error")
+        if e is not None:
+            e.bind(len(self.x))
+        return e
+
+    def values(self, role: str) -> Any:
+        v = self.x if role == "x" else self.y
+        e = self._error(role)
+        if e is None:
+            return v
+        lo, hi = e.ends(v)
+        out = array.array("d", v)
+        out.extend(lo)
+        out.extend(hi)
+        return out
+
+    def legend_points(self) -> tuple[Any, Any]:
+        return self.x, self.y
+
+    def _style(self, ctx: Any, glyph: bool = False) -> MarkerStyle:
+        return MarkerStyle(self, ctx, "", self.base_color(ctx), len(self.x), glyph)
+
+    def draw(self, ctx: Any) -> None:
+        idx = order_index(self, len(self.x))
+        style = MarkerStyle(self, ctx, "", self.base_color(ctx), len(self.x), False, idx)
+        simplify = self.simplify_arg()
+        glyph = self._style(ctx, True)
+        base = glyph.first_color("fill") or glyph.first_color("stroke")
+        for role in ("x", "y"):
+            e = self._error(role)
+            if e is not None:
+                e.draw(ctx, self.x, self.y, role == "x", base, 0.8, simplify, style.opacity)
+        xs = ctx.xmap.many(self.x)
+        ys = ctx.ymap.many(self.y)
+        if idx is not None:
+            xs, ys = permuted(xs, idx), permuted(ys, idx)
+        style.draw(ctx.canvas, xs, ys, simplify)
+
+    @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]:
+        return density_points(self, self.x, self.y)
+
+    def zero_default(self, role: str) -> bool:
+        return True
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        style = self._style(ctx, 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, True).glyph(ctx.canvas, x + w / 2, y + h / 2, h * 1.1)

plot_io/series/stem.py

@@ -0,0 +1,112 @@
+"""Stems: lines from a baseline to each value, ending in a marker (lollipops)."""
+
+import array
+from typing import Any
+
+from .. import _backend
+from ..settings import Setting, color, number, one_of, table
+from ..style import with_alpha
+from . import Series, common
+from .points import MarkerStyle, marker_settings
+
+__all__ = ["Stem"]
+
+
+class Stem(Series):
+    """Stems from ``baseline`` to ``y`` at ``x`` (or at 0, 1, … when ``y`` is omitted)."""
+
+    SETTINGS = table(
+        **marker_settings("marker_"),
+        color=Setting(color, doc="Stem and marker color; default: the next palette color."),
+        line_width=Setting(number(lo=0), inherited=True, doc="Stem width (pt).", length=True),
+        baseline=Setting(number(), doc="Value the stems start from."),
+        baseline_color=Setting(color, doc="Baseline color; `none`: no baseline."),
+        baseline_width=Setting(number(lo=0), doc="Baseline width (pt).", length=True),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` stems (values on y) or `horizontal`."),
+        **common("name", "alpha", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    def __init__(self, x: Any, y: Any = None, plot: Any = None, **settings: Any) -> None:
+        if y is None:
+            y = x
+            x = range(len(_backend.doubles(y)))
+        self.x, self.y = _backend.doubles(x), _backend.doubles(y)
+        if len(self.x) != len(self.y):
+            raise ValueError(f"x has {len(self.x)} values and y {len(self.y)}")
+        super().__init__(plot=plot, **settings)
+
+    def _horizontal(self) -> bool:
+        return self.get("orientation") == "horizontal"
+
+    def values(self, role: str) -> Any:
+        val_role = "x" if self._horizontal() else "y"
+        if role == val_role:
+            out = array.array("d", self.y)
+            out.append(self.get("baseline"))
+            return out
+        return self.x
+
+    def zero_default(self, role: str) -> bool:
+        return role == ("x" if self._horizontal() else "y")
+
+    def occupy(self, ctx: Any, occ: Any) -> None:
+        nan = float("nan")
+        b = self.get("baseline")
+        t, v = [], []
+        for x, y in zip(self.x, self.y):
+            t += [x, x, nan]
+            v += [b, y, nan]
+        px, py = (v, t) if self._horizontal() else (t, v)
+        occ.lines(ctx.xmap.many(px), ctx.ymap.many(py))
+
+    def legend_points(self) -> tuple[Any, Any]:
+        return (self.y, self.x) if self._horizontal() else (self.x, self.y)
+
+    def _color(self, ctx: Any) -> Any:
+        return with_alpha(self.base_color(ctx), self.get("alpha"))
+
+    def _markers(self, ctx: Any, n: int, glyph: bool = False) -> MarkerStyle:
+        style = MarkerStyle(self, ctx, "marker_", self._color(ctx), n, glyph)
+        return style
+
+    def draw(self, ctx: Any) -> None:
+        c = self._color(ctx)
+        horiz = self._horizontal()
+        base = self.get("baseline")
+        xs, ys = (self.y, self.x) if horiz else (self.x, self.y)
+        px, py = ctx.xmap.many(xs), ctx.ymap.many(ys)
+        canvas = ctx.canvas
+        bc = ctx.color(self.get("baseline_color"))
+        if bc is not None and self.get("baseline_width") and len(self.x):
+            n, lo, hi = _backend.extent(self.x, None)
+            if n:
+                if horiz:
+                    b = ctx.xmap(base)
+                    canvas.draw_lines([b, b], [ctx.ymap(lo), ctx.ymap(hi)], color=bc,
+                                      width=self.get("baseline_width"))
+                else:
+                    b = ctx.ymap(base)
+                    canvas.draw_lines([ctx.xmap(lo), ctx.xmap(hi)], [b, b], color=bc,
+                                      width=self.get("baseline_width"))
+        lw = self.get("line_width")
+        if c is not None and lw:
+            if horiz:
+                b = ctx.xmap(base)
+                canvas.draw_segments(b, py, px, py, color=c, width=lw, simplify=self.simplify_arg())
+            else:
+                b = ctx.ymap(base)
+                canvas.draw_segments(px, b, px, py, color=c, width=lw, simplify=self.simplify_arg())
+        self._markers(ctx, len(self.x)).draw(canvas, px, py, self.simplify_arg())
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        return self._color(ctx), None
+
+    def legend_glyph(self, ctx: Any, x: float, y: float, w: float, h: float) -> None:
+        c = self._color(ctx)
+        canvas = ctx.canvas
+        if c is not None:
+            canvas.draw_lines([x + w / 2, x + w / 2], [y + h, y + h * 0.35], color=c,
+                              width=self.get("line_width"))
+        self._markers(ctx, 1, True).glyph(canvas, x + w / 2, y + h * 0.35, h * 0.7)

plot_io/series/violin.py

@@ -0,0 +1,321 @@
+"""Violin plots: a mirrored density per category, with an inner box or quartiles."""
+
+import array
+import math
+from typing import Any
+
+from .. import _backend, stats
+from ..settings import Setting, boolean, color, either, literal, number, one_of, table
+from ..shapes import fill_polygons
+from ..slots import slots
+from ..style import dash_of, desaturate, with_alpha
+from . import Series, common
+from .catdata import category_values
+from .kde import check_bandwidth
+from ..values import Values, category_paint
+
+__all__ = ["Violin"]
+
+
+def _inner(v: Any) -> Any:
+    if v is False or v == "none":
+        return False
+    return one_of("box", "quartiles", "points")(v)
+
+
+class Violin(Series):
+    """Violins 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="Fill: a color, one per violin (list or dict by category), or "
+                          "numbers per violin mapped through `color_map`; default the next "
+                          "palette color."),
+        **common("color_map"),
+        line_color=Setting(color, doc="Outline and inner color."),
+        line_width=Setting(number(lo=0), doc="Outline width (pt).", length=True),
+        saturation=Setting(number(0, 1), doc="Saturation of the fills."),
+        alpha=Setting(number(0, 1), doc="Fill opacity."),
+        width=Setting(number(positive=True), doc="Width of a category's slot."),
+        bandwidth=Setting(check_bandwidth, doc="`scott`, `silverman` or a number."),
+        adjust=Setting(number(positive=True), doc="Factor applied to the bandwidth."),
+        cut=Setting(number(lo=0), doc="The density extends this many bandwidths past "
+                                           "the data."),
+        grid=Setting(number(lo=16, integer=True), doc="Points per violin outline."),
+        scale=Setting(one_of("area", "count", "width"),
+                      doc="`area`: equal areas; `count`: area proportional to the number of "
+                          "values; `width`: equal widths."),
+        inner=Setting(_inner,
+                      doc="Inside each violin: `box` (a thin box, whiskers and a median dot), "
+                          "`quartiles` (dashed lines), `points`, or `False` (nothing)."),
+        split=Setting(boolean, doc="Two violin series share each slot as facing "
+                                          "halves."),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (categories on x) or `horizontal`."),
+        dodge=Setting(boolean, doc="Violin and box 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."),
+        **common("name", "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:
+        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)} violins")
+        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"
+
+    # -- statistics -------------------------------------------------------------------
+
+    @property
+    def stats(self) -> dict[Any, dict[str, Any]]:
+        """``{category: {"grid", "density", "count", "box": BoxStats, "bandwidth"}}``."""
+        return self.cached("stats", self._compute)
+
+    def _compute(self) -> dict[Any, dict[str, Any]]:
+        out = {}
+        n = self.get("grid")
+        for k, d in zip(self.cats, self.data):
+            bs = _backend.box_stats(d, 1.5)
+            if not bs.count:
+                out[k] = {"grid": array.array("d"), "density": array.array("d"), "count": 0,
+                          "box": bs, "bandwidth": 0.0}
+                continue
+            bw = stats.bandwidth(d, self.get("bandwidth")) * self.get("adjust")
+            cnt, lo, hi = _backend.extent(d, None)
+            cut = self.get("cut")
+            g0, g1 = lo - cut * bw, hi + cut * bw
+            if g1 <= g0:
+                g0, g1 = g0 - 0.5, g1 + 0.5
+            dens = stats.kde(d, g0, g1, n, bw)
+            grid = array.array("d", (g0 + (g1 - g0) * i / (n - 1) for i in range(n)))
+            out[k] = {"grid": grid, "density": dens, "count": cnt, "box": bs, "bandwidth": bw}
+        return out
+
+    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 st in self.stats.values():
+            g = st["grid"]
+            if len(g):
+                out.extend((g[0], g[-1]))
+        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 occupy(self, ctx: Any, occ: Any) -> None:
+        lo, hi, c0, c1 = [], [], [], []
+        stats = self.stats
+        for (center, width), k in zip(slots(self, ctx), self.cats):
+            st = stats.get(k)
+            if st is None or not len(st["grid"]):
+                continue
+            lo.append(st["grid"][0])
+            hi.append(st["grid"][-1])
+            c0.append(center - width / 2)
+            c1.append(center + width / 2)
+        if self._horizontal():
+            occ.rects(ctx.xmap.many(lo), ctx.ymap.many(c0), ctx.xmap.many(hi), ctx.ymap.many(c1))
+        else:
+            occ.rects(ctx.xmap.many(c0), ctx.ymap.many(lo), ctx.xmap.many(c1), ctx.ymap.many(hi))
+
+    def legend_points(self) -> tuple[Any, Any] | None:
+        xs, ys = array.array("d"), array.array("d")
+        pos = self.positions or [float(i) for i in range(len(self.cats))]
+        for p, (k, st) in zip(pos, self.stats.items()):
+            b = st["box"]
+            if b.count:
+                for v in (b.low, b.q1, b.median, b.q3, b.high):
+                    xs.append(p)
+                    ys.append(v)
+        return (ys, xs) if self._horizontal() else (xs, ys)
+
+    # -- drawing ----------------------------------------------------------------------
+
+    def _per_violin(self, v: Any) -> list[float]:
+        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)} violins")
+        return list(v)
+
+    def color_sources(self) -> list[tuple[Any, Any]]:
+        import array
+        c = self.get("color")
+        if isinstance(c, Values):
+            return [(self.color_map_obj(), array.array("d", self._per_violin(c.data)))]
+        return []
+
+    def fills(self, ctx: Any) -> list[Any]:
+        c = self.get("color")
+        n = len(self.cats)
+        if isinstance(c, Values):
+            cm = self.color_map_obj()
+            flo, fhi = ctx.maps[id(cm)][:2]
+            from ..scales import get_scale
+            f = get_scale(cm.scale).f
+            span = (fhi - flo) or 1.0
+            cols = [cm((f(v) - flo) / span) for v in self._per_violin(c.data)]
+        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} violins")
+            cols = [ctx.color(x) for x in c]
+        else:
+            cols = [self.base_color(ctx)] * n
+        sat = self.get("saturation")
+        a = self.get("alpha")
+        return [with_alpha(desaturate(x, sat) if sat != 1.0 else x, a) if x is not None else None
+                for x in cols]
+
+    def _half_widths(self) -> dict[Any, float]:
+        """Scale factor per category: half-width in category units per unit of density."""
+        st = self.stats
+        mode = self.get("scale")
+        peaks = {k: (max(s["density"]) if len(s["density"]) else 0.0) for k, s in st.items()}
+        if mode == "width":
+            return {k: (1.0 / p if p else 0.0) for k, p in peaks.items()}
+        if mode == "count":
+            top = max((peaks[k] * s["count"] for k, s in st.items()), default=0.0)
+            return {k: (s["count"] / top if top else 0.0) for k, s in st.items()}
+        top = max(peaks.values(), default=0.0)
+        return {k: (1.0 / top if top else 0.0) for k in st}
+
+    def _side(self) -> int:
+        """0: both halves; -1: the left (lower) half; 1: the right half (split)."""
+        if not self.get("split"):
+            return 0
+        peers = [s for s in self.plot.series if isinstance(s, Violin) and s.get("split")
+                 and s._horizontal() == self._horizontal()]
+        return -1 if peers.index(self) % 2 == 0 else 1
+
+    def draw(self, ctx: Any) -> None:
+        horiz = self._horizontal()
+        cmap, vmap = (ctx.ymap, ctx.xmap) if horiz else (ctx.xmap, ctx.ymap)
+        st = self.stats
+        scale = self._half_widths()
+        side = self._side()
+        fills = self.fills(ctx)
+        lc = ctx.color(self.get("line_color"))
+        lw = self.get("line_width")
+        polys, polyfill = [], []
+        inner = self.get("inner")
+        canvas = ctx.canvas
+        geo = list(zip(slots(self, ctx), self.cats, fills))
+        for (center, width), k, fill in geo:
+            s = st[k]
+            if not s["count"]:
+                continue
+            half = width / 2
+            hw = [d * scale[k] * half for d in s["density"]]
+            pv = vmap.many(s["grid"])
+            right = [cmap(center + w) for w in hw] if side >= 0 else [cmap(center)] * len(hw)
+            left = [cmap(center - w) for w in hw] if side <= 0 else [cmap(center)] * len(hw)
+            ra = array.array("d", right)
+            ra.extend(reversed(left))
+            rv = array.array("d", pv)
+            rv.extend(reversed(pv))
+            polys.append([(rv, ra)] if horiz else [(ra, rv)])
+            polyfill.append(fill)
+        fill_polygons(canvas, polys, fill=polyfill, stroke=lc if lw else None,
+                      line_width=lw or None)
+        if not inner or lc is None:
+            return
+        for (center, width), k, fill in geo:
+            s = st[k]
+            if not s["count"]:
+                continue
+            b = s["box"]
+            off = 0.0 if not side else side * width * 0.06
+            c = center + off
+            if inner == "box":
+                bw = width * 0.06
+                a0, a1 = cmap(c - bw / 2), cmap(c + bw / 2)
+                q1, q3 = vmap(b.q1), vmap(b.q3)
+                ac = cmap(c)
+                lo, hi = vmap(b.low), vmap(b.high)
+                if horiz:
+                    canvas.draw_lines([lo, hi], [ac, ac], color=lc, width=max(lw, 0.5))
+                    canvas.begin_path()
+                    canvas.rect(min(q1, q3), min(a0, a1), abs(q3 - q1), abs(a1 - a0))
+                else:
+                    canvas.draw_lines([ac, ac], [lo, hi], color=lc, width=max(lw, 0.5))
+                    canvas.begin_path()
+                    canvas.rect(min(a0, a1), min(q1, q3), abs(a1 - a0), abs(q3 - q1))
+                canvas.fill(lc)
+                m = vmap(b.median)
+                mx, my = (m, ac) if horiz else (ac, m)
+                canvas.draw_markers([mx], [my], size=max(abs(a1 - a0) * 0.9, 2.0),
+                                    fill="white", stroke=None)
+            elif inner == "quartiles":
+                for v, dash in ((b.q1, "dashed"), (b.median, "dashed"), (b.q3, "dashed")):
+                    d = _density_at(s, v) * scale[k] * width / 2
+                    lo_a = c - d if side <= 0 else c
+                    hi_a = c + d if side >= 0 else c
+                    pv = vmap(v)
+                    xs, ys = ([pv, pv], [cmap(lo_a), cmap(hi_a)]) if horiz else \
+                        ([cmap(lo_a), cmap(hi_a)], [pv, pv])
+                    canvas.draw_lines(xs, ys, color=lc, width=lw or 0.8,
+                                      dash=dash_of("dashed" if v != b.median else "solid",
+                                                   lw or 0.8))
+            elif inner == "points":
+                d = self.data[self.cats.index(k)]
+                pv = vmap.many(d)
+                pc = cmap(c)
+                xs, ys = (pv, [pc] * len(pv)) if horiz else ([pc] * len(pv), pv)
+                canvas.draw_markers(xs, ys, size=2.0, fill=lc, stroke=None)
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        f = self.fills(ctx)
+        return (f[0] if f else None), ctx.color(self.get("line_color"))
+
+    def legend_glyph(self, ctx: Any, x: float, y: float, w: float, h: float) -> None:
+        fill, stroke = self.legend_colors(ctx)
+        canvas = ctx.canvas
+        bw = min(w, 1.6 * h)
+        canvas.begin_path()
+        canvas.rect(x + (w - bw) / 2, y, bw, h)
+        if fill is not None:
+            canvas.fill(fill)
+        if stroke is not None and self.get("line_width"):
+            canvas.line_width = self.get("line_width")
+            canvas.stroke(stroke)
+
+
+def _density_at(s: dict[str, Any], v: float) -> float:
+    g, d = s["grid"], s["density"]
+    n = len(g)
+    if not n or not (g[0] <= v <= g[-1]):
+        return 0.0
+    t = (v - g[0]) / (g[-1] - g[0]) * (n - 1) if g[-1] > g[0] else 0.0
+    i = min(int(t), n - 2)
+    f = t - i
+    return d[i] * (1 - f) + d[i + 1] * f
+
+
+del math