plot-io 0.1.0__py3-none-any.whl

plot_io/stats.py

@@ -0,0 +1,140 @@
+"""Statistics and geometry of the derived plot types: bins, densities, contours, swarms.
+
+The work is done in C by pdf_io's array helpers; these wrappers adapt their results to
+plot_io's needs (matplotlib's hexagon lattice, rows of 2-D histograms, sorted LOWESS
+fits, count rules for bins).
+"""
+
+import math
+from array import array
+from typing import Any
+
+from pdf_io import arrays as _arrays
+
+from . import _backend
+
+__all__ = ["bin_edges", "check_bins", "histogram", "histogram2d", "hexbin", "ecdf",
+           "bandwidth", "kde", "contour_lines", "contour_bands", "lowess", "swarm"]
+
+_RULES = ("auto", "fd", "sturges", "scott", "sqrt", "rice", "doane")
+
+
+def check_bins(v: Any) -> Any:
+    """A bin count, a rule name, or increasing edges."""
+    if isinstance(v, str):
+        if v not in _RULES:
+            raise ValueError(f"unknown bin rule {v!r} (use a count, edges or "
+                             f"{', '.join(_RULES)})")
+        return v
+    if isinstance(v, int) and not isinstance(v, bool):
+        if v < 1:
+            raise ValueError("bins must be at least 1")
+        return v
+    e = _backend.doubles(v)
+    if len(e) < 2 or any(not b > a for a, b in zip(e, e[1:])):
+        raise ValueError("bin edges must increase")
+    return e
+
+
+def bin_edges(values: Any, rule: Any = "auto", range: Any = None) -> array:
+    """Edges of even bins: ``rule`` is a count or one of numpy's rules."""
+    if not isinstance(rule, int):
+        return array("d", _arrays.bin_edges(values, rule, range))
+    if range is not None:
+        lo, hi = float(range[0]), float(range[1])
+    else:
+        n, lo, hi = _backend.extent(values, None)
+        if not n:
+            lo, hi = 0.0, 1.0
+    if lo == hi:
+        lo, hi = lo - 0.5, hi + 0.5
+    nb = max(1, rule)
+    edges = array("d", (lo + (hi - lo) * i / nb for i in builtins_range(nb + 1)))
+    edges[-1] = hi
+    return edges
+
+
+builtins_range = range
+
+
+def histogram(values: Any, edges: Any, weights: Any = None) -> array:
+    """Sum of weights (or counts) per bin; the last bin includes its right edge."""
+    return array("d", _arrays.histogram(values, edges, weights))
+
+
+def histogram2d(x: Any, y: Any, x_edges: Any, y_edges: Any, weights: Any = None) -> list[array]:
+    """Counts per ``(y bin, x bin)``: rows are y bins from the first edge."""
+    h, w, flat = _arrays.histogram2d(x, y, x_edges, y_edges, weights)
+    return [array("d", flat[r * w:(r + 1) * w]) for r in builtins_range(h)]
+
+
+_S3 = math.sqrt(3.0)
+
+
+def hexbin(x: Any, y: Any, x0: float, y0: float, dx: float, dy: float, nx: int, ny: int,
+           weights: Any = None) -> tuple[array, array, array]:
+    """matplotlib's hexagonal bins: lattices ``(x0 + i dx, y0 + j dy)`` (``0 ≤ i ≤ nx``,
+    ``0 ≤ j ≤ ny``) and ``(x0 + (i + ½) dx, y0 + (j + ½) dy)``, each point to the nearest
+    centre with y distances weighted by 3.  Returns the non-empty cells' centres and
+    sums."""
+    # In units (dx, dy / √3), matplotlib's metric is the plain distance pdf_io uses.
+    u = _backend.scaled(x, 1.0 / dx, -x0 / dx)
+    v = _backend.scaled(y, _S3 / dy, -_S3 * y0 / dy)
+    cx, cy, cs = _arrays.hexbin(u, v, 0.0, 0.0, 1.0, _S3, nx + 1, ny + 1, weights)
+    return (_backend.scaled(cx, dx, x0), _backend.scaled(cy, dy / _S3, y0), array("d", cs))
+
+
+def ecdf(values: Any, weights: Any = None) -> tuple[array, array]:
+    """Sorted finite values and the cumulative weight up to each."""
+    xs, cs = _arrays.ecdf(values, weights)
+    return array("d", xs), array("d", cs)
+
+
+def bandwidth(values: Any, rule: Any = "scott", weights: Any = None) -> float:
+    """Gaussian kernel bandwidth: Scott's or Silverman's factor times the (weighted) sample
+    standard deviation, as scipy's ``gaussian_kde``; a number is returned as is."""
+    if not isinstance(rule, str):
+        return float(rule)
+    return float(_arrays.bandwidth(values, rule, weights))
+
+
+def kde(values: Any, grid_min: float, grid_max: float, n: int, bw: float, weights: Any = None,
+        cumulative: bool = False) -> array:
+    """Gaussian kernel density (integral 1 over the real line) at ``n`` points from
+    ``grid_min`` to ``grid_max``; ``cumulative``: its integral."""
+    return array("d", _arrays.kde(values, grid_min, grid_max, n, bw, weights, cumulative))
+
+
+def contour_lines(grid: Any, w: int, h: int, xs: Any, ys: Any,
+                  level: float) -> list[tuple[array, array, bool]]:
+    """Iso-lines at ``level`` as ``(x, y, closed)`` polylines (node coordinates ``xs``,
+    ``ys``; a closed line repeats its first point)."""
+    return [(array("d", a), array("d", b), bool(c))
+            for a, b, c in _arrays.contour_lines(grid, w, h, xs, ys, level)]
+
+
+def contour_bands(grid: Any, w: int, h: int, xs: Any, ys: Any, lo: float,
+                  hi: float) -> tuple[array, array, array]:
+    """The region ``lo <= v < hi`` as rings ``(xs, ys, ring_starts)`` that fill it exactly
+    together, in one path with the nonzero rule (pdf_io's form)."""
+    a, b, starts = _arrays.contour_bands(grid, w, h, xs, ys, lo, hi)
+    return array("d", a), array("d", b), array("q", (int(s) for s in starts))
+
+
+def lowess(x: Any, y: Any, frac: float = 2.0 / 3.0, iterations: int = 3) -> tuple[array, array]:
+    """Locally weighted linear regression: the sorted x values and the fitted y values."""
+    xs0, ys0 = _backend.doubles(x), _backend.doubles(y)
+    pairs = sorted((a, b) for a, b in zip(xs0, ys0) if math.isfinite(a) and math.isfinite(b))
+    xs = array("d", (p[0] for p in pairs))
+    ys = array("d", (p[1] for p in pairs))
+    if len(xs) < 2:
+        return xs, ys
+    return xs, array("d", _arrays.lowess(xs, ys, frac, iterations))
+
+
+def swarm(positions: Any, size: Any, slot_width: float) -> tuple[array, int]:
+    """Offsets across the slot for markers at ``positions`` (page units along the value
+    axis) of diameter ``size`` so that they do not overlap; points that do not fit are
+    put at the slot edge.  Returns the offsets (in input order) and how many did not fit."""
+    offs, gutter = _arrays.swarm(positions, size, slot_width)
+    return array("d", offs), int(gutter)

plot_io/style.py

@@ -0,0 +1,71 @@
+"""Palette, palette references (``"C0"``…) and line dash styles."""
+
+from typing import Any
+
+from .defaults import OKABE_ITO
+
+__all__ = ["PALETTE", "resolve_color", "dash_of", "with_alpha", "check_palette", "desaturate"]
+
+PALETTE = OKABE_ITO
+
+
+def check_palette(v: Any) -> Any:
+    """A palette name, a function ``n -> colors``, or a list of colors."""
+    from .palettes import check_palette as check
+    return check(v)
+
+
+def resolve_color(c: Any, palette: tuple[Any, ...]) -> Any:
+    """A color with ``"C<n>"`` replaced by the palette entry."""
+    if isinstance(c, str) and len(c) >= 2 and c[0] == "C" and c[1:].isdigit():
+        return palette[int(c[1:]) % len(palette)]
+    if isinstance(c, str) and c.strip().lower() == "none":
+        return None
+    return c
+
+
+def with_alpha(c: Any, alpha: float) -> Any:
+    """``c`` with its alpha multiplied by ``alpha`` (as an RGBA tuple)."""
+    if c is None:
+        return None
+    if alpha >= 1:
+        return c
+    from pdf_io.colors import CMYK, to_rgba
+
+    if isinstance(c, CMYK):
+        return c.with_alpha(c[3] * alpha)
+    rgba = to_rgba(c)
+    if rgba is None:
+        return None
+    a = rgba[3] if len(rgba) > 3 else 1.0
+    return (rgba[0], rgba[1], rgba[2], a * alpha)
+
+
+def desaturate(c: Any, k: float) -> Any:
+    """``c`` with its HLS saturation multiplied by ``k`` (as an RGBA tuple)."""
+    import colorsys
+    from pdf_io.colors import to_rgba
+
+    rgba = to_rgba(c)
+    if rgba is None:
+        return None
+    h, light, s = colorsys.rgb_to_hls(rgba[0], rgba[1], rgba[2])
+    r, g, b = colorsys.hls_to_rgb(h, light, s * k)
+    return (r, g, b, rgba[3] if len(rgba) > 3 else 1.0)
+
+
+_DASHES = {"solid": None, "dashed": (3.7, 1.6), "dotted": (1.0, 1.65),
+           "dashdot": (6.4, 1.6, 1.0, 1.6)}
+
+
+def dash_of(style: Any, width: float) -> list[float] | None:
+    """Dash lengths (pt) of a line style, scaled by the line width."""
+    if style is None:
+        return None
+    if isinstance(style, (list, tuple)):
+        return [float(x) for x in style] or None
+    pattern = _DASHES[style]
+    if pattern is None:
+        return None
+    w = max(width, 0.5)
+    return [x * w for x in pattern]

plot_io/styles/__init__.py

@@ -0,0 +1,234 @@
+"""Styles: named presets of settings.
+
+A style is a dict of settings: setting names for inherited settings (``"font_size"``) and
+``"Class.name"`` for any setting of a class (``"Axis.grid"``).  The key ``"base"`` names
+the styles it builds on, one or a list, applied left to right before its own keys.  A
+figure's ``style`` is a registered name or such a dict; its effective theme is the base
+theme with the expanded style merged over it, lengths multiplied by ``scaling``.
+"""
+
+import contextlib
+import difflib
+from collections.abc import Iterator
+from typing import Any
+
+from ..defaults import DEFAULTS, class_default
+from ..settings import ALIASES, THEME, Setting
+
+__all__ = ["register_style", "styles", "style_settings", "set_style", "use_style",
+           "check_style", "effective", "current"]
+
+_STYLES: dict[str, dict[str, Any]] = {}
+_version = 0
+_session: Any = None
+_stack: list[Any] = []
+
+
+def _classes() -> dict[str, Any]:
+    from ..axis import Axis
+    from ..colorbar import Colorbar
+    from ..figure import Figure, FigureTitle
+    from ..plot import Legend, Plot, Title
+    from ..series.box import Box
+    from ..series.fill import Fill
+    from ..series.heatmap import Heatmap
+    from ..series.line import Line
+    from ..series.scatter import Scatter
+    from .. import decorations as d
+    from ..series import (area, bar, catpoints, contour, ecdf, errorbar, hexbin, hist, hist2d,
+                          kde2d,
+                          kde, pie, regression, stem, violin)
+    return {"Figure": Figure, "FigureTitle": FigureTitle, "Plot": Plot, "Title": Title,
+            "Legend": Legend, "Axis": Axis, "Colorbar": Colorbar, "Scatter": Scatter,
+            "Line": Line, "Fill": Fill, "Box": Box, "Heatmap": Heatmap, "Bar": bar.Bar,
+            "Hist": hist.Hist, "Kde": kde.Kde, "Kde2d": kde2d.Kde2d, "Ecdf": ecdf.Ecdf, "Violin": violin.Violin,
+            "Strip": catpoints.Strip, "Swarm": catpoints.Swarm, "Area": area.Area,
+            "Errorbar": errorbar.Errorbar, "Stem": stem.Stem,
+            "Regression": regression.Regression, "Hist2d": hist2d.Hist2d,
+            "Hexbin": hexbin.Hexbin, "Contour": contour.Contour, "Pie": pie.Pie,
+            "HLine": d.HLine, "VLine": d.VLine, "AxLine": d.AxLine, "HSpan": d.HSpan,
+            "VSpan": d.VSpan, "Text": d.Text, "Annotate": d.Annotate}
+
+
+def _setting(key: str) -> Setting:
+    """The setting a style key refers to."""
+    classes = _classes()
+    if "." in key:
+        cls_name, _, name = key.partition(".")
+        cls = classes.get(cls_name)
+        if cls_name in ("XAxis", "YAxis"):              # the x or y axis of plots only
+            cls = classes["Axis"]
+        if cls is None:
+            near = difflib.get_close_matches(cls_name, classes, n=1)
+            hint = f" (did you mean {near[0]!r}?)" if near else ""
+            raise ValueError(f"unknown class {cls_name!r} in style key {key!r}{hint}")
+        s = cls.SETTINGS.get(name)
+        if s is None and cls_name == "Colorbar":         # a setting of colorbar axes only
+            s = classes["Axis"].SETTINGS.get(name)
+        if s is None:
+            near = difflib.get_close_matches(name, cls.SETTINGS, n=1)
+            hint = f" (did you mean {cls_name}.{near[0]}?)" if near else ""
+            raise ValueError(f"unknown setting {key!r} in style{hint}")
+        return s
+    names: dict[str, Setting] = {}
+    for cls in classes.values():
+        for n, s in cls.SETTINGS.items():
+            if s.inherited:
+                names.setdefault(n, s)
+    if key not in names:
+        near = difflib.get_close_matches(key, names, n=1)
+        hint = f" (did you mean {near[0]!r}?)" if near else ""
+        raise ValueError(f"unknown style key {key!r}: not an inherited setting; use "
+                         f"\"Class.{key}\" for a setting of one class{hint}")
+    return names[key]
+
+
+def _bases(v: Any) -> tuple[str, ...]:
+    names = (v,) if isinstance(v, str) else tuple(v)
+    for n in names:
+        if not isinstance(n, str):
+            raise ValueError(f"a style base is a style name, got {n!r}")
+        _get(n)
+    return names
+
+
+def _validate(style: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key, value in style.items():
+        if key == "base":
+            out["base"] = _bases(value)
+            continue
+        cls_part, dot, name = key.rpartition(".")
+        if name in ALIASES:
+            key = f"{cls_part}{dot}{ALIASES[name]}"
+        s = _setting(key)
+        if value is None:
+            raise ValueError(f"style key {key!r}: None is not a value")
+        if s.check is not None:
+            try:
+                value = s.check(value)
+            except (TypeError, ValueError) as e:
+                raise ValueError(f"style key {key!r}: {e}") from None
+        out[key] = value
+    return out
+
+
+_loaded = False
+
+
+def _load() -> None:
+    """Register the bundled styles (on first use: they refer to every settings class)."""
+    global _loaded
+    if not _loaded:
+        _loaded = True
+        from . import library  # noqa: F401
+
+
+def _get(name: str) -> dict[str, Any]:
+    _load()
+    key = name.strip().lower()
+    if key not in _STYLES:
+        near = difflib.get_close_matches(key, _STYLES, n=1)
+        hint = f" (did you mean {near[0]!r}?)" if near else ""
+        raise ValueError(f"unknown style {name!r}{hint}")
+    return _STYLES[key]
+
+
+def register_style(name: str, style: dict[str, Any]) -> None:
+    """Register ``style`` (a dict of settings, with an optional ``"base"``) as ``name``."""
+    global _version
+    _load()
+    if not isinstance(style, dict):
+        raise ValueError("a style is a dict of settings")
+    _STYLES[name.strip().lower()] = _validate(style)
+    _version += 1
+
+
+def styles() -> list[str]:
+    """Names of the registered styles."""
+    _load()
+    return sorted(_STYLES)
+
+
+def check_style(v: Any) -> Any:
+    """Validator of the ``style`` setting: a registered name or a dict."""
+    if isinstance(v, str):
+        _get(v)
+        return v.strip().lower()
+    if isinstance(v, dict):
+        return _validate(v)
+    raise ValueError(f"a style is a style name or a dict of settings, got {v!r}")
+
+
+def expand(style: Any, _seen: tuple[str, ...] = ()) -> dict[str, Any]:
+    """The settings of ``style`` with its bases applied first."""
+    if isinstance(style, str):
+        key = style.strip().lower()
+        if key in _seen:
+            raise ValueError(f"style {key!r} is its own base ({' → '.join(_seen + (key,))})")
+        d, seen = _get(key), _seen + (key,)
+    else:
+        d, seen = check_style(style), _seen
+    out: dict[str, Any] = {}
+    for b in d.get("base", ()):
+        out.update(expand(b, seen))
+    out.update((k, v) for k, v in d.items() if k != "base")
+    return out
+
+
+def style_settings(style: Any) -> dict[str, Any]:
+    """The base theme with ``style`` merged over it (unscaled), to inspect or copy."""
+    return {**THEME, **expand(style)}
+
+
+def _scaled(theme: dict[str, Any], s: float) -> dict[str, Any]:
+    def scale(v: Any) -> Any:
+        return v * s if isinstance(v, (int, float)) and not isinstance(v, bool) else v
+
+    out = dict(theme)
+    for key, value in theme.items():
+        if _setting(key).length:
+            out[key] = scale(value)
+    for cls_name, cls in _classes().items():
+        for name, setting in cls.SETTINGS.items():
+            key = f"{cls_name}.{name}"
+            if setting.length and not setting.inherited and key not in out:
+                d = class_default(cls, name)
+                if not callable(d) and scale(d) is not d:
+                    out[key] = scale(d)
+    return out
+
+
+def effective(style: Any, scaling: float | None) -> dict[str, Any]:
+    """The effective theme of a figure with ``style`` (``None``: the base theme)."""
+    theme = {**THEME, **expand(style)} if style is not None else dict(THEME)
+    s = scaling if scaling is not None else theme.get("Figure.scaling", DEFAULTS["Figure.scaling"])
+    return _scaled(theme, s) if s != 1.0 else theme
+
+
+def version() -> int:
+    """Changes whenever a style is registered (for caches of effective themes)."""
+    _load()
+    return _version
+
+
+def current() -> Any:
+    """The style new figures take: the innermost ``use_style``, else ``set_style``'s."""
+    return _stack[-1] if _stack else _session
+
+
+def set_style(style: Any) -> None:
+    """Default style of figures created afterwards (``None``: back to ``"default"``)."""
+    global _session
+    _session = None if style is None else check_style(style)
+
+
+@contextlib.contextmanager
+def use_style(style: Any) -> Iterator[None]:
+    """Default style of figures created inside the block."""
+    _stack.append(check_style(style))
+    try:
+        yield
+    finally:
+        _stack.pop()
+