ENH: Give control whether twinx() or twiny() overlays the main axis (#31122)

sanrishi · sanrishi · commit dfc0d0566d93 · 2026-03-20T18:14:52.000+05:30
diff --git a/doc/release/next_whats_new/twin_axes_zorder.rst b/doc/release/next_whats_new/twin_axes_zorder.rst
@@ -0,0 +1,12 @@
+Twin Axes ``delta_zorder``
+--------------------------
+
+`~matplotlib.axes.Axes.twinx` and `~matplotlib.axes.Axes.twiny` now accept a
+*delta_zorder* keyword argument, a relative offset added to the original Axes'
+zorder, to control whether the twin Axes is drawn in front of, or behind, the
+original Axes.  For example, pass ``delta_zorder=-1`` to easily draw a twin Axes
+behind the main Axes.
+
+In addition, Matplotlib now automatically manages background patch visibility
+for each group of twinned Axes so that only the bottom-most Axes in the group
+has a visible background patch (respecting ``frameon``).
diff --git a/galleries/examples/subplots_axes_and_figures/twin_axes_zorder.py b/galleries/examples/subplots_axes_and_figures/twin_axes_zorder.py
@@ -0,0 +1,44 @@
+"""
+===========================
+Twin Axes with delta_zorder
+===========================
+
+`~matplotlib.axes.Axes.twinx` and `~matplotlib.axes.Axes.twiny` accept a
+*delta_zorder* keyword argument (a relative offset added to the original Axes'
+zorder) that controls whether the twin Axes is drawn in front of or behind the
+original Axes.
+
+Matplotlib also automatically manages background patch visibility for twinned
+Axes groups so that only the bottom-most Axes has a visible background patch
+(respecting ``frameon``). This avoids the background of a higher-zorder twin
+Axes covering artists drawn on the underlying Axes.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+x = np.linspace(0, 10, 400)
+y_main = np.sin(x)
+y_twin = 0.4 * np.cos(x) + 0.6
+
+fig, ax = plt.subplots()
+
+# Put the twin Axes behind the original Axes (relative to the original zorder).
+ax2 = ax.twinx(delta_zorder=-1)
+
+# Draw something broad on the twin Axes so that the stacking is obvious.
+ax2.fill_between(x, 0, y_twin, color="C1", alpha=0.35, label="twin fill")
+ax2.plot(x, y_twin, color="C1", lw=6, alpha=0.8)
+
+# Draw overlapping artists on the main Axes; they appear on top.
+ax.scatter(x[::8], y_main[::8], s=35, color="C0", edgecolor="k", linewidth=0.5,
+           zorder=3, label="main scatter")
+ax.plot(x, y_main, color="C0", lw=4)
+
+ax.set_xlabel("x")
+ax.set_ylabel("main y")
+ax2.set_ylabel("twin y")
+ax.set_title("Twin Axes drawn behind the main Axes using delta_zorder")
+
+fig.tight_layout()
+plt.show()
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -614,6 +614,10 @@ def __str__(self):
         return "{0}({1[0]:g},{1[1]:g};{1[2]:g}x{1[3]:g})".format(
             type(self).__name__, self._position.bounds)
 
+    def set_zorder(self, level):
+        super().set_zorder(level)
+        self._update_twinned_axes_patch_visibility()
+
     def __init__(self, fig,
                  *args,
                  facecolor=None,  # defaults to rc axes.facecolor
@@ -2470,20 +2474,6 @@ def _add_text(self, txt):
         self.stale = True
         return txt
 
-    def _point_in_data_domain(self, x, y):
-        """
-        Check if the data point (x, y) is within the valid domain of the axes
-        scales.
-
-        Returns False if the point is outside the data range
-        (e.g. negative coordinates with a log scale).
-        """
-        for val, axis in zip([x, y], self._axis_map.values()):
-            vmin, vmax = axis.limit_range_for_scale(val, val)
-            if vmin != val or vmax != val:
-                return False
-        return True
-
     def _update_line_limits(self, line):
         """
         Figures out the data limit of the given line, updating `.Axes.dataLim`.
@@ -3316,6 +3306,7 @@ def set_frame_on(self, b):
         b : bool
         """
         self._frameon = b
+        self._update_twinned_axes_patch_visibility()
         self.stale = True
 
     def get_axisbelow(self):
@@ -4683,7 +4674,31 @@ def get_tightbbox(self, renderer=None, *, call_axes_locator=True,
         return mtransforms.Bbox.union(
             [b for b in bb if b.width != 0 or b.height != 0])
 
-    def _make_twin_axes(self, *args, **kwargs):
+    def _update_twinned_axes_patch_visibility(self):
+        """
+        Update patch visibility for a group of twinned Axes.
+
+        Only the bottom-most Axes in the group (lowest zorder, breaking ties by
+        creation/insertion order) has a visible background patch.
+        """
+        if self not in self._twinned_axes:
+            return
+        twinned = list(self._twinned_axes.get_siblings(self))
+        if not twinned:
+            return
+        fig = self.get_figure(root=False)
+        fig_axes = fig.axes if fig is not None else []
+        insertion_order = {ax: idx for idx, ax in enumerate(fig_axes)}
+
+        twinned.sort(key=lambda ax: (ax.get_zorder(),
+                                     insertion_order.get(ax, len(fig_axes))))
+        bottom = twinned[0]
+        for ax in twinned:
+            patch = getattr(ax, "patch", None)
+            if patch is not None:
+                patch.set_visible((ax is bottom) and ax.get_frame_on())
+
+    def _make_twin_axes(self, *args, delta_zorder=None, **kwargs):
         """Make a twinx Axes of self. This is used for twinx and twiny."""
         if 'sharex' in kwargs and 'sharey' in kwargs:
             # The following line is added in v2.2 to avoid breaking Seaborn,
@@ -4700,12 +4715,15 @@ def _make_twin_axes(self, *args, **kwargs):
                     [0, 0, 1, 1], self.transAxes))
         self.set_adjustable('datalim')
         twin.set_adjustable('datalim')
-        twin.set_zorder(self.zorder)
+        original_zorder = self.get_zorder()
+        twin.set_zorder(original_zorder if delta_zorder is None
+                        else original_zorder + delta_zorder)
 
         self._twinned_axes.join(self, twin)
+        self._update_twinned_axes_patch_visibility()
         return twin
 
-    def twinx(self, axes_class=None, **kwargs):
+    def twinx(self, axes_class=None, *, delta_zorder=None, **kwargs):
         """
         Create a twin Axes sharing the xaxis.
 
@@ -4726,6 +4744,12 @@ def twinx(self, axes_class=None, **kwargs):
 
             .. versionadded:: 3.11
 
+        delta_zorder : float, optional
+            A zorder offset for the twin Axes, relative to the original Axes.
+            The twin's zorder is set to ``self.get_zorder() + delta_zorder``.
+            By default (*delta_zorder* is None), the twin has the same zorder
+            as the original Axes.
+
         kwargs : dict
             The keyword arguments passed to `.Figure.add_subplot` or `.Figure.add_axes`.
 
@@ -4743,18 +4767,18 @@ def twinx(self, axes_class=None, **kwargs):
         """
         if axes_class:
             kwargs["axes_class"] = axes_class
-        ax2 = self._make_twin_axes(sharex=self, **kwargs)
+        ax2 = self._make_twin_axes(sharex=self, delta_zorder=delta_zorder,
+                                   **kwargs)
         ax2.yaxis.tick_right()
         ax2.yaxis.set_label_position('right')
         ax2.yaxis.set_offset_position('right')
         ax2.set_autoscalex_on(self.get_autoscalex_on())
         self.yaxis.tick_left()
         ax2.xaxis.set_visible(False)
-        ax2.patch.set_visible(False)
         ax2.xaxis.units = self.xaxis.units
         return ax2
 
-    def twiny(self, axes_class=None, **kwargs):
+    def twiny(self, axes_class=None, *, delta_zorder=None, **kwargs):
         """
         Create a twin Axes sharing the yaxis.
 
@@ -4775,6 +4799,12 @@ def twiny(self, axes_class=None, **kwargs):
 
             .. versionadded:: 3.11
 
+        delta_zorder : float, optional
+            A zorder offset for the twin Axes, relative to the original Axes.
+            The twin's zorder is set to ``self.get_zorder() + delta_zorder``.
+            By default (*delta_zorder* is None), the twin has the same zorder
+            as the original Axes.
+
         kwargs : dict
             The keyword arguments passed to `.Figure.add_subplot` or `.Figure.add_axes`.
 
@@ -4792,13 +4822,13 @@ def twiny(self, axes_class=None, **kwargs):
         """
         if axes_class:
             kwargs["axes_class"] = axes_class
-        ax2 = self._make_twin_axes(sharey=self, **kwargs)
+        ax2 = self._make_twin_axes(sharey=self, delta_zorder=delta_zorder,
+                                   **kwargs)
         ax2.xaxis.tick_top()
         ax2.xaxis.set_label_position('top')
         ax2.set_autoscaley_on(self.get_autoscaley_on())
         self.xaxis.tick_bottom()
         ax2.yaxis.set_visible(False)
-        ax2.patch.set_visible(False)
         ax2.yaxis.units = self.yaxis.units
         return ax2
 
diff --git a/lib/matplotlib/axes/_base.pyi b/lib/matplotlib/axes/_base.pyi
@@ -386,8 +386,20 @@ class _AxesBase(martist.Artist):
         bbox_extra_artists: Sequence[Artist] | None = ...,
         for_layout_only: bool = ...
     ) -> Bbox | None: ...
-    def twinx(self, axes_class: Axes | None = ..., **kwargs) -> Axes: ...
-    def twiny(self, axes_class: Axes | None = ..., **kwargs) -> Axes: ...
+    def twinx(
+        self,
+        axes_class: Axes | None = ...,
+        *,
+        delta_zorder: float | None = ...,
+        **kwargs
+    ) -> Axes: ...
+    def twiny(
+        self,
+        axes_class: Axes | None = ...,
+        *,
+        delta_zorder: float | None = ...,
+        **kwargs
+    ) -> Axes: ...
     @classmethod
     def get_shared_x_axes(cls) -> cbook.GrouperView: ...
     @classmethod
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -2461,21 +2461,6 @@ def test_hist_log_barstacked():
     assert axs[0].get_ylim() == axs[1].get_ylim()
 
 
-def test_hist_timedelta_raises():
-    import numpy as np
-    import matplotlib.pyplot as plt
-
-    fig, ax = plt.subplots()
-
-    arr_np = np.array([1, 2, 5, 7], dtype="timedelta64[D]")
-    with pytest.raises(TypeError, match="does not currently support timedelta inputs"):
-        ax.hist(arr_np)
-
-    arr_py = [datetime.timedelta(seconds=i) for i in range(5)]
-    with pytest.raises(TypeError, match="does not currently support timedelta inputs"):
-        ax.hist(arr_py)
-
-
 @image_comparison(['hist_bar_empty.png'], remove_text=True)
 def test_hist_bar_empty():
     # From #3886: creating hist from empty dataset raises ValueError
@@ -8081,6 +8066,50 @@ def test_twinning_default_axes_class():
     assert type(twiny) is Axes
 
 
+def test_twinning_patch_visibility_default():
+    _, ax = plt.subplots()
+    ax2 = ax.twinx()
+    assert ax.patch.get_visible()
+    assert not ax2.patch.get_visible()
+
+
+def test_twinning_patch_visibility_respects_zorder():
+    _, ax = plt.subplots()
+    ax2 = ax.twinx(delta_zorder=-1)
+    assert ax2.get_zorder() == ax.get_zorder() - 1
+    assert ax2.patch.get_visible()
+    assert not ax.patch.get_visible()
+
+
+def test_twinning_patch_visibility_multiple_twins_same_zorder():
+    _, ax = plt.subplots()
+    ax2 = ax.twinx()
+    ax3 = ax.twinx()
+    assert ax.patch.get_visible()
+    assert not ax2.patch.get_visible()
+    assert not ax3.patch.get_visible()
+
+
+def test_twinning_patch_visibility_updates_for_new_bottom():
+    _, ax = plt.subplots()
+    ax2 = ax.twinx(delta_zorder=-1)
+    ax3 = ax.twinx(delta_zorder=-2)
+    assert ax3.patch.get_visible()
+    assert not ax2.patch.get_visible()
+    assert not ax.patch.get_visible()
+
+
+def test_twinning_patch_visibility_updates_after_set_zorder():
+    _, ax = plt.subplots()
+    ax2 = ax.twinx()
+    assert ax.patch.get_visible()
+    assert not ax2.patch.get_visible()
+
+    ax2.set_zorder(ax.get_zorder() - 1)
+    assert ax2.patch.get_visible()
+    assert not ax.patch.get_visible()
+
+
 def test_zero_linewidth():
     # Check that setting a zero linewidth doesn't error
     plt.plot([0, 1], [0, 1], ls='--', lw=0)
@@ -8530,7 +8559,7 @@ def test_normal_axes():
     ]
     for nn, b in enumerate(bbaxis):
         targetbb = mtransforms.Bbox.from_bounds(*target[nn])
-        assert_array_almost_equal(b.bounds, targetbb.bounds, decimal=1)
+        assert_array_almost_equal(b.bounds, targetbb.bounds, decimal=2)
 
     target = [
         [150.0, 119.999, 930.0, 11.111],
@@ -8548,7 +8577,7 @@ def test_normal_axes():
 
     target = [85.5138, 75.88888, 1021.11, 1017.11]
     targetbb = mtransforms.Bbox.from_bounds(*target)
-    assert_array_almost_equal(bbtb.bounds, targetbb.bounds, decimal=1)
+    assert_array_almost_equal(bbtb.bounds, targetbb.bounds, decimal=2)
 
     # test that get_position roundtrips to get_window_extent
     axbb = ax.get_position().transformed(fig.transFigure).bounds
