Update axis sharing to allow for top and right sharing.

Sharing is one of the core features of scientific plotting as it at the heart of UltraPlot. Sharing, unfortunately, is sometimes complex and is sometimes not handled correctly. This PR updates the sharing to allow for sharing top and right labels without needing to turn of the sharing feature.

Author: cvanelteren

docs/subplots.py

@@ -376,8 +376,14 @@
 #    are defined as follows:
 #
 #    * ``False`` or ``0``: Axis sharing is disabled.
-#    * ``'labels'``, ``'labs'``, or ``1``: Axis labels are shared, but
-#      nothing else. Labels will appear on the leftmost and bottommost subplots.
+#    * ``'labels'``, ``'labs'``, or ``1``: Axis labels are shared, but nothing else. Labels will appear on the outermost
+#  plots. This implies that for left, and bottom labels (default)
+# the labels will appear on the leftmost and bottommost subplots
+#  bottommost subplots. Note that labels will be shared only for
+#  plots that are immediately adjacent in the same row or column
+#  of the :class:`~ultraplot.gridspec.GridSpec`; a space or
+#  empty plot will add the labels, but not break the limit
+#  sharing. See below for a more complex example.
 #    * ``'limits'``, ``'lims'``, or ``2``: Same as ``1``, but axis limits, axis
 #      scales, and major and minor tick locations and formatting are also shared.
 #    * ``True`` or ``3`` (default): Same as ``2``, but axis tick labels are also
@@ -446,6 +452,25 @@
         yticks=5,
     )
 
+# %% [raw] raw_mimetype="text/restructuredtext"
+# When subplots are arranged on a grid, UltraPlot will
+# automatically share axis labels where appropriate. For more
+# complex layouts, UltraPlot will add the labels when the subplot
+# is facing and "edge" which is defined as not immediately having a subplot next to it. For example:
+import ultraplot as uplt, numpy as np
+
+layout = [[1, 0, 2], [0, 3, 0], [4, 0, 6]]
+fig, ax = uplt.subplots(layout)
+ax.format(xticklabelloc="top", yticklabelloc="right")
+# plot data to indicate that limits are still shared
+x = y = np.linspace(0, 1, 10)
+for axi in ax:
+    axi.plot(axi.number * x, axi.number * y)
+fig.show()
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# Notice how the top and right labels here are added since no
+# subplot is immediately adjacent to another, the limits however, are shared.
 
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_units:

ultraplot/axes/base.py

@@ -1532,7 +1532,7 @@ def shared(paxs):
             return [pax for pax in paxs if not pax._panel_hidden and pax._panel_share]
 
         # Internal axis sharing, share stacks of panels and main axes with each other
-        # NOTE: This is called on the main axes whenver a panel is created.
+        # NOTE: This is called on the main axes whenever a panel is created.
         # NOTE: This block is why, even though we have figure-wide share[xy], we
         # still need the axes-specific _share[xy]_override attribute.
         if not self._panel_side:  # this is a main axes
@@ -3259,7 +3259,6 @@ def _is_panel_group_member(self, other: "Axes") -> bool:
             and self._panel_parent is other._panel_parent
         ):
             return True
-
         # Not in the same panel group
         return False
 

ultraplot/axes/cartesian.py

@@ -9,13 +9,16 @@
 import matplotlib.ticker as mticker
 import numpy as np
 
+from packaging import version
+
 from .. import constructor
 from .. import scale as pscale
 from .. import ticker as pticker
 from ..config import rc
 from ..internals import ic  # noqa: F401
 from ..internals import _not_none, _pop_rc, _version_mpl, docstring, labels, warnings
 from . import plot, shared
+import matplotlib.axis as maxis
 
 __all__ = ["CartesianAxes"]
 
@@ -373,35 +376,162 @@ def _apply_axis_sharing(self):
         Enforce the "shared" axis labels and axis tick labels. If this is not
         called at drawtime, "shared" labels can be inadvertantly turned off.
         """
-        # X axis
         # NOTE: Critical to apply labels to *shared* axes attributes rather
         # than testing extents or we end up sharing labels with twin axes.
         # NOTE: Similar to how _align_super_labels() calls _apply_title_above() this
         # is called inside _align_axis_labels() so we align the correct text.
         # NOTE: The "panel sharing group" refers to axes and panels *above* the
         # bottommost or to the *right* of the leftmost panel. But the sharing level
         # used for the leftmost and bottommost is the *figure* sharing level.
-        axis = self.xaxis
-        if self._sharex is not None and axis.get_visible():
-            level = 3 if self._panel_sharex_group else self.figure._sharex
-            if level > 0:
-                labels._transfer_label(axis.label, self._sharex.xaxis.label)
-                axis.label.set_visible(False)
-            if level > 2:
-                # WARNING: Cannot set NullFormatter because shared axes share the
-                # same Ticker(). Instead use approach copied from mpl subplots().
-                axis.set_tick_params(which="both", labelbottom=False, labeltop=False)
-        # Y axis
-        axis = self.yaxis
-        if self._sharey is not None and axis.get_visible():
-            level = 3 if self._panel_sharey_group else self.figure._sharey
-            if level > 0:
-                labels._transfer_label(axis.label, self._sharey.yaxis.label)
-                axis.label.set_visible(False)
-            if level > 2:
-                axis.set_tick_params(which="both", labelleft=False, labelright=False)
+
+        # Get border axes once for efficiency
+        border_axes = self.figure._get_border_axes()
+
+        # Apply X axis sharing
+        self._apply_axis_sharing_for_axis("x", border_axes)
+
+        # Apply Y axis sharing
+        self._apply_axis_sharing_for_axis("y", border_axes)
+
+    def _apply_axis_sharing_for_axis(
+        self,
+        axis_name: str,
+        border_axes: dict[str, plot.PlotAxes],
+    ) -> None:
+        """
+        Apply axis sharing for a specific axis (x or y).
+
+        Parameters
+        ----------
+        axis_name : str
+            Either 'x' or 'y'
+        border_axes : dict
+            Dictionary from _get_border_axes() containing border information
+        """
+        if axis_name == "x":
+            axis = self.xaxis
+            shared_axis = self._sharex
+            panel_group = self._panel_sharex_group
+            sharing_level = self.figure._sharex
+            label_params = ["labeltop", "labelbottom"]
+            border_sides = ["top", "bottom"]
+        else:  # axis_name == 'y'
+            axis = self.yaxis
+            shared_axis = self._sharey
+            panel_group = self._panel_sharey_group
+            sharing_level = self.figure._sharey
+            label_params = ["labelleft", "labelright"]
+            border_sides = ["left", "right"]
+
+        if shared_axis is None or not axis.get_visible():
+            return
+
+        level = 3 if panel_group else sharing_level
+
+        # Handle axis label sharing (level > 0)
+        if level > 0:
+            shared_axis_obj = getattr(shared_axis, f"{axis_name}axis")
+            labels._transfer_label(axis.label, shared_axis_obj.label)
+            axis.label.set_visible(False)
+
+        # Handle tick label sharing (level > 2)
+        if level > 2:
+            label_visibility = self._determine_tick_label_visibility(
+                axis,
+                shared_axis,
+                axis_name,
+                label_params,
+                border_sides,
+                border_axes,
+            )
+            axis.set_tick_params(which="both", **label_visibility)
+        # Turn minor ticks off
         axis.set_minor_formatter(mticker.NullFormatter())
 
+    def _determine_tick_label_visibility(
+        self,
+        axis: maxis.Axis,
+        shared_axis: maxis.Axis,
+        axis_name: str,
+        label_params: list[str],
+        border_sides: list[str],
+        border_axes: dict[str, list[plot.PlotAxes]],
+    ) -> dict[str, bool]:
+        """
+        Determine which tick labels should be visible based on sharing rules and borders.
+
+        Parameters
+        ----------
+        axis : matplotlib axis
+            The current axis object
+        shared_axis : Axes
+            The axes this one shares with
+        axis_name : str
+            Either 'x' or 'y'
+        label_params : list
+            List of label parameter names (e.g., ['labeltop', 'labelbottom'])
+        border_sides : list
+            List of border side names (e.g., ['top', 'bottom'])
+        border_axes : dict
+            Dictionary from _get_border_axes()
+
+        Returns
+        -------
+        dict
+            Dictionary of label visibility parameters
+        """
+        ticks = axis.get_tick_params()
+        shared_axis_obj = getattr(shared_axis, f"{axis_name}axis")
+        sharing_ticks = shared_axis_obj.get_tick_params()
+
+        label_visibility = {}
+
+        def _convert_label_param(label_param: str) -> str:
+            # Deal with logic not being consistent
+            # in prior mpl versions
+            if version.parse(str(_version_mpl)) <= version.parse("3.9"):
+                if label_param == "labeltop" and axis_name == "x":
+                    label_param = "labelright"
+                elif label_param == "labelbottom" and axis_name == "x":
+                    label_param = "labelleft"
+            return label_param
+
+        for label_param, border_side in zip(label_params, border_sides):
+            # Check if user has explicitly set label location via format()
+            label_visibility[label_param] = False
+            has_panel = False
+            for panel in self._panel_dict[border_side]:
+                # Check if the panel is a colorbar
+                colorbars = [
+                    values
+                    for key, values in self._colorbar_dict.items()
+                    if border_side in key  # key is tuple (side, top | center | lower)
+                ]
+                if not panel in colorbars:
+                    # Skip colorbar as their
+                    # yaxis is not shared
+                    has_panel = True
+                    break
+            # When we have a panel, let the panel have
+            # the labels and turn-off for this axis + side.
+            if has_panel:
+                continue
+            is_border = self in border_axes.get(border_side, [])
+            is_panel = (
+                self in shared_axis._panel_dict[border_side]
+                and self == shared_axis._panel_dict[border_side][-1]
+            )
+            # Use automatic border detection logic
+            # if we are a panel we "push" the labels outwards
+            label_param_trans = _convert_label_param(label_param)
+            is_this_tick_on = ticks[label_param_trans]
+            is_parent_tick_on = sharing_ticks[label_param_trans]
+            if is_panel:
+                label_visibility[label_param] = is_parent_tick_on
+            elif is_border:
+                label_visibility[label_param] = is_this_tick_on
+        return label_visibility
+
     def _add_alt(self, sx, **kwargs):
         """
         Add an alternate axes.

ultraplot/axes/shared.py

@@ -12,6 +12,13 @@
 from ..utils import _fontsize_to_pt, _not_none, units
 from ..axes import Axes
 
+try:
+    # From python 3.12
+    from typing import override
+except ImportError:
+    # From Python 3.5
+    from typing_extensions import override
+
 
 class _SharedAxes(object):
     """
@@ -186,10 +193,11 @@ def _update_ticks(
             for lab in obj.get_ticklabels():
                 lab.update(kwtext_extra)
 
-    # Override matplotlib defaults to handle multiple axis sharing
+    @override
     def sharex(self, other):
         return self._share_axis_with(other, which="x")
 
+    @override
     def sharey(self, other):
         self._share_axis_with(other, which="y")