ENH: Allow tuple for borderpad in AnchoredOffsetbox #30359

Aaratrika-Shelly · 2025-07-25T22:22:50Z

This PR closes #30331 .

PR summary

This PR enhances AnchoredOffsetbox to allow the borderpad parameter to accept a tuple of (x_pad, y_pad) in addition to a single float value.

Why is this change necessary? Currently, borderpad applies the same padding in both x and y directions. This can be inflexible, especially when placing inset axes in a corner. For example, a user may want horizontal padding to avoid overlapping the main plot's y-axis labels, but no vertical padding in order to keep the inset flush with the top of the plot area.
What problem does it solve? It gives users finer control over the positioning of anchored elements, allowing for separate horizontal and vertical padding.
What is the reasoning for this implementation?
- The implementation modifies AnchoredOffsetbox.get_offset.
- It checks if self.borderpad is a tuple and calculates separate pad_x_pixels and pad_y_pixels.
- These values are then used to create a manually padded anchor box, which is a robust approach that does not require changing downstream helper functions.
- The implementation is fully backward-compatible, treating single float values as before.

A new unit test has been added to verify this functionality, and the docstring for AnchoredOffsetbox has been updated to reflect the new API.

PR checklist

"closes [ENH]: inset_axes has borderpadding, but not x/y individually. #30331" is in the body of the PR description to link the related issue
new and changed code is tested
[N/A] Plotting related features are demonstrated in an example
New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

rcomer

Thanks @Aaratrika-Shelly, nice work! I have confirmed this solves the inset_axes issue:

import matplotlib.pyplot as plt

from mpl_toolkits.axes_grid1.inset_locator import inset_axes

fig, ax = plt.subplots()

axins = inset_axes(ax, width="30%", height=1., loc="upper left", borderpad=(3, 0))

plt.show()

Please could you update the inset_axes docstring to match what you have done here? This should also get a what's new entry and "added" directive.

lib/matplotlib/tests/test_offsetbox.py

lib/matplotlib/offsetbox.py

Aaratrika-Shelly · 2025-07-26T21:48:00Z

All the suggested changes have been made. Thanks for the suggestions.

rcomer

Thanks @Aaratrika-Shelly, this will still need a new entry in https://github.com/matplotlib/matplotlib/tree/main/doc/users/next_whats_new

Also I just remembered that the type annotation will need updating in offsetbox.pyi. We do not yet have typing stubs for anything under toolkits so there is nothing to do for type annotations for inset_axes.

rcomer · 2025-07-27T10:20:05Z

lib/matplotlib/tests/test_offsetbox.py

+    ax.add_artist(text_tuple_equal)
+
+    # Case 3: Test that an asymmetric tuple with larger values works as expected.
+    text_tuple_asym = AnchoredText("tuple_asym", loc='lower left', borderpad=(10, 15))


I suggest making one of these less than 5. At the moment the below assertions would pass even if only one element of the tuple mistakenly got used for both x and y.

lib/matplotlib/offsetbox.py

rcomer · 2025-07-27T10:42:56Z

lib/mpl_toolkits/axes_grid1/inset_locator.py

+    versionchanged:: 3.11
+    The *borderpad* parameter now accepts a tuple of (x, y) paddings.


I think this should be versionadded because you are introducing a new option but the old option still works. Also it should go under the parameter description. For a similar example see

matplotlib/lib/matplotlib/stackplot.py

Lines 67 to 68 in 011d12f

.. versionadded:: 3.9

Support for list input

lib/matplotlib/offsetbox.py

lib/matplotlib/offsetbox.pyi

lib/mpl_toolkits/axes_grid1/inset_locator.py

lib/matplotlib/tests/test_offsetbox.py

timhoffm

Only minor nits left.

timhoffm · 2025-07-28T12:09:55Z

lib/matplotlib/offsetbox.py

    the *loc* code with the *borderpad*.
+    The paddings are specified by *pad_x* and *pad_y*.


Suggested change

the *loc* code with the *borderpad*.

The paddings are specified by *pad_x* and *pad_y*.

the *loc* code and padding *pad_x*, *pad_y*.

timhoffm · 2025-07-28T12:12:37Z

lib/matplotlib/legend.py

        return offsetbox._get_anchored_bbox(
            loc, bbox, parentbbox,
-            self.borderaxespad * renderer.points_to_pixels(self._fontsize))
+            pad,pad)


Suggested change

pad,pad)

pad, pad)

Could also be inlined to the line before.

rcomer · 2025-07-28T12:51:38Z

lib/matplotlib/tests/test_offsetbox.py

+    text_tuple_equal = AnchoredText("tuple", loc='lower left', borderpad=(5, 5))
+    ax.add_artist(text_tuple_equal)
+
+    # Case 3: Test that an asymmetric tuple with larger values works as expected.


Suggested change

# Case 3: Test that an asymmetric tuple with larger values works as expected.

# Case 3: Test that an asymmetric tuple with different values works as expected.

rcomer · 2025-07-28T12:56:42Z

lib/matplotlib/tests/test_offsetbox.py

+    # Assertion 2: Prove that the larger, asymmetric padding moved the box
+    # further from the origin than the baseline.


Suggested change

# Assertion 2: Prove that the larger, asymmetric padding moved the box

# further from the origin than the baseline.

# Assertion 2: Prove that the asymmetric padding moved the box

# further from the origin than the baseline in the x-direction and less far in the y-direction.

rcomer · 2025-07-28T12:59:37Z

lib/mpl_toolkits/axes_grid1/inset_locator.py

        The units are axes font size, i.e. for a default font size of 10 points
        *borderpad = 0.5* is equivalent to a padding of 5 points.

+        .. versionadded:: 3.10


Suggested change

.. versionadded:: 3.10

.. versionadded:: 3.11

v3.11 is the next version. This should also go in the AnchoredOffsetbox docstring.

rcomer · 2025-07-28T13:00:09Z

lib/mpl_toolkits/axes_grid1/inset_locator.py

@@ -256,6 +256,7 @@ def inset_axes(parent_axes, width, height, loc='upper right',
               axes_class=None, axes_kwargs=None,
               borderpad=0.5):
    """
+


Suggested change

Accidentally added line I think

rcomer · 2025-07-28T13:01:55Z

lib/matplotlib/offsetbox.pyi

@@ -157,7 +157,7 @@ class AnchoredOffsetbox(OffsetBox):
        loc: str,
        *,
        pad: float = ...,
-        borderpad: float = ...,
+        borderpad: float | tuple[float, float] = ...,


The same change should be made for AnchoredText below.

rcomer · 2025-07-28T13:33:04Z

Since you are amending the one commit, it would be good to also correct the typo: "tupple" -> "tuple"

Aaratrika-Shelly force-pushed the feature/tuple-borderpad branch 3 times, most recently from 98cfadf to 8df4614 Compare July 26, 2025 07:24

rcomer reviewed Jul 26, 2025

View reviewed changes

rcomer changed the title ~~ENH: Allow tupple for borderpad in AnchoredOffsetbox~~ ENH: Allow tuple for borderpad in AnchoredOffsetbox Jul 26, 2025

rcomer added the New feature label Jul 26, 2025

melissawm added this to First Time Contributors Jul 26, 2025

melissawm moved this to Waiting for author in First Time Contributors Jul 26, 2025

Aaratrika-Shelly force-pushed the feature/tuple-borderpad branch from 8df4614 to c84ef64 Compare July 26, 2025 21:46

github-actions bot added the topic: mpl_toolkit label Jul 26, 2025

rcomer reviewed Jul 27, 2025

View reviewed changes

Aaratrika-Shelly force-pushed the feature/tuple-borderpad branch from c84ef64 to 2b60116 Compare July 27, 2025 20:21

timhoffm reviewed Jul 27, 2025

View reviewed changes

Aaratrika-Shelly force-pushed the feature/tuple-borderpad branch 2 times, most recently from 5bd8215 to b98dbdc Compare July 28, 2025 10:19

github-actions bot added the topic: legend label Jul 28, 2025

timhoffm reviewed Jul 28, 2025

View reviewed changes

Aaratrika-Shelly force-pushed the feature/tuple-borderpad branch from b98dbdc to abbc352 Compare July 28, 2025 12:22

rcomer reviewed Jul 28, 2025

View reviewed changes

ENH: Allow tuple for borderpad in AnchoredOffsetbox

ca8f475

Aaratrika-Shelly force-pushed the feature/tuple-borderpad branch from abbc352 to ca8f475 Compare July 28, 2025 19:57

		versionchanged:: 3.11
		The borderpad parameter now accepts a tuple of (x, y) paddings.

		the loc code with the borderpad.
		The paddings are specified by pad_x and pad_y.

	the loc code with the borderpad.
	The paddings are specified by pad_x and pad_y.
	the loc code and padding pad_x, pad_y.

	# Case 3: Test that an asymmetric tuple with larger values works as expected.
	# Case 3: Test that an asymmetric tuple with different values works as expected.

		# Assertion 2: Prove that the larger, asymmetric padding moved the box
		# further from the origin than the baseline.

Uh oh!

ENH: Allow tuple for borderpad in AnchoredOffsetbox #30359

Are you sure you want to change the base?

ENH: Allow tuple for borderpad in AnchoredOffsetbox #30359

Conversation

Aaratrika-Shelly commented Jul 25, 2025

PR summary

PR checklist

Uh oh!

rcomer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Aaratrika-Shelly commented Jul 26, 2025

Uh oh!

rcomer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rcomer commented Jul 28, 2025

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.