plotnine 0.14.5__py3-none-any.whl → 0.15.0a2__py3-none-any.whl

plotnine/guides/guide_legend.py

@@ -25,7 +25,7 @@ if TYPE_CHECKING:
 
     from plotnine.geoms.geom import geom
     from plotnine.layer import layer
-    from plotnine.typing import SidePosition
+    from plotnine.typing import Side
 
 
 # See guides.py for terminology
@@ -171,21 +171,20 @@ class guide_legend(guide):
             # Modify aesthetics
 
             # When doing after_scale evaluations, we only consider those
-            # for the aesthetics of this legend. The reduces the spurious
-            # warnings where an evaluation of another aesthetic failed yet
-            # it is not needed.
+            # for the aesthetics that are valid for this layer/geom.
             aes_modifiers = {
-                ae: expr
-                for ae, expr in l.mapping._scaled.items()
-                if ae in matched_set
+                ae: l.mapping._scaled[ae]
+                for ae in l.geom.aesthetics() & l.mapping._scaled.keys()
             }
 
             try:
                 data = l.use_defaults(data, aes_modifiers)
             except PlotnineError:
                 warn(
-                    "Failed to apply `after_scale` modifications "
-                    "to the legend.",
+                    "Failed to apply `after_scale` modifications to the "
+                    "legend. This probably should not happen. Help us "
+                    "discover why, please open and issue at "
+                    "https://github.com/has2k1/plotnine/issues",
                     PlotnineWarning,
                 )
                 data = l.use_defaults(data, {})
@@ -226,10 +225,10 @@ class guide_legend(guide):
                 ncol = int(np.ceil(nbreak / 15))
 
         if nrow is None:
-            ncol = cast(int, ncol)
+            ncol = cast("int", ncol)
             nrow = int(np.ceil(nbreak / ncol))
         elif ncol is None:
-            nrow = cast(int, nrow)
+            nrow = cast("int", nrow)
             ncol = int(np.ceil(nbreak / nrow))
 
         return nrow, ncol
@@ -255,7 +254,7 @@ class guide_legend(guide):
         elements = self.elements
 
         # title
-        title = cast(str, self.title)
+        title = cast("str", self.title)
         title_box = TextArea(title)
         targets.legend_title = title_box._text  # type: ignore
 
@@ -282,7 +281,7 @@ class guide_legend(guide):
         targets.legend_key = drawings
 
         # Match Drawings with labels to create the entries
-        lookup: dict[SidePosition, tuple[type[PackerBase], slice]] = {
+        lookup: dict[Side, tuple[type[PackerBase], slice]] = {
             "right": (HPacker, reverse),
             "left": (HPacker, obverse),
             "bottom": (VPacker, reverse),
@@ -381,7 +380,7 @@ class GuideElementsLegend(GuideElements):
         )
 
     @cached_property
-    def text_position(self) -> SidePosition:
+    def text_position(self) -> Side:
         if not (pos := self.theme.getp("legend_text_position")):
             pos = "right"
         return pos
@@ -403,7 +402,7 @@ class GuideElementsLegend(GuideElements):
         dimensions are big enough.
         """
         #  Note the different height sizes for the entries
-        guide = cast(guide_legend, self.guide)
+        guide = cast("guide_legend", self.guide)
         min_size = (
             self.theme.getp("legend_key_width"),
             self.theme.getp("legend_key_height"),
@@ -452,7 +451,7 @@ class GuideElementsLegend(GuideElements):
         If legend is horizontal, then key heights must be equal, so we
         use the maximum
         """
-        hs = [h for h, _ in self._key_dimensions]
+        hs = [h for _, h in self._key_dimensions]
         if self.is_horizontal:
             return [max(hs)] * len(hs)
         return hs

plotnine/guides/guides.py

@@ -35,7 +35,7 @@ if TYPE_CHECKING:
         NoGuide,
         Orientation,
         ScaledAestheticsName,
-        SidePosition,
+        Side,
         TextJustification,
     )
 
@@ -104,7 +104,7 @@ class guides:
             raise ValueError("Got a guide for color and colour, choose one.")
         rename_aesthetics(self)
 
-    def __radd__(self, plot: ggplot):
+    def __radd__(self, other: ggplot):
         """
         Add guides to the plot
 
@@ -120,9 +120,9 @@ class guides:
         """
         for f in fields(self):
             if (g := getattr(self, f.name)) is not None:
-                setattr(plot.guides, f.name, g)
+                setattr(other.guides, f.name, g)
 
-        return plot
+        return other
 
     def _build(self) -> Sequence[guide]:
         """
@@ -326,7 +326,7 @@ class guides:
 
         # Group together guides for each position
         groups: dict[
-            tuple[SidePosition, float]
+            tuple[Side, float]
             | tuple[tuple[float, float], tuple[float, float]],
             list[PackerBase],
         ] = defaultdict(list)
@@ -342,8 +342,8 @@ class guides:
             if isinstance(position, str) and isinstance(just, (float, int)):
                 setattr(legends, position, outside_legend(aob, just))
             else:
-                position = cast(tuple[float, float], position)
-                just = cast(tuple[float, float], just)
+                position = cast("tuple[float, float]", position)
+                just = cast("tuple[float, float]", just)
                 legends.inside.append(inside_legend(aob, just, position))
 
         return legends
@@ -467,7 +467,7 @@ class GuidesElements:
             if just is None:
                 just = (0.5, 0.5)
             elif just in VALID_JUSTIFICATION_WORDS:
-                just = ensure_xy_location(just)  # pyright: ignore[reportArgumentType]
+                just = ensure_xy_location(just)
             elif isinstance(just, (float, int)):
                 just = (just, just)
             return just[idx]

plotnine/helpers.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Sequence
+
+    from plotnine import ggplot
+
+__all__ = ("get_aesthetic_limits",)
+
+
+def get_aesthetic_limits(
+    plot: ggplot,
+    ae: str,
+) -> (
+    tuple[float, float]
+    | Sequence[str]
+    | list[tuple[float]]
+    | list[Sequence[str]]
+):
+    """
+    Get the limits of an aesthetic
+
+    These are the limits before they are expanded.
+
+    Parameters
+    ----------
+    plot :
+        ggplot object
+
+    ae :
+        Name of aesthetic
+
+    Returns
+    -------
+    out :
+        The limits of the aesthetic. If the plot is facetted, (has many
+        panels), it is a sequence of limits, one for each panel.
+    """
+    plot = deepcopy(plot)
+    plot._build()
+    limits = [
+        getattr(panel, ae).limits
+        for panel in plot._build_objs.layout.panel_params
+    ]
+
+    return limits[0] if len(limits) == 1 else limits

plotnine/iapi.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import itertools
 from copy import copy
 from dataclasses import dataclass, field, fields
+from functools import cached_property
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -19,11 +20,14 @@ if TYPE_CHECKING:
     from matplotlib.figure import Figure
 
     from plotnine.scales.scale import scale
+    from plotnine.themes.elements.margin import margin
     from plotnine.typing import (
         CoordRange,
         FloatArrayLike,
+        HorizontalJustification,
         ScaledAestheticsName,
         StripPosition,
+        VerticalJustification,
     )
 
     from ._mpl.offsetbox import FlexibleAnchoredOffsetbox
@@ -76,6 +80,7 @@ class labels_view:
     title: Optional[str] = None
     caption: Optional[str] = None
     subtitle: Optional[str] = None
+    tag: Optional[str] = None
 
     def update(self, other: labels_view):
         """
@@ -228,13 +233,27 @@ class strip_draw_info:
     Information required to draw strips
     """
 
-    x: float
-    y: float
-    ha: str
-    va: str
-    box_width: float
-    box_height: float
-    strip_text_margin: float
+    bg_x: float
+    """Left of the strip background in transAxes"""
+
+    bg_y: float
+    """Bottom of the strip background in transAxes"""
+
+    ha: HorizontalJustification | float
+    """Horizontal justification of strip text within the background"""
+
+    va: VerticalJustification | float
+    """Vertical justification of strip text within the background"""
+
+    bg_width: float
+    """Width of the strip background in transAxes"""
+
+    bg_height: float
+    """Height of the strip background in transAxes"""
+
+    margin: margin
+    """Strip text margin with the units in lines"""
+
     strip_align: float
     position: StripPosition
     label: str
@@ -242,6 +261,13 @@ class strip_draw_info:
     rotation: float
     layout: layout_details
 
+    @cached_property
+    def is_oneline(self) -> bool:
+        """
+        Whether the strip text is a single line
+        """
+        return len(self.label.split("\n")) == 1
+
 
 @dataclass
 class strip_label_details:

plotnine/labels.py

@@ -90,6 +90,11 @@ class labs:
     The caption at the bottom of the plot.
     """
 
+    tag: str | None = None
+    """
+    A plot tag
+    """
+
     def __post_init__(self):
         kwargs: dict[str, str] = {
             f.name: value
@@ -98,12 +103,12 @@ class labs:
         }
         self.labels = labels_view(**rename_aesthetics(kwargs))
 
-    def __radd__(self, plot: p9.ggplot) -> p9.ggplot:
+    def __radd__(self, other: p9.ggplot) -> p9.ggplot:
         """
         Add labels to ggplot object
         """
-        plot.labels.update(self.labels)
-        return plot
+        other.labels.update(self.labels)
+        return other
 
 
 class xlab(labs):

plotnine/layer.py

@@ -125,16 +125,16 @@ class layer:
                 lkwargs[param] = geom.DEFAULT_PARAMS[param]
         return layer(**lkwargs)
 
-    def __radd__(self, plot: ggplot) -> ggplot:
+    def __radd__(self, other: ggplot) -> ggplot:
         """
         Add layer to ggplot object
         """
         try:
-            plot.layers.append(self)
+            other.layers.append(self)
         except AttributeError as e:
-            msg = f"Cannot add layer to object of type {type(plot)!r}"
+            msg = f"Cannot add layer to object of type {type(other)!r}"
             raise PlotnineError(msg) from e
-        return plot
+        return other
 
     def __deepcopy__(self, memo: dict[Any, Any]) -> layer:
         """

plotnine/mapping/_env.py

@@ -122,7 +122,7 @@ class Environment:
     def __hash__(self):
         return hash((Environment, tuple(self._namespace_ids())))
 
-    def __getstate__(*args, **kwargs):
+    def __getstate__(self):
         """
         Return state with no namespaces
         """
@@ -198,7 +198,7 @@ class StackedLookup(MutableMapping):
     def __repr__(self):
         return f"{self.__class__.__name__}({self.stack})"
 
-    def __getstate__(*args, **kwargs):
+    def __getstate__(self):
         """
         Return state with no namespace
         """

plotnine/mapping/_eval_environment.py

@@ -0,0 +1,85 @@
+"""
+These are functions that can be called by the user inside the aes()
+mapping. This is meant to make it easy to transform column-variables
+as easily as is possible in ggplot2.
+
+We only implement the most common functions.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    from typing import Any, Sequence
+
+__all__ = (
+    "factor",
+    "reorder",
+)
+
+
+def factor(
+    values: Sequence[Any],
+    categories: Sequence[Any] | None = None,
+    ordered: bool | None = None,
+) -> pd.Categorical:
+    """
+    Turn x in to a categorical (factor) variable
+
+    It is just an alias to `pandas.Categorical`
+
+    Parameters
+    ----------
+    values :
+        The values of the categorical. If categories are given, values not in
+        categories will be replaced with NaN.
+    categories :
+        The unique categories for this categorical. If not given, the
+        categories are assumed to be the unique values of `values`
+        (sorted, if possible, otherwise in the order in which they appear).
+    ordered :
+        Whether or not this categorical is treated as a ordered categorical.
+        If True, the resulting categorical will be ordered.
+        An ordered categorical respects, when sorted, the order of its
+        `categories` attribute (which in turn is the `categories` argument, if
+        provided).
+    """
+    return pd.Categorical(values, categories=categories, ordered=None)
+
+
+def reorder(x, y, fun=np.median, ascending=True):
+    """
+    Reorder categorical by sorting along another variable
+
+    It is the order of the categories that changes. Values in x
+    are grouped by categories and summarised to determine the
+    new order.
+
+    Credit: Copied from plydata
+
+    Parameters
+    ----------
+    x : list-like
+        Values that will make up the categorical.
+    y : list-like
+        Values by which `c` will be ordered.
+    fun : callable
+        Summarising function to `x` for each category in `c`.
+        Default is the *median*.
+    ascending : bool
+        If `True`, the `c` is ordered in ascending order of `x`.
+    """
+    if len(x) != len(y):
+        raise ValueError(f"Lengths are not equal. {len(x)=}, {len(x)=}")
+    summary = (
+        pd.Series(y)
+        .groupby(x, observed=True)
+        .apply(fun)
+        .sort_values(ascending=ascending)
+    )
+    cats = summary.index.to_list()
+    return pd.Categorical(x, categories=cats)

plotnine/mapping/aes.py

@@ -1,19 +1,19 @@
 from __future__ import annotations
 
 import re
-import typing
 from collections.abc import Iterable, Sequence
 from contextlib import suppress
 from copy import deepcopy
 from dataclasses import fields
-from typing import Any, Dict
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Dict
 
 import pandas as pd
 
 from ..iapi import labels_view
 from .evaluation import after_stat, stage
 
-if typing.TYPE_CHECKING:
+if TYPE_CHECKING:
     from typing import Protocol, TypeVar
 
     class ColorOrColour(Protocol):
@@ -171,27 +171,11 @@ class aes(Dict[str, Any]):
       ggplot(df, aes(x="df.index", y="np.sin(gam ma)"))
       ```
 
-    `aes` has 2 internal methods you can use to transform variables being
-    mapped.
+    `aes` has 2 internal functions that you can use in your expressions
+    when transforming the variables.
 
-      1. `factor` - This function turns the variable into a factor.
-         It is just an alias to `pandas.Categorical`:
-
-         ```python
-         ggplot(mtcars, aes(x="factor(cyl)")) + geom_bar()
-         ```
-
-      2. `reorder` - This function changes the order of first variable
-         based on values of the second variable:
-
-         ```python
-         df = pd.DataFrame({
-             "x": ["b", "d", "c", "a"],
-             "y": [1, 2, 3, 4]
-         })
-
-         ggplot(df, aes("reorder(x, y)", "y")) + geom_col()
-         ```
+      1. [](:func:`~plotnine.mapping._eval_environment.factor`)
+      1. [](:func:`~plotnine.mapping._eval_environment.reorder`)
 
     **The group aesthetic**
 
@@ -237,7 +221,7 @@ class aes(Dict[str, Any]):
                 kwargs[name] = after_stat(_after_stat)
         return kwargs
 
-    @property
+    @cached_property
     def _starting(self) -> dict[str, Any]:
         """
         Return the subset of aesthetics mapped from the layer data
@@ -254,7 +238,7 @@ class aes(Dict[str, Any]):
 
         return d
 
-    @property
+    @cached_property
     def _calculated(self) -> dict[str, Any]:
         """
         Return only the aesthetics mapped to calculated statistics
@@ -269,7 +253,7 @@ class aes(Dict[str, Any]):
 
         return d
 
-    @property
+    @cached_property
     def _scaled(self) -> dict[str, Any]:
         """
         Return only the aesthetics mapped to after scaling
@@ -298,14 +282,14 @@ class aes(Dict[str, Any]):
 
         return result
 
-    def __radd__(self, plot):
+    def __radd__(self, other):
         """
         Add aesthetic mappings to ggplot
         """
         self = deepcopy(self)
-        plot.mapping.update(self)
-        plot.labels.update(make_labels(self))
-        return plot
+        other.mapping.update(self)
+        other.labels.update(make_labels(self))
+        return other
 
     def copy(self):
         return aes(**self)

plotnine/mapping/evaluation.py

@@ -1,15 +1,16 @@
 from __future__ import annotations
 
 import numbers
-import typing
+from typing import TYPE_CHECKING
 
 import numpy as np
 import pandas as pd
 import pandas.api.types as pdtypes
 
 from ..exceptions import PlotnineError
+from ._eval_environment import factor, reorder
 
-if typing.TYPE_CHECKING:
+if TYPE_CHECKING:
     from typing import Any
 
     from . import aes
@@ -18,6 +19,9 @@ if typing.TYPE_CHECKING:
 
 __all__ = ("after_stat", "after_scale", "stage")
 
+
+EVAL_ENVIRONMENT = {"factor": factor, "reorder": reorder}
+
 _TPL_EVAL_FAIL = """\
 Could not evaluate the '{}' mapping: '{}' \
 (original error: {})"""
@@ -108,68 +112,6 @@ def after_scale(x):
     return stage(after_scale=x)
 
 
-def reorder(x, y, fun=np.median, ascending=True):
-    """
-    Reorder categorical by sorting along another variable
-
-    It is the order of the categories that changes. Values in x
-    are grouped by categories and summarised to determine the
-    new order.
-
-    Credit: Copied from plydata
-
-    Parameters
-    ----------
-    x : list-like
-        Values that will make up the categorical.
-    y : list-like
-        Values by which `c` will be ordered.
-    fun : callable
-        Summarising function to `x` for each category in `c`.
-        Default is the *median*.
-    ascending : bool
-        If `True`, the `c` is ordered in ascending order of `x`.
-
-    Examples
-    --------
-    >>> c = list('abbccc')
-    >>> x = [11, 2, 2, 3, 33, 3]
-    >>> cat_reorder(c, x)
-    [a, b, b, c, c, c]
-    Categories (3, object): [b, c, a]
-    >>> cat_reorder(c, x, fun=max)
-    [a, b, b, c, c, c]
-    Categories (3, object): [b, a, c]
-    >>> cat_reorder(c, x, fun=max, ascending=False)
-    [a, b, b, c, c, c]
-    Categories (3, object): [c, a, b]
-    >>> c_ordered = pd.Categorical(c, ordered=True)
-    >>> cat_reorder(c_ordered, x)
-    [a, b, b, c, c, c]
-    Categories (3, object): [b < c < a]
-    >>> cat_reorder(c + ['d'], x)
-    Traceback (most recent call last):
-        ...
-    ValueError: Lengths are not equal. len(c) is 7 and len(x) is 6.
-    """
-    if len(x) != len(y):
-        raise ValueError(f"Lengths are not equal. {len(x)=}, {len(x)=}")
-    summary = (
-        pd.Series(y)
-        .groupby(x, observed=True)
-        .apply(fun)
-        .sort_values(ascending=ascending)
-    )
-    cats = summary.index.to_list()
-    return pd.Categorical(x, categories=cats)
-
-
-# These are function that can be called by the user inside the aes()
-# mapping. This is meant to make the variable transformations as easy
-# as they are in ggplot2
-AES_INNER_NAMESPACE = {"factor": pd.Categorical, "reorder": reorder}
-
-
 def evaluate(
     aesthetics: aes | dict[str, Any], data: pd.DataFrame, env: Environment
 ) -> pd.DataFrame:
@@ -207,7 +149,7 @@ def evaluate(
     3  16
     4  25
     """
-    env = env.with_outer_namespace(AES_INNER_NAMESPACE)
+    env = env.with_outer_namespace(EVAL_ENVIRONMENT)
 
     # Store evaluation results in a dict column in a dict
     evaled = {}

plotnine/options.py

@@ -10,14 +10,11 @@ if TYPE_CHECKING:
     from plotnine import theme
     from plotnine.typing import FigureFormat
 
-close_all_figures = False
-"""
-Development flag, e.g. set to `True` to prevent
-the queuing up of figures when errors happen.
-"""
-
 current_theme: Optional[theme | Type[theme]] = None
-"""Theme used when none is added to the ggplot object"""
+"""Theme used when none is added to the ggplot object
+
+Another way to do it, to set a default theme using `theme_set()`.
+"""
 
 base_family: str = "sans-serif"
 """
@@ -77,6 +74,11 @@ def get_option(name: str) -> Any:
     ----------
     name :
         Name of the option
+
+    Notes
+    -----
+    See [reference](/reference/#options) for a list of all the available
+    options.
     """
     d = globals()
 
@@ -103,6 +105,11 @@ def set_option(name: str, value: Any) -> Any:
     -------
     :
         Old value of the option
+
+    Notes
+    -----
+    See [reference](/reference/#options) for a list of all the available
+    options.
     """
     d = globals()
 

plotnine/plot_composition/__init__.py

@@ -0,0 +1,10 @@
+from ._compose import ADD, DIV, OR, Compose
+from ._spacer import spacer
+
+__all__ = (
+    "Compose",
+    "ADD",
+    "DIV",
+    "OR",
+    "spacer",
+)