DEPR: passing `ax` to plotting methods

[jbrockmendel]

IIUC (a big if), we allow users to plot multiple objects on the same figure by passing an ax argument to plotting methods. I think this is part/all of the reason why we need all the statefulness in #54485.

What if we deprecate that argument, so all obj.plot(...) calls get a new ax object? Would that break any use cases we really care about? Would it allow us to simplify the code enough to make it actually maintainable?

[jbrockmendel]

Or is the ax they get somehow a global in matplotlib?

[jbrockmendel]

cc @jreback might understand the code and the stakes

[mroeschke]

We do demonstrate passing in ax in https://pandas.pydata.org/docs/user_guide/visualization.html#using-layout-and-targeting-multiple-axes, but I'm not sure significantly different (or meaningful) than specifying the subplot-creating arguments into the .plot API.

[jorisvandenbossche]

When using pandas plotting, I regularly use the ax keyword. I think this is a very standard way of doing things when using the object-oriented style of matplotlib: you add things to an existing AxesSubplot object, in which case you need the ax keyword.

If you are quickly exploring data, indeed just doing .plot() (with some keywords) and letting that create a new figure works just fine. But if you want some more control over the exact figure layout, subplots, sidebar, etc, you wan to use matplotlib directly and be able to specify where on the figure to have panda add a plot. For example, not allowing that would make it hard-to-impossible to use pandas' plotting with multiple subplots on one figure.

We don't have that much of those examples in our own docs, but one is in the section that Matt mentioned above (and which is not equivalent to specifying some subplot-creating argument to .plot()): I can't link to the exact section, but check "Another option is passing an ax argument to Series.plot() to plot on a particular axis:" in https://pandas.pydata.org/docs/user_guide/visualization.html#using-layout-and-targeting-multiple-axes (although it is not specific to Series, it also applies to DataFrame)

So personally I would say this deprecation idea is a non-starter, but I also have no idea about the complexity / statefullness it adds to the code, so can't judge on the trade-off.

[jorisvandenbossche]

Looking at #54485 (comment) (which has a good example of passing ax), I think there are also two separate issues: being able to specify an ax to plot on, and the fact that pandas stores some state on the ax so that when we are plotting a second time on the same ax we have some custom behaviour.

I think those are completely separate issues? We might want to reconsider that state, but that shouldn't require disallowing to simply specify the ax to plot on?

[jbrockmendel]

Sounds like this is a use case worth keeping. Closing.