plotnine 0.15.0a5__py3-none-any.whl → 0.15.0a7__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/_utils/__init__.py

@@ -1194,3 +1194,16 @@ def va_as_float(va: VerticalJustification | float) -> float:
         "center_baseline": 0.5,
     }
     return lookup[va] if isinstance(va, str) else va
+
+
+def has_alpha_channel(c: str | tuple) -> bool:
+    """
+    Return True if c a color with an alpha value
+
+    Either a 9 character hex string e.g. #AABBCC88 or
+    an RGBA tuple e.g. (.6, .7, .8, .5)
+    """
+    if isinstance(c, str):
+        return c.startswith("#") and len(c) == 9
+    else:
+        return color_utils.is_color_tuple(c) and len(c) == 4

plotnine/composition/__init__.py

@@ -0,0 +1,11 @@
+from ._arrange import Arrange
+from ._beside import Beside
+from ._plot_spacer import plot_spacer
+from ._stack import Stack
+
+__all__ = (
+    "Arrange",
+    "Stack",
+    "Beside",
+    "plot_spacer",
+)

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

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import abc
 from copy import deepcopy
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from io import BytesIO
 from typing import TYPE_CHECKING
 
@@ -24,37 +24,57 @@ if TYPE_CHECKING:
     from plotnine.ggplot import PlotAddable, ggplot
 
 
-class Compose:
+@dataclass
+class Arrange:
     """
-    Arrange two or more plots
+    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).
+
+    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
     """
 
-    def __init__(self, operands: list[ggplot | Compose]):
-        self.operands = operands
+    operands: list[ggplot | Arrange]
 
-        # These are created in the _create_figure method
-        self.figure: Figure
-        self.plotspecs: list[plotspec]
-        self.gridspec: p9GridSpec
+    # 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.operands = [
+            op if isinstance(op, Arrange) else deepcopy(op)
+            for op in self.operands
+        ]
 
     @abc.abstractmethod
-    def __or__(self, rhs: ggplot | Compose) -> Compose:
+    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
         """
         Add rhs as a column
         """
 
     @abc.abstractmethod
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
         """
         Add rhs as a row
         """
 
-    def __add__(self, rhs: ggplot | Compose | PlotAddable) -> Compose:
+    def __add__(self, rhs: ggplot | Arrange | PlotAddable) -> Arrange:
         """
         Add rhs to the composition
 
@@ -65,15 +85,15 @@ class Compose:
         """
         from plotnine import ggplot
 
-        if not isinstance(rhs, (ggplot, Compose)):
+        if not isinstance(rhs, (ggplot, Arrange)):
             cmp = deepcopy(self)
             cmp.last_plot = cmp.last_plot + rhs
             return cmp
         return self.__class__([*self, rhs])
 
-    def __sub__(self, rhs: ggplot | Compose) -> Compose:
+    def __sub__(self, rhs: ggplot | Arrange) -> Arrange:
         """
-        Add the rhs besides the composition
+        Add the rhs onto the composition
 
         Parameters
         ----------
@@ -82,7 +102,7 @@ class Compose:
         """
         return self.__class__([self, rhs])
 
-    def __and__(self, rhs: PlotAddable) -> Compose:
+    def __and__(self, rhs: PlotAddable) -> Arrange:
         """
         Add rhs to all plots in the composition
 
@@ -93,9 +113,9 @@ class Compose:
         """
         self = deepcopy(self)
 
-        def add_other(op: Compose):
+        def add_other(op: Arrange):
             for item in op:
-                if isinstance(item, Compose):
+                if isinstance(item, Arrange):
                     add_other(item)
                 else:
                     item += rhs
@@ -103,7 +123,7 @@ class Compose:
         add_other(self)
         return self
 
-    def __mul__(self, rhs: PlotAddable) -> Compose:
+    def __mul__(self, rhs: PlotAddable) -> Arrange:
         """
         Add rhs to the outermost nesting level of the composition
 
@@ -127,7 +147,7 @@ class Compose:
         """
         return len(self.operands)
 
-    def __iter__(self) -> Iterator[ggplot | Compose]:
+    def __iter__(self) -> Iterator[ggplot | Arrange]:
         """
         Return an iterable of all the operands
         """
@@ -227,7 +247,7 @@ class Compose:
         from plotnine._mpl.gridspec import p9GridSpec
 
         def _make_plotspecs(
-            cmp: Compose, parent_gridspec: p9GridSpec | None
+            cmp: Arrange, parent_gridspec: p9GridSpec | None
         ) -> Generator[plotspec]:
             """
             Return the plot specification for each subplot in the composition
@@ -289,7 +309,7 @@ class Compose:
 
     def draw(self, *, show: bool = False) -> Figure:
         """
-        Render the composed plots
+        Render the arranged plots
 
         Parameters
         ----------
@@ -315,9 +335,15 @@ class Compose:
             )
         return figure
 
-    def save(self, filename: str | Path | BytesIO, format: str | None = None):
+    def save(
+        self,
+        filename: str | Path | BytesIO,
+        format: str | None = None,
+        dpi: int | None = None,
+        **kwargs,
+    ):
         """
-        Save a Compose object as an image file
+        Save a composition as an image file
 
         Parameters
         ----------
@@ -326,14 +352,25 @@ class Compose:
         format :
             Image format to use, automatically extract from
             file name extension.
-        """
-        figure = self.draw()
+        dpi :
+            DPI to use for raster graphics. If None, defaults to using
+            the `dpi` of theme to the first plot.
+        kwargs :
+            These are ignored. Here to "softly" match the API of
+            `ggplot.save()`.
+        """
+        from plotnine import theme
+
+        # To set the dpi, we only need to change the dpi of
+        # the last plot and theme gets added to the last plot
+        plot = (self + theme(dpi=dpi)) if dpi else self
+        figure = plot.draw()
         figure.savefig(filename, format=format)
 
 
 @dataclass
 class plot_composition_context:
-    cmp: Compose
+    cmp: Arrange
     show: bool
 
     def __post_init__(self):
@@ -368,95 +405,3 @@ class plot_composition_context:
                 plt.close(self.cmp.figure)
 
         self._rc_context.__exit__(exc_type, exc_value, exc_traceback)
-
-
-class OR(Compose):
-    """
-    Compose by adding a column
-    """
-
-    @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 OR([*self, rhs])
-
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a row
-        """
-        return DIV([self, rhs])
-
-
-class DIV(Compose):
-    """
-    Compose by adding a row
-    """
-
-    @property
-    def nrow(self) -> int:
-        return len(self)
-
-    @property
-    def ncol(self) -> int:
-        return 1
-
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a row
-        """
-        # This is an adjacent div i.e. (DIV | rhs) so we collapse the
-        # operands into a single operation
-        return DIV([*self, rhs])
-
-    def __or__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a column
-        """
-        return OR([self, rhs])
-
-
-class ADD(Compose):
-    """
-    Compose by adding
-    """
-
-    @property
-    def nrow(self) -> int:
-        from plotnine.facets.facet_wrap import wrap_dims
-
-        return wrap_dims(len(self))[0]
-
-    @property
-    def ncol(self) -> int:
-        from plotnine.facets.facet_wrap import wrap_dims
-
-        return wrap_dims(len(self))[1]
-
-    def __or__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a column
-        """
-        return OR([self, rhs])
-
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a row
-        """
-        return DIV([self, rhs])
-
-    def __sub__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a column
-        """
-        return OR([self, rhs])

plotnine/composition/_beside.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ._arrange import Arrange
+
+if TYPE_CHECKING:
+    from plotnine.ggplot import ggplot
+
+
+@dataclass
+class Beside(Arrange):
+    """
+    Place plots or compositions side by side
+
+    **Usage**
+
+        plot | plot
+        plot | composition
+        composition | plot
+        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
+    """
+
+    @property
+    def nrow(self) -> int:
+        return 1
+
+    @property
+    def ncol(self) -> int:
+        return len(self)
+
+    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+        """
+        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])
+
+    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+        """
+        Add rhs as a row
+        """
+        from ._stack import Stack
+
+        return Stack([self, rhs])