plotnine 0.15.0a6__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/composition/_arrange.py

@@ -38,6 +38,12 @@ class Arrange:
     ----------
     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
     """
 
     operands: list[ggplot | Arrange]
@@ -47,6 +53,15 @@ class Arrange:
     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 | Arrange) -> Arrange:
         """
@@ -78,7 +93,7 @@ class Arrange:
 
     def __sub__(self, rhs: ggplot | Arrange) -> Arrange:
         """
-        Add the rhs besides the composition
+        Add the rhs onto the composition
 
         Parameters
         ----------

plotnine/composition/_beside.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from ._arrange import Arrange
@@ -8,6 +9,7 @@ if TYPE_CHECKING:
     from plotnine.ggplot import ggplot
 
 
+@dataclass
 class Beside(Arrange):
     """
     Place plots or compositions side by side
@@ -20,6 +22,11 @@ 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
     """
 
     @property

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.Arrange : For more on arranging plots
     """
 
     def __init__(

plotnine/composition/_stack.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from ._arrange import Arrange
@@ -8,6 +9,7 @@ if TYPE_CHECKING:
     from plotnine.ggplot import ggplot
 
 
+@dataclass
 class Stack(Arrange):
     """
     Place plots or compositions on top of each other
@@ -20,6 +22,11 @@ class Stack(Arrange):
         composition / composition
 
     Typically, you will use this class through the `/` operator.
+
+    See Also
+    --------
+    plotnine.composition.Beside : To arrange plots side by side
+    plotnine.composition.plot_spacer : To add a blank space between plots
     """
 
     @property

plotnine/geoms/geom_bar.py

@@ -32,6 +32,7 @@ class geom_bar(geom_rect):
     See Also
     --------
     plotnine.geom_histogram
+    plotnine.stat_count : The default `stat` for this `geom`.
     """
 
     REQUIRED_AES = {"x", "y"}

plotnine/geoms/geom_bin_2d.py

@@ -17,6 +17,10 @@ class geom_bin_2d(geom_rect):
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_bin_2d : The default stat for this `geom`.
     """
 
     DEFAULT_PARAMS = {"stat": "bin_2d", "position": "identity", "na_rm": False}

plotnine/geoms/geom_boxplot.py

@@ -70,6 +70,10 @@ class geom_boxplot(geom):
     fatten : float, default=2
         A multiplicative factor used to increase the size of the
         middle bar across the box.
+
+    See Also
+    --------
+    plotnine.stat_boxplot : The default `stat` for this `geom`.
     """
 
     DEFAULT_AES = {

plotnine/geoms/geom_count.py

@@ -16,6 +16,10 @@ class geom_count(geom_point):
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_sum : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {"stat": "sum", "position": "identity", "na_rm": False}

plotnine/geoms/geom_density_2d.py

@@ -14,6 +14,10 @@ class geom_density_2d(geom_path):
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_density_2d : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {

plotnine/geoms/geom_dotplot.py

@@ -46,7 +46,7 @@ class geom_dotplot(geom):
 
     See Also
     --------
-    plotnine.stat_bindot
+    plotnine.stat_bindot : The default `stat` for this `geom`.
     """
 
     DEFAULT_AES = {"alpha": 1, "color": "black", "fill": "black"}

plotnine/geoms/geom_histogram.py

@@ -15,7 +15,7 @@ class geom_histogram(geom_bar):
 
     See Also
     --------
-    plotnine.geom_bar
+    plotnine.geom_bar : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {"stat": "bin", "position": "stack", "na_rm": False}

plotnine/geoms/geom_pointdensity.py

@@ -12,6 +12,10 @@ class geom_pointdensity(geom_point):
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_pointdensity : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {

plotnine/geoms/geom_qq.py

@@ -12,6 +12,10 @@ class geom_qq(geom_point):
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_qq : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {"stat": "qq", "position": "identity", "na_rm": False}

plotnine/geoms/geom_qq_line.py

@@ -12,6 +12,10 @@ class geom_qq_line(geom_path):
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_qq_line : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {

plotnine/geoms/geom_quantile.py

@@ -16,6 +16,10 @@ class geom_quantile(geom_path):
         Line end style. This option is applied for solid linetypes.
     linejoin : Literal["round", "miter", "bevel"], default="round"
         Line join style. This option is applied for solid linetypes.
+
+    See Also
+    --------
+    plotnine.stat_quantile : The default `stat` for this `geom`.
     """
 
     DEFAULT_AES = {

plotnine/geoms/geom_sina.py

@@ -20,7 +20,7 @@ class geom_sina(geom_point):
 
     See Also
     --------
-    plotnine.stat_sina
+    plotnine.stat_sina : The default `stat` for this `geom`.
 
     References
     ----------

plotnine/geoms/geom_smooth.py

@@ -34,6 +34,10 @@ class geom_smooth(geom):
         How much (vertically) of the legend box should be filled by
         the color that indicates the confidence intervals. Should be
         in the range [0, 1].
+
+    See Also
+    --------
+    plotnine.stat_smooth : The default `stat` for this `geom`.
     """
 
     DEFAULT_AES = {

plotnine/geoms/geom_violin.py

@@ -45,6 +45,10 @@ class geom_violin(geom):
         'left-right'  # Alternate (left first) half violins by the group
         'right-left'  # Alternate (right first) half violins by the group
         ```
+
+    See Also
+    --------
+    plotnine.stat_ydensity : The default `stat` for this `geom`.
     """
 
     DEFAULT_AES = {

plotnine/stats/stat_bin.py

@@ -53,6 +53,10 @@ class stat_bin(stat):
     pad : bool, default=False
         If `True`{.py}, adds empty bins at either side of x.
         This ensures that frequency polygons touch 0.
+
+    See Also
+    --------
+    plotnine.histogram : The default `geom` for this `stat`.
     """
 
     _aesthetics_doc = """

plotnine/stats/stat_bin_2d.py

@@ -35,6 +35,10 @@ class stat_bin_2d(stat):
         the stories in your data.
     drop : bool, default=False
         If `True`{.py}, removes all cells with zero counts.
+
+    See Also
+    --------
+    plotnine.geom_rect : The default `geom` for this `stat`.
     """
 
     _aesthetics_doc = """

plotnine/stats/stat_bindot.py

@@ -68,6 +68,7 @@ class stat_bindot(stat):
 
     See Also
     --------
+    plotnine.geom_dotplot : The default `geom` for this `stat`.
     plotnine.stat_bin
     """
 

plotnine/stats/stat_boxplot.py

@@ -22,7 +22,7 @@ class stat_boxplot(stat):
 
     See Also
     --------
-    plotnine.geom_boxplot
+    plotnine.geom_boxplot: The default `geom` for this `stat`.
     """
 
     _aesthetics_doc = """

plotnine/stats/stat_count.py

@@ -23,6 +23,7 @@ class stat_count(stat):
 
     See Also
     --------
+    plotnine.geom_histogram : The default `geom` for this `stat`.
     plotnine.stat_bin
     """
 

plotnine/stats/stat_density.py

@@ -85,7 +85,7 @@ class stat_density(stat):
 
     See Also
     --------
-    plotnine.geom_density
+    plotnine.geom_density : The default `geom` for this `stat`.
     statsmodels.nonparametric.kde.KDEUnivariate
     statsmodels.nonparametric.kde.KDEUnivariate.fit
     """

plotnine/stats/stat_density_2d.py

@@ -37,6 +37,7 @@ class stat_density_2d(stat):
 
     See Also
     --------
+    plotnine.geom_density_2d : The default `geom` for this `stat`.
     statsmodels.nonparametric.kernel_density.KDEMultivariate
     scipy.stats.gaussian_kde
     sklearn.neighbors.KernelDensity

plotnine/stats/stat_ecdf.py

@@ -25,7 +25,7 @@ class stat_ecdf(stat):
 
     See Also
     --------
-    plotnine.geom_step
+    plotnine.geom_step : The default `geom` for this `stat`.
     """
 
     _aesthetics_doc = """

plotnine/stats/stat_ellipse.py

@@ -37,6 +37,10 @@ class stat_ellipse(stat):
         The confidence level at which to draw the ellipse.
     segments : int, default=51
         Number of segments to be used in drawing the ellipse.
+
+    See Also
+    --------
+    plotnine.geom_path : The default `geom` for this `stat`.
     """
 
     REQUIRED_AES = {"x", "y"}