plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/presets/kde2d.py

@@ -0,0 +1,147 @@
+"""2-D kernel density contours (``kde(x, y)``, stat ``kde2d`` then ``contour``): seaborn's
+``kdeplot(x=, y=)``."""
+
+import array
+import math
+from typing import Any
+
+from .._methods import Kde2dMixin
+from .. import columns
+from ..density import _bandwidth
+from ..layers import stats
+from ..layers.base import Series
+from ..layers.core import Call, Layer, Table
+from ..layers.geoms import GEOMS
+from ..layers.paint import base_color
+from ..settings import Setting, number, table
+from .contour import Contour
+
+__all__ = ["Kde2d"]
+
+
+class Kde2d(Kde2dMixin, Contour):
+    """Density contours of points ``(x, y)``: the 2-D Gaussian density on a grid over the
+    data plus ``cut`` bandwidths, drawn at levels enclosing equal shares of the mass.
+
+    Made by ``p.kde(x, y)`` (or ``plt.Kde(x, y)``), as seaborn's ``kdeplot(x=, y=)``.  The
+    bandwidth is as `Density <docs/api.md#point-density>`_'s: scipy's covariance times Scott's
+    factor, or Silverman's, a number or a matrix, times ``adjust``; the grid is ``points``
+    × ``points`` in axis positions (log axes in log space).  With a number n of ``levels``,
+    level k (0 … n − 1) encloses 1 − p of the mass, p = ``thresh`` + (1 − ``thresh``)·k/(n −
+    1): the outermost 1 − ``thresh``, the last at the density's maximum; a list gives density
+    values.  Unfilled lines take the plot's next color, unless ``color_map`` is set (a map,
+    or one color: as :class:`Contour`'s); ``fill=True`` colors the bands through
+    ``color_map``, the top band up to the maximum.  Drawn by :class:`Contour`'s code (lines,
+    labels, colorbar).
+
+    Example::
+
+        rng = random.Random(1)
+        x = [rng.gauss(0, 1) for _ in range(300)]
+        p = plt.Plot(width=240, height=160)
+        p.kde(x, [v + rng.gauss(0, 0.6) for v in x], levels=6)
+    """
+
+    SETTINGS = table(
+        **{k: v for k, v in Contour.SETTINGS.items() if k != "levels"},
+        levels=Setting(lambda v: v if isinstance(v, list) else number(lo=1, integer=True)(v),
+                       doc="A number n of iso-proportion levels: level k (0 … n − 1) encloses "
+                           "1 − p of the mass, p = `thresh` + (1 − `thresh`)·k/(n − 1) (the "
+                           "outermost 1 − `thresh`, the last at the density's maximum); or "
+                           "density values."),
+        thresh=Setting(number(0, 1),
+                       doc="Lowest iso-proportion: the outermost contour encloses 1 − "
+                           "`thresh` of the mass."),
+        bandwidth=Setting(_bandwidth,
+                          doc="`\"scott\"`, `\"silverman\"`, a number or a 2 × 2 matrix, as "
+                              "`Density`."),
+        adjust=Setting(number(positive=True), doc="Factor of the bandwidth."),
+        weights=Setting(lambda v: columns.numbers(v, "weights"),
+                        doc="A weight per point, counted as repeated points."),
+        cut=Setting(number(lo=0), doc="Grid extends this many bandwidths past the data."),
+        points=Setting(number(lo=16, hi=1024, integer=True),
+                       doc="Grid points per side."),
+    )
+
+    DATA = {"x": "numbers", "y": "numbers"}
+
+    def __init__(self, x: Any, y: Any, plot: Any = None, **settings: Any) -> None:
+        self.h = self.w = 2
+        self.flat = array.array("d", [0.0] * 4)
+        self.xn = self.yn = array.array("d", [0.0, 1.0])
+        Series.__init__(self, plot=plot, **settings)
+
+    def _grid(self) -> dict[str, Any]:
+        sx, sy = self._scales()
+        return stats.compute(self, "kde2d", (sx, sy), kind="grid")
+
+    def _grid_data(self) -> tuple[Any, int, int, Any, Any]:
+        g = self._grid()
+        return g["flat"], g["w"], g["h"], g["fx"], g["fy"]
+
+    def level_values(self) -> list[float]:
+        lv = self.resolve("levels")
+        if isinstance(lv, list):
+            return sorted(float(v) for v in lv)
+        g = self._grid()
+        values = sorted((v for v in g["flat"] if v == v), reverse=True)
+        total = sum(values)
+        if not total:
+            return [0.0]
+        thresh = self.resolve("thresh")
+        props = [thresh + (1.0 - thresh) * i / (lv - 1) for i in range(lv)] if lv > 1 \
+            else [thresh]
+        cum, out, acc, j = [], [], 0.0, 0
+        for v in values:
+            acc += v
+            cum.append(acc / total)
+        for p in props:                      # density whose upper set holds 1 − p
+            target = 1.0 - p
+            while j < len(cum) - 1 and cum[j] < target:
+                j += 1
+            out.append(values[min(j, len(values) - 1)])
+            j = 0
+        return sorted(set(out))
+
+    def _bands(self, lv: list[float]) -> list[tuple[float, float, float]]:
+        flat = self._grid()["flat"]
+        out = []
+        for lo, hi in zip(lv, lv[1:] + [math.inf]):
+            top = hi if math.isfinite(hi) else max(flat) * 1.0001 + 1e-300
+            out.append((lo, hi if math.isfinite(hi) else top, top))
+        return out
+
+    def _level_color(self, ctx: Any, i: int, level: float) -> Any:
+        if not self._filled() and not self._mapped_given():
+            return base_color(self, ctx)
+        return super()._level_color(ctx, i, level)
+
+    def _mapped_given(self) -> bool:
+        """Whether a map is given (unfilled contours otherwise take the plot's color)."""
+        return self.is_set("color_map") or self.is_set("color_axis")
+
+    def _color_count(self) -> int:
+        uses = not self._filled() and not self._mapped_given()
+        return 1 if uses else 0
+
+    def _mapped_source(self) -> bool:
+        if not self._filled() and not self._mapped_given():
+            return False
+        return super()._mapped_source()
+
+    def _roles(self) -> dict[str, str]:
+        return {}
+
+    def _occupancy(self, call: Call) -> None:
+        # the density's points mark the cells for legend placement
+        for la in call.layers:
+            la.occupy = False
+        call.layers.append(Layer(GEOMS["points"], Table(x=self.cols["x"], y=self.cols["y"]),
+                                 paint=None,
+                                 key=False, bounds=False))
+
+    def _extent(self, call: Call) -> None:
+        sx, sy = self._scales()
+        g = self._grid()
+        call.extra = {"x": array.array("d", [sx.inverse(g["fx"][0]), sx.inverse(g["fx"][-1])]),
+                      "y": array.array("d", [sy.inverse(g["fy"][0]), sy.inverse(g["fy"][-1])])}

plot_io/presets/line.py

@@ -0,0 +1,143 @@
+"""Line: a polyline through points, or several sharing x (``Path``), with optional markers
+(``Points``) and error bars (``Segments``)."""
+
+import array
+from typing import TYPE_CHECKING, Any, Self, Unpack
+
+from .. import groups
+from ..color.values import color
+from ..layers.base import common
+from ..layers.core import Table
+from ..layers.grammar import Lay, Spec
+from ..layers.paint import xy_density_points
+from ..settings import Setting, one_of, table
+from ..transform import settings_both as coord_settings
+from .curves import curve_settings
+from .errors import Summarized, error_value
+
+if TYPE_CHECKING:
+    from ..types import LineSettings
+
+__all__ = ["Line"]
+
+
+class Line(Summarized):
+    """A line through ``(x, y)``; ``y`` may hold several columns (one line each, sharing
+    ``x``: a 2-D buffer's columns, a data frame, a list of arrays), and
+    ``x`` may be omitted (``0, 1, 2, …``).  ``orientation="horizontal"`` draws ``x`` on
+    the y axis (a profile along y).  Numbers per point (or ``"density"``) in
+    ``marker_color``/``marker_edge_color`` map through the series' color axis.
+
+    Named line styles scale with the width.  With replicates, ``estimate`` draws a line
+    through their estimates and ``interval`` a band (or error bars) around it
+    (`summaries <docs/api.md#summaries-estimate-interval>`_).  Markers (``marker``, ``marker_size``, ``marker_color``, …) are drawn at
+    the points when ``marker`` or ``show_markers`` is set; numbers per point in
+    ``marker_color`` and ``marker_edge_color`` go through the series' `color axis <docs/api.md#6-color-and-size-axes>`_
+    (``p.add_colorbar(line)``), as ``color`` does on :class:`Scatter`; the line keeps
+    ``color``, and the legend's marker takes the gradient's middle color.
+
+    - ``interpolation``: ``linear``; ``step-pre``, ``step-post``, ``step-mid``; ``monotone`` (a
+      cubic through every point that never overshoots, Fritsch–Carlson; ``spline`` where x is
+      not monotonic); ``spline`` (centripetal Catmull–Rom, may overshoot).  Each segment is
+      one exact Bézier, computed on the page after the axis scales.  Steps and curves are not
+      decimated by ``simplify``.
+    - ``missing``: ``break`` ends a run at a missing value (NaN, ``None``, or outside the
+      axis scale's domain); runs are drawn on their own and a one-point run draws nothing.
+      ``skip`` connects the points on either side.
+
+    Example::
+
+        import math
+        x = [i / 10 for i in range(64)]
+        p = plt.Plot(width=240, height=160)
+        p.line(x, [math.sin(v) for v in x], name="sin")
+        p.line(x, [math.cos(v) for v in x], name="cos", interpolation="step-mid")
+    """
+
+    SETTINGS = table(
+        **coord_settings(),
+        color=Setting(color, doc="Line color; default: the plot's next color."),
+        **groups.Stroke.embed(only=("line_width", "line_style", "cap", "join"),
+                              inherited=("line_width",),
+                              docs={"line_style": "`solid`, `dashed`, `dotted`, `dashdot` or "
+                                                  "a dash list; named styles scale with the "
+                                                  "width."}),
+        **curve_settings(),
+        **groups.Marker.embed("marker_"),
+        **common("color_map"),
+        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`)."),
+        orientation=Setting(one_of("vertical", "horizontal"),
+                            doc="`vertical` (x along the x axis) or `horizontal` (x along "
+                                "the y axis)."),
+        **common("estimate"),
+        interval_style=Setting(one_of("band", "bars"),
+                               doc="The interval of `estimate`: a `band` (at 0.25 times "
+                                   "`opacity`) or error `bars`."),
+        **common("name", "opacity", "z", "rasterize", "simplify", "font_size", "font_family",
+                 "text_color"),
+    )
+
+    DATA = {"x": "position", "y": "sets"}
+
+    def __init__(self, x: Any, y: Any = None, plot: Any = None, **settings: Any) -> None:
+        self._markers_on = "marker" in settings
+        super().__init__(plot=plot, **settings)
+
+    @property
+    def x(self) -> Any:
+        """x of the points (categories at their index among their own)."""
+        return self.cols["x"]
+
+    @property
+    def ys(self) -> list[array.array]:
+        """The lines' y: one column each."""
+        return self.cols.values
+
+    @property
+    def y(self) -> array.array:
+        return self.ys[0]
+
+    def set(self, **settings: "Unpack[LineSettings]") -> Self:  # type: ignore[override]
+        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.resolve("show_markers"))
+
+    def density_points(self) -> tuple[Any, Any]:
+        """The markers' positions on the plot's axes (a density in ``marker_color``)."""
+        if len(self.ys) > 1:
+            raise ValueError("Line: a density in marker_color needs a single line (y has "
+                             f"{len(self.ys)} rows)")
+        return xy_density_points(self, self.x, self.ys[0])
+
+    SPEC = Spec(
+        [Lay("errors", ("error_source", {})),
+         Lay("band", ("band", {"color": "faded", "opacity": 0.25}), table="interval",
+             key=False, occupy=False),
+         Lay("path", ("stroke", {"dash": True, "opacity": True,
+                                 "extra": ("cap", "join", "simplify", "interpolation",
+                                           "missing")})),
+         Lay("points", ("marker", {"prefix": "marker_", "n": lambda s: len(s.x)}),
+             table="markers", when="_markers()", occupy=False, key="first")],
+        tables={"data": lambda s, b: Table(x=s.x, y=s.ys if len(s.ys) > 1 else s.ys[0]),
+                "interval": lambda s, b: _bands(s),
+                "markers": lambda s, b: [Table(x=s.x, y=r) for r in s.ys]},
+        key={"fill": "base", "stroke": "base"},
+        zero=("y",), color_sources="_markers()")
+
+
+def _bands(s: Line) -> list[Table] | None:
+    """The interval of ``estimate`` as a band per set (``interval_style="band"``)."""
+    st = s.stats
+    if st is None or s.resolve("interval") is None or s.resolve("interval_style") != "band":
+        return None
+    return [Table(x=s.x, y1=array.array("d", (m - d for m, d in zip(e, lo))),
+                  y2=array.array("d", (m + d for m, d in zip(e, hi))))
+            for _, e, lo, hi in st["sets"]]