ggh4x-python 0.3.1.9000__py3-none-any.whl

ggh4x/_utils.py

@@ -0,0 +1,150 @@
+"""Small internal utilities (R source: utils.R, utils_grid.R).
+
+Grob/unit measurement helpers used by strip and facet assembly. These delegate to grid_py's
+snake_case conversion API.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+import numpy as np
+
+from ._cli import cli_abort
+
+__all__ = [
+    "width_cm",
+    "height_cm",
+    "seq_range",
+    "has_null_unit",
+]
+
+
+def _is_grob(x: Any) -> bool:
+    from grid_py import is_grob
+
+    return bool(is_grob(x))
+
+
+def _is_unit(x: Any) -> bool:
+    from grid_py import is_unit
+
+    return bool(is_unit(x))
+
+
+def width_cm(x: Any) -> float | np.ndarray | List[Any]:
+    """Width in cm of a grob, unit, or list thereof, mirroring ``utils.R::width_cm``.
+
+    Parameters
+    ----------
+    x : grob | unit | list
+        A grid grob, a unit object, or a list of either.
+
+    Returns
+    -------
+    float or numpy.ndarray or list
+        Width(s) in centimetres. A length-1 unit/grob collapses to a Python
+        ``float``; a multi-element unit returns a ``numpy.ndarray`` (one value
+        per element), matching R's vectorised ``convertWidth(..., valueOnly=TRUE)``.
+
+    Raises
+    ------
+    ValueError
+        If *x* is none of grob/unit/list.
+    """
+    from grid_py import convert_width, grob_width
+
+    if _is_grob(x):
+        return float(convert_width(grob_width(x), "cm", valueOnly=True))
+    if _is_unit(x):
+        vals = np.asarray(convert_width(x, "cm", valueOnly=True), dtype=float)
+        if vals.size == 1:
+            return float(vals.reshape(-1)[0])
+        return vals
+    if isinstance(x, (list, tuple)):
+        return [width_cm(e) for e in x]
+    cli_abort(f"Unknown input: {type(x).__name__}.")
+
+
+def height_cm(x: Any) -> float | np.ndarray | List[Any]:
+    """Height in cm of a grob, unit, or list thereof, mirroring ``utils.R::height_cm``.
+
+    Parameters
+    ----------
+    x : grob | unit | list
+        A grid grob, a unit object, or a list of either.
+
+    Returns
+    -------
+    float or numpy.ndarray or list
+        Height(s) in centimetres. A length-1 unit/grob collapses to a Python
+        ``float``; a multi-element unit returns a ``numpy.ndarray`` (one value
+        per element), matching R's vectorised ``convertHeight(..., valueOnly=TRUE)``.
+
+    Raises
+    ------
+    ValueError
+        If *x* is none of grob/unit/list.
+    """
+    from grid_py import convert_height, grob_height
+
+    if _is_grob(x):
+        return float(convert_height(grob_height(x), "cm", valueOnly=True))
+    if _is_unit(x):
+        vals = np.asarray(convert_height(x, "cm", valueOnly=True), dtype=float)
+        if vals.size == 1:
+            return float(vals.reshape(-1)[0])
+        return vals
+    if isinstance(x, (list, tuple)):
+        return [height_cm(e) for e in x]
+    cli_abort(f"Unknown input: {type(x).__name__}.")
+
+
+def seq_range(dat: Any, step: float | None = None, length_out: int | None = None) -> np.ndarray:
+    """Sequence over the data range, mirroring ``utils.R::seq_range`` (``seq.int(min, max, ...)``).
+
+    Parameters
+    ----------
+    dat : array-like
+        Values whose min/max bound the sequence (NA ignored).
+    step : float, optional
+        Step size (``by`` in R).
+    length_out : int, optional
+        Number of points (``length.out`` in R).
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    arr = np.asarray(dat, dtype=float)
+    lo = np.nanmin(arr)
+    hi = np.nanmax(arr)
+    if length_out is not None:
+        return np.linspace(lo, hi, length_out)
+    if step is not None:
+        return np.arange(lo, hi + step / 2.0, step)
+    # R seq_range = seq.int(min, max, ...); with no step/length it is the unit
+    # step sequence min, min+1, ..., <= max (NOT just the two endpoints).
+    return np.arange(lo, hi + 0.5, 1.0)
+
+
+def has_null_unit(x: Any) -> bool:
+    """Test whether a unit object contains any ``"null"`` units, mirroring ``has_null_unit``.
+
+    Parameters
+    ----------
+    x : unit
+        A grid unit (possibly compound/vector).
+
+    Returns
+    -------
+    bool
+    """
+    from grid_py import unit_type
+
+    if x is None:
+        return False
+    types = unit_type(x)
+    if isinstance(types, str):
+        return types == "null"
+    return "null" in list(types)

ggh4x/_vctrs.py

@@ -0,0 +1,233 @@
+"""vctrs shims (R source: vctrs usage in ggh4x).
+
+Faithful Python reimplementations of the small set of ``vec_*`` helpers ggh4x uses for
+data-frame and vector manipulation. Each mirrors the exact R semantics (ordering,
+run-length, recycling) verified against a live ``vctrs`` session.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Sequence
+
+import numpy as np
+import pandas as pd
+
+__all__ = [
+    "vec_interleave",
+    "vec_unrep",
+    "vec_rep_each",
+    "vec_match",
+    "vec_unique",
+    "vec_unique_count",
+    "vec_group_loc",
+    "vec_rbind",
+    "vec_recycle_common",
+    "data_frame0",
+]
+
+
+def vec_interleave(*args: Sequence[Any]) -> np.ndarray:
+    """Interleave vectors element-by-element, mirroring ``vctrs::vec_interleave``.
+
+    Parameters
+    ----------
+    *args : sequence
+        Vectors of length 1 or *n* (length-1 recycles; incompatible lengths
+        raise, matching R).
+
+    Returns
+    -------
+    np.ndarray
+        ``[a0, b0, ..., a1, b1, ...]`` order.
+    """
+    if not args:
+        return np.array([])
+    # R: vec_interleave recycles via vec_recycle_common — only length-1 vectors
+    # recycle; incompatible lengths ERROR (rather than silently cycling, which
+    # np.resize would do).
+    arrays = vec_recycle_common(*args)
+    if not arrays or len(arrays[0]) == 0:
+        return np.array([])
+    return np.stack(arrays, axis=1).reshape(-1)
+
+
+def vec_unrep(x: Sequence[Any]) -> pd.DataFrame:
+    """Run-length encode, mirroring ``vctrs::vec_unrep``.
+
+    Parameters
+    ----------
+    x : sequence
+        Input vector.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns ``key`` (the run values, in order) and ``times`` (run lengths).
+    """
+    arr = np.asarray(x, dtype=object)
+    n = len(arr)
+    if n == 0:
+        return pd.DataFrame({"key": pd.Series([], dtype=object), "times": pd.Series([], dtype=int)})
+    # boundaries where the value changes
+    change = np.empty(n, dtype=bool)
+    change[0] = True
+    change[1:] = arr[1:] != arr[:-1]
+    idx = np.flatnonzero(change)
+    keys = arr[idx]
+    times = np.diff(np.append(idx, n))
+    return pd.DataFrame({"key": keys, "times": times.astype(int)})
+
+
+def vec_rep_each(x: Sequence[Any], times: Sequence[int] | int) -> np.ndarray:
+    """Repeat each element *times[i]* times, mirroring ``vctrs::vec_rep_each``.
+
+    Parameters
+    ----------
+    x : sequence
+        Values to repeat.
+    times : sequence of int or int
+        Per-element repeat counts (or a scalar applied to all).
+
+    Returns
+    -------
+    np.ndarray
+        Expanded vector.
+    """
+    arr = np.asarray(x)
+    return np.repeat(arr, times)
+
+
+def vec_match(needles: Sequence[Any], haystack: Sequence[Any]) -> np.ndarray:
+    """First-match index of *needles* in *haystack*, mirroring ``vctrs::vec_match``.
+
+    Parameters
+    ----------
+    needles : sequence
+        Values to look up.
+    haystack : sequence
+        Table of unique-or-not reference values.
+
+    Returns
+    -------
+    np.ndarray
+        0-based indices of the first match (or -1 when absent). NB: R returns 1-based or
+        ``NA``; callers that need R indices add 1.
+    """
+    # R vec_match: first match, and it tolerates a DUPLICATED haystack
+    # (pd.Index.get_indexer raises on a non-unique index).  NA matches NA;
+    # absent -> -1 (R returns NA; -1 is this port's documented sentinel).
+    first_pos: dict = {}
+    na_pos = -1
+    for i, v in enumerate(haystack):
+        if pd.isna(v):
+            if na_pos == -1:
+                na_pos = i
+        elif v not in first_pos:
+            first_pos[v] = i
+    out = [(na_pos if pd.isna(nd) else first_pos.get(nd, -1)) for nd in needles]
+    return np.array(out, dtype=int)
+
+
+def vec_unique(x: Sequence[Any]) -> np.ndarray:
+    """Unique values preserving first-appearance order, mirroring ``vctrs::vec_unique``.
+
+    Parameters
+    ----------
+    x : sequence
+
+    Returns
+    -------
+    np.ndarray
+    """
+    return pd.unique(pd.Series(list(x)))
+
+
+def vec_unique_count(x: Sequence[Any]) -> int:
+    """Number of unique values, mirroring ``vctrs::vec_unique_count``.
+
+    Parameters
+    ----------
+    x : sequence
+
+    Returns
+    -------
+    int
+    """
+    return int(len(vec_unique(x)))
+
+
+def vec_group_loc(x: Sequence[Any]) -> pd.DataFrame:
+    """Group rows by value, mirroring ``vctrs::vec_group_loc``.
+
+    Parameters
+    ----------
+    x : sequence
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns ``key`` (first-appearance order) and ``loc`` (0-based row indices per group).
+    """
+    s = pd.Series(list(x))
+    keys = pd.unique(s)
+    loc = [np.flatnonzero((s == k).to_numpy()) for k in keys]
+    return pd.DataFrame({"key": list(keys), "loc": loc})
+
+
+def vec_rbind(*frames: pd.DataFrame) -> pd.DataFrame:
+    """Row-bind data frames filling missing columns, mirroring ``vctrs::vec_rbind``.
+
+    Parameters
+    ----------
+    *frames : pandas.DataFrame
+
+    Returns
+    -------
+    pandas.DataFrame
+        Column union; absent columns filled with ``NA``; row index reset.
+    """
+    frames = [f for f in frames if f is not None and len(f.columns) > 0]
+    if not frames:
+        return pd.DataFrame()
+    return pd.concat(frames, axis=0, ignore_index=True, sort=False)
+
+
+def vec_recycle_common(*args: Sequence[Any]) -> List[np.ndarray]:
+    """Recycle vectors to a common length, mirroring ``vctrs::vec_recycle_common``.
+
+    Parameters
+    ----------
+    *args : sequence
+        Vectors of length 1 or *n*.
+
+    Returns
+    -------
+    list of np.ndarray
+        All recycled to the common length *n*.
+
+    Raises
+    ------
+    ValueError
+        If lengths are incompatible (not 1 and not *n*).
+    """
+    arrays = [np.asarray(a) for a in args]
+    lengths = {len(a) for a in arrays if len(a) != 1}
+    if len(lengths) > 1:
+        raise ValueError(f"Incompatible lengths for recycling: {sorted(lengths)}")
+    n = lengths.pop() if lengths else (len(arrays[0]) if arrays else 0)
+    return [np.resize(a, n) if len(a) == 1 else a for a in arrays]
+
+
+def data_frame0(**columns: Any) -> pd.DataFrame:
+    """Construct a DataFrame, mirroring ggh4x's ``data_frame0`` (minimal name repair).
+
+    Parameters
+    ----------
+    **columns : Any
+        Column name -> values.
+
+    Returns
+    -------
+    pandas.DataFrame
+    """
+    return pd.DataFrame(columns)