plotnine 0.15.0.dev3__py3-none-any.whl → 0.15.2__py3-none-any.whl

plotnine/_mpl/layout_manager/_spaces.py

@@ -14,8 +14,9 @@ from __future__ import annotations
 from abc import ABC
 from dataclasses import dataclass, field, fields
 from functools import cached_property
-from typing import TYPE_CHECKING
+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
@@ -26,7 +27,8 @@ if TYPE_CHECKING:
 
     from plotnine import ggplot
     from plotnine._mpl.gridspec import p9GridSpec
-
+    from plotnine.iapi import outside_legend
+    from plotnine.typing import Side
 
 # Note
 # Margins around the plot are specified in figure coordinates
@@ -69,16 +71,12 @@ class _side_spaces(ABC):
     """
 
     items: LayoutItems
-    alignment_margin: float = 0
-    """
-    A margin added to align this plot 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.
-    """
 
     def __post_init__(self):
+        self.side: Side = cast("Side", self.__class__.__name__[:-7])
+        """
+        Side of the panel(s) that this class applies to
+        """
         self._calculate()
 
     def _calculate(self):
@@ -132,17 +130,21 @@ class _side_spaces(ABC):
         values e.g. 0.2, instead of just left, right, top,  bottom &
         center.
         """
-        return (0, 0)
+        if not self.has_legend:
+            return (0, 0)
+
+        ol: outside_legend = getattr(self.items.legends, self.side)
+        return self.items.calc.size(ol.box)
 
     @cached_property
-    def _legend_width(self) -> float:
+    def legend_width(self) -> float:
         """
         Return width of legend in figure coordinates
         """
         return self._legend_size[0]
 
     @cached_property
-    def _legend_height(self) -> float:
+    def legend_height(self) -> float:
         """
         Return height of legend in figure coordinates
         """
@@ -204,6 +206,81 @@ class _side_spaces(ABC):
         """
         return self.offset + rel_value
 
+    @property
+    def has_tag(self) -> bool:
+        """
+        Return True if the space/margin to this side of the panel has a tag
+
+        If it does, then it will be included in the layout
+        """
+        getp = self.items.plot.theme.getp
+        return getp("plot_tag_location") == "margin" and self.side in getp(
+            "plot_tag_position"
+        )
+
+    @property
+    def has_legend(self) -> bool:
+        """
+        Return True if the space/margin to this side of the panel has a legend
+
+        If it does, then it will be included in the layout
+        """
+        if not self.items.legends:
+            return False
+        return hasattr(self.items.legends, self.side)
+
+    @property
+    def tag_width(self) -> float:
+        """
+        The width of the tag including the margins
+
+        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
+        """
+        return 0
+
+    @property
+    def tag_height(self) -> float:
+        """
+        The height of the tag including the margins
+
+        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):
@@ -214,14 +291,63 @@ class left_spaces(_side_spaces):
     """
 
     plot_margin: float = 0
+    tag_alignment: float = 0
+    """
+    Space added to align the tag in this plot with others in a composition
+
+    This value is calculated during the layout process, and it ensures that
+    all tags on this side of the plot take up the same amount of space in
+    the margin. e.g. from
+
+         ------------------------------------
+        | plot_margin | tag | artists        |
+        |------------------------------------|
+        | plot_margin | A long tag | artists |
+         ------------------------------------
+
+    to
+
+         ------------------------------------
+        | plot_margin |     tag    | artists |
+        |------------------------------------|
+        | plot_margin | A long tag | artists |
+         ------------------------------------
+
+    And the tag is justified within that space e.g if ha="left" we get
+
+         ------------------------------------
+        | plot_margin | tag        | artists |
+        |------------------------------------|
+        | plot_margin | A long tag | artists |
+         ------------------------------------
+
+    So, contrary to the order in which the space items are laid out, the 
+    tag_alignment does not necessarily come before the plot_tag.
+    """
     plot_tag_margin_left: float = 0
     plot_tag: float = 0
     plot_tag_margin_right: float = 0
+    margin_alignment: float = 0
+    """
+    Space added to align this plot 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.
+    """
     legend: float = 0
     legend_box_spacing: float = 0
     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
@@ -232,22 +358,16 @@ class left_spaces(_side_spaces):
         calc = self.items.calc
         items = self.items
 
-        # If the plot_tag is in the margin, it is included in the layout.
-        # So we make space for it, including any margins it may have.
-        plot_tag_in_layout = theme.getp(
-            "plot_tag_location"
-        ) == "margin" and "left" in theme.getp("plot_tag_position")
-
         self.plot_margin = theme.getp("plot_margin_left")
 
-        if items.plot_tag and plot_tag_in_layout:
+        if self.has_tag and items.plot_tag:
             m = theme.get_margin("plot_tag").fig
             self.plot_tag_margin_left = m.l
             self.plot_tag = calc.width(items.plot_tag)
             self.plot_tag_margin_right = m.r
 
         if items.legends and items.legends.left:
-            self.legend = self._legend_width
+            self.legend = self.legend_width
             self.legend_box_spacing = theme.getp("legend_box_spacing")
 
         if items.axis_title_y:
@@ -273,13 +393,6 @@ class left_spaces(_side_spaces):
         if adjustment > 0:
             self.plot_margin += adjustment
 
-    @cached_property
-    def _legend_size(self) -> tuple[float, float]:
-        if not (self.items.legends and self.items.legends.left):
-            return (0, 0)
-
-        return self.items.calc.size(self.items.legends.left.box)
-
     @property
     def offset(self) -> float:
         """
@@ -309,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):
@@ -329,6 +442,17 @@ class left_spaces(_side_spaces):
         """
         return self.x1("legend")
 
+    @property
+    def tag_width(self):
+        """
+        The width of the tag including the margins
+        """
+        return (
+            self.plot_tag_margin_left
+            + self.plot_tag
+            + self.plot_tag_margin_right
+        )
+
 
 @dataclass
 class right_spaces(_side_spaces):
@@ -339,36 +463,33 @@ class right_spaces(_side_spaces):
     """
 
     plot_margin: float = 0
+    tag_alignment: float = 0
     plot_tag_margin_right: float = 0
     plot_tag: float = 0
     plot_tag_margin_left: float = 0
+    margin_alignment: float = 0
     legend: float = 0
     legend_box_spacing: float = 0
-    strip_text_y_width_right: float = 0
+    strip_text_y_extra_width: float = 0
 
     def _calculate(self):
         items = self.items
         theme = self.items.plot.theme
         calc = self.items.calc
-        # If the plot_tag is in the margin, it is included in the layout.
-        # So we make space for it, including any margins it may have.
-        plot_tag_in_layout = theme.getp(
-            "plot_tag_location"
-        ) == "margin" and "right" in theme.getp("plot_tag_position")
 
         self.plot_margin = theme.getp("plot_margin_right")
 
-        if items.plot_tag and plot_tag_in_layout:
+        if self.has_tag and items.plot_tag:
             m = theme.get_margin("plot_tag").fig
             self.plot_tag_margin_right = m.r
             self.plot_tag = calc.width(items.plot_tag)
             self.plot_tag_margin_left = m.l
 
         if items.legends and items.legends.right:
-            self.legend = self._legend_width
+            self.legend = self.legend_width
             self.legend_box_spacing = theme.getp("legend_box_spacing")
 
-        self.strip_text_y_width_right = items.strip_text_y_width("right")
+        self.strip_text_y_extra_width = items.strip_text_y_extra_width("right")
 
         # Adjust plot_margin to make room for ylabels that protude well
         # beyond the axes
@@ -378,13 +499,6 @@ class right_spaces(_side_spaces):
         if adjustment > 0:
             self.plot_margin += adjustment
 
-    @cached_property
-    def _legend_size(self) -> tuple[float, float]:
-        if not (self.items.legends and self.items.legends.right):
-            return (0, 0)
-
-        return self.items.calc.size(self.items.legends.right.box)
-
     @property
     def offset(self):
         """
@@ -414,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):
@@ -434,6 +548,17 @@ class right_spaces(_side_spaces):
         """
         return self.x2("legend")
 
+    @property
+    def tag_width(self):
+        """
+        The width of the tag including the margins
+        """
+        return (
+            self.plot_tag_margin_right
+            + self.plot_tag
+            + self.plot_tag_margin_left
+        )
+
 
 @dataclass
 class top_spaces(_side_spaces):
@@ -444,9 +569,11 @@ class top_spaces(_side_spaces):
     """
 
     plot_margin: float = 0
+    tag_alignment: float = 0
     plot_tag_margin_top: float = 0
     plot_tag: float = 0
     plot_tag_margin_bottom: float = 0
+    margin_alignment: float = 0
     plot_title_margin_top: float = 0
     plot_title: float = 0
     plot_title_margin_bottom: float = 0
@@ -455,7 +582,7 @@ class top_spaces(_side_spaces):
     plot_subtitle_margin_bottom: float = 0
     legend: float = 0
     legend_box_spacing: float = 0
-    strip_text_x_height_top: float = 0
+    strip_text_x_extra_height: float = 0
 
     def _calculate(self):
         items = self.items
@@ -463,15 +590,10 @@ class top_spaces(_side_spaces):
         calc = self.items.calc
         W, H = theme.getp("figure_size")
         F = W / H
-        # If the plot_tag is in the margin, it is included in the layout.
-        # So we make space for it, including any margins it may have.
-        plot_tag_in_layout = theme.getp(
-            "plot_tag_location"
-        ) == "margin" and "top" in theme.getp("plot_tag_position")
 
         self.plot_margin = theme.getp("plot_margin_top") * F
 
-        if items.plot_tag and plot_tag_in_layout:
+        if self.has_tag and items.plot_tag:
             m = theme.get_margin("plot_tag").fig
             self.plot_tag_margin_top = m.t
             self.plot_tag = calc.height(items.plot_tag)
@@ -490,10 +612,10 @@ class top_spaces(_side_spaces):
             self.plot_subtitle_margin_bottom = m.b * F
 
         if items.legends and items.legends.top:
-            self.legend = self._legend_height
+            self.legend = self.legend_height
             self.legend_box_spacing = theme.getp("legend_box_spacing") * F
 
-        self.strip_text_x_height_top = items.strip_text_x_height("top")
+        self.strip_text_x_extra_height = items.strip_text_x_extra_height("top")
 
         # Adjust plot_margin to make room for ylabels that protude well
         # beyond the axes
@@ -503,13 +625,6 @@ class top_spaces(_side_spaces):
         if adjustment > 0:
             self.plot_margin += adjustment
 
-    @cached_property
-    def _legend_size(self) -> tuple[float, float]:
-        if not (self.items.legends and self.items.legends.top):
-            return (0, 0)
-
-        return self.items.calc.size(self.items.legends.top.box)
-
     @property
     def offset(self) -> float:
         """
@@ -542,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):
@@ -562,6 +677,17 @@ class top_spaces(_side_spaces):
         """
         return self.y2("legend")
 
+    @property
+    def tag_height(self):
+        """
+        The height of the tag including the margins
+        """
+        return (
+            self.plot_tag_margin_top
+            + self.plot_tag
+            + self.plot_tag_margin_bottom
+        )
+
 
 @dataclass
 class bottom_spaces(_side_spaces):
@@ -572,9 +698,11 @@ class bottom_spaces(_side_spaces):
     """
 
     plot_margin: float = 0
+    tag_alignment: float = 0
     plot_tag_margin_bottom: float = 0
     plot_tag: float = 0
     plot_tag_margin_top: float = 0
+    margin_alignment: float = 0
     plot_caption_margin_bottom: float = 0
     plot_caption: float = 0
     plot_caption_margin_top: float = 0
@@ -583,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
@@ -594,15 +731,10 @@ class bottom_spaces(_side_spaces):
         calc = self.items.calc
         W, H = theme.getp("figure_size")
         F = W / H
-        # If the plot_tag is in the margin, it is included in the layout.
-        # So we make space for it, including any margins it may have.
-        plot_tag_in_layout = theme.getp(
-            "plot_tag_location"
-        ) == "margin" and "bottom" in theme.getp("plot_tag_position")
 
         self.plot_margin = theme.getp("plot_margin_bottom") * F
 
-        if items.plot_tag and plot_tag_in_layout:
+        if self.has_tag and items.plot_tag:
             m = theme.get_margin("plot_tag").fig
             self.plot_tag_margin_bottom = m.b
             self.plot_tag = calc.height(items.plot_tag)
@@ -615,7 +747,7 @@ class bottom_spaces(_side_spaces):
             self.plot_caption_margin_top = m.t * F
 
         if items.legends and items.legends.bottom:
-            self.legend = self._legend_height
+            self.legend = self.legend_height
             self.legend_box_spacing = theme.getp("legend_box_spacing") * F
 
         if items.axis_title_x:
@@ -640,13 +772,6 @@ class bottom_spaces(_side_spaces):
         if adjustment > 0:
             self.plot_margin += adjustment
 
-    @cached_property
-    def _legend_size(self) -> tuple[float, float]:
-        if not (self.items.legends and self.items.legends.bottom):
-            return (0, 0)
-
-        return self.items.calc.size(self.items.legends.bottom.box)
-
     @property
     def offset(self) -> float:
         """
@@ -679,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):
@@ -699,6 +824,17 @@ class bottom_spaces(_side_spaces):
         """
         return self.y1("legend")
 
+    @property
+    def tag_height(self):
+        """
+        The height of the tag including the margins
+        """
+        return (
+            self.plot_tag_margin_bottom
+            + self.plot_tag
+            + self.plot_tag_margin_top
+        )
+
 
 @dataclass
 class LayoutSpaces:
@@ -802,14 +938,76 @@ 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:
+        """
+        Width [figure dimensions] of space taken up by the tag
+        """
+        # Atleast one of these is zero
+        return max(self.l.tag_width, self.r.tag_width)
+
+    @property
+    def tag_height(self) -> float:
+        """
+        Height [figure dimensions] of space taken up by the tag
+        """
+        # Atleast one of these is zero
+        return max(self.t.tag_height, self.b.tag_height)
+
+    @property
+    def left_tag_width(self) -> float:
+        """
+        Width [figure dimensions] of space taken up by a left tag
+        """
+        return self.l.tag_width
+
+    @property
+    def right_tag_width(self) -> float:
+        """
+        Width [figure dimensions] of space taken up by a right tag
+        """
+        return self.r.tag_width
+
+    @property
+    def top_tag_height(self) -> float:
+        """
+        Width [figure dimensions] of space taken up by a top tag
+        """
+        return self.t.tag_height
+
+    @property
+    def bottom_tag_height(self) -> float:
+        """
+        Height [figure dimensions] of space taken up by a bottom tag
+        """
+        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):
         """
@@ -847,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:
@@ -869,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,
         )
@@ -886,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.
@@ -893,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
@@ -911,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
@@ -927,7 +1131,7 @@ class LayoutSpaces:
         # Only interested in the proportion of the strip that
         # does not overlap with the panel
         if strip_align_x > -1:
-            self.sh += self.t.strip_text_x_height_top * (1 + strip_align_x)
+            self.sh += self.t.strip_text_x_extra_height * (1 + strip_align_x)
 
         if facet.free["x"]:
             self.sh += self.items.axis_text_x_max_height_at(
@@ -939,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
@@ -951,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