ggh4x-python 0.3.1.9000__py3-none-any.whl

ggh4x/stat_rle.py

@@ -0,0 +1,290 @@
+"""Run length encoding stat (R source: ggh4x/R/stat_rle.R).
+
+Port of ggh4x's :func:`stat_rle` / ``StatRle``. Run length encoding takes a
+vector of values (the ``label`` aesthetic) and, after ordering the data on the
+``x`` aesthetic, computes the lengths of consecutive repeated values, turning
+each run into a rectangle spanning the run's ``x`` extent.
+
+In contrast to :func:`base::rle`, ``NA`` values are considered equivalent
+(consecutive ``NA`` form a single run), mirroring ``vctrs::vec_unrep`` as used
+by the R implementation.
+
+The computed columns are ``start``, ``end``, ``start_id``, ``end_id``,
+``run_id``, ``runlength`` and ``runvalue``; the geom defaults map these onto a
+``geom_rect`` via :func:`after_stat`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from ggplot2_py import ggproto_parent  # noqa: F401  (kept for parity / future use)
+from ggplot2_py.aes import AfterStat
+from ggplot2_py.layer import layer
+from ggplot2_py.stat import Stat
+
+from ._rlang import arg_match0
+
+__all__ = ["stat_rle", "StatRle"]
+
+
+# -- helpers ----------------------------------------------------------------
+
+
+def _vec_unrep(x: "np.ndarray | pd.Series | List[Any]") -> pd.DataFrame:
+    """Run-length encode consecutive equal values, ``NA``-as-equal.
+
+    Faithful reimplementation of ``vctrs::vec_unrep`` for the semantics ggh4x
+    relies on: consecutive equal values (including consecutive ``NA`` / ``None``)
+    collapse into a single run. This differs from the more general
+    :func:`ggh4x._vctrs.vec_unrep`, which compares with ``!=`` and therefore
+    splits runs of ``NaN`` (because ``NaN != NaN``).
+
+    Parameters
+    ----------
+    x : numpy.ndarray, pandas.Series, or list
+        Input vector. May contain ``NA``/``NaN``/``None``. A pandas
+        ``Categorical``/factor dtype is preserved in the returned ``key``.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Two columns: ``key`` (the run value in first-appearance order, dtype
+        preserved from the input) and ``times`` (``int`` run length).
+
+    Raises
+    ------
+    ValueError
+        If ``x`` is ``None`` (mirrors R's ``vec_unrep(NULL)`` scalar-type error).
+    """
+    if x is None:
+        raise ValueError("`x` must be a vector, not `None`.")
+
+    s = x if isinstance(x, pd.Series) else pd.Series(list(x))
+    n = len(s)
+    if n == 0:
+        return pd.DataFrame(
+            {
+                "key": pd.Series([], dtype=s.dtype),
+                "times": pd.Series([], dtype=int),
+            }
+        )
+
+    # Boundaries: a new run starts at position 0 and wherever the current value
+    # differs from the previous one, treating NA as equal to a preceding NA.
+    cur = s.iloc[1:].reset_index(drop=True)
+    prev = s.iloc[:-1].reset_index(drop=True)
+    cur_na = cur.isna().to_numpy()
+    prev_na = prev.isna().to_numpy()
+    # equal if both NA, or (neither NA and values match)
+    eq = (cur_na & prev_na) | ((~cur_na) & (~prev_na) & (cur.to_numpy() == prev.to_numpy()))
+
+    change = np.empty(n, dtype=bool)
+    change[0] = True
+    change[1:] = ~eq
+    idx = np.flatnonzero(change)
+    times = np.diff(np.append(idx, n)).astype(int)
+    key = s.iloc[idx].reset_index(drop=True)
+    return pd.DataFrame({"key": key, "times": times})
+
+
+# -- ggproto ----------------------------------------------------------------
+
+
+class StatRle(Stat):
+    """Run length encoding stat turning runs of ``label`` into rectangles.
+
+    Notes
+    -----
+    Port of ``StatRle`` (``ggh4x/R/stat_rle.R`` L113-162). The data is ordered
+    on ``x`` and the ``label`` aesthetic is run-length encoded (``NA``-as-equal).
+    Four ``align`` modes (``none``/``centre``/``start``/``end``) control how the
+    ``start``/``end`` ``x`` positions of each run are computed.
+    """
+
+    required_aes: List[str] = ["x", "label"]
+    default_aes: Dict[str, Any] = {
+        "xmin": AfterStat("start"),
+        "xmax": AfterStat("end"),
+        "ymin": AfterStat(lambda d: np.full(len(d), -np.inf)),
+        "ymax": AfterStat(lambda d: np.full(len(d), np.inf)),
+        "fill": AfterStat("runvalue"),
+    }
+    dropped_aes: List[str] = ["x", "label"]
+    extra_params: List[str] = ["na_rm", "orientation", "align"]
+
+    def setup_params(self, data: pd.DataFrame, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Set ``flipped_aes`` from the requested orientation.
+
+        Parameters
+        ----------
+        data : pandas.DataFrame
+            Layer data (unused; present for signature parity).
+        params : dict
+            Stat parameters. Read ``orientation``.
+
+        Returns
+        -------
+        dict
+            ``params`` with ``flipped_aes`` set to ``orientation == 'y'``.
+        """
+        params["flipped_aes"] = params.get("orientation") == "y"
+        return params
+
+    def compute_group(
+        self,
+        data: pd.DataFrame,
+        scales: Any = None,
+        flipped_aes: bool = False,
+        align: str = "none",
+        **kwargs: Any,
+    ) -> pd.DataFrame:
+        """Run-length encode ``label`` and compute per-run ``x`` extents.
+
+        Parameters
+        ----------
+        data : pandas.DataFrame
+            Group data, must contain ``x`` and ``label`` columns.
+        scales : Any, optional
+            Panel scales (unused; present for signature parity).
+        flipped_aes : bool, optional
+            Orientation flag (unused by the computation; kept for parity).
+        align : {'none', 'centre', 'start', 'end'}, optional
+            How to derive ``start``/``end`` positions:
+
+            * ``none`` -- exact ``x`` at run boundaries.
+            * ``centre`` -- midpoint between a run boundary and its neighbour.
+            * ``start`` -- align run starts to the previous run's end.
+            * ``end`` -- align run ends to the next run's start.
+        **kwargs : Any
+            Ignored extra parameters.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Columns ``start``, ``end``, ``start_id``, ``end_id``, ``run_id``,
+            ``runlength`` and ``runvalue``.
+        """
+        # Order on x (stable, mirroring R's order()).
+        order = np.argsort(data["x"].to_numpy(), kind="stable")
+        data = data.iloc[order].reset_index(drop=True)
+        n = len(data)
+
+        run = _vec_unrep(data["label"])
+        times = run["times"].to_numpy()
+
+        # 1-based boundary indices (R semantics).
+        end_id = np.cumsum(times)
+        start_id = end_id - times + 1
+
+        xvals = data["x"].to_numpy()
+
+        def _x(idx_1based: np.ndarray) -> np.ndarray:
+            # idx_1based is a 1-based index array (already clamped to [1, n]).
+            return xvals[idx_1based.astype(int) - 1]
+
+        if align == "centre":
+            start = (
+                _x(np.maximum(start_id, 1)) + _x(np.maximum(start_id - 1, 1))
+            ) / 2.0
+            end = (_x(np.minimum(end_id, n)) + _x(np.minimum(end_id + 1, n))) / 2.0
+        elif align == "end":
+            start = _x(np.maximum(start_id - 1, 1))
+            end = _x(end_id)
+        elif align == "start":
+            start = _x(start_id)
+            end = _x(np.minimum(end_id + 1, n))
+        else:  # "none"
+            start = _x(start_id)
+            end = _x(end_id)
+
+        run_id = np.arange(1, len(run) + 1)
+
+        return pd.DataFrame(
+            {
+                "start": start,
+                "end": end,
+                "start_id": start_id.astype(int),
+                "end_id": end_id.astype(int),
+                "run_id": run_id.astype(int),
+                "runlength": times.astype(int),
+                "runvalue": run["key"].reset_index(drop=True),
+            }
+        )
+
+
+# -- constructor ------------------------------------------------------------
+
+
+def stat_rle(
+    mapping: Optional[Any] = None,
+    data: Optional[Any] = None,
+    geom: str = "rect",
+    position: str = "identity",
+    *,
+    align: str = "none",
+    na_rm: bool = False,
+    orientation: str = "x",
+    show_legend: Optional[bool] = None,
+    inherit_aes: bool = True,
+    **kwargs: Any,
+) -> Any:
+    """Run length encoding layer.
+
+    Run length encoding takes a vector of values (the ``label`` aesthetic) and
+    calculates the lengths of consecutive repeated values, after ordering the
+    data on ``x``. Each run is rendered as a rectangle by default.
+
+    Parameters
+    ----------
+    mapping : Mapping, optional
+        Aesthetic mapping. Requires ``x`` and ``label``.
+    data : DataFrame or callable, optional
+        Layer data.
+    geom : str, optional
+        Geom to use. Defaults to ``"rect"``.
+    position : str, optional
+        Position adjustment. Defaults to ``"identity"``.
+    align : {'none', 'centre', 'center', 'start', 'end'}, optional
+        Effects the computed ``start`` and ``end`` variables. ``"center"`` is
+        normalised to ``"centre"``. Defaults to ``"none"``.
+    na_rm : bool, optional
+        If ``False`` (default), missing values are removed with a warning.
+    orientation : {'x', 'y'}, optional
+        Orientation of the stat. Defaults to ``"x"``.
+    show_legend : bool, optional
+        Whether to show a legend for this layer.
+    inherit_aes : bool, optional
+        Whether to inherit aesthetics from the plot. Defaults to ``True``.
+    **kwargs : Any
+        Additional parameters passed to the layer.
+
+    Returns
+    -------
+    Layer
+        A ggplot2_py layer.
+    """
+    align = arg_match0(align, ["none", "centre", "center", "start", "end"], "align")
+    if align == "center":
+        align = "centre"
+
+    params: Dict[str, Any] = {
+        "na_rm": na_rm,
+        "orientation": orientation,
+        "align": align,
+    }
+    params.update(kwargs)
+
+    return layer(
+        data=data,
+        mapping=mapping,
+        stat=StatRle,
+        geom=geom,
+        position=position,
+        show_legend=show_legend,
+        inherit_aes=inherit_aes,
+        params=params,
+    )

ggh4x/stat_rollingkernel.py

@@ -0,0 +1,369 @@
+"""Rolling-kernel smoother stat.
+
+Python port of ``stat_roll.R`` from the R package **ggh4x**
+(``StatRollingkernel`` ggproto object, the ``stat_rollingkernel`` constructor,
+and the three kernel helpers ``.kernel_norm`` / ``.kernel_unif`` /
+``.kernel_cauchy``).
+
+A rolling kernel moves along one of the axes and assigns weights to datapoints
+depending on the distance to the kernel's location. It then computes a weighted
+average of the y-values, creating a trendline. Unlike a (weighted) rolling
+average, the spacing between datapoints need not be constant.
+
+The computation follows the R source verbatim:
+
+#. ``flip_data`` the input when ``orientation == "y"``.
+#. Resolve the bandwidth: a :class:`~ggplot2_py.Rel` object becomes
+   ``bw.value * diff(range(x))``; a string names one of the ``stats::bw.*``
+   rules (delegated to :func:`ggplot2_py.stat._precompute_bw`).
+#. Drop non-finite ``x``/``y`` rows.
+#. Build an evaluation sequence of length ``n`` spanning
+   ``mid +/- (1 + expand) * 0.5 * diff(range(x))``.
+#. Form the outer difference matrix ``outer(x, seq, "-")``, apply the kernel,
+   column-normalize by ``colSums`` (this yields ``NaN`` columns where the kernel
+   has zero total weight, exactly as in R), multiply by ``y`` and sum down the
+   columns to obtain the smoothed value.
+#. ``flip_data`` the result back.
+
+The kernels mirror ``stats::dnorm`` / ``stats::dunif`` / ``stats::dcauchy``
+through ``scipy.stats`` PDFs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+from ggplot2_py import Rel
+from ggplot2_py.layer import layer as _layer
+from ggplot2_py.stat import Stat, _flip_data, _precompute_bw
+
+from ._cli import cli_abort
+
+__all__ = [
+    "StatRollingkernel",
+    "stat_rollingkernel",
+    "_kernel_norm",
+    "_kernel_unif",
+    "_kernel_cauchy",
+]
+
+
+# ---------------------------------------------------------------------------
+# Kernels
+# ---------------------------------------------------------------------------
+
+def _kernel_norm(x: np.ndarray, bw: float) -> np.ndarray:
+    """Gaussian kernel.
+
+    Port of ``.kernel_norm <- function(x, bw) dnorm(x, sd = bw)``.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        Distances from the kernel location.
+    bw : float
+        Bandwidth, used as the standard deviation.
+
+    Returns
+    -------
+    numpy.ndarray
+        Relative weights, i.e. ``dnorm(x, sd = bw)``.
+    """
+    from scipy import stats as _st
+
+    return _st.norm.pdf(x, scale=bw)
+
+
+def _kernel_unif(x: np.ndarray, bw: float) -> np.ndarray:
+    """Uniform kernel.
+
+    Port of ``.kernel_unif <- function(x, bw) dunif(x, min = -0.5 * bw,
+    max = 0.5 * bw)``. Equivalent to a simple unweighted moving average.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        Distances from the kernel location.
+    bw : float
+        Bandwidth; the uniform support is ``[-0.5 * bw, 0.5 * bw]``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Relative weights, i.e. ``dunif(x, -0.5 * bw, 0.5 * bw)``.
+    """
+    from scipy import stats as _st
+
+    # scipy's ``uniform`` is parameterised by (loc, scale) == (min, max - min).
+    # Its support is the closed interval [loc, loc + scale], matching R's
+    # ``dunif`` which returns 1/(max-min) at both endpoints.
+    return _st.uniform.pdf(x, loc=-0.5 * bw, scale=bw)
+
+
+def _kernel_cauchy(x: np.ndarray, bw: float) -> np.ndarray:
+    """Cauchy kernel.
+
+    Port of ``.kernel_cauchy <- function(x, bw) dcauchy(x, scale = bw)``. The
+    Cauchy distribution has fatter tails than the normal distribution.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        Distances from the kernel location.
+    bw : float
+        Bandwidth, used as the scale parameter (location fixed at 0).
+
+    Returns
+    -------
+    numpy.ndarray
+        Relative weights, i.e. ``dcauchy(x, scale = bw)``.
+    """
+    from scipy import stats as _st
+
+    return _st.cauchy.pdf(x, scale=bw)
+
+
+# Mapping from R ``switch`` kernel names to the callable kernels.
+_KERNEL_LOOKUP: Dict[str, Callable[[np.ndarray, float], np.ndarray]] = {
+    "gaussian": _kernel_norm,
+    "norm": _kernel_norm,
+    "unif": _kernel_unif,
+    "mean": _kernel_unif,
+    "cauchy": _kernel_cauchy,
+}
+
+
+# ---------------------------------------------------------------------------
+# ggproto
+# ---------------------------------------------------------------------------
+
+class StatRollingkernel(Stat):
+    """Rolling-kernel smoother (port of ``StatRollingkernel``).
+
+    Computed variables
+    ------------------
+    x : float
+        A sequence of ordered x positions.
+    y : float
+        The weighted value of the rolling kernel.
+    weight : float
+        The sum of weight strengths at a position.
+    scaled : float
+        ``weight / sum(weight)`` by group.
+    """
+
+    required_aes = ["x", "y"]
+    extra_params = ["na_rm", "orientation"]
+
+    def setup_params(
+        self, data: pd.DataFrame, params: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Resolve orientation and the kernel callable.
+
+        Mirrors the R ``setup_params`` (which carries an unused third
+        ``scales`` argument). Sets ``flipped_aes`` from ``orientation`` and
+        resolves a string ``kernel`` into a callable.
+
+        Parameters
+        ----------
+        data : pandas.DataFrame
+            Layer data (unused, kept for signature parity).
+        params : dict
+            Layer parameters.
+
+        Returns
+        -------
+        dict
+            Updated parameters with ``flipped_aes`` set and ``kernel``
+            resolved to a callable.
+
+        Raises
+        ------
+        Exception
+            Via :func:`ggh4x._cli.cli_abort` if the kernel name is unknown.
+        """
+        params["flipped_aes"] = params.get("orientation") == "y"
+        kernel = params.get("kernel")
+        if isinstance(kernel, str):
+            resolved = _KERNEL_LOOKUP.get(kernel)
+            if resolved is None:
+                cli_abort(f"Unknown kernel specification: {kernel}.")
+            params["kernel"] = resolved
+        return params
+
+    def compute_group(
+        self,
+        data: pd.DataFrame,
+        scales: Any,
+        n: int = 256,
+        bw: Any = 0.02,
+        expand: float = 0,
+        kernel: Callable[[np.ndarray, float], np.ndarray] = _kernel_norm,
+        flipped_aes: bool = False,
+    ) -> pd.DataFrame:
+        """Compute the rolling-kernel trendline for one group.
+
+        Parameters
+        ----------
+        data : pandas.DataFrame
+            Group data with at least ``x`` and ``y`` columns.
+        scales : Any
+            Panel scales (unused).
+        n : int, default 256
+            Number of evaluation points to return.
+        bw : float, str, or ggplot2_py.Rel, default 0.02
+            Bandwidth. A :class:`~ggplot2_py.Rel` becomes
+            ``bw.value * diff(range(x))``; a string names a ``bw.*`` rule.
+        expand : float, default 0
+            Fraction by which to expand the evaluation range beyond the data.
+        kernel : callable, default :func:`_kernel_norm`
+            Kernel ``f(distances, bw) -> weights``.
+        flipped_aes : bool, default False
+            Whether x/y are swapped (orientation ``"y"``).
+
+        Returns
+        -------
+        pandas.DataFrame
+            Columns ``x``, ``y``, ``weight`` and ``scaled`` (flipped back when
+            ``flipped_aes`` is true).
+        """
+        data = _flip_data(data, flipped_aes)
+
+        x_full = np.asarray(data["x"], dtype=float)
+
+        # -- Resolve bandwidth -------------------------------------------------
+        if isinstance(bw, Rel):
+            bw = bw.value * (np.nanmax(x_full) - np.nanmin(x_full))
+        elif isinstance(bw, str):
+            # ``_precompute_bw`` maps nrd0/nrd/sj/sj-ste/sj-dpi/ucv/bcv.
+            lname = bw.lower()
+            if lname not in ("nrd0", "nrd", "ucv", "bcv", "sj", "sj-ste", "sj-dpi"):
+                cli_abort(f"Unknown bandwidth rule: {bw}.")
+            bw = _precompute_bw(x_full, lname)
+        bw = float(bw)
+
+        # -- Drop non-finite rows ---------------------------------------------
+        x = np.asarray(data["x"], dtype=float)
+        y = np.asarray(data["y"], dtype=float)
+        keep = np.isfinite(x) & np.isfinite(y)
+        x = x[keep]
+        y = y[keep]
+
+        # -- Evaluation sequence ----------------------------------------------
+        lo = float(np.min(x))
+        hi = float(np.max(x))
+        mid = (lo + hi) / 2.0
+        half = (1.0 + expand) * (0.5 * (hi - lo))
+        seq_range = np.linspace(mid - half, mid + half, int(n))
+
+        # -- Kernel-weighted average ------------------------------------------
+        # krnl[i, j] = x[i] - seq_range[j]   (R: outer(data$x, seq_range, "-"))
+        krnl = x[:, None] - seq_range[None, :]
+        krnl = kernel(krnl, bw)
+        krnl = np.asarray(krnl, dtype=float)
+
+        # weight = colSums(krnl); column-normalise (0/0 -> NaN, as in R).
+        with np.errstate(divide="ignore", invalid="ignore"):
+            weight = krnl.sum(axis=0)
+            krnl = krnl / weight[None, :]
+        krnl = krnl * y[:, None]
+        y_out = krnl.sum(axis=0)
+
+        with np.errstate(divide="ignore", invalid="ignore"):
+            scaled = weight / weight.sum()
+
+        out = pd.DataFrame(
+            {
+                "x": seq_range,
+                "y": y_out,
+                "weight": weight,
+                "scaled": scaled,
+            }
+        )
+        return _flip_data(out, flipped_aes)
+
+
+# ---------------------------------------------------------------------------
+# Constructor
+# ---------------------------------------------------------------------------
+
+def stat_rollingkernel(
+    mapping: Optional[Any] = None,
+    data: Any = None,
+    geom: str = "line",
+    position: str = "identity",
+    *,
+    bw: Any = "nrd",
+    kernel: Any = "gaussian",
+    n: int = 256,
+    expand: float = 0.1,
+    na_rm: bool = False,
+    orientation: str = "x",
+    show_legend: Optional[bool] = None,
+    inherit_aes: bool = True,
+    **kwargs: Any,
+) -> Any:
+    """Rolling-kernel trendline layer.
+
+    A rolling kernel moves along one of the axes, assigns distance-based
+    weights to datapoints and computes a weighted average of the y-values,
+    producing a trendline.
+
+    Parameters
+    ----------
+    mapping : aes, optional
+        Aesthetic mapping.
+    data : DataFrame or callable, optional
+        Layer data.
+    geom : str, default ``"line"``
+        Geom used to draw the trendline.
+    position : str, default ``"identity"``
+        Position adjustment.
+    bw : float, str, or ggplot2_py.Rel, default ``"nrd"``
+        Bandwidth. One of: a numeric kernel width in data units; a
+        :class:`~ggplot2_py.Rel` for a width relative to the group data range;
+        or a string naming one of the ``stats::bw.nrd`` family of rules.
+    kernel : str or callable, default ``"gaussian"``
+        Either a callable ``f(distances, bw) -> weights`` or one of
+        ``"gaussian"``/``"norm"``, ``"unif"``/``"mean"`` or ``"cauchy"``.
+    n : int, default 256
+        Number of points to return per group.
+    expand : float, default 0.1
+        How much to expand the evaluation range beyond the extreme datapoints.
+    na_rm : bool, default False
+        Whether to silently remove missing values.
+    orientation : str, default ``"x"``
+        Axis along which the rolling occurs, either ``"x"`` or ``"y"``.
+    show_legend : bool, optional
+        Whether to show a legend.
+    inherit_aes : bool, default True
+        Whether to inherit aesthetics from the plot.
+    **kwargs
+        Additional parameters passed to the layer.
+
+    Returns
+    -------
+    Layer
+        A ggplot2 layer ggproto object.
+    """
+    return _layer(
+        data=data,
+        mapping=mapping,
+        stat=StatRollingkernel,
+        geom=geom,
+        position=position,
+        show_legend=show_legend,
+        inherit_aes=inherit_aes,
+        params={
+            "bw": bw,
+            "kernel": kernel,
+            "n": n,
+            "expand": expand,
+            "na_rm": na_rm,
+            "orientation": orientation,
+            **kwargs,
+        },
+    )