ggplot2-python 4.0.2.9000__py3-none-any.whl

ggplot2_py/guides/__init__.py

@@ -0,0 +1,8 @@
+"""
+Guides sub-package for ggplot2_py.
+
+Re-exports all public names from :mod:`ggplot2_py.guide`.
+"""
+
+from ggplot2_py.guide import *  # noqa: F401,F403
+from ggplot2_py.guide import __all__  # noqa: F401

ggplot2_py/labeller.py

@@ -0,0 +1,296 @@
+"""
+Facet labeller functions — faithful port of R's facet-labeller.R.
+
+Labeller functions format the strip labels of facet grids and wraps.
+They accept a dict of ``{variable_name: [values...]}`` and return
+a list of formatted label strings.
+
+R references
+------------
+* ``ggplot2/R/facet-labeller.R`` — label_value, label_both, etc.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from typing import Any, Callable, Dict, List, Optional, Union
+
+__all__ = [
+    "label_value",
+    "label_both",
+    "label_context",
+    "label_parsed",
+    "label_wrap_gen",
+    "as_labeller",
+]
+
+
+# ---------------------------------------------------------------------------
+# label_value
+# ---------------------------------------------------------------------------
+
+def label_value(
+    labels: Dict[str, List[str]],
+    multi_line: bool = True,
+) -> List[str]:
+    """Return only the factor values.
+
+    This is the default labeller in ggplot2.
+
+    Mirrors ``label_value`` in R (facet-labeller.R:105-112).
+
+    Parameters
+    ----------
+    labels : dict
+        ``{variable_name: [value_per_panel...]}``.
+    multi_line : bool
+        If ``True`` (default), return one line per variable.
+        If ``False``, collapse all variables into one line.
+
+    Returns
+    -------
+    list of str
+        Formatted labels, one per panel.
+
+    Examples
+    --------
+    >>> label_value({"drv": ["4", "f", "r"]})
+    ["4", "f", "r"]
+    >>> label_value({"drv": ["4", "f"], "cyl": ["4", "6"]}, multi_line=False)
+    ["4, 4", "f, 6"]
+    """
+    var_names = list(labels.keys())
+    if not var_names:
+        return []
+
+    n_panels = len(next(iter(labels.values())))
+
+    if multi_line and len(var_names) == 1:
+        return [str(v) for v in labels[var_names[0]]]
+
+    if multi_line:
+        # Return one label per variable per panel — for multi-line strips,
+        # join with newline
+        result = []
+        for i in range(n_panels):
+            parts = [str(labels[v][i]) for v in var_names]
+            result.append("\n".join(parts))
+        return result
+    else:
+        # Single line: collapse all variables
+        result = []
+        for i in range(n_panels):
+            parts = [str(labels[v][i]) for v in var_names]
+            result.append(", ".join(parts))
+        return result
+
+
+# ---------------------------------------------------------------------------
+# label_both
+# ---------------------------------------------------------------------------
+
+def label_both(
+    labels: Dict[str, List[str]],
+    multi_line: bool = True,
+    sep: str = ": ",
+) -> List[str]:
+    """Return ``"variable: value"`` labels.
+
+    Mirrors ``label_both`` in R (facet-labeller.R:119-142).
+
+    Parameters
+    ----------
+    labels : dict
+        ``{variable_name: [value_per_panel...]}``.
+    multi_line : bool
+        If ``True``, one line per variable; if ``False``, collapse.
+    sep : str
+        Separator between variable name and value.
+
+    Returns
+    -------
+    list of str
+        Formatted labels.
+
+    Examples
+    --------
+    >>> label_both({"drv": ["4", "f", "r"]})
+    ["drv: 4", "drv: f", "drv: r"]
+    """
+    var_names = list(labels.keys())
+    if not var_names:
+        return []
+
+    n_panels = len(next(iter(labels.values())))
+
+    if multi_line:
+        result = []
+        for i in range(n_panels):
+            parts = [f"{v}{sep}{labels[v][i]}" for v in var_names]
+            result.append("\n".join(parts))
+        return result
+    else:
+        result = []
+        for i in range(n_panels):
+            var_part = ", ".join(var_names)
+            val_part = ", ".join(str(labels[v][i]) for v in var_names)
+            result.append(f"{var_part}{sep}{val_part}")
+        return result
+
+
+# ---------------------------------------------------------------------------
+# label_context
+# ---------------------------------------------------------------------------
+
+def label_context(
+    labels: Dict[str, List[str]],
+    multi_line: bool = True,
+    sep: str = ": ",
+) -> List[str]:
+    """Context-dependent labeller.
+
+    Uses ``label_value`` for single-variable faceting, ``label_both``
+    when multiple variables are involved.
+
+    Mirrors ``label_context`` in R (facet-labeller.R:147-153).
+
+    Parameters
+    ----------
+    labels : dict
+        ``{variable_name: [value_per_panel...]}``.
+    multi_line : bool
+        Multi-line mode.
+    sep : str
+        Separator for ``label_both``.
+
+    Returns
+    -------
+    list of str
+        Formatted labels.
+    """
+    if len(labels) <= 1:
+        return label_value(labels, multi_line)
+    else:
+        return label_both(labels, multi_line, sep)
+
+
+# ---------------------------------------------------------------------------
+# label_parsed
+# ---------------------------------------------------------------------------
+
+def label_parsed(
+    labels: Dict[str, List[str]],
+    multi_line: bool = True,
+) -> List[str]:
+    """Interpret labels as expressions (Python: return as-is).
+
+    In R, this parses labels as plotmath expressions.  In Python we
+    simply return the string values, since matplotlib mathtext or
+    LaTeX rendering is handled downstream by the text grob.
+
+    Mirrors ``label_parsed`` in R (facet-labeller.R:158-173).
+
+    Parameters
+    ----------
+    labels : dict
+        ``{variable_name: [value_per_panel...]}``.
+    multi_line : bool
+        Multi-line mode.
+
+    Returns
+    -------
+    list of str
+        Labels (unchanged).
+    """
+    return label_value(labels, multi_line)
+
+
+# ---------------------------------------------------------------------------
+# label_wrap_gen
+# ---------------------------------------------------------------------------
+
+def label_wrap_gen(width: int = 25) -> Callable:
+    """Generate a labeller that wraps text at *width* characters.
+
+    Mirrors ``label_wrap_gen`` in R (facet-labeller.R:220-229).
+
+    Parameters
+    ----------
+    width : int
+        Maximum number of characters before wrapping.
+
+    Returns
+    -------
+    callable
+        A labeller function.
+
+    Examples
+    --------
+    >>> labeller = label_wrap_gen(10)
+    >>> labeller({"class": ["compact car", "midsize SUV"]})
+    ["compact\\ncar", "midsize\\nSUV"]
+    """
+    def _wrap_labeller(
+        labels: Dict[str, List[str]],
+        multi_line: bool = True,
+    ) -> List[str]:
+        base = label_value(labels, multi_line)
+        return ["\n".join(textwrap.wrap(str(lab), width)) for lab in base]
+
+    return _wrap_labeller
+
+
+# ---------------------------------------------------------------------------
+# as_labeller
+# ---------------------------------------------------------------------------
+
+_LABELLER_REGISTRY: Dict[str, Callable] = {
+    "label_value": label_value,
+    "label_both": label_both,
+    "label_context": label_context,
+    "label_parsed": label_parsed,
+}
+
+
+def as_labeller(x: Any) -> Callable:
+    """Coerce *x* to a labeller function.
+
+    Mirrors ``as_labeller`` in R (facet-labeller.R:284-299).
+
+    Parameters
+    ----------
+    x : str, dict, or callable
+        - ``str``: lookup by name (e.g. ``"label_value"``).
+        - ``dict``: a lookup table mapping values to labels.
+        - ``callable``: returned as-is.
+
+    Returns
+    -------
+    callable
+        A labeller function.
+    """
+    if callable(x):
+        return x
+
+    if isinstance(x, str):
+        if x in _LABELLER_REGISTRY:
+            return _LABELLER_REGISTRY[x]
+        raise ValueError(
+            f"Unknown labeller: {x!r}. "
+            f"Available: {list(_LABELLER_REGISTRY.keys())}"
+        )
+
+    if isinstance(x, dict):
+        # Lookup-table labeller: maps values to custom labels
+        lookup = x
+
+        def _dict_labeller(
+            labels: Dict[str, List[str]],
+            multi_line: bool = True,
+        ) -> List[str]:
+            base = label_value(labels, multi_line)
+            return [lookup.get(lab, lab) for lab in base]
+
+        return _dict_labeller
+
+    raise TypeError(f"Cannot coerce {type(x).__name__} to a labeller.")

ggplot2_py/labels.py

@@ -0,0 +1,309 @@
+"""
+Label helpers for ggplot2 plots.
+
+Provides ``labs()``, ``xlab()``, ``ylab()``, ``ggtitle()`` for setting
+axis titles, plot titles, subtitles, captions, tags, and alt-text.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from ggplot2_py._compat import Waiver, is_waiver, waiver, cli_warn
+
+__all__ = [
+    "labs",
+    "xlab",
+    "ylab",
+    "ggtitle",
+    "Labels",
+    "is_labels",
+    "get_labs",
+    "update_labels",
+    "make_labels",
+]
+
+
+# ---------------------------------------------------------------------------
+# Labels container
+# ---------------------------------------------------------------------------
+
+class Labels(dict):
+    """A thin ``dict`` subclass marking an object as a labels specification.
+
+    Behaves like a regular dictionary but carries a type tag so that the
+    ``+`` operator on a ``GGPlot`` object can dispatch correctly.
+    """
+
+    def __repr__(self) -> str:
+        items = ", ".join(f"{k}={v!r}" for k, v in self.items())
+        return f"Labels({items})"
+
+
+def is_labels(x: Any) -> bool:
+    """Return ``True`` if *x* is a :class:`Labels` instance.
+
+    Parameters
+    ----------
+    x : object
+        Object to test.
+
+    Returns
+    -------
+    bool
+    """
+    return isinstance(x, Labels)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+# Canonical label keys that are NOT aesthetics.
+_SPECIAL_KEYS = frozenset({
+    "title", "subtitle", "caption", "tag",
+    "alt", "alt_insight", "dictionary",
+})
+
+
+def labs(
+    *,
+    title: Any = None,
+    subtitle: Any = None,
+    caption: Any = None,
+    tag: Any = None,
+    alt: Any = None,
+    alt_insight: Any = None,
+    dictionary: Any = None,
+    **kwargs: Any,
+) -> Labels:
+    """Create a labels specification.
+
+    Parameters
+    ----------
+    title : str or None, optional
+        Plot title.
+    subtitle : str or None, optional
+        Plot subtitle (displayed below the title).
+    caption : str or None, optional
+        Plot caption (typically data source info).
+    tag : str or None, optional
+        Plot tag (e.g. ``"A"`` for sub-figures).
+    alt : str or callable or None, optional
+        Alt-text for accessibility.
+    alt_insight : str or None, optional
+        Short insight appended to auto-generated alt-text.
+    dictionary : dict or None, optional
+        Named dictionary for label look-ups.
+    **kwargs
+        Aesthetic-name = label pairs, e.g. ``x="Weight"``, ``colour="Class"``.
+
+    Returns
+    -------
+    Labels
+        A labels specification suitable for adding to a ggplot via ``+``.
+
+    Examples
+    --------
+    >>> labs(x="Engine displacement", y="Highway MPG", colour="Vehicle class")
+    """
+    # Collect special keyword args
+    args: Dict[str, Any] = {}
+    if title is not None:
+        args["title"] = title
+    if subtitle is not None:
+        args["subtitle"] = subtitle
+    if caption is not None:
+        args["caption"] = caption
+    if tag is not None:
+        args["tag"] = tag
+    if alt is not None:
+        args["alt"] = alt
+    if alt_insight is not None:
+        args["alt_insight"] = alt_insight
+    if dictionary is not None:
+        args["dictionary"] = dictionary
+
+    # Aesthetic label kwargs -- apply alias normalisation
+    from ggplot2_py.aes import standardise_aes_names  # lazy to avoid circular
+
+    for k, v in kwargs.items():
+        canonical = standardise_aes_names([k])[0]
+        args[canonical] = v
+
+    return Labels(args)
+
+
+def xlab(label: Optional[str]) -> Labels:
+    """Set the x-axis label.
+
+    Parameters
+    ----------
+    label : str or None
+        Label text.  ``None`` removes the label.
+
+    Returns
+    -------
+    Labels
+    """
+    return labs(x=label)
+
+
+def ylab(label: Optional[str]) -> Labels:
+    """Set the y-axis label.
+
+    Parameters
+    ----------
+    label : str or None
+        Label text.  ``None`` removes the label.
+
+    Returns
+    -------
+    Labels
+    """
+    return labs(y=label)
+
+
+def ggtitle(
+    label: Optional[str],
+    subtitle: Optional[str] = None,
+) -> Labels:
+    """Set the plot title (and optionally subtitle).
+
+    Parameters
+    ----------
+    label : str or None
+        Title text.
+    subtitle : str or None, optional
+        Subtitle text.
+
+    Returns
+    -------
+    Labels
+    """
+    return labs(title=label, subtitle=subtitle)
+
+
+# ---------------------------------------------------------------------------
+# update_labels helper
+# ---------------------------------------------------------------------------
+
+def update_labels(plot: Any, labels: Union[Labels, Dict[str, Any]]) -> Any:
+    """Merge *labels* into *plot*'s existing labels.
+
+    Parameters
+    ----------
+    plot : GGPlot
+        The plot to update (will be cloned).
+    labels : Labels or dict
+        New labels to merge in.
+
+    Returns
+    -------
+    GGPlot
+        A shallow copy of *plot* with updated labels.
+    """
+    # Import here to avoid circular dependency
+    p = plot._clone()
+    # Merge: new labels override existing
+    merged = dict(p.labels)
+    merged.update(labels)
+    p.labels = Labels(merged)
+    return p
+
+
+# ---------------------------------------------------------------------------
+# make_labels
+# ---------------------------------------------------------------------------
+
+def make_labels(mapping: Any) -> Dict[str, str]:
+    """Convert an aesthetic mapping into text labels.
+
+    Parameters
+    ----------
+    mapping : Mapping
+        An aesthetic mapping (from ``aes()``).
+
+    Returns
+    -------
+    dict
+        A dictionary of aesthetic-name -> label-string.
+    """
+    from ggplot2_py.aes import Mapping, AfterStat, AfterScale, Stage
+
+    # Accept both ``Mapping`` (from ``aes()``) and plain ``dict``
+    # (used by Stat.default_aes / Geom.default_aes).  R's
+    # ``make_labels()`` treats any named list uniformly (labels.R:124).
+    if isinstance(mapping, Mapping):
+        mapping_items = mapping.items()
+    elif isinstance(mapping, dict):
+        mapping_items = mapping.items()
+    else:
+        return {}
+
+    def _label_for(val: Any) -> str:
+        """Generate a human-readable label for an aesthetic value."""
+        if val is None:
+            return ""
+        if callable(val) and not isinstance(val, str):
+            return getattr(val, "__name__", "<expr>")
+        return str(val)
+
+    result: Dict[str, str] = {}
+    for aes_name, val in mapping_items:
+        if val is None:
+            result[aes_name] = aes_name
+        elif isinstance(val, str):
+            result[aes_name] = val
+        elif isinstance(val, AfterStat):
+            result[aes_name] = _label_for(val.x)
+        elif isinstance(val, AfterScale):
+            result[aes_name] = _label_for(val.x)
+        elif isinstance(val, Stage):
+            # Use the start mapping if available, then after_stat, then after_scale
+            if val.start is not None:
+                result[aes_name] = _label_for(val.start)
+            elif val.after_stat is not None:
+                result[aes_name] = _label_for(val.after_stat)
+            elif val.after_scale is not None:
+                result[aes_name] = _label_for(val.after_scale)
+            else:
+                result[aes_name] = aes_name
+        elif callable(val):
+            result[aes_name] = _label_for(val)
+        else:
+            result[aes_name] = str(val)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# get_labs (requires a built plot)
+# ---------------------------------------------------------------------------
+
+def get_labs(plot: Any = None) -> Labels:
+    """Retrieve completed labels from a plot.
+
+    Parameters
+    ----------
+    plot : GGPlot or None
+        A ggplot object.  If ``None``, uses ``get_last_plot()``.
+
+    Returns
+    -------
+    Labels
+        Resolved label dictionary.
+    """
+    if plot is None:
+        # lazy import to avoid circular
+        from ggplot2_py.plot import get_last_plot
+        plot = get_last_plot()
+
+    if plot is None:
+        return Labels()
+
+    # If already built, grab labels directly
+    if hasattr(plot, "plot") and hasattr(plot, "layout"):
+        # BuiltGGPlot
+        return Labels(plot.plot.labels)
+
+    return Labels(plot.labels)