+0.5. I think, this is more readable for the cases presented here.

I'm a bit worried on theax = plt.figure().add_subplot(projection='3d') chaining. This is not a pattern commonly used in matplotlib so far. And explicitly creating a figure without binding it to a variable may appear a bit pedantic. In the pyplot world (which you are sort of in here even if you are later only working on the axes, this could simply beax = plt.subplot(projection='3d').

So if we're going away from "just useplt.subplots() and then work with the axes", I think we can equally allowplt.figure() andplt.subplot().

The advantage ofplt.figure().add_subplot() overplt.subplot() is that it makes the figure creation explicit, and the chain is easily split if it turns out that one needs a reference to the figure. It takes more typing, but I think that it might in the end help new users understand mpl more quickly than if they rely on the additional pyplot magic inplt.subplot().

I agree that the explicit figure creation has its merit, and partly withdraw my argument thatplt.subplot() andplt.subplots() should be used equally (it's unfortunate that these functions are named similarly, but have a different behavior with respect to figure creation).

This whole axes creation is a bit of a mess. If we did not have history

ax = plt.figure().add_subplot()axs = plt.figure().add_subplots()

would look like a reaonable API to me (maybe with optional pyplot shortcuts using implicit figure creation). But we're not there. The latter isplt.figure().subplots() and we've advertizedplt.subplots() instead.

I'm really worried we're confusing users with all these different methods and changed recommendations for axes creation. Even ifplt.subplots(subplot_kw={"foo": bar}) is ugly, at least it's the straight forward extension ofplt.subplots() /plt.subplots([2, 2]). Making the former look nicer but in exchange break API similarity with related functions is not a big win (if any).

Essentially, I see two reasonable ways:

1. Keep as is for now to not have yet another partial change; i.e. stay withplt.subplots() for now.
2. Rethink the whole Axes generation and establish one consistent API. This could be:

• CreateFigure.add_subplots() as a synonym forFigure.subplots() (deprecate or keep the latter).
• establish

  ax = plt.figure().add_subplot()axs = plt.figure().add_subplots()

  as a canonical way to create axes. Split the call if you need a reference to the figure. Optionally use pyplot functions as a shortcut. Should that beplt.subplot[s]() orplt.add_subplot[s]()?

This is just an of-the-top of my head concept and certainly would need more thorough consideration.

Well, I would really have preferred to haveFigure.add_subplots instead ofFigure.subplots but I lost the discussion at#5139#5146 :(

I agree that ever-changing recommendations are not great :( but OTOH we're all (well, at least I'm definitely still) learning how to best design an API.

I guess this discussion is also colliding with#14421 now.

I'm not a fan of favouring a different API for a single subplot than for multiple subplots, and I'm not at all a fan ofadd_subplot which is really just a matlab-ism. OTOH, I agree thatsubplot_kw is pretty ugly, and makes those kwargs non-discoverable. Would be good to talk about these use cases in one place and come up w/ what we think should be canonical?

Since this Pull Request has not been updated in 60 days, it has been marked "inactive." This does not mean that it will be closed, though it may be moved to a "Draft" state. This helps maintainers prioritize their reviewing efforts. You can pick the PR back up anytime - please ping us if you need a review or guidance to move the PR forward! If you do not plan on continuing the work, please let us know so that we can either find someone to take the PR over, or close it.

@efiring@timhoffm Do we want to use this pattern at least in some cases? If not, let's just close the PR.

Since this Pull Request has not been updated in 60 days, it has been marked "inactive." This does not mean that it will be closed, though it may be moved to a "Draft" state. This helps maintainers prioritize their reviewing efforts. You can pick the PR back up anytime - please ping us if you need a review or guidance to move the PR forward! If you do not plan on continuing the work, please let us know so that we can either find someone to take the PR over, or close it.

OK, I rewrote the whole thing to just make the changes that should be uncontroversial.

Uh I hate to jump in this late but I'm concerned about theax = plt.figure(). construction hiding the figure.

is that it makes the figure creation explicit, and the chain is easily split if it turns out that one needs a reference to the figure

My concern is w/ the folks who won't realize it's a chained call...I know the () should be a giveaway but I don't think it will be. I'd rather go all the way explicit here and use the unchained construction and leave "you can chain" to a section of the user guide or a tutorial.

I think acrucial point of python semantics as opposed to matlab (which is still pretty commonly used in my field) is exactly that youcan chain calls, i.e.tmp = foo(); b = tmp.bar() is equivalent tob = foo().bar() and therefore you explicitly don't need to litter your code with all the intermediate temporaries (and another crucial point is that parentheses mark function calls, which again isn't the case in matlab (which implicitly calls functions with no args)).
I would say the chained call is proper style; if there's opposition to it I'd rather just close the whole thing rather than writingfig = plt.figure(); ax = fig.add_subplot(...) which is worse IMO.

I would say the chained call is proper style;

I don't disagree in the case where they're definitely not going to use the figure object, but my concern is that this is example gallery code where the expectation is folks will c&p and then tweak.

I think I agree w/@jklymak that we should probably pin down a standard.

Let's just close this until we can actually decide on a standard.

re: deciding on a standard:

Is there an existingstandard for constructing a figure / axes / subplots? I see this in Getting Started:

fig, ax = plt.subplots()ax.plot(x, y)plt.show()

Given that figure/ax construction is both super confusing for beginners and ubiquitous for using mpl, I think that specifically warrants a standard that the gallery examples really stick to. That way users can focus on the feature they're looking for, without having to detangle how the figure is constructed. If a different setup is unavoidable or nonsensical for 3D projections etc, it may be worth anticipating confusion by adding a link at the bottom of the example page to thequick start guide or another tutorial that explains the difference in setup.

That seems to me to be potentially aseparate question from a standard about using chained calls in general. I'm ambivalent there -- it seems easier to figure out when it's later on in the code, but I would avoid shortcuts in the setup.

And FWIW, personally I thinkfig andax should always be explicit in the gallery examples because that setup is already confusing enough if you're not a frequent user. Itis a little jarring to only seeax inthis example after looking at several others that use bothfig andax.

We have already added width_ratio and height_ratio as pass throughs. The only one I really miss is facecolor

I think in general passing the figure back to the user is quite often necessary even in the case of a single subplot - in particular for colorbars. We could have ax.colorbar but again, having a separate idiom for single axes versus multiple axes in the docs seems confusing. I think we should always use fig, axs = plt.subplots() for consistency, even if there is just one axes.