ggh4x-python 0.3.1.9000__py3-none-any.whl

ggh4x/_borrowed_ggplot2.py

@@ -0,0 +1,273 @@
+"""ggplot2-internal helpers borrowed by ggh4x (R source: borrowed_ggplot2.R).
+
+These are ggplot2 internals that ggh4x copies because they are not exported. Only the ones
+ggh4x actually uses for facet layout / strip assembly are ported here; the rest are sourced
+from ``ggplot2_py`` where available. The crown jewel is ``id``/``id_var`` — the radix-based
+panel-id assignment that defines facet panel ordering. Ported verbatim and verified against R.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Sequence
+
+import numpy as np
+import pandas as pd
+
+__all__ = [
+    "id_var",
+    "id",
+    "empty",
+    "is_zero",
+    "snake_class",
+    "ulevels",
+    "unique_combs",
+]
+
+
+def _is_factor(x: Any) -> bool:
+    return isinstance(x, pd.Categorical) or (
+        isinstance(x, pd.Series) and isinstance(x.dtype, pd.CategoricalDtype)
+    )
+
+
+def id_var(x: Sequence[Any], drop: bool = False) -> np.ndarray:
+    """Assign integer ids to a single variable, mirroring ggplot2's ``id_var``.
+
+    Parameters
+    ----------
+    x : sequence
+        A vector (optionally a pandas Categorical/factor).
+    drop : bool
+        If ``True``, drop unused factor levels before id assignment.
+
+    Returns
+    -------
+    np.ndarray
+        1-based integer ids with an attached ``n`` (number of distinct values) accessible
+        via ``result.n`` (set as an attribute on the returned ndarray subclass).
+    """
+    if len(x) == 0:
+        out = _IdArray(np.array([], dtype=int))
+        out.n = 0
+        return out
+    if _is_factor(x) and not drop:
+        cat = x if isinstance(x, pd.Categorical) else pd.Categorical(x)
+        levels = list(cat.categories)
+        codes = cat.codes.astype(int)
+        has_na = bool((codes < 0).any())
+        # addNA(x, ifany=TRUE): NA becomes an extra level if present
+        if has_na:
+            ids = np.where(codes < 0, len(levels) + 1, codes + 1)
+            n = len(levels) + 1
+        else:
+            ids = codes + 1
+            n = len(levels)
+        out = _IdArray(ids.astype(int))
+        out.n = n
+        return out
+    # else branch: drop=True (including factors) or non-factor.
+    # R: levels <- sort(unique0(x), na.last = TRUE); id <- match(x, levels).
+    # For a FACTOR, R's sort() orders by LEVEL order (NOT alphabetical) and
+    # keeps only present values (unique0); na.last puts NA at the end.  Earlier
+    # this branch always used np.sort, which alphabetised factor levels and so
+    # mis-ordered facet PANEL/ROW/COL for non-alphabetical factor levels.
+    s = pd.Series(list(x))
+    has_na = bool(s.isna().any())
+    if _is_factor(x):
+        cat = x if isinstance(x, pd.Categorical) else pd.Categorical(x)
+        present = {int(c) for c in np.asarray(cat.codes) if c >= 0}
+        levels = [
+            cat.categories[k] for k in range(len(cat.categories)) if k in present
+        ]
+    else:
+        uniq = pd.unique(s.dropna())
+        levels = list(np.sort(uniq)) if len(uniq) else []
+    level_list = list(levels) + ([np.nan] if has_na else [])
+    lookup = {v: i + 1 for i, v in enumerate(levels)}
+    na_id = len(levels) + 1 if has_na else 0
+    ids = np.array([na_id if pd.isna(v) else lookup[v] for v in s], dtype=int)
+    out = _IdArray(ids)
+    out.n = int(len(level_list))
+    return out
+
+
+class _IdArray(np.ndarray):
+    """ndarray carrying an ``n`` attribute (R's ``attr(id, 'n')``)."""
+
+    n: int
+
+    def __new__(cls, input_array: np.ndarray) -> "_IdArray":
+        obj = np.asarray(input_array, dtype=int).view(cls)
+        obj.n = 0
+        return obj
+
+    def __array_finalize__(self, obj: Any) -> None:
+        if obj is None:
+            return
+        self.n = getattr(obj, "n", 0)
+
+
+def id(variables: pd.DataFrame | Sequence[Any], drop: bool = False) -> _IdArray:
+    """Compute a unique id per row across multiple variables, mirroring ggplot2's ``id``.
+
+    Uses radix mixing: variables are reversed (so the first varies slowest), each is
+    id-coded, and ids are combined as ``sum((id_i - 1) * cumprod(n_{<i})) + 1``. This is
+    what determines facet ``PANEL`` ordering.
+
+    Parameters
+    ----------
+    variables : pandas.DataFrame or sequence of vectors
+        The faceting variables (columns).
+    drop : bool
+        Drop unused combinations.
+
+    Returns
+    -------
+    _IdArray
+        1-based row ids with ``.n`` = number of distinct combinations.
+    """
+    if isinstance(variables, pd.DataFrame):
+        nrows = len(variables)
+        cols = [variables[c] for c in variables.columns]
+    else:
+        nrows = None
+        cols = list(variables)
+    cols = [c for c in cols if len(c) > 0]
+    if len(cols) == 0:
+        n = nrows if nrows is not None else 0
+        out = _IdArray(np.arange(1, n + 1))
+        out.n = n
+        return out
+    if len(cols) == 1:
+        return id_var(cols[0], drop=drop)
+    ids = [id_var(c, drop=drop) for c in cols][::-1]  # rev()
+    ndistinct = np.array([i.n for i in ids], dtype=float)
+    n = int(np.prod(ndistinct))
+    p = len(ids)
+    combs = np.concatenate([[1.0], np.cumprod(ndistinct[: p - 1])])
+    mat = np.column_stack([np.asarray(i, dtype=float) for i in ids])
+    res = ((mat - 1.0) @ combs + 1.0).astype(int)
+    if drop:
+        return id_var(res, drop=True)
+    out = _IdArray(res)
+    out.n = n
+    return out
+
+
+def empty(df: Any) -> bool:
+    """Test whether a data frame is "empty", mirroring ggplot2's ``empty``.
+
+    Parameters
+    ----------
+    df : Any
+
+    Returns
+    -------
+    bool
+        ``True`` if *df* is ``None`` or has zero rows or zero columns.
+    """
+    if df is None:
+        return True
+    if isinstance(df, pd.DataFrame):
+        return df.shape[0] == 0 or df.shape[1] == 0
+    return False
+
+
+def is_zero(x: Any) -> bool:
+    """Test for a zero/empty grob, mirroring ggplot2's ``is.zero``.
+
+    Parameters
+    ----------
+    x : Any
+
+    Returns
+    -------
+    bool
+        ``True`` if *x* is ``None`` or a zeroGrob/null grob.
+    """
+    if x is None:
+        return True
+    cls = type(x).__name__
+    return cls in ("ZeroGrob", "zeroGrob", "NullGrob") or getattr(x, "_grid_class", None) in (
+        "zeroGrob",
+        "null",
+    )
+
+
+def snake_class(x: Any) -> str:
+    """Convert a class name to snake_case, mirroring ggplot2's ``snake_class``.
+
+    Parameters
+    ----------
+    x : Any
+        An object (its first class name is used) or a class-name string.
+
+    Returns
+    -------
+    str
+        e.g. ``FacetGrid2`` -> ``facet_grid2``.
+    """
+    import re
+
+    name = x if isinstance(x, str) else type(x).__name__
+    name = re.sub(r"([A-Za-z])([A-Z])([a-z])", r"\1_\2\3", name)
+    name = name.replace(".", "_")
+    name = re.sub(r"([a-z])([A-Z])", r"\1_\2", name)
+    return name.lower()
+
+
+def ulevels(x: Sequence[Any]) -> np.ndarray:
+    """Unique sorted levels (NA included for factors), mirroring ggplot2's ``ulevels``.
+
+    Parameters
+    ----------
+    x : sequence
+
+    Returns
+    -------
+    np.ndarray
+    """
+    if _is_factor(x):
+        cat = x if isinstance(x, pd.Categorical) else pd.Categorical(x)
+        levels = list(cat.categories)
+        # R addNA(x, ifany=TRUE): add an <NA> level when an NA value is present.
+        if bool((np.asarray(cat.codes) < 0).any()):
+            return np.asarray(levels + [np.nan], dtype=object)
+        return np.asarray(levels)
+    s = pd.Series(list(x))
+    uniq = pd.unique(s.dropna())
+    sorted_uniq = np.sort(uniq) if len(uniq) else np.array([])
+    # R sort(..., na.last = TRUE): keep NA as the last level when present.
+    if bool(s.isna().any()):
+        return np.asarray(list(sorted_uniq) + [np.nan], dtype=object)
+    return sorted_uniq
+
+
+def unique_combs(df: pd.DataFrame) -> pd.DataFrame:
+    """All unique combinations of the columns' levels, mirroring ggplot2's ``unique_combs``.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+
+    Returns
+    -------
+    pandas.DataFrame
+        Cross-product of per-column ``ulevels``.  Mirrors R
+        ``rev(expand.grid(rev(unique_values)))``: the FIRST column varies
+        slowest and the last varies fastest, and NA levels are included.
+    """
+    if df.shape[1] == 0:
+        return pd.DataFrame()
+    level_lists = {c: ulevels(df[c]) for c in df.columns}
+    cols = list(df.columns)
+    from itertools import product
+
+    # itertools.product varies its first argument slowest -> first column
+    # slowest, matching R's rev(expand.grid(rev(...))).
+    rows = list(product(*[level_lists[c] for c in cols]))
+    data = {c: [] for c in cols}
+    for combo in rows:
+        for c, v in zip(cols, combo):
+            data[c].append(v)
+    return pd.DataFrame(data)[cols]

ggh4x/_cli.py

@@ -0,0 +1,84 @@
+"""cli message shims (R source: cli package usage in ggh4x).
+
+ggh4x calls ``cli::cli_abort`` / ``cli::cli_warn`` / ``cli::cli_inform`` for user-facing
+messages. The Python port maps these to standard exceptions / ``warnings`` so failures stay
+loud (per the error-handling discipline) while stripping cli's ``{.arg}`` glue markup.
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+from typing import NoReturn, Type
+
+__all__ = ["cli_abort", "cli_warn", "cli_inform", "strip_cli_markup"]
+
+# cli inline-markup spans like {.arg foo}, {.code x}, {.field y}, {.val 3}, {.cls C}.
+_CLI_SPAN = re.compile(r"\{\.[a-zA-Z_]+\s+([^{}]*)\}")
+# Leftover interpolation braces {x} -> x (we cannot evaluate R glue, just unwrap).
+_CLI_BRACE = re.compile(r"\{([^{}]*)\}")
+
+
+def strip_cli_markup(message: str) -> str:
+    """Remove cli inline-markup so a plain message remains.
+
+    Parameters
+    ----------
+    message : str
+        A message possibly containing cli markup such as ``{.arg x}``.
+
+    Returns
+    -------
+    str
+        The message with markup spans replaced by their content.
+    """
+    prev = None
+    out = message
+    while prev != out:
+        prev = out
+        out = _CLI_SPAN.sub(r"\1", out)
+    out = _CLI_BRACE.sub(r"\1", out)
+    return out
+
+
+def cli_abort(message: str, error_class: Type[Exception] = ValueError) -> NoReturn:
+    """Raise an exception, mirroring ``cli::cli_abort``.
+
+    Parameters
+    ----------
+    message : str
+        Error message (cli markup is stripped).
+    error_class : type[Exception]
+        Exception type to raise (default ``ValueError``; pass ``TypeError`` where the R
+        error is about an input type).
+
+    Raises
+    ------
+    Exception
+        Always raises *error_class*.
+    """
+    raise error_class(strip_cli_markup(message))
+
+
+def cli_warn(message: str, category: Type[Warning] = UserWarning) -> None:
+    """Emit a warning, mirroring ``cli::cli_warn``.
+
+    Parameters
+    ----------
+    message : str
+        Warning message (cli markup is stripped).
+    category : type[Warning]
+        Warning category (default ``UserWarning``).
+    """
+    warnings.warn(strip_cli_markup(message), category, stacklevel=2)
+
+
+def cli_inform(message: str) -> None:
+    """Print an informational message, mirroring ``cli::cli_inform``.
+
+    Parameters
+    ----------
+    message : str
+        Message to print (cli markup is stripped).
+    """
+    print(strip_cli_markup(message))

ggh4x/_datasets.py

@@ -0,0 +1,106 @@
+"""Dataset loaders for tutorials/tests (R source: base ``datasets`` + ggplot2 datasets).
+
+ggh4x bundles no data; its vignettes use standard R datasets. This module loads the
+base-R datasets (bundled as CSVs in ``ggh4x/resources/``) and re-exports the ggplot2
+datasets from ``ggplot2_py`` so tutorial/validation code is self-contained and R-faithful.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+
+import numpy as np
+import pandas as pd
+
+__all__ = [
+    "load_iris",
+    "load_mtcars",
+    "load_faithful",
+    "load_pressure",
+    "load_volcano",
+    "mpg",
+    "diamonds",
+    "economics",
+]
+
+
+def _resource_path(filename: str):
+    return resources.files("ggh4x.resources").joinpath(filename)
+
+
+def load_iris() -> pd.DataFrame:
+    """Load the ``iris`` dataset (150x5), mirroring base R.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns ``Sepal.Length``, ``Sepal.Width``, ``Petal.Length``, ``Petal.Width``,
+        ``Species`` (``Species`` as a category).
+    """
+    with resources.as_file(_resource_path("iris.csv")) as p:
+        df = pd.read_csv(p)
+    df["Species"] = pd.Categorical(df["Species"])
+    return df
+
+
+def load_mtcars() -> pd.DataFrame:
+    """Load the ``mtcars`` dataset (32x11), mirroring base R.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Model name is the index (matching R rownames); 11 numeric columns.
+    """
+    with resources.as_file(_resource_path("mtcars.csv")) as p:
+        df = pd.read_csv(p, index_col=0)
+    df.index.name = "model"
+    return df
+
+
+def load_faithful() -> pd.DataFrame:
+    """Load the ``faithful`` dataset (272x2), mirroring base R.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns ``eruptions`` and ``waiting``.
+    """
+    with resources.as_file(_resource_path("faithful.csv")) as p:
+        return pd.read_csv(p)
+
+
+def load_pressure() -> pd.DataFrame:
+    """Load the ``pressure`` dataset (19x2), mirroring base R.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns ``temperature`` and ``pressure``.
+    """
+    with resources.as_file(_resource_path("pressure.csv")) as p:
+        return pd.read_csv(p)
+
+
+def load_volcano() -> np.ndarray:
+    """Load the ``volcano`` matrix (87x61), mirroring base R.
+
+    Returns
+    -------
+    numpy.ndarray
+        Topographic heights as a float array.
+    """
+    with resources.as_file(_resource_path("volcano.csv")) as p:
+        return pd.read_csv(p, header=None).to_numpy(dtype=float)
+
+
+def _ggplot2_dataset(name: str) -> pd.DataFrame:
+    from ggplot2_py import datasets as _ds
+
+    return getattr(_ds, name)
+
+
+# ggplot2 datasets re-exported from ggplot2_py (loaded lazily on attribute access).
+def __getattr__(name: str):  # pragma: no cover - thin re-export
+    if name in ("mpg", "diamonds", "economics"):
+        return _ggplot2_dataset(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

ggh4x/_download.py

@@ -0,0 +1,111 @@
+"""Transparent download and caching for remote data assets."""
+
+import hashlib
+import sys
+import urllib.request
+from pathlib import Path
+
+from ._registry import CACHE_DIR_NAME, DATA_DIR_NAME, REGISTRY
+
+__all__ = ["resolve_data_path"]
+
+# <pkg>-python/<import_name>/_download.py  →  parent.parent = <pkg>-python/
+_PKG_ROOT = Path(__file__).resolve().parent.parent
+
+
+def resolve_data_path(filename: str) -> Path:
+    """Resolve a remote data asset to a local file path.
+
+    Resolution order:
+
+    1. ``<work_dir>/<DATA_DIR_NAME>/<filename>``  — local staging copy
+    2. ``~/.cache/<CACHE_DIR_NAME>/<filename>``  — previously downloaded
+    3. Download from registry URL → save to cache
+
+    Parameters
+    ----------
+    filename : str
+        Filename as registered in ``REGISTRY``.
+
+    Returns
+    -------
+    Path
+        Absolute path to the resolved local file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file cannot be resolved from any source.
+    """
+    # 1. local staging dir (sibling of <pkg>-python/)
+    local = _PKG_ROOT.parent / DATA_DIR_NAME / filename
+    if local.exists():
+        return local
+
+    # 2. cache
+    cache_dir = Path.home() / ".cache" / CACHE_DIR_NAME
+    cached = cache_dir / filename
+    if cached.exists():
+        return cached
+
+    # 3. download
+    if filename not in REGISTRY:
+        raise FileNotFoundError(
+            f"\'{filename}\' not found locally and not in registry.\n"
+            f"Place it in: {local}"
+        )
+
+    entry = REGISTRY[filename]
+    url = entry.get("url")
+    if not url:
+        raise FileNotFoundError(
+            f"\'{filename}\' has no download URL in registry.\n"
+            f"Place it manually in: {local}"
+        )
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    _download(url, cached)
+    _verify_sha256(cached, entry.get("sha256"))
+    return cached
+
+
+def _download(url: str, dest: Path) -> None:
+    """Stream-download *url* to *dest* with progress."""
+    print(f"Downloading {dest.name} …", file=sys.stderr, flush=True)
+    with urllib.request.urlopen(url) as resp:
+        total = int(resp.headers.get("Content-Length", 0))
+        received = 0
+        with open(dest, "wb") as fout:
+            while True:
+                chunk = resp.read(1 << 16)  # 64 KiB
+                if not chunk:
+                    break
+                fout.write(chunk)
+                received += len(chunk)
+                if total:
+                    pct = received * 100 // total
+                    print(
+                        f"\r  {received / 1e6:.1f}/{total / 1e6:.1f} MB ({pct}%)",
+                        end="",
+                        file=sys.stderr,
+                        flush=True,
+                    )
+    if total:
+        print(file=sys.stderr)
+
+
+def _verify_sha256(path: Path, expected: str | None) -> None:
+    """Check SHA-256; delete file and raise on mismatch."""
+    if not expected:
+        return
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 16), b""):
+            h.update(chunk)
+    actual = h.hexdigest()
+    if actual != expected:
+        path.unlink(missing_ok=True)
+        raise RuntimeError(
+            f"SHA-256 mismatch for {path.name}: "
+            f"expected {expected[:16]}…, got {actual[:16]}…"
+        )