ENH: add supxlabel and supylabel

[jklymak]

PR Summary

UPDATE: 10 Oct 2020, this still works as below.

There are a couple of fixes to padding in suptitle placement in constrained_layout.

This PR adds supxlabel and supylabel. Works with tight_layout and the new constrained_layout. Not so well with no layout manager ;-)

Closes #11147

import matplotlib.pyplot as plt

for tl, cl in zip([True, False, False], [False, False, True]):
    fig = plt.figure(constrained_layout=cl, tight_layout=tl)

    gs = fig.add_gridspec(2, 3)

    ax = dict()

    ax['A'] = fig.add_subplot(gs[0, 0:2])
    ax['B'] = fig.add_subplot(gs[1, 0:2])
    ax['C'] = fig.add_subplot(gs[:, 2])

    ax['C'].set_xlabel('Booger')
    ax['B'].set_xlabel('Booger')
    ax['A'].set_ylabel('Booger Y')
    fig.suptitle(f'TEST: tight_layout={tl} constrained_layout={cl}')
    fig.supxlabel('XLAgg')
    fig.supylabel('YLAgg')

    fig.savefig(f'/Users/jklymak/downloads/suplabels_tl{tl}_cl{cl}.png', dpi=75)
    plt.show()

PR Checklist

• Has Pytest style unit tests
• Code is Flake 8 compliant
• New features are documented, with examples if plot related
• Documentation is sphinx and numpydoc compliant
• Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
• Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

[timhoffm]

Have you considered that people might want suplabels on parts of a grid? e.g. columns 1 and 2 share an xlabel while column 0 has it's own label.

I'm not claiming that you should implement it now or even that it's necessary, but the desire may come up. If we consider this a reasonable extension, we should at least think about if an extension of the proposed API in that direction is possible and staight forward.

[jklymak]

Right now the API is the same as suptitle, and that has the same potential to only apply to some axes and not others.

There are two somewhat orthogonal issues here.

1. suplabels don’t align with axes, they align w/ the figure. It’s a reasonable extension to align them with the spines of the child axes, but I’ve not implemented this here. It’s non trivial to do so in a way that works with all the layout managers...
2. How do you only label a subset of axes? I’d argue this is best served with the subpanels/subfigure concept. Then the subpanel gets the suplabels. I think we should make subpanels subclasses of figures (in some way) so they will get this change for free.

[jklymak]

i.e. this figure just has suptitles for each subpanel, but was made w two subpanels, and could just as easily have supx and supylabels (from #17437)

[sks-2020]

Could the functions to add supxlabels and supylabels please be added to future releases of gridspec? Also have multicolumn row titles in the gridspec layout, as in the below figure?

[jklymak]

@sks-2020 What do you anticipate wanting to do with gridspec that the sub-panel functionality won't give you?

[sks-2020]

@jklymak I think the subpanel function will solve what I am hoping to do. My issue is the same as outlined here:
https://stackoverflow.com/questions/40936729/matplotlib-title-spanning-two-or-any-number-of-subplot-columns

I found a possible way of solving this, but doesn't use the neat layout option of using gridspec:
https://stackoverflow.com/questions/27426668/row-titles-for-matplotlib-subplot?rq=1

In summary, I have a gridspec subplots layout within another gridspec. I do the plotting part in the inner grid and need the labeling flexibility in the outer grid. At the moment, using the current release of matplotlib, I can only achieve this using text annotations. Inbuilt functions (like supxlabel, supylabel, supxticklabels, supyticklabels, suptitle), for the outer grid, will be very useful.

[jklymak]

@mwaskom This is the suplabel PR. This doesn't really require the other PR, but would be nice to do it after....

[mwaskom]

I'm afraid I don't know where to find it in the diff, but is the default font size here bigger than regular axes labels?

I'm not sure I've ever needed to add a "suplabel" pertaining to multiple axes that have existing, distinct labels. My use-case is almost always a situation where I have multiple subplots with shared axes and I want to add a single label to identify them. In that case, I'd want to the label to have the same size as a normal axis label.

Also, will these suplabels be tighter against the axes when there are no first-order labels?

I won't assert or claim to know which is a more common usecase, but I do think it's an application this PR should consider...

[jklymak]

I think they may be larger by default (just like suptitle) but the user can change this.

If there are no individual labels and you use constrained_layout the suplabels will be tight against the axes. Can likely be made to work with tight_layout as well. With no layout manager the whole thing is a bit of a mess anyhow.

As noted above, the suplables will be centered on the figure, not the spines or some other measure of what the label is supposed to span. That may or may not be acceptable depending on axes decorations, but it's a lot simpler.

[jklymak]

This is ready for review, and closes at least one feature request, and something seaborn would like.

[dopplershift]

Were we relying on Travis to run any unique test configurations? I'm wondering why test lines execute has dropped so much...

[QuLogic]

Is it not posting? It seems to have run...

Not everything is installed in Azure Pipelines, so I don't think it covers the same things.

[dopplershift]

Travis CI doesn't show up in the current list of checks on this PR. It looks like no PR builds have run in 3 days. I'm assuming we're running into the same thing that SciPy and NumPy have run into due to Travis changing their pricing model:

[QuLogic]

Oh, I did not notice the date. I guess we'll put this back on the meeting agenda.

[tacaswell]

This is very nice looking!

I also really like the test images, they make it very clear what is going on.

[tacaswell]

Anyone can merge on CI green.

[QuLogic]

Code coverage is normal again, since this ran with GitHub Actions after @tacaswell's commit.

[jklymak]

Thanks for everyone's reviews, and for @QuLogic for fixing codecov!