Stack inset figure-level artists above the host

Every figure-level artist owned by a plot — panel borders, titles,
strip text, legends, watermarks, plus the plot/composition background
and footer rects — now goes through a single _add_figure_artist helper
on ggplot and Compose that offsets its zorder by the owning plot's
_zorder. This guarantees an inset's whole stack paints above the host's
whole stack, including the previously-missed strip backgrounds, titles,
and legends.

INSET_ZORDER_STEP is set to 1000 (well above the largest within-plot
zorder, watermarks at 99.9) so host and inset bands never overlap.

Watermark zorder is now managed entirely by plotnine; a user-supplied
value is dropped with a PlotnineWarning, and watermark.draw reads its
host's _zorder via the parent reference set in __radd__. plot_title and
the other figure-level texts are constructed as matplotlib.text.Text
and added through the same helper, dropping figure.text indirection.

Author: has2k1

plotnine/composition/_compose.py

@@ -590,6 +590,20 @@ def _draw_plots(self):
             if isinstance(item, ggplot):
                 item.draw()
 
+    def _add_figure_artist(self, artist):
+        """
+        Add an artist to this composition's figure with the right zorder
+
+        For a top-level composition this is a no-op offset; on an inset
+        composition every figure-level artist (titles, panel borders,
+        legends, ...) is shifted up by the composition's `_zorder` so
+        the inset sits wholly above the host. Returns the artist so the
+        call site can keep a single-statement assignment.
+        """
+        artist.set_zorder(artist.get_zorder() + self._zorder)
+        self.figure.add_artist(artist)
+        return artist
+
     def _draw_composition_background(self):
         """
         Draw the background rectangle of the composition
@@ -601,22 +615,27 @@ def _draw_composition_background(self):
         # backgrounds (which are at zorder=-1000), so the per-plot
         # backgrounds layer on top of it instead of being covered.
         zorder = -2000
-        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=zorder)
-        self.figure.add_artist(rect)
+        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=zorder - 0.5)
+        self._add_figure_artist(rect)
         self._gridspec.patch = rect
         self.theme.targets.plot_background = rect
 
         if self.annotation.footer:
             rect = Rectangle(
-                (0, 0), 0, 0, facecolor="none", linewidth=0, zorder=zorder + 1
+                (0, 0),
+                0,
+                0,
+                facecolor="none",
+                linewidth=0,
+                zorder=zorder - 0.4,
             )
-            self.figure.add_artist(rect)
+            self._add_figure_artist(rect)
             self.theme.targets.plot_footer_background = rect
 
             line = Line2D(
-                [0, 0], [0, 0], color="none", linewidth=0, zorder=zorder + 2
+                [0, 0], [0, 0], color="none", linewidth=0, zorder=zorder - 0.3
             )
-            self.figure.add_artist(line)
+            self._add_figure_artist(line)
             self.theme.targets.plot_footer_line = line
 
     def _draw_annotation(self):
@@ -629,20 +648,23 @@ def _draw_annotation(self):
         if self.annotation.empty():
             return
 
-        figure = self.theme.figure
+        from matplotlib.text import Text
+
         targets = self.theme.targets
 
         if title := self.annotation.title:
-            targets.plot_title = figure.text(0, 0, title)
+            targets.plot_title = self._add_figure_artist(Text(text=title))
 
         if subtitle := self.annotation.subtitle:
-            targets.plot_subtitle = figure.text(0, 0, subtitle)
+            targets.plot_subtitle = self._add_figure_artist(
+                Text(text=subtitle)
+            )
 
         if caption := self.annotation.caption:
-            targets.plot_caption = figure.text(0, 0, caption)
+            targets.plot_caption = self._add_figure_artist(Text(text=caption))
 
         if footer := self.annotation.footer:
-            targets.plot_footer = figure.text(0, 0, footer)
+            targets.plot_footer = self._add_figure_artist(Text(text=footer))
 
     def save(
         self,

plotnine/composition/_inset_element.py

@@ -9,6 +9,16 @@
     from ._compose import Compose
 
 
+INSET_ZORDER_STEP = 1000
+"""
+Zorder added to the host's value when an inset is drawn, so every
+figure-level artist on the inset (axes, plot_background, titles,
+strip text, legends, ...) sits above every figure-level artist on the
+host. Must exceed the largest existing zorder used inside a single
+plot — watermarks at 99.9 — so the host and inset stacks never overlap.
+"""
+
+
 @dataclass
 class inset_element:
     """

plotnine/facets/strips.py

@@ -127,7 +127,7 @@ def draw(self):
         text = StripText(draw_info)
         rect = text.patch
 
-        self.figure.add_artist(text)
+        self.facet.plot._add_figure_artist(text)
 
         if draw_info.position == "right":
             targets.strip_background_y.append(rect)

plotnine/ggplot.py

@@ -516,7 +516,7 @@ def _draw_panel_borders(self):
                 clip_path=ax.patch,
                 clip_on=False,
             )
-            self.figure.add_artist(rect)
+            self._add_figure_artist(rect)
             self.theme.targets.panel_border.append(rect)
 
     def _draw_layers(self):
@@ -561,43 +561,39 @@ def _draw_figure_texts(self):
         """
         Draw title, x label, y label and caption onto the figure
         """
-        figure = self.figure
-        theme = self.theme
-        targets = theme.targets
+        from matplotlib.text import Text
 
-        title = self.labels.get("title", "")
-        subtitle = self.labels.get("subtitle", "")
-        caption = self.labels.get("caption", "")
-        tag = self.labels.get("tag", "")
-        footer = self.labels.get("footer", "")
-
-        # Get the axis labels (default or specified by user)
-        # and let the coordinate modify them e.g. flip
-        labels = self.coordinates.labels(
-            self.layout.set_xy_labels(self.labels)
-        )
+        targets = self.theme.targets
 
         # The locations are handled by the layout manager
-        if title:
-            targets.plot_title = figure.text(0, 0, title)
+        if title := self.labels.get("title", ""):
+            targets.plot_title = self._add_figure_artist(Text(text=title))
 
-        if subtitle:
-            targets.plot_subtitle = figure.text(0, 0, subtitle)
+        if subtitle := self.labels.get("subtitle", ""):
+            targets.plot_subtitle = self._add_figure_artist(
+                Text(text=subtitle)
+            )
+
+        if caption := self.labels.get("caption", ""):
+            targets.plot_caption = self._add_figure_artist(Text(text=caption))
 
-        if caption:
-            targets.plot_caption = figure.text(0, 0, caption)
+        if footer := self.labels.get("footer", ""):
+            targets.plot_footer = self._add_figure_artist(Text(text=footer))
 
-        if footer:
-            targets.plot_footer = figure.text(0, 0, footer)
+        if tag := self.labels.get("tag", ""):
+            targets.plot_tag = self._add_figure_artist(Text(text=tag))
 
-        if tag:
-            targets.plot_tag = figure.text(0, 0, tag)
+        # Get the axis labels (default or specified by user)
+        # and let the coordinate modify them e.g. flip
+        labels = self.coordinates.labels(
+            self.layout.set_xy_labels(self.labels)
+        )
 
         if labels.x:
-            targets.axis_title_x = figure.text(0, 0, labels.x)
+            targets.axis_title_x = self._add_figure_artist(Text(text=labels.x))
 
         if labels.y:
-            targets.axis_title_y = figure.text(0, 0, labels.y)
+            targets.axis_title_y = self._add_figure_artist(Text(text=labels.y))
 
     def _draw_watermarks(self):
         """
@@ -611,39 +607,60 @@ def _draw_insets(self):
         Draw every inset attached to this plot into the host figure
 
         Each inset reuses the host's figure instead of creating its own.
-        The inset's zorder is raised above the host's so its axes paint
-        on top; for Compose insets this zorder is propagated down the
-        sub-tree when the composition is drawn.
+        The inset's zorder is raised by `INSET_ZORDER_STEP` so every
+        figure-level artist on the inset sits above the host's; for
+        Compose insets this zorder is propagated down the sub-tree when
+        the composition is drawn.
         """
+        from .composition._inset_element import INSET_ZORDER_STEP
+
         for inset in self._insets:
             inset.obj.figure = self.figure
-            inset.obj._zorder = self._zorder + 1
+            inset.obj._zorder = self._zorder + INSET_ZORDER_STEP
             inset.obj.draw()
 
+    def _add_figure_artist(self, artist):
+        """
+        Add an artist to this plot's figure with the right zorder offset
+
+        For a top-level plot this is a no-op offset; on an inset every
+        figure-level artist (titles, panel borders, legends, strip text,
+        ...) is shifted up by the inset's `_zorder` so the inset sits
+        wholly above the host. Returns the artist so the call site can
+        keep a single-statement assignment.
+        """
+        artist.set_zorder(artist.get_zorder() + self._zorder)
+        self.figure.add_artist(artist)
+        return artist
+
     def _draw_plot_background(self):
         from matplotlib.lines import Line2D
         from matplotlib.patches import Rectangle
 
-        zorder = -1000
-        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=zorder)
-        self.figure.add_artist(rect)
-        self._gridspec.patch = rect
-        self.theme.targets.plot_background = rect
+        targets = self.theme.targets
+
+        # The background sits just below this plot's own axes layer.
+        # _add_figure_artist offsets every figure-level artist by
+        # self._zorder, so for a top-level plot this stays at -0.5
+        # and for an inset it sits between the host's axes and the
+        # inset's axes — the inset background covers the host.
+        targets.plot_background = self._add_figure_artist(
+            Rectangle((0, 0), 0, 0, facecolor="none", zorder=-0.5)
+        )
+        self._gridspec.patch = targets.plot_background
 
         # Footer background and line only if there is a footer, and put
         # it on top of the plot background
         if self.labels.get("footer", ""):
-            rect = Rectangle(
-                (0, 0), 0, 0, facecolor="none", linewidth=0, zorder=zorder + 1
+            targets.plot_footer_background = self._add_figure_artist(
+                Rectangle(
+                    (0, 0), 0, 0, facecolor="none", linewidth=0, zorder=-0.4
+                )
             )
-            self.figure.add_artist(rect)
-            self.theme.targets.plot_footer_background = rect
 
-            line = Line2D(
-                [0, 0], [0, 0], color="none", linewidth=0, zorder=zorder + 2
+            targets.plot_footer_line = self._add_figure_artist(
+                Line2D([0, 0], [0, 0], color="none", linewidth=0, zorder=-0.3)
             )
-            self.figure.add_artist(line)
-            self.theme.targets.plot_footer_line = line
 
     def _save_filename(self, ext: str) -> Path:
         """

plotnine/guides/guides.py

@@ -380,7 +380,7 @@ def draw(self) -> Optional[OffsetBox]:
         self._apply_guide_themes(gdefs)
         legends = self._assemble_guides(gdefs, guide_boxes)
         for aob in legends.boxes:
-            self.plot.figure.add_artist(aob)
+            self.plot._add_figure_artist(aob)
 
         self.plot.theme.targets.legends = legends
 

plotnine/watermark.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 import typing
+from warnings import warn
+
+from .exceptions import PlotnineWarning
 
 if typing.TYPE_CHECKING:
     import pathlib
@@ -13,6 +16,15 @@
 __all__ = ("watermark",)
 
 
+_BASE_ZORDER = 99.9
+"""
+Default zorder for a watermark on a top-level plot
+
+Plotnine manages the zorder of every figure-level artist so that insets
+stack predictably above their host.
+"""
+
+
 class watermark:
     """
     Add watermark to plot
@@ -29,13 +41,16 @@ class watermark:
         Alpha blending value.
     kwargs :
         Additional parameters passed to
-        [](`~matplotlib.figure.figimage`)
+        [](`~matplotlib.figure.figimage`). Note that ``zorder`` is
+        managed by plotnine and any user-supplied value is dropped.
 
     Notes
     -----
     You can add more than one watermark to a plot.
     """
 
+    _parent: p9.ggplot
+
     def __init__(
         self,
         filename: str | pathlib.Path,
@@ -45,15 +60,22 @@ def __init__(
         **kwargs: Any,
     ):
         self.filename = filename
+        if "zorder" in kwargs:
+            warn(
+                "watermark zorder is managed by plotnine; "
+                "the user-supplied value is being ignored.",
+                PlotnineWarning,
+                stacklevel=2,
+            )
+            kwargs.pop("zorder")
         kwargs.update(xo=xo, yo=yo, alpha=alpha)
-        if "zorder" not in kwargs:
-            kwargs["zorder"] = 99.9
         self.kwargs = kwargs
 
     def __radd__(self, other: p9.ggplot) -> p9.ggplot:
         """
         Add watermark to ggplot object
         """
+        self._parent = other
         other.watermarks.append(self)
         return other
 
@@ -68,5 +90,8 @@ def draw(self, figure: matplotlib.figure.Figure):
         """
         from matplotlib.image import imread
 
-        X = imread(self.filename)
-        figure.figimage(X, **self.kwargs)
+        figure.figimage(
+            imread(self.filename),
+            zorder=_BASE_ZORDER + self._parent._zorder,
+            **self.kwargs,
+        )