ggplot2-python 4.0.2.9000__py3-none-any.whl

ggplot2_py/protocols.py

@@ -0,0 +1,171 @@
+"""
+Structural typing protocols for ggplot2_py GOG components.
+
+These :class:`~typing.Protocol` definitions specify the **contracts** that
+custom Geom, Stat, Scale, Coord, Facet, and Position classes should satisfy.
+They are ``@runtime_checkable``, so you can use ``isinstance()`` to verify
+compliance without requiring inheritance from the base classes.
+
+This is a **Python-exclusive** feature — R's ggplot2 has no equivalent
+compile-time or runtime contract checking.
+
+Usage
+-----
+Mypy / pyright will flag violations statically::
+
+    class MyStat(Stat):
+        required_aes = ("x",)
+        # Missing compute_group → type error
+
+At runtime you can check::
+
+    from ggplot2_py.protocols import StatProtocol
+    assert isinstance(my_stat, StatProtocol)
+
+Notes
+-----
+These protocols describe the *minimum* interface required for each
+component to participate in the GOG pipeline.  They do **not** replace
+the base classes (``Geom``, ``Stat``, etc.) — they complement them by
+enabling structural (duck-typed) checking.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Dict,
+    List,
+    Protocol,
+    Sequence,
+    Tuple,
+    Union,
+    runtime_checkable,
+)
+
+import pandas as pd
+
+__all__ = [
+    "GeomProtocol",
+    "StatProtocol",
+    "ScaleProtocol",
+    "CoordProtocol",
+    "FacetProtocol",
+    "PositionProtocol",
+]
+
+
+# ---------------------------------------------------------------------------
+# Geom
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class GeomProtocol(Protocol):
+    """Contract for geometry objects.
+
+    A conforming Geom must declare its aesthetic requirements and provide
+    at least ``draw_panel`` or ``draw_group`` for rendering.
+    """
+
+    required_aes: Union[Tuple[str, ...], List[str]]
+    default_aes: Any  # Mapping or dict
+    draw_key: Any  # callable
+
+    def setup_params(self, data: pd.DataFrame, params: dict) -> dict: ...
+    def setup_data(self, data: pd.DataFrame, params: dict) -> pd.DataFrame: ...
+    def draw_panel(self, data: pd.DataFrame, panel_params: dict,
+                   coord: Any, **kwargs: Any) -> Any: ...
+
+
+# ---------------------------------------------------------------------------
+# Stat
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class StatProtocol(Protocol):
+    """Contract for statistical transformation objects.
+
+    A conforming Stat must declare its aesthetic requirements and provide
+    ``compute_group`` (or ``compute_panel`` / ``compute_layer``).
+    """
+
+    required_aes: Union[Tuple[str, ...], List[str]]
+    default_aes: Any
+
+    def setup_params(self, data: pd.DataFrame, params: dict) -> dict: ...
+    def setup_data(self, data: pd.DataFrame, params: dict) -> pd.DataFrame: ...
+    def compute_group(self, data: pd.DataFrame, scales: Any,
+                      **params: Any) -> pd.DataFrame: ...
+
+
+# ---------------------------------------------------------------------------
+# Scale
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class ScaleProtocol(Protocol):
+    """Contract for scale objects.
+
+    A conforming Scale mediates between data space and aesthetic space
+    via train / transform / map.
+    """
+
+    aesthetics: Any  # list of str
+
+    def train(self, x: Any) -> None: ...
+    def transform(self, x: Any) -> Any: ...
+    def map(self, x: Any) -> Any: ...
+    def get_breaks(self) -> Any: ...
+    def get_labels(self, breaks: Any = None) -> Any: ...
+    def clone(self) -> Any: ...
+
+
+# ---------------------------------------------------------------------------
+# Coord
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class CoordProtocol(Protocol):
+    """Contract for coordinate system objects.
+
+    A conforming Coord transforms data positions into viewport positions
+    and renders background / axes.
+    """
+
+    def setup_params(self, data: list) -> dict: ...
+    def transform(self, data: pd.DataFrame, panel_params: dict) -> pd.DataFrame: ...
+    def setup_panel_params(self, scale_x: Any, scale_y: Any,
+                           params: dict = ...) -> dict: ...
+
+
+# ---------------------------------------------------------------------------
+# Facet
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class FacetProtocol(Protocol):
+    """Contract for faceting specification objects.
+
+    A conforming Facet computes panel layout and assigns data to panels.
+    """
+
+    def compute_layout(self, data: list, params: dict) -> pd.DataFrame: ...
+    def map_data(self, data: pd.DataFrame, layout: pd.DataFrame,
+                 params: dict) -> pd.DataFrame: ...
+
+
+# ---------------------------------------------------------------------------
+# Position
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class PositionProtocol(Protocol):
+    """Contract for position adjustment objects.
+
+    A conforming Position adjusts data coordinates (e.g. dodge, stack)
+    after stat computation but before coordinate transformation.
+    """
+
+    def setup_params(self, data: pd.DataFrame) -> dict: ...
+    def compute_layer(self, data: pd.DataFrame, params: dict,
+                      layout: Any) -> pd.DataFrame: ...

ggplot2_py/qplot.py

@@ -0,0 +1,233 @@
+"""
+Quick plotting shortcut (deprecated).
+
+Provides :func:`qplot` / :func:`quickplot` for creating simple plots
+with less typing.  This interface is deprecated in favour of the full
+``ggplot() + geom_*()`` pipeline.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any, List, Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+
+from ggplot2_py._compat import cli_warn
+
+__all__ = [
+    "qplot",
+    "quickplot",
+]
+
+
+def qplot(
+    x: Any = None,
+    y: Any = None,
+    *,
+    data: Optional[pd.DataFrame] = None,
+    geom: Union[str, List[str]] = "auto",
+    facets: Any = None,
+    xlim: Optional[Sequence] = None,
+    ylim: Optional[Sequence] = None,
+    log: str = "",
+    main: Optional[str] = None,
+    xlab: Optional[str] = None,
+    ylab: Optional[str] = None,
+    asp: Optional[float] = None,
+    colour: Any = None,
+    color: Any = None,
+    fill: Any = None,
+    size: Any = None,
+    shape: Any = None,
+    alpha: Any = None,
+    **kwargs: Any,
+) -> Any:
+    """Create a quick plot (deprecated).
+
+    ``qplot`` is a shorthand for ``ggplot() + geom_*()``.  It is
+    deprecated; prefer the full ggplot pipeline.
+
+    Parameters
+    ----------
+    x, y : str or array-like, optional
+        Variables for the x and y axes.  If strings, they are interpreted
+        as column names in *data*.
+    data : DataFrame, optional
+        Dataset.
+    geom : str or list of str, optional
+        Geom name(s) to use (e.g. ``"point"``, ``"histogram"``).
+        ``"auto"`` guesses from the supplied aesthetics.
+    facets : str or None, optional
+        Faceting formula (stub).
+    xlim, ylim : sequence, optional
+        Axis limits.
+    log : str, optional
+        Which axes to log-transform (``"x"``, ``"y"``, or ``"xy"``).
+    main : str, optional
+        Plot title.
+    xlab, ylab : str, optional
+        Axis labels.
+    asp : float, optional
+        Aspect ratio (y/x).
+    colour, color, fill, size, shape, alpha : str or array-like, optional
+        Additional aesthetics.
+    **kwargs
+        Other parameters passed to the geom.
+
+    Returns
+    -------
+    GGPlot
+        A ggplot object.
+
+    Warnings
+    --------
+    ``qplot()`` is deprecated since ggplot2 3.4.0.  Use ``ggplot()``
+    instead.
+    """
+    warnings.warn(
+        "qplot() is deprecated. Use ggplot() + geom_*() instead.",
+        FutureWarning,
+        stacklevel=2,
+    )
+
+    from ggplot2_py.aes import aes
+    from ggplot2_py.plot import ggplot, GGPlot
+    from ggplot2_py.labels import labs
+
+    # Normalise colour/color
+    if color is not None and colour is None:
+        colour = color
+
+    # Build data if not provided
+    if data is None:
+        data_dict: dict = {}
+        if x is not None and not isinstance(x, str):
+            data_dict["x"] = np.asarray(x)
+            x = "x"
+        if y is not None and not isinstance(y, str):
+            data_dict["y"] = np.asarray(y)
+            y = "y"
+        if colour is not None and not isinstance(colour, str):
+            data_dict["colour"] = np.asarray(colour)
+            colour = "colour"
+        if fill is not None and not isinstance(fill, str):
+            data_dict["fill"] = np.asarray(fill)
+            fill = "fill"
+        if size is not None and not isinstance(size, str):
+            data_dict["size"] = np.asarray(size)
+            size = "size"
+        if shape is not None and not isinstance(shape, str):
+            data_dict["shape"] = np.asarray(shape)
+            shape = "shape"
+        if alpha is not None and not isinstance(alpha, str):
+            data_dict["alpha"] = np.asarray(alpha)
+            alpha = "alpha"
+        if data_dict:
+            data = pd.DataFrame(data_dict)
+        else:
+            data = pd.DataFrame()
+
+    # Build mapping
+    mapping_kwargs: dict = {}
+    if x is not None:
+        mapping_kwargs["x"] = x
+    if y is not None:
+        mapping_kwargs["y"] = y
+    if colour is not None:
+        mapping_kwargs["colour"] = colour
+    if fill is not None:
+        mapping_kwargs["fill"] = fill
+    if size is not None:
+        mapping_kwargs["size"] = size
+    if shape is not None:
+        mapping_kwargs["shape"] = shape
+    if alpha is not None:
+        mapping_kwargs["alpha"] = alpha
+
+    mapping = aes(**mapping_kwargs)
+
+    # Auto-detect geom
+    if isinstance(geom, str):
+        geoms = [geom]
+    else:
+        geoms = list(geom)
+
+    if "auto" in geoms:
+        if y is not None:
+            geoms = ["point" if g == "auto" else g for g in geoms]
+        elif x is not None:
+            # Check if x is discrete
+            if isinstance(data, pd.DataFrame) and x in data.columns:
+                col = data[x]
+                if col.dtype == object or hasattr(col, "cat"):
+                    geoms = ["bar" if g == "auto" else g for g in geoms]
+                else:
+                    geoms = ["histogram" if g == "auto" else g for g in geoms]
+            else:
+                geoms = ["histogram" if g == "auto" else g for g in geoms]
+        else:
+            geoms = ["point" if g == "auto" else g for g in geoms]
+
+    # Determine axis labels
+    if xlab is None:
+        xlab = str(x) if x is not None else ""
+    if ylab is None:
+        ylab = str(y) if y is not None else ""
+
+    # Build plot
+    p = ggplot(data, mapping)
+
+    # Add geoms
+    import ggplot2_py.geoms as _geoms_mod
+
+    for g in geoms:
+        geom_fn = getattr(_geoms_mod, f"geom_{g}", None)
+        if geom_fn is None:
+            cli_warn(f"Unknown geom: 'geom_{g}'.")
+            continue
+        p = p + geom_fn(**kwargs)
+
+    # Log transforms
+    if "x" in log:
+        try:
+            from ggplot2_py.scales import scale_x_log10
+            p = p + scale_x_log10()
+        except ImportError:
+            pass
+    if "y" in log:
+        try:
+            from ggplot2_py.scales import scale_y_log10
+            p = p + scale_y_log10()
+        except ImportError:
+            pass
+
+    # Aspect ratio
+    if asp is not None:
+        from ggplot2_py.theme import theme
+        p = p + theme(aspect_ratio=asp)
+
+    # Labels
+    label_kwargs: dict = {}
+    if xlab:
+        label_kwargs["x"] = xlab
+    if ylab:
+        label_kwargs["y"] = ylab
+    if main:
+        label_kwargs["title"] = main
+    if label_kwargs:
+        p = p + labs(**label_kwargs)
+
+    # Axis limits
+    if xlim is not None:
+        from ggplot2_py.limits import xlim as _xlim
+        p = p + _xlim(*xlim)
+    if ylim is not None:
+        from ggplot2_py.limits import ylim as _ylim
+        p = p + _ylim(*ylim)
+
+    return p
+
+
+quickplot = qplot