plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/presets/errors.py

@@ -0,0 +1,296 @@
+"""Error bars: ``Errors`` values, and their layers (segments and caps) on the series
+that take ``x_error``/``y_error`` (scatter, line, errorbar) or ``error`` (bar); the types
+that summarize replicates (``estimate``, ``interval``: :class:`Summarized`)."""
+
+import array
+import math
+from typing import Any
+
+from vec_io.arrays import doubles
+
+from ..color.values import color
+from ..layers.base import Series
+from ..layers.core import Layer, Table
+from ..layers.geoms import GEOMS
+from ..layers.paint import Paint, color_of, role
+from ..units import SettingError, resolve_raw
+from ..validators import length, typed
+
+__all__ = ["Errors", "error_value", "error_layers", "Summarized", "errors_of"]
+
+
+_CAP = length(lo=0, data=True)
+_WIDTH = length(lo=0)
+
+
+class Errors:
+    """Error bars: ``values`` is a value or sequence (symmetric) or a pair
+    ``(low, high)``; ``color`` defaults to the series color, ``line_width`` to the
+    series', ``cap_length`` is the cap width (a length, `data` units across the error; 0:
+    no caps; default: the series' ``cap_length``, else 4 px)."""
+
+    def __init__(self, values: Any, color: Any = None, line_width: Any = None,
+                 cap_length: Any = None) -> None:
+        self.values = values
+        self.color = None if color is None else _color(color)
+        self.line_width = None if line_width is None else _WIDTH(line_width)
+        self.cap = None if cap_length is None else _CAP(cap_length)
+        self._low: Any = None
+        self._high: Any = None
+        self._owner: Any = None
+        self._name = ""
+
+    def __repr__(self) -> str:
+        return "Errors()"
+
+    def bind(self, n: int, owner: Any = None, name: str = "") -> None:
+        """Convert the values for ``n`` points (of setting ``name`` of ``owner``)."""
+        v = self.values
+        try:
+            if _is_pair(v):
+                low, high = _column(v[0], n), _column(v[1], n)
+            else:
+                low = high = _column(v, n)
+        except ValueError as e:
+            if owner is None:
+                raise
+            raise SettingError(f"{owner.kind} setting {name!r}: {e}", owner, name) from None
+        self._low, self._high = low, high
+        self._owner, self._name = owner, name
+
+    def ends(self, center: Any) -> tuple[array.array, array.array]:
+        """The low and high ends at ``center``; their span must be a finite number."""
+        lo = array.array("d", (c - e for c, e in zip(center, self._low)))
+        hi = array.array("d", (c + e for c, e in zip(center, self._high)))
+        ends = [v for v in (*lo, *hi) if math.isfinite(v)]
+        if ends and not math.isfinite(max(ends) - min(ends)):
+            owner, name = self._owner, self._name
+            msg = "errors reach beyond the number range"
+            if owner is None:
+                raise ValueError(msg)
+            raise SettingError(f"{owner.kind} setting {name!r}: {msg}", owner, name)
+        return lo, hi
+
+    def cap_px(self, ctx: Any, owner: Any, horizontal: bool) -> float:
+        """Cap width (px): this object's, else the series' ``cap_length``, else 4 px."""
+        state, mapper = (ctx.y, ctx.ymap) if horizontal else (ctx.x, ctx.xmap)
+        raw = self.cap
+        if raw is None:
+            if "cap_length" in owner.SETTINGS:
+                return owner.resolve("cap_length", scale=_scale(state, mapper),
+                                     time=_is_time(state))
+            raw = 4.0
+        return resolve_raw(owner, "cap_length", _CAP, raw, scale=_scale(state, mapper),
+                           time=_is_time(state))
+
+
+@role("error_source")
+def _error_source(s: Any, ctx: Any, glyph: bool, color: Any = "base", width: str = "scaling",
+                  simplify: bool = True, opacity: Any = "series",
+                  marker: Any = None) -> tuple[Any, float, Any, Any]:
+    """``(color, width, simplify, opacity)`` of a series' error bars: ``color`` a source
+    (``"marker"``: its legend markers' first color), ``width`` a setting (``"scaling"``: the
+    series' line width scaling), ``opacity`` ``"series"`` (1 when unset), ``"marker"`` (its
+    markers') or a number."""
+    if color == "marker":
+        g = marker.resolve(ctx, True)
+        c = g.first_color("fill") or g.first_color("stroke")
+    else:
+        c = color_of(s, ctx, color)
+    w = s._scaling() if width == "scaling" else s.resolve(width)
+    if opacity == "marker":
+        opacity = marker.resolve(ctx, False).opacity
+    elif opacity == "series":
+        o = s.resolve("opacity")
+        opacity = 1.0 if o is None else o
+    return c, w, s.resolve("simplify") if simplify else None, opacity
+
+
+@role("error_bars")
+def _error_bars(owner: Any, ctx: Any, glyph: bool, errors: Any = None, source: Any = None,
+                caps: Any = None) -> dict[str, Any]:
+    """The segments of error bars (``caps``: the axis their caps run across, else the
+    bars); the ``Errors``' own color and width before the series' (``source``)."""
+    base, width, simplify, opacity = source.resolve(ctx, False)
+    e = errors
+    c = ctx.color(e.color) if e.color is not None else base
+    w = (resolve_raw(owner, "line_width", _WIDTH, e.line_width)
+         if e.line_width is not None else width)
+    if c is None or not w:
+        return {"color": None}
+    p = {"color": c, "width": w, "opacity": opacity, "simplify": simplify}
+    if caps is not None:
+        cap = e.cap_px(ctx, owner, caps == "y")
+        if not cap:
+            return {"color": None}
+        p["tick"] = cap
+    return p
+
+
+def error_layers(owner: Any, e: Errors, xs: Any, ys: Any, horizontal: bool, source: Any,
+                 flip: bool = False) -> list[Layer]:
+    """The layers of error bars at data points ``(xs, ys)`` of a frame: a segment per point
+    along x (``horizontal``) or y between the error ends, and caps at both ends (ticks
+    across).  ``xs`` may be a function of the drawing context (slot centres).  ``source``:
+    a :class:`~plot_io.layers.paint.Paint` of the series' ``(color, width, simplify,
+    opacity)`` (role ``error_source``).  ``flip``: the frame's x is the plot's y."""
+    center = xs if horizontal else ys
+    across_v = ys if horizontal else xs
+    lo, hi = e.ends(center)
+    if horizontal:
+        t = Table(x0=lo, x1=hi)
+        ends = [Table(x0=lo), Table(x0=hi)]
+    else:
+        t = Table(y0=lo, y1=hi)
+        ends = [Table(y0=lo), Table(y0=hi)]
+    a0, a1 = ("y0", "y1") if horizontal else ("x0", "x1")
+    for table in [t] + ends:
+        for name in (a0, a1) if table is t else (a0,):
+            if callable(across_v):
+                table.lazy[name] = across_v
+            else:
+                table[name] = across_v
+    # caps run across the errors: along the frame's y for horizontal errors
+    across = ("y" if not flip else "x") if horizontal else ("x" if not flip else "y")
+    geom = GEOMS["segments"]
+    out = [Layer(geom, t, paint=Paint(owner, "error_bars", errors=e, source=source),
+                 flip=flip, key=False, occupy=False)]
+    caps = Paint(owner, "error_bars", errors=e, source=source, caps=across)
+    for table in ends:
+        out.append(Layer(geom, table, paint=caps, flip=flip, key=False, occupy=False,
+                         tick="v" if horizontal else "u"))
+    return out
+
+
+def _scale(state: Any, mapper: Any) -> float | None:
+    """px per data unit of a linear, time or category axis (else ``None``)."""
+    if state.scale is not None and state.scale.name not in ("linear", "time"):
+        return None
+    return abs(mapper.a) or None
+
+
+def _is_time(state: Any) -> bool:
+    return state.scale is not None and state.scale.name == "time"
+
+
+def _is_pair(v: Any) -> bool:
+    return isinstance(v, (tuple, list)) and len(v) == 2 and not _is_number(v[0]) \
+        and hasattr(v[0], "__len__")
+
+
+def _is_number(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _color(v: Any) -> Any:
+    return color(v)
+
+
+def _column(v: Any, n: int) -> array.array:
+    if _is_number(v):
+        return array.array("d", [float(v)] * n)
+    col = doubles(v)
+    if len(col) != n:
+        raise ValueError(f"{len(col)} error values for {n} points")
+    return col
+
+
+@typed("SupportsFloat | Column | Errors")
+def error_value(v: Any) -> Errors:
+    if isinstance(v, Errors):
+        return v
+    if _is_number(v):
+        if not (v >= 0 and math.isfinite(v)):
+            raise ValueError(f"expected a non-negative error, got {v!r}")
+        return Errors(v)
+    try:
+        for col in (v if _is_pair(v) else (v,)):
+            if isinstance(col, (str, bytes, bool)):
+                raise ValueError
+            doubles(col)
+    except (TypeError, ValueError):
+        raise ValueError(f"expected an error: a number, a sequence or a pair of sequences, "
+                         f"got {v!r}") from None
+    return Errors(v)
+
+
+class Summarized(Series):
+    """A type taking ``estimate`` (and ``interval``: bar, line, errorbar, scatter; stem
+    takes ``estimate`` only): with an
+    ``estimate``, :attr:`cols` holds the estimate per position and set (the ``summary``
+    stat of the call's rows), and the interval takes the place of the setting ``ERROR``."""
+
+    #: the error setting the interval replaces
+    ERROR = "y_error"
+
+    @property
+    def cols(self) -> Any:
+        st = self.summary()
+        return self.__dict__["_rows"] if st is None else st["columns"]
+
+    @cols.setter
+    def cols(self, v: Any) -> None:
+        self.__dict__["_rows"] = v
+
+    @property
+    def stats(self) -> dict[str, Any] | None:
+        """With an ``estimate``, the ``summary`` stat of the call's rows (``x``, ``sets``:
+        ``(set, estimate, below, above)``) and its ``columns``; else ``None``."""
+        return self.summary()
+
+    def summary(self) -> dict[str, Any] | None:
+        """:attr:`stats` (scatter's ``stats`` are its density's)."""
+        from ..layers.stats import STATS, params
+        if self.resolve("estimate") is None:
+            return None
+        st = STATS["summary"]
+
+        def run() -> dict[str, Any]:
+            rows = self.__dict__["_rows"]
+            out: dict[str, Any] = st.fn(rows, params(self, "summary"), ())
+            out["columns"] = _summary_columns(rows, out)
+            return out
+        return self.cached("summary", run, st.reads, kind="summary")
+
+    def set(self, **settings: Any) -> Any:
+        super().set(**settings)
+        if "interval" not in self.SETTINGS:
+            return self
+        est, iv = self.resolve("estimate"), self.resolve("interval")
+        if iv is None:
+            return self
+        if est is None:
+            raise ValueError(f"{self.kind}: interval needs an estimate")
+        if self.is_set(self.ERROR):
+            raise ValueError(f"{self.kind}: {self.ERROR}= and interval= both give error bars; "
+                             "use one")
+        if (iv if isinstance(iv, str) else iv[0]) == "ci" and est != "mean":
+            raise ValueError(f"{self.kind}: interval='ci' is a t interval of the mean; with "
+                             f"estimate={est!r} use 'pi'")
+        return self
+
+
+def _summary_columns(rows: Any, out: dict[str, Any]) -> Any:
+    """The columns of a summary: its estimates at its positions."""
+    from ..columns import Columns, Keys
+    name = next(n for n in rows.kinds if n != "x")
+    keys = out["keys"]
+    x = Keys(out["x"], keys.levels) if keys is not None else array.array("d", out["x"])
+    sets = out["sets"]
+    y: Any = ({k: e for k, e, _, _ in sets} if out["named"] else
+              sets[0][1] if len(sets) == 1 else [e for _, e, _, _ in sets])
+    return Columns(rows.kinds, {**rows.args, "x": x, name: y}, rows.options,
+                   dict(rows.titles), rows.orders, dict(rows.times))
+
+
+def errors_of(s: Any, name: str) -> Any:
+    """The errors of setting ``name`` of ``s``: the interval of its summary in place of
+    its ``ERROR`` setting (``Errors``, or one per set; ``None`` when a line draws it as a
+    band), else the setting's."""
+    if (name != getattr(s, "ERROR", None) or s.resolve("estimate") is None
+            or s.resolve("interval") is None):
+        return s.resolve(name)
+    if "interval_style" in s.SETTINGS and s.resolve("interval_style") == "band":
+        return None
+    es = [Errors((lo, hi)) for _, _, lo, hi in s.summary()["sets"]]
+    return es[0] if len(es) == 1 else es

plot_io/presets/fill.py

@@ -0,0 +1,74 @@
+"""Fill: the area between two curves (``Band``)."""
+
+from typing import Any
+
+from .._methods import FillMixin
+from .. import groups
+from ..color.values import color
+from ..layers.base import Series, common
+from ..layers.core import Table
+from ..layers.grammar import Lay, Spec
+from ..settings import Setting, number, one_of, table
+from ..transform import settings_both as coord_settings
+from .curves import curve_settings
+
+__all__ = ["Fill"]
+
+
+class Fill(FillMixin, Series):
+    """The area between ``y1`` and ``y2`` (a sequence or a constant) along ``x``;
+    ``orientation="horizontal"`` fills between x curves along y (``fill(y, x1, x2)``).
+
+    ``y1`` may be two columns ``[upper, lower]`` (or an ``(n, 2)`` buffer).
+    ``interpolation`` and ``missing`` work as for :class:`Line`, on both edges (a point is
+    missing when x, y1 or y2 is), so a band with the settings of its line matches it,
+    horizontal ones included.  ``color_below`` colors the parts where ``y1`` is below ``y2``
+    (a difference between two curves, each side in its color).
+
+    Example::
+
+        import math
+        x = [i / 10 for i in range(64)]
+        y = [math.sin(v) for v in x]
+        p = plt.Plot(width=240, height=160)
+        p.fill(x, [v + 0.3 for v in y], [v - 0.3 for v in y])
+        p.line(x, y)
+    """
+
+    SETTINGS = table(
+        **coord_settings(),
+        color=Setting(color, doc="Fill color; default: the plot's next color."),
+        color_below=Setting(color, doc="Fill color where `y1` is below `y2` (crossings "
+                                       "found on straight segments); default `color` "
+                                       "everywhere."),
+        opacity=Setting(number(0, 1), inherited=True,
+                      doc="Opacity; default 0.3 × the plot's."),
+        **groups.Stroke.embed("edge_",
+                              only=("color", "line_width"),
+                              docs={"color": "Outline color; default none.",
+                                    "line_width": "Outline width; default the line width."}),
+        **curve_settings(),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical`: between y curves; `horizontal`: between x "
+                                "curves."),
+        **common("name", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    DATA = {"x": "position", "y1": "curve", "y2": "curve"}
+
+    def __init__(self, x: Any, y1: Any, y2: Any = 0.0, plot: Any = None,
+                 **settings: Any) -> None:
+        super().__init__(plot=plot, **settings)
+
+    @property
+    def v2(self) -> Any:
+        """``y2``: a column, or a constant."""
+        return self.cols["y2"]
+
+    SPEC = Spec(
+        [Lay("band", ("band", {"opacity": "opacity", "edges": True,
+                               "extra": ("simplify", "interpolation", "missing")}))],
+        tables={"data": lambda s, b: Table(x=s.cols["x"], y1=s.cols["y1"], y2=s.cols["y2"])},
+        key={"fill": "faded", "stroke": "edge_color", "when": "edge_width"},
+        zero=("y",))