plot-io 0.1.0__py3-none-any.whl

plot_io/series/line.py

@@ -0,0 +1,173 @@
+"""Line: a polyline through points (or several sharing x)."""
+
+import array
+from typing import Any
+
+from pdf_io import arrays as pdf_arrays
+
+from .. import _backend
+from ..settings import Setting, color, number, one_of, table
+from ..style import dash_of
+from . import Series, common
+from .errors import error_value
+from .curves import curve_settings, line_args
+from .points import MarkerStyle, marker_settings
+
+__all__ = ["Line"]
+
+
+def _dash_value(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)
+
+
+def _rows(y: Any) -> list[array.array]:
+    rows = pdf_arrays.rows(y)
+    if rows is not None:
+        return rows
+    if isinstance(y, (list, tuple)) and y and all(
+            hasattr(r, "__len__") and not isinstance(r, str) for r in y):
+        return [_backend.doubles(r) for r in y]
+    return [_backend.doubles(y)]
+
+
+class Line(Series):
+    """A line through ``(x, y)``; ``y`` may be 2-D (one line per row, sharing ``x``), and
+    ``x`` may be omitted (``0, 1, 2, …``)."""
+
+    SETTINGS = table(
+        color=Setting(color, doc="Line color; default: the next palette color."),
+        line_width=Setting(number(lo=0), inherited=True, doc="Line width (pt).", length=True),
+        line_style=Setting(_dash_value,
+                           doc="`solid`, `dashed`, `dotted`, `dashdot` or a dash list (pt); "
+                               "named styles scale with the width."),
+        **curve_settings(),
+        cap=Setting(one_of("butt", "round", "square"), doc="Line cap."),
+        join=Setting(one_of("miter", "round", "bevel"), doc="Line join."),
+        **{k: v for k, v in marker_settings("marker_").items()},
+        x_error=Setting(error_value, doc="Horizontal error bars at the points."),
+        y_error=Setting(error_value, doc="Vertical error bars at the points."),
+        show_markers=Setting(lambda v: bool(v),
+                             doc="Draw markers at the points (also turned on by setting "
+                                 "`marker`)."),
+        **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
+            rows = _rows(y)
+            x = array.array("d", range(len(rows[0])))
+        else:
+            rows = _rows(y)
+        self.x = _backend.doubles(x)
+        for r in rows:
+            if len(r) != len(self.x):
+                raise ValueError(f"x has {len(self.x)} values and y {len(r)}")
+        self.ys = rows
+        self._markers_on = "marker" in settings
+        super().__init__(plot=plot, **settings)
+
+    @property
+    def y(self) -> array.array:
+        return self.ys[0]
+
+    def set(self, **settings: Any) -> "Line":
+        if "marker" in settings:
+            self._markers_on = settings["marker"] is not None
+        super().set(**settings)
+        return self
+
+    def _markers(self) -> bool:
+        return self._markers_on or bool(self.get("show_markers"))
+
+    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:
+        if role == "x":
+            v = self.x
+        elif len(self.ys) == 1:
+            v = self.ys[0]
+        else:
+            v = array.array("d")
+            for r in self.ys:
+                v.extend(r)
+        e = self._error(role)
+        if e is None:
+            return v
+        center = self.x if role == "x" else self.ys[0]
+        lo, hi = e.ends(center)
+        out = array.array("d", v)
+        out.extend(lo)
+        out.extend(hi)
+        return out
+
+    def occupy(self, ctx: Any, occ: Any) -> None:
+        from ..occupancy import MAX_VERTICES, thin
+        for r in self.ys:
+            x, y = thin(self.x, r, limit=MAX_VERTICES)
+            occ.lines(ctx.xmap.many(x), ctx.ymap.many(y))
+
+    def legend_points(self) -> tuple[Any, Any]:
+        if len(self.ys) == 1:
+            return self.x, self.ys[0]
+        xs, ys = array.array("d"), array.array("d")
+        for r in self.ys:
+            xs.extend(self.x)
+            ys.extend(r)
+        return xs, ys
+
+    def _line_args(self, ctx: Any) -> tuple[Any, float, Any, float]:
+        c = self.base_color(ctx)
+        w = self.get("line_width")
+        alpha = self.get("alpha")
+        return c, w, dash_of(self.get("line_style"), w), 1.0 if alpha is None else alpha
+
+    def draw(self, ctx: Any) -> None:
+        c, w, dash, opacity = self._line_args(ctx)
+        simplify = self.simplify_arg()
+        canvas = ctx.canvas
+        for role in ("x", "y"):
+            e = self._error(role)
+            if e is not None:
+                e.draw(ctx, self.x, self.ys[0], role == "x", c, 0.8, simplify, opacity)
+        px = ctx.xmap.many(self.x)
+        xs_page = [px] * len(self.ys)
+        ys_page = [ctx.ymap.many(r) for r in self.ys]
+        args = line_args(self)
+        if c is not None and w:
+            canvas.line_cap = self.get("cap")
+            canvas.line_join = self.get("join")
+            canvas.draw_lines(xs_page if len(xs_page) > 1 else xs_page[0],
+                              ys_page if len(ys_page) > 1 else ys_page[0],
+                              color=c, width=w, dash=dash, opacity=opacity,
+                              simplify=self.simplify_arg(lines=True),
+                              **args)
+        if self._markers():
+            style = MarkerStyle(self, ctx, "marker_", c, len(self.x))
+            for r in self.ys:
+                style.draw(canvas, ctx.xmap.many(self.x), ctx.ymap.many(r), simplify)
+
+    def zero_default(self, role: str) -> bool:
+        return role == "y"
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        c = self.base_color(ctx)
+        return c, c
+
+    def legend_glyph(self, ctx: Any, x: float, y: float, w: float, h: float) -> None:
+        c, lw, dash, opacity = self._line_args(ctx)
+        canvas = ctx.canvas
+        cy = y + h / 2
+        if c is not None and lw:
+            canvas.draw_lines([x, x + w], [cy, cy], color=c, width=lw, dash=dash,
+                              opacity=opacity)
+        if self._markers():
+            MarkerStyle(self, ctx, "marker_", c, len(self.x), glyph=True).glyph(
+                canvas, x + w / 2, cy, h * 1.1)

plot_io/series/pie.py

@@ -0,0 +1,304 @@
+"""Pie and donut charts, on a plot without axes."""
+
+import array
+import math
+from typing import Any
+
+import pdf_io
+
+from .. import _backend
+from ..labels import ink_for
+from ..numbers import NumberStyle, check_format, format_numbers, number_settings
+from ..settings import Setting, boolean, color, either, literal, number, one_of, table
+from ..style import with_alpha
+from ..text import Font, draw_text, measure
+from . import Series, common
+
+__all__ = ["Pie"]
+
+
+def _colors(v: Any) -> list[Any]:
+    return [color(c) for c in v]
+
+
+def _explode(v: Any) -> Any:
+    if isinstance(v, (int, float)) and not isinstance(v, bool):
+        return number(lo=0)(v)
+    return [number(lo=0)(x) for x in v]
+
+
+def _arc(path: Any, cx: float, cy: float, r: float, a0: float, a1: float) -> None:
+    """Append an arc of radius ``r`` from angle ``a0`` to ``a1`` (radians, counterclockwise
+    on the page: y up) as cubic Béziers of at most 90°."""
+    n = max(1, math.ceil(abs(a1 - a0) / (math.pi / 2) - 1e-9))
+    step = (a1 - a0) / n
+    k = 4.0 / 3.0 * math.tan(step / 4.0)
+    for i in range(n):
+        t0, t1 = a0 + i * step, a0 + (i + 1) * step
+        x0, y0 = cx + r * math.cos(t0), cy - r * math.sin(t0)
+        x3, y3 = cx + r * math.cos(t1), cy - r * math.sin(t1)
+        x1, y1 = x0 - k * r * math.sin(t0), y0 - k * r * math.cos(t0)
+        x2, y2 = x3 + k * r * math.sin(t1), y3 + k * r * math.cos(t1)
+        path.curve_to(x1, y1, x2, y2, x3, y3)
+
+
+class Pie(Series):
+    """A pie (or donut, with ``hole``) of ``values``: a sequence, or a dict
+    ``{label: value}``; the plot is drawn without axes."""
+
+    SETTINGS = table(
+        labels=Setting(lambda v: [str(x) for x in v],
+                       doc="Wedge names (default: the dict's keys)."),
+        colors=Setting(_colors, doc="One color per wedge; default palette colors."),
+        start=Setting(number(), doc="Angle where the first wedge starts (degrees, 0: "
+                                          "3 o'clock, 90: 12 o'clock)."),
+        counterclockwise=Setting(boolean, doc="Direction of the wedges."),
+        hole=Setting(number(0, 0.95), doc="Radius of the hole (fraction of the "
+                                               "radius): a donut."),
+        explode=Setting(_explode, doc="Offset of the wedges from the centre (fraction of the "
+                                      "radius): one value or one per wedge."),
+        sort=Setting(boolean, doc="Sort the wedges by decreasing value."),
+        label_position=Setting(one_of("outside", "inside", "none"),
+                               doc="Where the names go: `outside`, `inside` or `none` (in "
+                                   "the legend instead)."),
+        value_labels=Setting(either(literal(False), one_of("percent", "value")),
+                             doc="Write each wedge's `percent` or `value` inside it (outside, "
+                                 "with a leader line, when it does not fit)."),
+        label_format=Setting(check_format,
+                             doc="Number format of the value labels (percentages: of 100)."),
+        line_color=Setting(color, doc="Wedge outline color; `none`: no outline."),
+        line_width=Setting(number(lo=0), doc="Wedge outline width (pt).", length=True),
+        alpha=Setting(number(0, 1), doc="Opacity."),
+        **common("name", "z", "rasterize", "simplify", "font_size", "font_family", "text_color"),
+        **number_settings(),
+    )
+    AXES = False
+
+    def __init__(self, values: Any, plot: Any = None, **settings: Any) -> None:
+        if isinstance(values, dict):
+            self.keys: list[Any] = [str(k) for k in values]
+            vals = _backend.doubles(list(values.values()))
+        else:
+            vals = _backend.doubles(values)
+            self.keys = []
+        if any(not (v >= 0) for v in vals if math.isfinite(v)):
+            raise ValueError("pie values must be non-negative")
+        self.vals = vals
+        super().__init__(plot=plot, **settings)
+        if not self.plot.is_set("axes"):
+            self.plot.set(axes=False)
+        if not self.plot.legend.is_set("position"):
+            self.plot.legend.set(position="outside right")
+
+    # -- geometry ---------------------------------------------------------------------
+
+    def names(self) -> list[Any]:
+        given = self.get("labels")
+        if given is not None:
+            if len(given) != len(self.vals):
+                raise ValueError(f"{len(given)} labels for {len(self.vals)} wedges")
+            return given
+        return list(self.keys)
+
+    def order(self) -> list[int]:
+        idx = [i for i in range(len(self.vals)) if math.isfinite(self.vals[i]) and self.vals[i] > 0]
+        if self.get("sort"):
+            idx.sort(key=lambda i: -self.vals[i])
+        return idx
+
+    @property
+    def stats(self) -> list[dict[str, Any]]:
+        """Per wedge (in drawing order): ``index``, ``value``, ``fraction``, ``start`` and
+        ``end`` angles (degrees, counterclockwise from 3 o'clock)."""
+        order = self.order()
+        total = math.fsum(self.vals[i] for i in order)
+        sign = 1.0 if self.get("counterclockwise") else -1.0
+        a = self.get("start")
+        out = []
+        for i in order:
+            frac = self.vals[i] / total if total else 0.0
+            b = a + sign * 360.0 * frac
+            out.append({"index": i, "value": self.vals[i], "fraction": frac, "start": a, "end": b})
+            a = b
+        return out
+
+    def _explode_of(self, i: int) -> float:
+        e = self.get("explode")
+        if e is None:
+            return 0.0
+        if isinstance(e, list):
+            if len(e) != len(self.vals):
+                raise ValueError(f"{len(e)} explode values for {len(self.vals)} wedges")
+            return e[i]
+        return e
+
+    def _reach(self) -> float:
+        e = self.get("explode")
+        ex = max(e) if isinstance(e, list) and e else (e or 0.0)
+        out = self.get("label_position") == "outside" or self.get("value_labels")
+        return 1.0 + ex + (0.45 if out else 0.05)
+
+    def values(self, role: str) -> Any:
+        r = self._reach()
+        return array.array("d", [-r, r])
+
+    def zero_padding(self, role: str) -> bool:
+        return True
+
+    def palette_count(self) -> int:
+        return len(self.vals)
+
+    def has_own_color(self) -> bool:
+        return self.is_set("colors")
+
+    def legend_labels(self) -> list[Any]:
+        if self.get("label_position") == "none":
+            names = self.names()
+            return [names[w["index"]] for w in self.stats] if names else []
+        return []
+
+    def wedge_colors(self, ctx: Any) -> list[Any]:
+        """Colors in value order (one per value)."""
+        given = self.get("colors")
+        n = len(self.vals)
+        if given is not None:
+            if len(given) < n:
+                raise ValueError(f"{len(given)} colors for {n} wedges")
+            cols = [ctx.color(c) for c in given[:n]]
+        else:
+            cols = self.auto_colors(ctx)
+            cols = (cols * (n // max(len(cols), 1) + 1))[:n]
+        a = self.get("alpha")
+        return [with_alpha(c, a) for c in cols]
+
+    # -- drawing ----------------------------------------------------------------------
+
+    def _center(self, ctx: Any) -> tuple[float, float, float]:
+        cx, cy = ctx.xmap(0.0), ctx.ymap(0.0)
+        r = abs(ctx.xmap(1.0) - cx)
+        return cx, cy, r
+
+    def draw(self, ctx: Any) -> None:
+        cx, cy, r = self._center(ctx)
+        hole = self.get("hole")
+        cols = self.wedge_colors(ctx)
+        paths, fills = [], []
+        for w in self.stats:
+            i = w["index"]
+            a0, a1 = math.radians(w["start"]), math.radians(w["end"])
+            mid = (a0 + a1) / 2
+            ex = self._explode_of(i) * r
+            ox, oy = cx + ex * math.cos(mid), cy - ex * math.sin(mid)
+            p = pdf_io.Path()
+            if w["fraction"] >= 1.0 - 1e-12:
+                p.move_to(ox + r, oy)
+                _arc(p, ox, oy, r, 0.0, 2 * math.pi)
+                p.close()
+                if hole:
+                    p.move_to(ox + hole * r, oy)
+                    _arc(p, ox, oy, hole * r, 2 * math.pi, 0.0)
+                    p.close()
+            else:
+                p.move_to(ox + r * math.cos(a0), oy - r * math.sin(a0))
+                _arc(p, ox, oy, r, a0, a1)
+                if hole:
+                    p.line_to(ox + hole * r * math.cos(a1), oy - hole * r * math.sin(a1))
+                    _arc(p, ox, oy, hole * r, a1, a0)
+                else:
+                    p.line_to(ox, oy)
+                p.close()
+            paths.append(p)
+            fills.append(cols[i])
+        lc = ctx.color(self.get("line_color"))
+        lw = self.get("line_width")
+        if paths:
+            ctx.canvas.fill_polygons(paths, fill=fills, stroke=lc if lw else None,
+                                     line_width=lw or None, simplify=self.simplify_arg())
+
+    def draw_overlay(self, ctx: Any) -> None:
+        cx, cy, r = self._center(ctx)
+        hole = self.get("hole")
+        canvas = ctx.canvas
+        names = self.names()
+        pos = self.get("label_position")
+        vl = self.get("value_labels")
+        stats = self.stats
+        font = Font(self.get("font_size"), self.get("font_family"),
+                    color=ctx.color(self.get("text_color")))
+        cols = self.wedge_colors(ctx)
+        texts: list[Any] = [None] * len(stats)
+        placed: list[list[Any]] = []
+        if vl:
+            vals = [100.0 * w["fraction"] if vl == "percent" else w["value"] for w in stats]
+            style = NumberStyle.of(self)
+            fmt = self.get("label_format")
+            if vl == "percent" and fmt == "auto":
+                style.suffix = style.suffix or "%"
+                if style.precision is None:
+                    style.precision = 2
+            texts = format_numbers(vals, fmt, style)
+        for k, w in enumerate(stats):
+            i = w["index"]
+            a0, a1 = math.radians(w["start"]), math.radians(w["end"])
+            mid = (a0 + a1) / 2
+            ex = self._explode_of(i) * r
+            ox, oy = cx + ex * math.cos(mid), cy - ex * math.sin(mid)
+            ux, uy = math.cos(mid), -math.sin(mid)
+            side = "left" if ux >= 0 else "right"
+            outside_texts = []
+            if names and pos == "outside":
+                outside_texts.append(names[i])
+            if names and pos == "inside":
+                draw_text(canvas, names[i], ox + ux * r * (0.5 + hole / 2),
+                          oy + uy * r * (0.5 + hole / 2),
+                          Font(font.size, font.family, color=ink_for(cols[i])), "center",
+                          "bottom" if vl else "center")
+            if texts[k] is not None:
+                rin = r * (0.5 + hole / 2) if hole else r * 0.62
+                tw, ta, td = measure(canvas, texts[k], font)
+                arc_len = abs(a1 - a0) * rin
+                fits = arc_len >= 1.2 * max(tw, ta + td) and (1 - hole) * r >= 1.1 * (ta + td)
+                if fits:
+                    draw_text(canvas, texts[k], ox + ux * rin, oy + uy * rin,
+                              Font(font.size, font.family, color=ink_for(cols[i])), "center",
+                              "top" if names and pos == "inside" else "center")
+                else:
+                    outside_texts.append(texts[k])
+            if outside_texts:
+                text = "  ".join(str(t) for t in outside_texts) if all(
+                    isinstance(t, str) for t in outside_texts) else outside_texts[0]
+                lead = not (names and pos == "outside") or len(outside_texts) > 1
+                placed.append([oy + uy * r * 1.12, ox + ux * r * 1.12, side, text, lead,
+                               (ox + ux * r, oy + uy * r)])
+        self._outside_labels(canvas, placed, font)
+
+    @staticmethod
+    def _outside_labels(canvas: Any, placed: list[list[Any]], font: Font) -> None:
+        """Draw the outside labels, pushed apart vertically on each side so that they do
+        not overlap; moved labels get a leader line."""
+        gap = 1.25 * font.size
+        for side in ("left", "right"):
+            items = sorted((p for p in placed if p[2] == side), key=lambda p: p[0])
+            want = [p[0] for p in items]
+            for k in range(1, len(items)):
+                items[k][0] = max(items[k][0], items[k - 1][0] + gap)
+            for p, w in zip(items, want):
+                ty, tx, _, text, lead, (ex, ey) = p
+                if lead or abs(ty - w) > 0.5:
+                    canvas.draw_lines([ex, tx - (2 if side == "left" else -2)], [ey, ty],
+                                      color=font.color, width=0.5)
+                draw_text(canvas, text, tx, ty, font, side, "center")
+
+    def legend_colors_at(self, ctx: Any, i: int) -> tuple[Any, Any]:
+        cols = self.wedge_colors(ctx)
+        st = self.stats
+        return (cols[st[i]["index"]] if i < len(st) else None), None
+
+    def legend_glyph_at(self, ctx: Any, i: int, x: float, y: float, w: float, h: float) -> None:
+        fill, _ = self.legend_colors_at(ctx, i)
+        if fill is not None:
+            ctx.canvas.fill_style = fill
+            ctx.canvas.fill_rect(x + (w - h) / 2, y, h, h)
+
+    def legend_glyph(self, ctx: Any, x: float, y: float, w: float, h: float) -> None:
+        self.legend_glyph_at(ctx, 0, x, y, w, h)