plotnine 0.15.0a6__py3-none-any.whl → 0.15.0a8__py3-none-any.whl

plotnine/_mpl/layout_manager/_spaces.py

@@ -16,6 +16,7 @@ from dataclasses import dataclass, field, fields
 from functools import cached_property
 from typing import TYPE_CHECKING, cast
 
+from plotnine.exceptions import PlotnineError
 from plotnine.facets import facet_grid, facet_null, facet_wrap
 
 from ._layout_items import LayoutItems
@@ -233,7 +234,7 @@ class _side_spaces(ABC):
         """
         The width of the tag including the margins
 
-        The value is zero expect if all these are true:
+        The value is zero except if all these are true:
             - The tag is in the margin `theme(plot_tag_position = "margin")`
             - The tag at one one of the the following locations;
               left, right, topleft, topright, bottomleft or bottomright
@@ -245,13 +246,41 @@ class _side_spaces(ABC):
         """
         The height of the tag including the margins
 
-        The value is zero expect if all these are true:
+        The value is zero except if all these are true:
             - The tag is in the margin `theme(plot_tag_position = "margin")`
             - The tag at one one of the the following locations;
               top, bottom, topleft, topright, bottomleft or bottomright
         """
         return 0
 
+    @property
+    def axis_title_clearance(self) -> float:
+        """
+        The distance between the axis title and the panel
+
+         Figure
+         ----------------------------
+        |         Panel              |
+        |         -----------        |
+        |        |           |       |
+        |        |           |       |
+        |  Y<--->|           |       |
+        |        |           |       |
+        |        |           |       |
+        |         -----------        |
+        |                            |
+         ----------------------------
+
+        We use this value to when aligning axis titles in a
+        plot composition.
+        """
+
+        try:
+            return self.total - self.sum_upto("axis_title_alignment")
+        except AttributeError as err:
+            # There is probably an error in in the layout manager
+            raise PlotnineError("Side has no axis title") from err
+
 
 @dataclass
 class left_spaces(_side_spaces):
@@ -311,6 +340,14 @@ class left_spaces(_side_spaces):
     axis_title_y_margin_left: float = 0
     axis_title_y: float = 0
     axis_title_y_margin_right: float = 0
+    axis_title_alignment: float = 0
+    """
+    Space added to align the axis title with others in a composition
+
+    This value is calculated during the layout process. The amount is
+    the difference between the largest and smallest axis_title_clearance
+    among the items in the composition.
+    """
     axis_text_y_margin_left: float = 0
     axis_text_y: float = 0
     axis_text_y_margin_right: float = 0
@@ -385,18 +422,18 @@ class left_spaces(_side_spaces):
         return self.to_figure_space(self.sum_incl(item))
 
     @property
-    def left_relative(self):
+    def panel_left_relative(self):
         """
         Left (relative to the gridspec) of the panels in figure dimensions
         """
         return self.total
 
     @property
-    def left(self):
+    def panel_left(self):
         """
         Left of the panels in figure space
         """
-        return self.to_figure_space(self.left_relative)
+        return self.to_figure_space(self.panel_left_relative)
 
     @property
     def plot_left(self):
@@ -491,18 +528,18 @@ class right_spaces(_side_spaces):
         return self.to_figure_space(1 - self.sum_upto(item))
 
     @property
-    def right_relative(self):
+    def panel_right_relative(self):
         """
         Right (relative to the gridspec) of the panels in figure dimensions
         """
         return 1 - self.total
 
     @property
-    def right(self):
+    def panel_right(self):
         """
         Right of the panels in figure space
         """
-        return self.to_figure_space(self.right_relative)
+        return self.to_figure_space(self.panel_right_relative)
 
     @property
     def plot_right(self):
@@ -620,18 +657,18 @@ class top_spaces(_side_spaces):
         return self.to_figure_space(1 - self.sum_upto(item))
 
     @property
-    def top_relative(self):
+    def panel_top_relative(self):
         """
         Top (relative to the gridspec) of the panels in figure dimensions
         """
         return 1 - self.total
 
     @property
-    def top(self):
+    def panel_top(self):
         """
         Top of the panels in figure space
         """
-        return self.to_figure_space(self.top_relative)
+        return self.to_figure_space(self.panel_top_relative)
 
     @property
     def plot_top(self):
@@ -674,6 +711,15 @@ class bottom_spaces(_side_spaces):
     axis_title_x_margin_bottom: float = 0
     axis_title_x: float = 0
     axis_title_x_margin_top: float = 0
+    axis_title_alignment: float = 0
+    """
+    Space added to align the axis title with others in a composition
+
+    This value is calculated during the layout process in a tree structure
+    that has convenient access to the sides/edges of the panels in the
+    composition. It's amount is the difference in height between this axis
+    text (and it's margins) and the tallest axis text (and it's margin).
+    """
     axis_text_x_margin_bottom: float = 0
     axis_text_x: float = 0
     axis_text_x_margin_top: float = 0
@@ -758,18 +804,18 @@ class bottom_spaces(_side_spaces):
         return self.to_figure_space(self.sum_incl(item))
 
     @property
-    def bottom_relative(self):
+    def panel_bottom_relative(self):
         """
         Bottom (relative to the gridspec) of the panels in figure dimensions
         """
         return self.total
 
     @property
-    def bottom(self):
+    def panel_bottom(self):
         """
         Bottom of the panels in figure space
         """
-        return self.to_figure_space(self.bottom_relative)
+        return self.to_figure_space(self.panel_bottom_relative)
 
     @property
     def plot_bottom(self):
@@ -892,14 +938,14 @@ class LayoutSpaces:
         """
         Width [figure dimensions] of panels
         """
-        return self.r.right - self.l.left
+        return self.r.panel_right - self.l.panel_left
 
     @property
     def panel_height(self) -> float:
         """
         Height [figure dimensions] of panels
         """
-        return self.t.top - self.b.bottom
+        return self.t.panel_top - self.b.panel_bottom
 
     @property
     def tag_width(self) -> float:
@@ -945,6 +991,24 @@ class LayoutSpaces:
         """
         return self.b.tag_height
 
+    @property
+    def left_axis_title_clearance(self) -> float:
+        """
+        Distance between the left y-axis title and the panel
+
+        In figure dimensions.
+        """
+        return self.l.axis_title_clearance
+
+    @property
+    def bottom_axis_title_clearance(self) -> float:
+        """
+        Distance between the bottom x-axis title and the panel
+
+        In figure dimensions.
+        """
+        return self.b.axis_title_clearance
+
     def increase_horizontal_plot_margin(self, dw: float):
         """
         Increase the plot_margin to the right & left of the panels
@@ -981,8 +1045,8 @@ class LayoutSpaces:
 
         This is the area in which the panels are drawn.
         """
-        x1, x2 = self.l.left, self.r.right
-        y1, y2 = self.b.bottom, self.t.top
+        x1, x2 = self.l.panel_left, self.r.panel_right
+        y1, y2 = self.b.panel_bottom, self.t.panel_top
         return ((x1, y1), (x2, y2))
 
     def _calculate_panel_spacing(self) -> GridSpecParams:
@@ -1003,10 +1067,10 @@ class LayoutSpaces:
             raise TypeError(f"Unknown type of facet: {type(self.plot.facet)}")
 
         return GridSpecParams(
-            self.l.left_relative,
-            self.r.right_relative,
-            self.t.top_relative,
-            self.b.bottom_relative,
+            self.l.panel_left_relative,
+            self.r.panel_right_relative,
+            self.t.panel_top_relative,
+            self.b.panel_bottom_relative,
             wspace,
             hspace,
         )
@@ -1020,6 +1084,9 @@ class LayoutSpaces:
         ncol = self.plot.facet.ncol
         nrow = self.plot.facet.nrow
 
+        left, right = self.l.panel_left, self.r.panel_right
+        top, bottom = self.t.panel_top, self.b.panel_bottom
+
         # Both spacings are specified as fractions of the figure width
         # Multiply the vertical by (W/H) so that the gullies along both
         # directions are equally spaced.
@@ -1027,8 +1094,8 @@ class LayoutSpaces:
         self.sh = theme.getp("panel_spacing_y") * self.W / self.H
 
         # width and height of axes as fraction of figure width & height
-        self.w = ((self.r.right - self.l.left) - self.sw * (ncol - 1)) / ncol
-        self.h = ((self.t.top - self.b.bottom) - self.sh * (nrow - 1)) / nrow
+        self.w = ((right - left) - self.sw * (ncol - 1)) / ncol
+        self.h = ((top - bottom) - self.sh * (nrow - 1)) / nrow
 
         # Spacing as fraction of axes width & height
         wspace = self.sw / self.w
@@ -1045,6 +1112,9 @@ class LayoutSpaces:
         ncol = facet.ncol
         nrow = facet.nrow
 
+        left, right = self.l.panel_left, self.r.panel_right
+        top, bottom = self.t.panel_top, self.b.panel_bottom
+
         # Both spacings are specified as fractions of the figure width
         self.sw = theme.getp("panel_spacing_x")
         self.sh = theme.getp("panel_spacing_y") * self.W / self.H
@@ -1073,8 +1143,8 @@ class LayoutSpaces:
             ) + self.items.axis_ticks_y_max_width_at("all")
 
         # width and height of axes as fraction of figure width & height
-        self.w = ((self.r.right - self.l.left) - self.sw * (ncol - 1)) / ncol
-        self.h = ((self.t.top - self.b.bottom) - self.sh * (nrow - 1)) / nrow
+        self.w = ((right - left) - self.sw * (ncol - 1)) / ncol
+        self.h = ((top - bottom) - self.sh * (nrow - 1)) / nrow
 
         # Spacing as fraction of axes width & height
         wspace = self.sw / self.w
@@ -1085,8 +1155,8 @@ class LayoutSpaces:
         """
         Calculate spacing parts for facet_null
         """
-        self.w = self.r.right - self.l.left
-        self.h = self.t.top - self.b.bottom
+        self.w = self.r.panel_right - self.l.panel_left
+        self.h = self.t.panel_top - self.b.panel_bottom
         self.sw = 0
         self.sh = 0
         return 0, 0

plotnine/_mpl/text.py

@@ -32,7 +32,7 @@ class StripText(Text):
             "clip_on": False,
             "zorder": 3.3,
             # Since the text can be rotated, it is simpler to anchor it at
-            # the center, align it then do the rotation. Vertically,
+            # the center, align it, then do the rotation. Vertically,
             # center_baseline places the text in the visual center, but
             # only if it is one line. For multiline text, we are better
             # off with plain center.
@@ -45,12 +45,6 @@ class StripText(Text):
         self.draw_info = info
         self.patch = StripTextPatch(self)
 
-        # self.set_horizontalalignment("center")
-        # self.set_verticalalignment(
-        #     "center_baseline" if info.is_oneline else "center"
-        # )
-        # self.set_rotation_mode("anchor")
-
     # TODO: This should really be part of the unit conversions in the
     # margin class.
     @lru_cache(2)

plotnine/composition/__init__.py

@@ -1,10 +1,10 @@
-from ._arrange import Arrange
 from ._beside import Beside
+from ._compose import Compose
 from ._plot_spacer import plot_spacer
 from ._stack import Stack
 
 __all__ = (
-    "Arrange",
+    "Compose",
     "Stack",
     "Beside",
     "plot_spacer",

plotnine/composition/_beside.py

@@ -1,14 +1,16 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from ._arrange import Arrange
+from ._compose import Compose
 
 if TYPE_CHECKING:
     from plotnine.ggplot import ggplot
 
 
-class Beside(Arrange):
+@dataclass
+class Beside(Compose):
     """
     Place plots or compositions side by side
 
@@ -20,6 +22,12 @@ class Beside(Arrange):
         composition | composition
 
     Typically, you will use this class through the `|` operator.
+
+    See Also
+    --------
+    plotnine.composition.Stack : To arrange plots vertically
+    plotnine.composition.plot_spacer : To add a blank space between plots
+    plotnine.composition.Compose : For more on composing plots
     """
 
     @property
@@ -30,7 +38,7 @@ class Beside(Arrange):
     def ncol(self) -> int:
         return len(self)
 
-    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a column
         """
@@ -38,7 +46,7 @@ class Beside(Arrange):
         # operands into a single operation
         return Beside([*self, rhs])
 
-    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a row
         """

plotnine/composition/{_arrange.py → _compose.py}

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 import abc
-from copy import deepcopy
+from copy import copy, deepcopy
 from dataclasses import dataclass, field
 from io import BytesIO
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, overload
 
 from .._utils.ipython import (
     get_display_function,
@@ -25,41 +25,93 @@ if TYPE_CHECKING:
 
 
 @dataclass
-class Arrange:
+class Compose:
     """
     Base class for those that create plot compositions
 
     As a user, you will never directly work with this class, except
-    the operators [`|`](`plotnine.composition.Beside`) and
-    [`/`](`plotnine.composition.Stack`) that are powered by subclasses
-    of this class.
-
-    Parameters
-    ----------
-    operands:
-        The objects to be put together (composed).
+    through the operators that it makes possible.
+    The operators are of two kinds:
+
+    ### 1. Composing Operators
+
+    The combine plots or compositions into a single composition.
+    Both operands are either a plot or a composition.
+
+    `/`
+
+    :   Arrange operands side by side.
+        Powered by the subclass [](`~plotnine.composition.Beside`).
+
+    `|`
+
+    :   Arrange operands vertically.
+        Powered by the subclass [](`~plotnine.composition.Stack`).
+
+    `-`
+
+    :   Arrange operands side by side _and_ at the same nesting level.
+        Also powered by the subclass [](`~plotnine.composition.Beside`).
+
+    ### 2. Plot Modifying Operators
+
+    The modify all or some of the plots in a composition.
+    The left operand is a composition and the right operand is a
+    _plotaddable_; any object that can be added to a `ggplot` object
+    e.g. _geoms_, _stats_, _themes_, _facets_, ... .
+
+    `&`
+
+    :   Add right hand side to all plots in the composition.
+
+    `*`
+
+    :   Add right hand side to all plots in the top-most nesting
+        level of the composition.
+
+    `+`
+
+    :    Add right hand side to the last plot in the composition.
+
+    See Also
+    --------
+    plotnine.composition.Beside : To arrange plots side by side
+    plotnine.composition.Stack : To arrange plots vertically
+    plotnine.composition.plot_spacer : To add a blank space between plots
     """
 
-    operands: list[ggplot | Arrange]
+    items: list[ggplot | Compose]
+    """
+    The objects to be arranged (composed).
+    """
 
     # These are created in the _create_figure method
     figure: Figure = field(init=False, repr=False)
     plotspecs: list[plotspec] = field(init=False, repr=False)
     gridspec: p9GridSpec = field(init=False, repr=False)
 
+    def __post_init__(self):
+        # The way we handle the plots has consequences that would
+        # prevent having a duplicate plot in the composition.
+        # Using copies prevents this.
+        self.items = [
+            op if isinstance(op, Compose) else deepcopy(op)
+            for op in self.items
+        ]
+
     @abc.abstractmethod
-    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a column
         """
 
     @abc.abstractmethod
-    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a row
         """
 
-    def __add__(self, rhs: ggplot | Arrange | PlotAddable) -> Arrange:
+    def __add__(self, rhs: ggplot | Compose | PlotAddable) -> Compose:
         """
         Add rhs to the composition
 
@@ -70,24 +122,36 @@ class Arrange:
         """
         from plotnine import ggplot
 
-        if not isinstance(rhs, (ggplot, Arrange)):
+        if not isinstance(rhs, (ggplot, Compose)):
             cmp = deepcopy(self)
             cmp.last_plot = cmp.last_plot + rhs
             return cmp
-        return self.__class__([*self, rhs])
 
-    def __sub__(self, rhs: ggplot | Arrange) -> Arrange:
+        t1, t2 = type(self).__name__, type(rhs).__name__
+        msg = f"unsupported operand type(s) for +: '{t1}' and '{t2}'"
+        raise TypeError(msg)
+
+    def __sub__(self, rhs: ggplot | Compose) -> Compose:
         """
-        Add the rhs besides the composition
+        Add the rhs onto the composition
 
         Parameters
         ----------
         rhs:
             What to place besides the composition
         """
-        return self.__class__([self, rhs])
+        from plotnine import ggplot
+
+        from . import Beside
+
+        if not isinstance(rhs, (ggplot, Compose)):
+            t1, t2 = type(self).__name__, type(rhs).__name__
+            msg = f"unsupported operand type(s) for -: '{t1}' and '{t2}'"
+            raise TypeError(msg)
 
-    def __and__(self, rhs: PlotAddable) -> Arrange:
+        return Beside([self, rhs])
+
+    def __and__(self, rhs: PlotAddable) -> Compose:
         """
         Add rhs to all plots in the composition
 
@@ -98,17 +162,17 @@ class Arrange:
         """
         self = deepcopy(self)
 
-        def add_other(op: Arrange):
-            for item in op:
-                if isinstance(item, Arrange):
+        def add_other(cmp: Compose):
+            for i, item in enumerate(cmp):
+                if isinstance(item, Compose):
                     add_other(item)
                 else:
-                    item += rhs
+                    cmp[i] = item + copy(rhs)
 
         add_other(self)
         return self
 
-    def __mul__(self, rhs: PlotAddable) -> Arrange:
+    def __mul__(self, rhs: PlotAddable) -> Compose:
         """
         Add rhs to the outermost nesting level of the composition
 
@@ -121,22 +185,38 @@ class Arrange:
 
         self = deepcopy(self)
 
-        for item in self:
+        for i, item in enumerate(self):
             if isinstance(item, ggplot):
-                item += rhs
+                self[i] = item + copy(rhs)
+
         return self
 
     def __len__(self) -> int:
         """
         Number of operand
         """
-        return len(self.operands)
+        return len(self.items)
 
-    def __iter__(self) -> Iterator[ggplot | Arrange]:
+    def __iter__(self) -> Iterator[ggplot | Compose]:
         """
-        Return an iterable of all the operands
+        Return an iterable of all the items
         """
-        return iter(self.operands)
+        return iter(self.items)
+
+    @overload
+    def __getitem__(self, index: int) -> ggplot | Compose: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[ggplot | Compose]: ...
+
+    def __getitem__(
+        self,
+        index: int | slice,
+    ) -> ggplot | Compose | list[ggplot | Compose]:
+        return self.items[index]
+
+    def __setitem__(self, key, value):
+        self.items[key] = value
 
     def _ipython_display_(self):
         """
@@ -165,7 +245,7 @@ class Arrange:
         """
         from plotnine import ggplot
 
-        last_operand = self.operands[-1]
+        last_operand = self.items[-1]
         if isinstance(last_operand, ggplot):
             return last_operand
         else:
@@ -178,9 +258,9 @@ class Arrange:
         """
         from plotnine import ggplot
 
-        last_operand = self.operands[-1]
+        last_operand = self.items[-1]
         if isinstance(last_operand, ggplot):
-            self.operands[-1] = plot
+            self.items[-1] = plot
         else:
             last_operand.last_plot = plot
 
@@ -232,7 +312,7 @@ class Arrange:
         from plotnine._mpl.gridspec import p9GridSpec
 
         def _make_plotspecs(
-            cmp: Arrange, parent_gridspec: p9GridSpec | None
+            cmp: Compose, parent_gridspec: p9GridSpec | None
         ) -> Generator[plotspec]:
             """
             Return the plot specification for each subplot in the composition
@@ -340,7 +420,7 @@ class Arrange:
         dpi :
             DPI to use for raster graphics. If None, defaults to using
             the `dpi` of theme to the first plot.
-        kwargs :
+        **kwargs :
             These are ignored. Here to "softly" match the API of
             `ggplot.save()`.
         """
@@ -355,7 +435,7 @@ class Arrange:
 
 @dataclass
 class plot_composition_context:
-    cmp: Arrange
+    cmp: Compose
     show: bool
 
     def __post_init__(self):

plotnine/composition/_plot_spacer.py

@@ -17,6 +17,12 @@ class plot_spacer(ggplot):
 
         The color can also be modified by adding a [](`~plotnine.theme`)
         and setting the [](`~plotnine.themes.themeable.plot_background`).
+
+    See Also
+    --------
+    plotnine.composition.Beside : To arrange plots side by side
+    plotnine.composition.Stack : To arrange plots vertically
+    plotnine.composition.Compose : For more on composing plots
     """
 
     def __init__(