API: decide what to return from plotting functions

[cpcloud]

most plotting functions return an Artist instance whereas a few return something else. for example, boxplot returns a dict and scatter returns a tuple. they should at least return a matplotlib.artist.Artist subclass (usually either a Figure or Axes) or an array of Artists.

this has been brought up before but it would be nice to make a decision here.

mailing list thread and #3474.

[jtratner]

there was a link a while back that covered this...some issue having to do with statsmodels.

[jtratner]

@cpcloud here's what I was thinking of - #1501 (comment) - apparently standard is figure?

[cpcloud]

i guess so; maybe it got lost in the mix, wanted to make sure this is addressed in 0.13

[jreback]

@cpcloud @jtratner maybe close this and go back to #1501 (or vice-versa) ? Any decisions?

[cpcloud]

i think #1501 is just about probability plots not sure if the API was ever resolved, but returning figure only would break a lot of existing code, since many of the plotting methods return an Axes object...maybe new methods return a figure? but then new stuff will probably be added with the kind argument and it would be god-awful to return a figure for say kind='scatter' and an Axes object otherwise. So it seems were in a stalemate :|

[jreback]

why wouldn't we standardize on returning axes?

and just do a 1 time API change where needed?

I think makes most sense

can u make a list what everything returns now?

[cpcloud]

this is why we wouldn't standardize on return axes: #1501 (comment)

i agree that it would be nice to standardize on axes, but that's different than what the comment says is the standard.

[cpcloud]

(that's a link to a comment)

[jreback]

where does it say its not the standard?

[cpcloud]

the list:

kind:

• kde
• line
• box
• bar

all of the above return an AxesSubplot object

methods

• hist: ndarray of AxesSubplots for DataFrame and AxesSubplot for Series unless by is not None then it's an ndarray of AxesSubplots
• boxplot: dict of lists of Line2Ds, keys are strs describing each component of the plot.

top-level plotting

• scatter_matrix: ndarray of AxesSubplots
• radviz: AxesSubplot
• bootstrap_plot: Figure
• parallel_coordinates: AxesSubplot
• lag_plot: AxesSubplot
• autocorrelation_plot: AxesSubplot
• scatter_plot: Figure

[jreback]

I think there is an issue to fix box plot already

is there a reason for the top level plotting at all ? why are these not all done via the kind to plot?

then everything can return an axes or ndarray of axes

?

[cpcloud]

not sure .... looks like a handful of different authors on those functions. maybe @wesm knows?

[cpcloud]

@jreback re your previous question, this:

all the plot functions in pandas should return a figure like in statsmodels

[jreback]

ic

except that breaks everything!

maybe like matplotlob

fig, ax = func(...)

?

[cpcloud]

one thing to note is that anything returning Figure will show up double on pylab=inline whether it's notebook or qtconsole

[cpcloud]

not sure if that's an ipython bug, i don't think so bc that's actually a way to show the plot again

[jreback]

why do u think sm returns figures?

[cpcloud]

not sure since most of the time if you want to change things u don't need the fig u need the axes

[cpcloud]

let me go read the pydata discussion again...maybe there's some logic behind why they do it

[jreback]

I say practicality - lets return ax

could have a option return_figure to provide the figure instead (I don't like doing that but no choice really)

[cpcloud]

it's so weird....it's so simple to get the figure by just calling get_figure() arggghh

i agree tho, return axes (or ndarray of them).

i honestly can't think of a time ever when i've modified the figure except trivial cases of tight_layout(), otoh i modify axes properties all the time!

[cpcloud]

what do to about boxplot? it's the runt of the bunch with its dict of whatever return value

[jreback]

I read the discussion

they always return a figure because then u don't have to know whether u get an ax or ndarray of axes

I would just have everything return as now
and fix box plot (party sure there is an issue out ther)

ten deprecate all I the top level methods and use kind (if possible)

[cpcloud]

#4264 and the pr to return the axes: #4472

[tacaswell]

[disclaimer, speaking for my self, not mpl here]

It is better to return the Artist objects added to the plot rather than the Axes. If the artists are not returned it is impossible (fine, very difficult and unreliable) to tell what the artists associated with your data is which makes doing anything interactive with the artists later impossible. For example, wanting to toggle the lines from a given column of a data frame on/off by clicking on it. If the end-user has the Line2D objects drawn this is very easy (just register on on-click call back which inverts the visible property).

If the user did not pass in an Axes object, then they can get to the axes through plt.gca() or just using the pyplot api. If the user passed in ax as an argument they already have a reference to it and don't need it back. All artists also have an ax property which is the axes they are currently associated with.

Returning artists from plotting commands would also bring the pandas API in line with the upstream mpl api.

I would also advocate moving all of the pandas plotting methods to be functions in a top level module with signatures like artists = pd.plot.lines(ax, df, style_kwargs) or arts = pd.plot.bar(ax, df, style_kwargs)

All of these changes will make it easier to (eventually) move pandas aware plotting to an mpl umbrella organization project.

[mroeschke]

It think the plotting API return types have been solidified for years now so I think we can close this out. If we decide to change a return type we can open a individual issue