I would suggest not including this third category here. It is complicated enough to explain (1) whether the target figure/axes is explicit or implicit and (2) the subtle differences in the configuration functions/methods across those two APIs. Introducing the imperative/declarative distinction and third-party libraries that users may or may not have encountered only serves to distract from that key message, IMO.

I'm also not sure I would even call the pandas/xarray interfaces "declarative". They are basically just semantic sugar that convert

df.scatter(x="column a", y="column b", ax=ax)

to

ax.scatter(x=data["column a"], y=data["column b"])

This is distinct from the declarative nature of an interface like gpplot or seaborn, where you could say

scatter(data=df, x="column a", y="column b", color="column c")

and the arguments to parameters like color would be data values, rather than rgb tuples.

Opinions about how to categorize these may differ (you could argue that the groupby/faceting interface in pandas plotting is more declarative), but it's a pretty fuzzy distinction IMO and that fuzziness only adds unnecessary complexity here.

I think it's worthwhile to discuss this category

• This should be clearly separated from native Matplotlib think
  • Matplotlib
    • Axes
    • pyplot
  • Third party
• I agree that we should not call it declarative. If we don't find a better name the section could be titled "How third party libraries provide plotting functions".
• Not sure if the synthetic example is easy to transfer. I'd go with the probably most used third-party lib and make a pandas example.

wrt to the synthetic example, we do not have pandas (or xarray) as a doc dependency, so we would need to agree to add that. The only issue there might be the temptation to add pandas examples everywhere, which I think would be a mistake.

While I think converging on a standardized nomenclature for the two interfaces and using them consistently is good and important, this page should introduce the various synonyms as well, because you want people to get here when they google "matplotlib object oriented interface", and you want people to be able to map whatever concepts they learn here onto the terms they see elsewhere.

I would try to get to the point faster.

You haven't told them what the "higher-level interface" is yet, this makes me want to jump ahead to find out what it is.

Also is the pyplot interface "higher-level"? I don't think so — it's just implicit.

Why not use subplots here? Either plt.subplots or plt.figure().subplots? Using add_axes with a generic rectangle should be an antipattern.

Argeed that suplots() is the canonical pattern and should be used here. add_axes is for special purposes.

How does the implicit interface not "tell matplotlib how to compose the visualization"?

I'm not sure what you mean by "pure" here; remember that the intended audience should be "scientists who are trying to plot their data in the right place" not "programming paradigm connoisseurs".

Sure, decided to drop this paragraph as not particularly useful...

Does this reference to MATLAB and casual snippet of its syntax help introduce the key distinction? I think that making the connection to the MATLAB origins is fine, but it doesn't help introduce the concept, so I'd move it to a side comment after you make the main point.

If I am a new user who is confused about the distinction between these interfaces, it is going to be hard for me to just imagine what matplotlib is going to do in this situation or why the counterfactual explicit implementation would be more straight-forward.

I would make this recommendation in a separate section, rather than as an aside here.