plotnine 0.16.0a12__tar.gz → 0.16.0a13__tar.gz

{plotnine-0.16.0a12 → plotnine-0.16.0a13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotnine
-Version: 0.16.0a12
+Version: 0.16.0a13
 Summary: A Grammar of Graphics for Python
 Author-email: Hassan Kibirige <has2k1@gmail.com>
 License: The MIT License (MIT)

{plotnine-0.16.0a12 → plotnine-0.16.0a13}/doc/changelog.qmd

@@ -21,6 +21,10 @@ title: Changelog
 - [](:class:`~plotnine.composition.plot_layout`) gained a `design` parameter for
   patchwork-style text-grid layouts.
 
+- [](:class:`~plotnine.composition.plot_layout`) gained `axes` and `axis_title`
+  parameters. Use them to show an axis, or an axis title, once for plots in a
+  composition that share it.
+
 - You can now pass a sequence of horizontal and vertical alignment (ha & va) values in
   element_text for colorbars.
 
@@ -179,6 +183,13 @@ title: Changelog
   [](:class:`~plotnine.geom_point`) when the shape is mapped to variable with missing
   values.
 
+- Specific theme elements now override blank general elements. For example,
+  adding `theme(axis_text_x_bottom=element_text(size=14))` to
+  [](:class:`~plotnine.theme_void`) displays the bottom x-axis tick labels and
+  reserves space for them. Previously, the blank `axis_text_x` element
+  prevented layout from reserving their space, so the labels could render
+  outside the figure.
+
 ### Enhancements
 
 - The `factor` function available when evaluating expressions in

{plotnine-0.16.0a12 → plotnine-0.16.0a13}/plotnine/_mpl/layout_manager/_composition_side_space.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from functools import cached_property
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from plotnine._mpl.layout_manager._layout_tree import LayoutTree
 from plotnine._mpl.layout_manager._plot_side_space import PlotSideSpaces
@@ -10,6 +10,7 @@ from ._composition_layout_items import CompositionLayoutItems
 from ._side_space import GridSpecParams, _side_space
 
 if TYPE_CHECKING:
+    from plotnine import ggplot
     from plotnine.composition._compose import Compose
     from plotnine.iapi import outside_legend
 
@@ -442,11 +443,29 @@ class CompositionSideSpaces:
 
     def _create_plot_sidespaces(self):
         """
-        Create sidespaces for all the plots in the composition
+        Create plot side spaces and collected axis title spans
+
+        Each span retains its plots' side spaces, so its bounds reflect later
+        panel resizing.
         """
+        from plotnine.composition._axis_collection import PanelSpan
+
         for plot in self.cmp.iter_plots_all():
             plot._sidespaces = PlotSideSpaces(plot)
 
+        for cmp in self.cmp.iter_compositions_all():
+            for position, sides in cmp._collected_spans.items():
+                keeper = cast("ggplot", cmp.items[position])
+                keeper._sidespaces.axis_title_span = {
+                    side: PanelSpan(
+                        tuple(
+                            cast("ggplot", cmp.items[i])._sidespaces
+                            for i in positions
+                        )
+                    )
+                    for side, positions in sides.items()
+                }
+
     def resize_gridspec(self):
         """
         Apply the space calculations to the sub_gridspec

{plotnine-0.16.0a12 → plotnine-0.16.0a13}/plotnine/_mpl/layout_manager/_grid.py

@@ -1,6 +1,8 @@
-from collections.abc import Iterator
+from __future__ import annotations
+
 from dataclasses import InitVar, dataclass
 from typing import (
+    TYPE_CHECKING,
     Callable,
     Generic,
     Literal,
@@ -11,6 +13,11 @@ from typing import (
 
 import numpy as np
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from plotnine.typing import Side
+
 T = TypeVar("T")
 
 Rect = tuple[int, int, int, int]
@@ -19,14 +26,24 @@ Rect = tuple[int, int, int, int]
 
 @dataclass
 class Grid(Generic[T]):
+    """
+    Rectangular grid of items that occupy individual cells
+
+    Items fill the grid in row-major or column-major order. Unfilled cells
+    contain `None`.
+    """
+
     nrow: InitVar[int]
+    """Number of rows in the grid"""
+
     ncol: InitVar[int]
+    """Number of columns in the grid"""
+
     items: InitVar[Sequence[T]]
+    """Items to place in the grid"""
+
     order: InitVar[Literal["row_major", "col_major"]] = "row_major"
-    """
-    Put items into the grid left->right, top->bottom starting at `start`.
-    Unfilled cells remain None. Returns the number of items written.
-    """
+    """Order in which to fill the cells"""
 
     def __post_init__(
         self,
@@ -151,7 +168,7 @@ class Grid(Generic[T]):
 
     def items_on_edge(
         self,
-        side: Literal["top", "bottom", "left", "right"],
+        side: Side,
         idx: int,
     ) -> list[T]:
         """
@@ -179,6 +196,91 @@ class Grid(Generic[T]):
         cells = self[idx, :] if side in ("top", "bottom") else self[:, idx]
         return [n for n in cells if n is not None]
 
+    def _rect_of(self, item: T) -> Rect:
+        """
+        Return the inclusive cell bounds occupied by an item
+
+        Return the first matching cell when the same object occupies
+        more than one cell.
+
+        Parameters
+        ----------
+        item
+            Item to find. Identity matching supports objects with custom
+            equality.
+
+        Returns
+        -------
+        out
+            Inclusive `(r0, r1, c0, c1)` cell bounds.
+
+        Raises
+        ------
+        ValueError
+            If the item is not in the grid.
+        """
+        nrow, ncol = self._grid.shape
+        for r in range(nrow):
+            for c in range(ncol):
+                if self._grid[r, c] is item:
+                    return (r, r, c, c)
+        raise ValueError(f"{item!r} is not in the grid")
+
+    def is_outermost(self, item: T, side: Side) -> bool:
+        """
+        Return whether no item lies beyond `item` on `side`
+
+        An item is outermost on its bottom when every cell below the
+        columns it covers is empty, and correspondingly for the other
+        three sides. In a full grid this is the last row or column; in a
+        ragged one an item can be outermost from an interior cell.
+
+        Parameters
+        ----------
+        item
+            Item to inspect, matched by identity.
+        side
+            Side of the grid to look beyond.
+
+        Returns
+        -------
+        out
+            Whether every cell beyond the item on that side is empty.
+        """
+        r0, r1, c0, c1 = self._rect_of(item)
+        if side == "top":
+            beyond = self._grid[:r0, c0 : c1 + 1]
+        elif side == "bottom":
+            beyond = self._grid[r1 + 1 :, c0 : c1 + 1]
+        elif side == "left":
+            beyond = self._grid[r0 : r1 + 1, :c0]
+        else:
+            beyond = self._grid[r0 : r1 + 1, c1 + 1 :]
+        return all(n is None for n in beyond.flat)
+
+    def edge_index(self, item: T, side: Side) -> int:
+        """
+        Return the row or column of `item`'s `side` edge
+
+        The inverse of `items_on_edge`: the index it returns is the one
+        that would list `item` for that side.
+
+        Parameters
+        ----------
+        item
+            Item in the grid, matched by identity.
+        side
+            Side of the item to locate.
+
+        Returns
+        -------
+        out
+            Row index for `"top"` and `"bottom"`, column index for
+            `"left"` and `"right"`.
+        """
+        r0, r1, c0, c1 = self._rect_of(item)
+        return {"top": r0, "bottom": r1, "left": c0, "right": c1}[side]
+
 
 class DesignGrid(Grid[T]):
     """
@@ -264,7 +366,7 @@ class DesignGrid(Grid[T]):
 
     def items_on_edge(
         self,
-        side: Literal["top", "bottom", "left", "right"],
+        side: Side,
         idx: int,
     ) -> list[T]:
         # An item's top/bottom edge is its r0/r1; left/right is c0/c1.
@@ -276,3 +378,11 @@ class DesignGrid(Grid[T]):
             if edge == idx:
                 out.append(item)
         return out
+
+    def _rect_of(self, item: T) -> Rect:
+        # Use the recorded span instead of treating its first cell as the
+        # whole item.
+        for it, rect in zip(self._items, self._rects):
+            if it is item:
+                return rect
+        raise ValueError(f"{item!r} is not in the grid")

{plotnine-0.16.0a12 → plotnine-0.16.0a13}/plotnine/_mpl/layout_manager/_layout_tree.py

@@ -6,7 +6,6 @@ from typing import TYPE_CHECKING, Iterator, cast
 
 import numpy as np
 
-from ._grid import Grid
 from ._plot_side_space import PlotSideSpaces
 
 if TYPE_CHECKING:
@@ -21,6 +20,8 @@ if TYPE_CHECKING:
     )
     from plotnine.composition import Compose
 
+    from ._grid import Grid
+
     Node: TypeAlias = "PlotSideSpaces | LayoutTree"
 
 
@@ -172,18 +173,7 @@ class LayoutTree:
             else:
                 nodes.append(LayoutTree.create(item))
 
-        if (spec := getattr(cmp, "_design_spec", None)) is not None:
-            grid = spec.make_grid(nodes)
-        else:
-            order = "row_major" if cmp.layout.byrow else "col_major"
-            grid = Grid["Node"](
-                cast("int", cmp.layout.nrow),
-                cast("int", cmp.layout.ncol),
-                nodes,
-                order=order,
-            )
-
-        return LayoutTree(cmp, nodes, grid)
+        return LayoutTree(cmp, nodes, cmp._make_grid(nodes))
 
     @cached_property
     def sub_compositions(self) -> list[LayoutTree]:

{plotnine-0.16.0a12 → plotnine-0.16.0a13}/plotnine/_mpl/layout_manager/_plot_layout_items.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, cast
 from matplotlib.text import Text
 
 from plotnine._utils import ha_as_float, side_artists, va_as_float
+from plotnine.composition._axis_collection import PanelSpan
 from plotnine.composition._compose import Compose
 from plotnine.exceptions import PlotnineError
 
@@ -691,22 +692,30 @@ class PlotLayoutItems:
         if self.axis_title_x_bottom:
             ha = theme.getp(("axis_title_x_bottom", "ha"), "center")
             self.axis_title_x_bottom.set_y(spaces.b.y1("axis_title"))
-            justify.horizontally_about(self.axis_title_x_bottom, ha, "panel")
+            _justify_axis_title(
+                justify, spaces, self.axis_title_x_bottom, ha, "bottom"
+            )
 
         if self.axis_title_x_top:
             ha = theme.getp(("axis_title_x_top", "ha"), "center")
             self.axis_title_x_top.set_y(spaces.t.y1("axis_title"))
-            justify.horizontally_about(self.axis_title_x_top, ha, "panel")
+            _justify_axis_title(
+                justify, spaces, self.axis_title_x_top, ha, "top"
+            )
 
         if self.axis_title_y_left:
             va = theme.getp(("axis_title_y_left", "va"), "center")
             self.axis_title_y_left.set_x(spaces.l.x1("axis_title"))
-            justify.vertically_about(self.axis_title_y_left, va, "panel")
+            _justify_axis_title(
+                justify, spaces, self.axis_title_y_left, va, "left"
+            )
 
         if self.axis_title_y_right:
             va = theme.getp(("axis_title_y_right", "va"), "center")
             self.axis_title_y_right.set_x(spaces.r.x1("axis_title"))
-            justify.vertically_about(self.axis_title_y_right, va, "panel")
+            _justify_axis_title(
+                justify, spaces, self.axis_title_y_right, va, "right"
+            )
 
         if self.legends:
             _position_legends(self.legends, spaces)
@@ -1133,6 +1142,40 @@ def _text_is_visible(text: Text) -> bool:
     return text.get_visible() and text._text  # type: ignore
 
 
+def _justify_axis_title(
+    justify: TextJustifier,
+    spaces: PlotSideSpaces,
+    text: Text,
+    ratio: float,
+    side: Side,
+):
+    """
+    Position an axis title across the panels it labels
+
+    A collected title spans every panel it labels. An uncollected title uses
+    the plot's own panel bounds, so its span contains only that plot's
+    panels.
+
+    Parameters
+    ----------
+    justify :
+        Text positioner for figure-space bounds.
+    spaces :
+        Side spaces for the plot that draws the title.
+    text :
+        Axis title to position.
+    ratio :
+        Horizontal or vertical alignment within the span.
+    side :
+        Side containing the title.
+    """
+    span = spaces.axis_title_span.get(side) or PanelSpan((spaces,))
+    if side in ("bottom", "top"):
+        justify.horizontally(text, ratio, span.left, span.right)
+    else:
+        justify.vertically(text, ratio, span.bottom, span.top)
+
+
 def _position_plot_labels(
     figure: Figure,
     theme: theme,

{plotnine-0.16.0a12 → plotnine-0.16.0a13}/plotnine/_mpl/layout_manager/_plot_side_space.py

@@ -25,7 +25,9 @@ from ._side_space import GridSpecParams, _side_space
 if TYPE_CHECKING:
     from plotnine import ggplot
     from plotnine._mpl.gridspec import p9GridSpec
+    from plotnine.composition._axis_collection import PanelSpan
     from plotnine.iapi import outside_legend
+    from plotnine.typing import Side
 
 
 class _plot_side_space(_side_space):
@@ -931,6 +933,13 @@ class PlotSideSpaces:
 
         self.W, self.H = plot.theme.getp("figure_size")
 
+        self.axis_title_span: dict[Side, PanelSpan] = {}
+        """
+        Combined panel bounds for each collected axis title, keyed by side
+
+        The mapping is empty when the plot retains no collected title.
+        """
+
     @property
     def owner(self) -> ggplot:
         """