plotnine 0.15.2__py3-none-any.whl → 0.16.0a1__py3-none-any.whl

plotnine/_mpl/layout_manager/_side_space.py

@@ -0,0 +1,176 @@
+"""
+Routines to adjust subplot params so that subplots are
+nicely fit in the figure. In doing so, only axis labels, tick labels, axes
+titles and offsetboxes that are anchored to axes are currently considered.
+
+Internally, this module assumes that the margins (left margin, etc.) which are
+differences between `Axes.get_tightbbox` and `Axes.bbox` are independent of
+Axes position. This may fail if `Axes.adjustable` is `datalim` as well as
+such cases as when left or right margin are affected by xlabel.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from plotnine._mpl.gridspec import p9GridSpec
+    from plotnine.typing import Side
+
+
+# Note
+# Margins around the plot are specified in figure coordinates
+# We interpret that value to be a fraction of the width. So along
+# the vertical direction we multiply by W/H to get equal space
+# in both directions
+
+
+class GridSpecParamsError(Exception):
+    """
+    Error thrown when there isn't enough space for some panels
+    """
+
+
+@dataclass
+class GridSpecParams:
+    """
+    Gridspec Parameters
+    """
+
+    left: float
+    right: float
+    top: float
+    bottom: float
+    wspace: float
+    hspace: float
+
+    def validate(self):
+        """
+        Return True if the params will create a non-empty area
+        """
+        if not (self.top - self.bottom > 0 and self.right - self.left > 0):
+            raise GridSpecParamsError(
+                "The parameters of the gridspec do not create a regular "
+                "rectangle."
+            )
+
+
+class _side_space(ABC):
+    """
+    Base class to for spaces
+
+    A *_space class does the book keeping for all the artists that may
+    fall on that side of the panels. The same name may appear in multiple
+    side classes (e.g. legend).
+
+    The amount of space for each artist is computed in figure coordinates.
+    """
+
+    gridspec: p9GridSpec
+    """
+    The gridspec (1x1) of the plot or composition
+    """
+
+    def _calculate(self):
+        """
+        Calculate the space taken up by each artist
+        """
+
+    @cached_property
+    def side(self) -> Side:
+        """
+        Side of the panel(s) that this class applies to
+        """
+        return cast("Side", self.__class__.__name__.split("_")[0])
+
+    @cached_property
+    def parts(self) -> list[str]:
+        """
+        The names of the part of the spaces
+        """
+        return [
+            name
+            for name, value in self.__class__.__dict__.items()
+            if not (
+                name.startswith("_")
+                or callable(value)
+                or isinstance(value, property)
+            )
+        ]
+
+    @property
+    def total(self) -> float:
+        """
+        Total space
+        """
+        return sum(getattr(self, name) for name in self.parts)
+
+    def sum_upto(self, item: str) -> float:
+        """
+        Sum of space upto but not including item
+
+        Sums from the edge of the figure i.e. the "plot_margin".
+        """
+        stop = self.parts.index(item)
+        return sum(getattr(self, name) for name in self.parts[:stop])
+
+    def sum_incl(self, item: str) -> float:
+        """
+        Sum of space upto and including the item
+
+        Sums from the edge of the figure i.e. the "plot_margin".
+        """
+        stop = self.parts.index(item) + 1
+        return sum(getattr(self, name) for name in self.parts[:stop])
+
+    @property
+    def offset(self) -> float:
+        """
+        Distance in figure dimensions from the edge of the figure
+
+        Derived classes should override this method
+
+        The space/margin and size consumed by artists is in figure dimensions
+        but the exact position is relative to the position of the GridSpec
+        within the figure. The offset accounts for the position of the
+        GridSpec and allows us to accurately place artists using figure
+        coordinates.
+
+        Example of an offset
+
+         Figure
+         ----------------------------------------
+        |                                        |
+        |          Plot GridSpec                 |
+        |          --------------------------    |
+        | offset  |                          |   |
+        |<------->| X                        |   |
+        |         |   Panels GridSpec        |   |
+        |         |   --------------------   |   |
+        |         |  |                    |  |   |
+        |         |  |                    |  |   |
+        |         |  |                    |  |   |
+        |         |  |                    |  |   |
+        |         |   --------------------   |   |
+        |         |                          |   |
+        |          --------------------------    |
+        |                                        |
+         ----------------------------------------
+        """
+        return 0
+
+    def to_figure_space(self, rel_value: float) -> float:
+        """
+        Convert value relative to the gridspec to one in figure space
+
+        The result is meant to be used with transFigure transforms.
+
+        Parameters
+        ----------
+        rel_value :
+            Position relative to the position of the gridspec
+        """
+        return self.offset + rel_value

plotnine/_mpl/utils.py

@@ -1,19 +1,27 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
 
 from matplotlib.transforms import Affine2D, Bbox
 
+from plotnine._utils import ha_as_float, va_as_float
+
 from .transforms import ZEROS_BBOX
 
 if TYPE_CHECKING:
+    from typing import Literal, Sequence
+
     from matplotlib.artist import Artist
     from matplotlib.axes import Axes
     from matplotlib.backend_bases import RendererBase
     from matplotlib.figure import Figure
     from matplotlib.gridspec import SubplotSpec
+    from matplotlib.text import Text
     from matplotlib.transforms import Transform
 
+    from plotnine.typing import HorizontalJustification, VerticalJustification
+
     from .gridspec import p9GridSpec
 
 
@@ -144,3 +152,253 @@ def draw_bbox(bbox, figure, color="black", **kwargs):
             **kwargs,
         )
     )
+
+
+@dataclass
+class ArtistGeometry:
+    """
+    Helper to calculate the position & extents (space) of an artist
+    """
+
+    figure: Figure
+
+    def __post_init__(self):
+        self.renderer = cast("RendererBase", self.figure._get_renderer())  # pyright: ignore
+
+    def bbox(self, artist: Artist) -> Bbox:
+        """
+        Bounding box of artist in figure coordinates
+        """
+        return bbox_in_figure_space(artist, self.figure, self.renderer)
+
+    def tight_bbox(self, artist: Artist) -> Bbox:
+        """
+        Bounding box of artist and its children in figure coordinates
+        """
+        return tight_bbox_in_figure_space(artist, self.figure, self.renderer)
+
+    def width(self, artist: Artist) -> float:
+        """
+        Width of artist in figure space
+        """
+        return self.bbox(artist).width
+
+    def tight_width(self, artist: Artist) -> float:
+        """
+        Width of artist and its children in figure space
+        """
+        return self.tight_bbox(artist).width
+
+    def height(self, artist: Artist) -> float:
+        """
+        Height of artist in figure space
+        """
+        return self.bbox(artist).height
+
+    def tight_height(self, artist: Artist) -> float:
+        """
+        Height of artist and its children in figure space
+        """
+        return self.tight_bbox(artist).height
+
+    def size(self, artist: Artist) -> tuple[float, float]:
+        """
+        (width, height) of artist in figure space
+        """
+        bbox = self.bbox(artist)
+        return (bbox.width, bbox.height)
+
+    def tight_size(self, artist: Artist) -> tuple[float, float]:
+        """
+        (width, height) of artist and its children in figure space
+        """
+        bbox = self.tight_bbox(artist)
+        return (bbox.width, bbox.height)
+
+    def left_x(self, artist: Artist) -> float:
+        """
+        x value of the left edge of the artist
+
+         ---
+        x   |
+         ---
+        """
+        return self.bbox(artist).min[0]
+
+    def right_x(self, artist: Artist) -> float:
+        """
+        x value of the left edge of the artist
+
+         ---
+        |   x
+         ---
+        """
+        return self.bbox(artist).max[0]
+
+    def top_y(self, artist: Artist) -> float:
+        """
+        y value of the top edge of the artist
+
+         -y-
+        |   |
+         ---
+        """
+        return self.bbox(artist).max[1]
+
+    def bottom_y(self, artist: Artist) -> float:
+        """
+        y value of the bottom edge of the artist
+
+         ---
+        |   |
+         -y-
+        """
+        return self.bbox(artist).min[1]
+
+    def max_width(self, artists: Sequence[Artist]) -> float:
+        """
+        Return the maximum width of list of artists
+        """
+        widths = [
+            bbox_in_figure_space(a, self.figure, self.renderer).width
+            for a in artists
+        ]
+        return max(widths) if len(widths) else 0
+
+    def max_height(self, artists: Sequence[Artist]) -> float:
+        """
+        Return the maximum height of list of artists
+        """
+        heights = [
+            bbox_in_figure_space(a, self.figure, self.renderer).height
+            for a in artists
+        ]
+        return max(heights) if len(heights) else 0
+
+
+@dataclass
+class JustifyBoundaries:
+    """
+    Limits about which text can be justified
+    """
+
+    plot_left: float
+    plot_right: float
+    plot_bottom: float
+    plot_top: float
+    panel_left: float
+    panel_right: float
+    panel_bottom: float
+    panel_top: float
+
+
+class TextJustifier:
+    """
+    Justify Text
+
+    The justification methods reinterpret alignment values to be justification
+    about a span.
+    """
+
+    def __init__(self, figure: Figure, boundaries: JustifyBoundaries):
+        self.geometry = ArtistGeometry(figure)
+        self.boundaries = boundaries
+
+    def horizontally(
+        self,
+        text: Text,
+        ha: HorizontalJustification | float,
+        left: float,
+        right: float,
+        width: float | None = None,
+    ):
+        """
+        Horizontally Justify text between left and right
+        """
+        rel = ha_as_float(ha)
+        if width is None:
+            width = self.geometry.width(text)
+        x = rel_position(rel, width, left, right)
+        text.set_x(x)
+        text.set_horizontalalignment("left")
+
+    def vertically(
+        self,
+        text: Text,
+        va: VerticalJustification | float,
+        bottom: float,
+        top: float,
+        height: float | None = None,
+    ):
+        """
+        Vertically Justify text between bottom and top
+        """
+        rel = va_as_float(va)
+
+        if height is None:
+            height = self.geometry.height(text)
+        y = rel_position(rel, height, bottom, top)
+        text.set_y(y)
+        text.set_verticalalignment("bottom")
+
+    def horizontally_across_panel(
+        self, text: Text, ha: HorizontalJustification | float
+    ):
+        """
+        Horizontally Justify text accross the panel(s) width
+        """
+        self.horizontally(
+            text, ha, self.boundaries.panel_left, self.boundaries.panel_right
+        )
+
+    def horizontally_across_plot(
+        self, text: Text, ha: HorizontalJustification | float
+    ):
+        """
+        Horizontally Justify text across the plot's width
+        """
+        self.horizontally(
+            text, ha, self.boundaries.plot_left, self.boundaries.plot_right
+        )
+
+    def vertically_along_panel(
+        self, text: Text, va: VerticalJustification | float
+    ):
+        """
+        Horizontally Justify text along the panel(s) height
+        """
+        self.vertically(
+            text, va, self.boundaries.panel_bottom, self.boundaries.panel_top
+        )
+
+    def vertically_along_plot(
+        self, text: Text, va: VerticalJustification | float
+    ):
+        """
+        Vertically Justify text along the plot's height
+        """
+        self.vertically(
+            text, va, self.boundaries.plot_bottom, self.boundaries.plot_top
+        )
+
+    def horizontally_about(
+        self, text: Text, ratio: float, how: Literal["panel", "plot"]
+    ):
+        """
+        Horizontally Justify text across the panel or plot
+        """
+        if how == "panel":
+            self.horizontally_across_panel(text, ratio)
+        else:
+            self.horizontally_across_plot(text, ratio)
+
+    def vertically_about(
+        self, text: Text, ratio: float, how: Literal["panel", "plot"]
+    ):
+        """
+        Vertically Justify text along the panel or plot
+        """
+        if how == "panel":
+            self.vertically_along_panel(text, ratio)
+        else:
+            self.vertically_along_plot(text, ratio)

plotnine/_utils/__init__.py

@@ -35,7 +35,6 @@ if TYPE_CHECKING:
         FloatArray,
         FloatArrayLike,
         HorizontalJustification,
-        IntArray,
         Side,
         VerticalJustification,
     )
@@ -309,7 +308,7 @@ def ninteraction(df: pd.DataFrame, drop: bool = False) -> list[int]:
     def len_unique(x):
         return len(np.unique(x))
 
-    ndistinct: IntArray = ids.apply(len_unique, axis=0).to_numpy()
+    ndistinct = ids.apply(len_unique, axis=0).to_numpy()
 
     combs = np.array(np.hstack([1, np.cumprod(ndistinct[:-1])]))
     mat = np.array(ids)
@@ -743,7 +742,7 @@ def ungroup(data: DataLike) -> DataLike:
     """Return an ungrouped DataFrame, or pass the original data back."""
 
     if isinstance(data, DataFrameGroupBy):
-        return data.obj
+        return data.obj  # pyright: ignore[reportReturnType]
 
     return data
 
@@ -1207,3 +1206,24 @@ def has_alpha_channel(c: str | tuple) -> bool:
         return c.startswith("#") and len(c) == 9
     else:
         return color_utils.is_color_tuple(c) and len(c) == 4
+
+
+def nextafter_range(rng: tuple[float, float]) -> tuple[float, float]:
+    """
+    Expand floating-point range by a step to adjacent representable numbers
+
+    Parameters
+    ----------
+    rng :
+        A tuple (min, max) representing the range to expand.
+
+    Returns
+    -------
+    :
+        A new tuple (lower, upper) where,
+        - lower is moved 1 float toward -∞
+        - upper is moved 1 float toward +∞
+    """
+    from math import inf, nextafter
+
+    return (nextafter(rng[0], -inf), nextafter(rng[1], inf))

plotnine/_utils/context.py

@@ -116,7 +116,7 @@ class plot_composition_context:
         # https://github.com/matplotlib/matplotlib/issues/24644
         # When drawing the Composition, the dpi themeable is infective
         # because it sets the rcParam after this figure is created.
-        rcParams = {"figure.dpi": self.cmp.last_plot.theme.getp("dpi")}
+        rcParams = {"figure.dpi": self.cmp.theme.getp("dpi")}
         self._rc_context = mpl.rc_context(rcParams)
 
     def __enter__(self) -> Self:

plotnine/_utils/dataclasses.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import fields
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any, Iterable
+
+
+def non_none_init_items(obj) -> Iterable[tuple[str, Any]]:
+    """
+    Yield (name, value) pairs of dataclass fields of `obj` that:
+
+      1. Have `init=True` in their definition
+      2. Have a value that is not `None`
+
+    This function is shallow and does not recursively yield nested
+    dataclasses.
+    """
+    return (
+        (f.name, value)
+        for f in fields(obj)
+        if f.init and (value := getattr(obj, f.name)) is not None
+    )

plotnine/animation.py

@@ -188,6 +188,7 @@ class PlotnineAnimation(ArtistAnimation):
                         "different limits from those of the first frame."
                     )
 
+        first_plot: ggplot | None = None
         figure: Figure | None = None
         axs: list[Axes] = []
         artists = []
@@ -198,14 +199,15 @@ class PlotnineAnimation(ArtistAnimation):
         # onto the figure and axes created by the first ggplot and
         # they create the subsequent frames.
         for frame_no, p in enumerate(plots):
-            if figure is None:
-                figure = p.draw()
-                axs = figure.get_axes()
+            if first_plot is None:
+                first_plot = p
+                figure = first_plot.draw()
+                axs = first_plot.figure.get_axes()
                 initialise_artist_offsets(len(axs))
-                scales = p._build_objs.scales
+                scales = first_plot._build_objs.scales
                 set_scale_limits(scales)
             else:
-                plot = self._draw_animation_plot(p, figure, axs)
+                plot = self._draw_animation_plot(p, first_plot)
                 check_scale_limits(plot.scales, frame_no)
 
             artists.append(get_frame_artists(axs))
@@ -213,14 +215,11 @@ class PlotnineAnimation(ArtistAnimation):
         if figure is None:
             figure = plt.figure()
 
-        assert figure is not None
         # Prevent Jupyter from plotting any static figure
         plt.close(figure)
         return figure, artists
 
-    def _draw_animation_plot(
-        self, plot: ggplot, figure: Figure, axs: list[Axes]
-    ) -> ggplot:
+    def _draw_animation_plot(self, plot: ggplot, first_plot: ggplot) -> ggplot:
         """
         Draw a plot/frame of the animation
 
@@ -229,10 +228,12 @@ class PlotnineAnimation(ArtistAnimation):
         from ._utils.context import plot_context
 
         plot = deepcopy(plot)
-        plot.figure = figure
-        plot.axs = axs
+        plot.figure = first_plot.figure
+        plot.axs = first_plot.axs
+        plot._gridspec = first_plot._sub_gridspec
+        plot._sub_gridspec = first_plot._sub_gridspec
         with plot_context(plot):
             plot._build()
-            plot.axs = plot.facet.setup(plot)
+            _ = plot.facet.setup(plot)
             plot._draw_layers()
         return plot

plotnine/composition/__init__.py

@@ -1,11 +1,17 @@
 from ._beside import Beside
 from ._compose import Compose
+from ._plot_annotation import plot_annotation
+from ._plot_layout import plot_layout
 from ._plot_spacer import plot_spacer
 from ._stack import Stack
+from ._wrap import Wrap
 
 __all__ = (
     "Compose",
     "Stack",
     "Beside",
+    "Wrap",
+    "plot_annotation",
+    "plot_layout",
     "plot_spacer",
 )

plotnine/composition/_beside.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from ._compose import Compose
@@ -9,7 +8,6 @@ if TYPE_CHECKING:
     from plotnine.ggplot import ggplot
 
 
-@dataclass(repr=False)
 class Beside(Compose):
     """
     Place plots or compositions side by side
@@ -26,25 +24,18 @@ class Beside(Compose):
     See Also
     --------
     plotnine.composition.Stack : To arrange plots vertically
+    plotnine.composition.Wrap : To arrange plots in a grid
     plotnine.composition.plot_spacer : To add a blank space between plots
     plotnine.composition.Compose : For more on composing plots
     """
 
-    @property
-    def nrow(self) -> int:
-        return 1
-
-    @property
-    def ncol(self) -> int:
-        return len(self)
-
     def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a column
         """
         # This is adjacent or i.e. (OR | rhs) so we collapse the
         # operands into a single operation
-        return Beside([*self, rhs])
+        return Beside([*self, rhs]) + self.layout + self.annotation
 
     def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
@@ -53,3 +44,14 @@ class Beside(Compose):
         from ._stack import Stack
 
         return Stack([self, rhs])
+
+    def __add__(self, rhs):
+        """
+        Add rhs into the besides composition
+        """
+        from plotnine import ggplot
+
+        if not isinstance(rhs, (ggplot, Compose)):
+            return super().__add__(rhs)
+
+        return self | rhs