I don't feel that removinggridspec.Gridspec completely from the tutorial is a good idea. After all this is the gridspec tutorial. AndGridspec is in principle not bound to any figure. I.e. you can define a GridSpec and use it for several figures.

Theadd_gridspec is a really nice idea and it's really useful in most cases. I would just not replace the complete tutorial with it.

I would not use constrained_layout by default throughout the tutorial. This makes it hard to see where it plays a role. Just as it was before, whentight_layout got called in certain examples, one should usecontrained_layout where necessary/useful/desired; but within the individual example itself.

I have a problem with the call tocanvas.draw() and the sentence

Sometime constrained_layout needs an extra draw...

If contrained layout needs to draw the figure twice it needs to take care of that by itself. It's not useful to show examples with undeterministic behaviour. Up till now you never ever needed to draw a figure before showing it in matplotlib. Introducing this practice between the lines is really 👎 .

@ImportanceOfBeingErnest Fair enough about keeping a fewGridSpec examples in there. I was looking at it as akin toLegend, which we rarely need to call directly. I appreciate thatGridSpec need not belong to a specific figure, but in my opinion that is a mistake, because a GridSpec is an organizational element in complicated figures, and in order forconstrained_layout to work, it needs to associate a figure with each GridSpec. (Of course that would help a lot oftight_layout problems as well, but...

tight_layout was called in all the examples where I useconstrained_layout.

I appreciate the problem aboutfig.canvas.draw(). You don'tneed to call this, but the plot where I do is slightly cropped if you don't. This is a mild flaw ofconstrained_layout. I think there are actually plenty of places where we tell people they need to trigger a draw to get layout to work properly.

The alternative, fromconstrained_layout point of view is toalways call it twice behind the scenes, and that is expensive. I'm personally of the opinion its just as well to admit our flaws for something that works 95% of the time, and let the user deal with the result. However, I'll look into it; maybe I can make the padding a bit bigger to take care of most cases...

I'm stumbling over the nameadd_gridspec. There is nothing added to the figure here. It's just creating a GridSpec holding a reference to the figure.

Not knowing if an additionaldraw() is needed for a layout to be correct is off-settling. If possible that should be solved. I don't know anything about constrained_layout, but maybe you can check if artists are clipped and then trigger a redraw?

If this cannot be solved easily, can we please use examples that do not require workaround for flaws, unless the example is explicitly designed to show the limitations and explain how to cope with them.

I just saw thatthis example disappeared from the tutorial.

This is the most useful of all to show how to use Gridspec and would really like it not to be thrown away. (I guess that happened already in a previous version, but still...)

My point about the constrained_layout use is that you define it at the very beginning. Instead it should be inside the example itself. Otherwise users copy the example, run it and get a different figure. You cannot expect them to check for some setting being done at some completely different place.

Personally I would prefer there to be a separete section which explains how you may useadd_gridspec() instead ofgridspec.Gridspec() and show the advantages of it. Those are:

• no need to importmatplotlib.gridspec
• the ability to use one of the grid managers, namely contrained_layout, with it.

I do think those weight strong enough to actually add this function. But I do not see that they help in understandinggridspec; instead they add a dimension of complexity to the examples, which is not needed, and potentially distracts from the actual point of the tutorial.

@timhoffm

I'm stumbling over the name add_gridspec. There is nothing added to the figure here. It's just creating a GridSpec holding a reference to the figure.

Agreed. I contemplated adding a list of gridspecs to figure, but decided it wasn't totally necessary. But from user's point of view, they are adding a gridspec, and I'd argue the name makes sense. I could be convinced that it should be justfigure.gridspec, but I'm not a huge fan of that because it makes it sound like that is a property. While there is a case to be made that each figure should only have one parent gridspec, thats not the case now. Other suggestions for method names that are easily discoverable would be welcome.

@ImportanceOfBeingErnest

My point about the constrained_layout use is that you define it at the very beginning.

OK, fair enough - I'll change that. And I can add back in the complicated example. I liked that one too, and in fact prefer it to the somewhat messy double nested thing at the end of the current tutorial.

Personally I would prefer there to be a separete section which explains how you may use add_gridspec() instead of gridspec.Gridspec()

I understand what you are saying. I just disagree thatgridspec.GridSpec() needs ever be directly referenced and explained if we adopt these new convenience methods. The only reason would be if

a) someone wants to use the abstraction ability of having a GridSpec they drag from one figure to the next, a feature I find of dubious value.
b) so that folks can make sense of old examples.

But more to the point, the new convenience methods areexactly the same as the direct method, so I don't think any understanding is lost.

What I mean is that you'd create the gridspec once and use it for all figures you create.

import matplotlib.pyplot as pltfrom matplotlib.gridspec import GridSpecgs = GridSpec(2, 2, left=0.2, right=0.93, wspace=0.05, hspace=0.12,             width_ratios=[1, 2], height_ratios=[4, 1])fig = plt.figure()ax1 = fig.add_subplot(gs[0, :])ax2 = fig.add_subplot(gs[1, 0])ax3 = fig.add_subplot(gs[1, 1])fig2 = plt.figure()ax21 = fig2.add_subplot(gs[0, 0])ax22 = fig2.add_subplot(gs[1, 0])ax23 = fig2.add_subplot(gs[:, 1])fig3 = ...

Yeah I understand the use-case. Pretty skeptical that gets used much in practice though. If we completely got rid of that interface you’d still get the same thing by packing the args in a dict. Not that I think we should get rid of the fundamental interface at all.

Would an example like the above explaining the advantage ofnot using the convenience method make sense?

The big disadvantage of your example is that constrained_layout won’t work at all, whereas it works fine for the new interface.

My overarching point for a while is that we have this nice hierarchical way of organizing subplots, but we don’t keep track of that hierarchy, and hence lose information about the users desires. Without that hierarchy automating layout is impossible for general layouts. This is a small step to enforcing that hierarchy at a slight loss of convenience in some obscure use cases.

Removing WIP as this is the extent of what I am planning. However, open to

• changing the name of.Figure.add_gridspec
• further refinement or changes in the tutorials

I'm strongly in favor of this and I understand concerns about the naming.

what aboutfig.[set|make|create]_gridspec?

set_gridspec strongly suggests that a figure can only ever haveone gridspec attached at a time, which seems a bit too strong (even though "mostly" true).make_/create_/attach_ may sound better?

Re name:

I just think of it as parallel toadd_subplot. I appreciate thatadd_subplot actually adds a subplot to the figure, whereasadd_gridspec doesn't until a subplot is added, but thats arguing consitency from the point of view of the developer. I think from the user's point of view its more consistent and easier to remember:

1. add a gridspec
2. add a subplot

If it would make things nicer, I'dlove it if a figure kept track of it's child gridspec. But thats consistency fromour point of view.

I thinkset_gridspec is out of the question, just asfig.gridspec is, because it connotes a property.

If I don't prevail in my argument here,make_gridspec orcreate_gridspec are not too bad...

Agreed.set_ is off the table.

attach_ sounds like it would accept an existing gridspec as a parameter.

Bothadd_ andset_ imply that the gridspec is somehow attached to the figure and there is something likeget_gridspec(s). The semantic difference betweenadd_ andset_ would be if a figure can have multiple or just one gridspec.

If there would be an agreement that the figure should keep a reference to the gridspec (as suggested by@jklymak), it would be ok to use these terms in anticipation of the future functionality. Then again, it's probably better think of a more general API like:

• set_layout(layout)
• get_layout(layout)
• set_gridspec_layout(rows, cols, ...) convenience function similar to theadd_gridspec above and equivalent toset_layout(GridSpec(rows, cols, ...).

So -0.5 onadd_ andset_.

For now, I thinkmake_ andcreate_ are the best options (slight personal preference onmake_).

OK, due to popular demand, I addedfigure._gridspecs as a private list of gridspecs added usingadd_gridspec. We can add convenience functions for getting the list if and when the need arises.

Though I still prefermake_gridspec, I think adding to a private list is a good move and makesadd_gridspec something I would support.

Why not let the figure have a gridspec by default?

@Tillsten A gridspec needs the grid parameters (m, n) before it means anything, so that needs user input I think... We could just put a default one in, and indeed thats what happens if there is just one axes in the figure.

Actually, this probably should at least look for wheresubplots adds a GridSpec and include that in the list.WIP until I get to it! Done!

This had a lot of good input; anyone up for a full review? Its not a big conceptual change, though I did edit the tutorial a fair bit...

Pinging for review on this. Its a pretty straightforward enhancement, and I think I addressed the concerns about the nameadd_gridspec by actually adding a property to the figure...

...rebased

Squash and rebase. I think it'd be wrong to say that this is release critical, but it'd be nice to include in 3.0; its pretty straightforward, just adding new access points to the gridspec w/o the user having to know all the magical incantations...

EDIT: fixed now...

Doc build fails w/

Warning, treated as error:/home/circleci/project/doc/users/next_whats_new/fig_gridspec.rst:document isn't included in any toctree

I forget how to fix that. Note that thenext_whats_new got cleaned out in the 3.0 doc prep...

Self merging. This did pass AppVeyor before the rebase, and the rebase was trivial, and had no Windows related changes.