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