Add guide_area() to host collected guides inside a cell

`guide_area()` (a `plot_spacer` subclass) marks a cell in a composition
that should hold the legend produced by `plot_layout(guides="collect")`.
It must be a direct child of the collecting composition — nested
guide_areas belong to their own sub-grid and are not reached by an
outer collector. When no guide_area is eligible, collected guides fall
back to side placement.

Author: has2k1

doc/_quartodoc.yml

@@ -549,6 +549,7 @@ quartodoc:
         - plot_spacer
         - plot_layout
         - inset_element
+        - guide_area
 
     - title: Options
       desc: |

plotnine/_mpl/layout_manager/_plot_layout_items.py

@@ -6,6 +6,7 @@
 from matplotlib.text import Text
 
 from plotnine._mpl.patches import StripTextPatch
+from plotnine.composition._compose import Compose
 from plotnine.exceptions import PlotnineError
 
 from ..utils import (
@@ -653,8 +654,13 @@ def set_position(
         y = spaces.b.y1("legend")
         set_position(legends.bottom.box, (x, y), (0, 0))
 
-    # Inside legends are placed using the panels coordinate system
+    # Inside legends are placed using the panels coordinate system.
+    # For a `Compose` owner with a `guide_area` host, the guides are
+    # rendered in the guide_areas panel, so we need that gridspec
     if legends.inside:
+        if isinstance(spaces.owner, Compose) and spaces.owner._guide_area:
+            panels_gs = spaces.owner._guide_area._sub_gridspec
+
         transPanels = panels_gs.to_transform()
         for l in legends.inside:
             set_position(l.box, l.position, l.justification, transPanels)

plotnine/composition/__init__.py

@@ -1,5 +1,6 @@
 from ._beside import Beside
 from ._compose import Compose
+from ._guide_area import guide_area
 from ._inset_element import inset_element
 from ._plot_annotation import plot_annotation
 from ._plot_layout import plot_layout
@@ -12,6 +13,7 @@
     "Stack",
     "Beside",
     "Wrap",
+    "guide_area",
     "inset_element",
     "plot_annotation",
     "plot_layout",

plotnine/composition/_compose.py

@@ -2,6 +2,7 @@
 
 import abc
 from copy import copy, deepcopy
+from functools import cached_property
 from io import BytesIO
 from typing import TYPE_CHECKING, cast, overload
 
@@ -32,6 +33,7 @@
     from plotnine._mpl.layout_manager._composition_side_space import (
         CompositionSideSpaces,
     )
+    from plotnine.composition._guide_area import guide_area
     from plotnine.ggplot import PlotAddable, ggplot
     from plotnine.typing import FigureFormat, MimeBundle
 
@@ -455,6 +457,31 @@ def _walk_guide_owners(self):
         for sub in self.iter_sub_compositions():
             yield from sub._walk_guide_owners()
 
+    @cached_property
+    def _guide_area(self) -> guide_area | None:
+        """
+        The cell that hosts this composition's collected legend
+
+        Only a `guide_area` placed directly at this composition's
+        level is eligible; one nested inside a sub-composition
+        belongs to that sub-grid, so an outer collector cannot
+        reach it.
+
+        Returns
+        -------
+        out :
+            The first matching `guide_area` among the composition's
+            direct items, or `None` when no eligible cell exists —
+            in which case collected guides fall back to side
+            placement.
+        """
+        from ._guide_area import guide_area
+
+        for item in self.iter_plots():
+            if isinstance(item, guide_area):
+                return item
+        return None
+
     @property
     def last_plot(self) -> ggplot:
         """

plotnine/composition/_guide_area.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from ._plot_spacer import plot_spacer
+
+
+class guide_area(plot_spacer):
+    """
+    A grid cell that hosts collected guides
+
+    Used in a composition that collects guides with
+    `plot_layout(guides="collect")` to route the merged legend into a
+    cell of the grid instead of placing it on the side of the
+    composition.
+
+    Renders empty (like [](`~plotnine.composition.plot_spacer`)) when
+    no collection is in effect, no guides exist to collect, or another
+    `guide_area` was selected first.
+
+    Parameters
+    ----------
+    fill :
+        Background color. The default is a transparent area.
+    alpha :
+        Opacity of the background fill, between 0 (transparent) and 1
+        (opaque). The default leaves the area transparent.
+
+    See Also
+    --------
+    plotnine.composition.plot_spacer : Blank cell with the same styling.
+    plotnine.composition.plot_layout : Set `guides="collect"` to enable
+        collection.
+    """

plotnine/guides/guides.py

@@ -28,6 +28,7 @@
     from matplotlib.offsetbox import OffsetBox, PackerBase
 
     from plotnine import ggplot, guide_colorbar, guide_legend, theme
+    from plotnine._mpl.offsetbox import FlexibleAnchoredOffsetbox
     from plotnine.composition import Compose
     from plotnine.iapi import labels_view
     from plotnine.scales.scale import scale
@@ -358,9 +359,21 @@ def draw(self) -> Optional[OffsetBox]:
         for g in gdefs:
             g.theme.apply()
 
-        legends = assemble_legend_artists(
-            gdefs, guide_boxes, self.elements, figure
-        )
+        # Rendering in a guide_area is simpler because we render all guides
+        # together and at the center
+        use_guide_area = (
+            self._owner._guide_area
+            if isinstance(self._owner, Compose)
+            else None
+        ) is not None
+        if use_guide_area:
+            legends = assemble_guide_area_legend(
+                guide_boxes, self.elements, figure
+            )
+        else:
+            legends = assemble_legend_artists(
+                gdefs, guide_boxes, self.elements, figure
+            )
 
         # Attach legend offsetboxes to the figure and register them
         for aob in legends.boxes:
@@ -410,42 +423,6 @@ def assemble_legend_artists(
     figure :
         The figure the offsetboxes will be anchored to.
     """
-    from matplotlib.font_manager import FontProperties
-    from matplotlib.offsetbox import HPacker, VPacker
-
-    from .._mpl.offsetbox import FlexibleAnchoredOffsetbox
-
-    # Combine all the guides into a single box
-    # The direction matters only when there is more than legend
-    lookup: dict[Orientation, type[PackerBase]] = {
-        "horizontal": HPacker,
-        "vertical": VPacker,
-    }
-
-    def _anchored_offset_box(boxes: list[PackerBase]):
-        """
-        Put a group of guides into a single box for drawing
-        """
-        packer = lookup[elements.box]
-
-        box = packer(
-            children=boxes,  # type: ignore
-            align=elements.box_just,
-            pad=elements.box_margin,
-            sep=elements.spacing,
-        )
-
-        return FlexibleAnchoredOffsetbox(
-            xy_loc=(0.5, 0.5),
-            child=box,
-            pad=1,
-            frameon=False,
-            prop=FontProperties(size=1, stretch=0),
-            bbox_to_anchor=(0, 0),
-            bbox_transform=figure.transFigure,
-            borderpad=0.0,
-        )
-
     # Group together guides for each position
     groups: dict[
         tuple[Side, float] | tuple[tuple[float, float], tuple[float, float]],
@@ -459,7 +436,7 @@ def _anchored_offset_box(boxes: list[PackerBase]):
 
     # Create an anchoredoffsetbox for each group/position
     for (position, just), group in groups.items():
-        aob = _anchored_offset_box(group)
+        aob = _anchored_offset_box(group, elements, figure)
         if isinstance(position, str) and isinstance(just, (float, int)):
             setattr(legends, position, outside_legend(aob, just))
         else:
@@ -470,6 +447,79 @@ def _anchored_offset_box(boxes: list[PackerBase]):
     return legends
 
 
+def assemble_guide_area_legend(
+    boxes: list[PackerBase],
+    elements: GuidesElements,
+    figure: Figure,
+) -> legend_artists:
+    """
+    Pack collected guides into one centered legend for a `guide_area`
+
+    All trained guides are combined into a single AnchoredOffsetbox
+    centered in panel coordinates, irrespective of their individual
+    `legend_position` settings. Used when the rendering owner is a
+    `Compose` whose `_guide_area` selects a host cell.
+
+    Parameters
+    ----------
+    boxes :
+        The per-guide drawn boxes that will be packed together.
+    elements :
+        Theme-resolved layout elements (direction, box justification,
+        margins, spacing).
+    figure :
+        The figure the offsetbox will be anchored to.
+
+    Returns
+    -------
+    out :
+        A `legend_artists` whose only entry is a single inside
+        legend at `(0.5, 0.5)`.
+    """
+    aob = _anchored_offset_box(boxes, elements, figure)
+    legends = legend_artists()
+    legends.inside.append(inside_legend(aob, (0.5, 0.5), (0.5, 0.5)))
+    return legends
+
+
+def _anchored_offset_box(
+    boxes: list[PackerBase],
+    elements: GuidesElements,
+    figure: Figure,
+) -> FlexibleAnchoredOffsetbox:
+    """
+    Pack a list of guide boxes into a single AnchoredOffsetbox
+    """
+    from matplotlib.font_manager import FontProperties
+    from matplotlib.offsetbox import HPacker, VPacker
+
+    from .._mpl.offsetbox import FlexibleAnchoredOffsetbox
+
+    lookup: dict[Orientation, type[PackerBase]] = {
+        "horizontal": HPacker,
+        "vertical": VPacker,
+    }
+    packer = lookup[elements.box]
+
+    box = packer(
+        children=boxes,  # type: ignore
+        align=elements.box_just,
+        pad=elements.box_margin,
+        sep=elements.spacing,
+    )
+
+    return FlexibleAnchoredOffsetbox(
+        xy_loc=(0.5, 0.5),
+        child=box,
+        pad=1,
+        frameon=False,
+        prop=FontProperties(size=1, stretch=0),
+        bbox_to_anchor=(0, 0),
+        bbox_transform=figure.transFigure,
+        borderpad=0.0,
+    )
+
+
 def _merge_guides(gdefs: Sequence[guide]) -> list[guide]:
     """
     Group guides by hash and fold each group