Thoughts on PR #418 about legend placement

[gepcel]

I like what you have done in PR #418. But there's a little more I'd like to discuss if you don't mind. Please excuse me if I'm mistaken.

I've been exploring the ax/row(s)/col(s)/span arguments of legend. These arguments are useful when someone wants the legend placed based on specific axes rather than the whole figure. However, when using this feature, two questions naturally arise: which axes' elements to include and where to position the legend. This leads to some confusion. I don't have definite answers, but I'd like to highlight this for your consideration.

Take the following code (without the fig.legend part) as an example, and let's assume loc="bottom throughout the discussion.

import ultraplot as pplt
fig, axs = pplt.subplots(ncols=4, nrows=4, share='all', width='10cm')
axs.format(yticklabels=[], xticklabels=[])
cycle = pplt.Cycle("default", N=16)
for n, ax in enumerate(axs):
    ax.text(.5, .5,f'ax:{n}\ncols:{n%4+1}', transform=ax.transAxes, ha='center',va='center')
    ax.scatter(.5, .25, transform=ax.transAxes, color=cycle.get_next()['color'], label=f"ax:{n}")

# Now the fig.legend() part.

1. fig.legend(ax=axs[4:6], loc='b', span=(1,2)) works as expected:

   1. axs[4:6] → includes elements from axs[4] and axs[5].
   2. span=(1,2) → merges them into a single legend and places it below columns 1 and 2, i.e., below axs[4] and axs[5].

2. fig.legend(ax=axs[4:6], loc="bottom", span=(3,4)) works, though seems odd but makes sense with complex layout. It includes elements from axs[4] and axs[5] but places the legend below columns 3 and 4, i.e., below axs[6] and axs[7]. What about other rows? Since ax and cols can be disrelevant, then how to put legend under 1st row, i.e., below axs[2] and axs[3]

Currently, ax accepts a zero‑based slice but not an array. [4:7] is valid, while [4,5] is not. Meanwhile, span/cols accept a one‑based tuple but not a slice or array. In the example above, for the second row, cols=(1,3) essentially corresponds to axs[4:7].

If ax controls which elements are included, it should accept a scalar, slice, or list. And if span=(1,3) means “from column 1 to column 3,” that makes sense. But why does axs start at 0 while cols start at 1?

Trying fig.legend(ax=axs[0,3,6], loc='bottom', span=(3,4)) # or axs[[0,3,6]] results in only axs[3] being included, which doesn't seem right.

[cvanelteren]

You bring up some excellent points. Let me see if I can carefully unpack them.
The confusion comes from the way UltraPlot (and by extension Proplot) handles axes numbers. Internally, axes are number from 1, but indexed from 0. So axs[0] will have axs[0].number == 1. The span parameter will always start from one and the second number will say how long it will span for. For example span = (1,4)will say start from the first subplot (index 0, number 1) and span until the 4th plot (number 4, index 3) within the slice. Since python starts from 0th index, the different indexing is a cause for confusion. I think 0 is used to allow for complex layout definition with 0 indicating no plot instead of resorting to using None.

Regarding, the slicing, I think you are right and we should allow for this. I will create a subissue to track this to make it more flexible for end users.

[cvanelteren]

For your particular solution you could place the legend like this:

fig.legend(ax=axs[0, :], loc="bottom", span=(1, 4))
fig.legend(ax=axs[1, :], loc="bottom", span=(1, 4))

read as (span 1 row until 4th column starting from position (1, 0) in the grid layout)

[gepcel]

So quick response.

What about the following result:

[cvanelteren]

What code did you use to produce that?

[gepcel]

What code did you use to produce that?

Photoshop. haha

And the thing about slice is, only continous axs can be included in legend. So cann't include only ax0, ax3, ax5, and put legend below ax10 and ax11.

[cvanelteren]

On #461 you can place it like that as fig.legend(ax=axs[[0, 1]], loc="bottom", span=(3, 4), row=2)

[cvanelteren]

But I am debating whether this interface is more intuitive or to have an achor argument.

[cvanelteren]

Going with the anchor method -- I think this wil scale better on non-grid layouts.

[gepcel]

But I am debating whether this interface is more intuitive or to have an achor argument.

Yeah, things will get very complicate quickly. This is just loc='b', then with loc=r`, should think about vertical slice of axs. That's why I'm here only giving some thoughts, but no answers.

[cvanelteren]

This is going to be the new api:

# .. _ug_guides_decouple:
#
# Decoupling legend content and location
# --------------------------------------
#
# Sometimes you may want to generate a legend using handles from specific axes
# but place it relative to other axes. In UltraPlot, you can achieve this by passing
# both the `ax` and `ref` keywords to :func:`~ultraplot.figure.Figure.legend`
# (or :func:`~ultraplot.figure.Figure.colorbar`). The `ax` keyword specifies the
# axes used to generate the legend handles, while the `ref` keyword specifies the
# reference axes used to determine the legend location.
#
# For example, to draw a legend based on the handles in the second row of subplots
# but place it below the first row of subplots, you can use
# ``fig.legend(ax=axs[1, :], ref=axs[0, :], loc='bottom')``. If ``ref`` is a list
# of axes, UltraPlot intelligently infers the span (width or height) and anchors
# the legend to the appropriate outer edge (e.g., the bottom-most axis for ``loc='bottom'``
# or the right-most axis for ``loc='right'``).