API: dedicated plot methods like plot.scatter as an alternative to using kind

[shoyer]

Currently, we use the plot for every possible kind of plot, and switch between them using the kind keyword argument.

From an API design and discoverability perspective, this seems less than ideal. If we had separate methods, standard introspection tools like IPython and autocomplete could help users figure out which arguments are applicable for which type of plot with less reliance on the documentation.

Another option is to make a .plot also an accessor, so we could have df.plot.scatter and so forth. But I suspect .plot_scatter would be a bit more discoverable.

[dalejung]

I'm +1 on the accessor. We might want to group additional methods/attributes that don't fit the plot_ prefix. I recall there being an issue about grouping the already large pandas global namespace into logical groups.

[shoyer]

cc @sinhrks @TomAugspurger @onesandzeroes @jorisvandenbossche

[jorisvandenbossche]

I agree with the sentiment of plot being too overloaded, and by having all the different plot types in one function making this a huge function. Also from a documentation point of view it is very difficult to document all the parameters, as a lot of plot kinds have specific ones only for that plot type.

But, the latest evolution in pandas was actually in the opposite direction. As lately, the separate hist and boxplot methods have also been added to the plot kind interface. See eg #7809

[shoyer]

@jorisvandenbossche I think it was a good idea to move hist and boxplot to plot kind purely from a consistency perspective -- these methods were hard to find on their own without a common accessor or prefix. But the common prefix or accessor would be even better, and of course we would keep .plot(kind=...) deprecated (or maybe only discouraged) for quite a long time before removing it.

[jreback]

plot_* methods are pretty inflexible from s user perspective

not easy to switch bar to line or whatever and really hard to do programmatically (you have to compose the method name)

so big -1 on that

the accessor is a bit more amenable as it then allows kw separation and tab completion

should only be 1 obvious method of doing this

.plot(kind=...) seems intuitive to me

[shoyer]

Perhaps we could just consolidate plotting methods based on their API.

Off the top of my head:

category	kinds
1d	line, bar, area, pie?
density	hist, kde/density
1d/density	box (violin?)
2d	scatter, hexbin (hist2d?)

From a programmatic perspective, it's nice to be able to use kind to toggle between sub-kinds of the same category (e.g., line to bar), but not between categories.

[jreback]

@shoyer that looks reasonable

[shoyer]

That said, I do still think dedicated methods/accessor would be a better API. Even within a category, there are plenty of kind specific options.

On Sun, Dec 21, 2014 at 2:51 PM, jreback notifications@github.com wrote:

@shoyer that looks reasonable

Reply to this email directly or view it on GitHub:
#9124 (comment)

[dalejung]

I wonder if making plot both a callable and accessor is an option? plot() would work the same but also have methods with plot-type specific docs and call signatures i.e. plot.scatter. I would assume the methods would just wrap around plot.

[shoyer]

I wonder if making plot both a callable and accessor is an option? plot() would work the same but also have methods with plot-type specific docs and call signatures i.e. plot.scatter. I would assume the methods would just wrap around plot.

Yes, this is not a bad option, although ultimately it would probably be cleaner to have the base plot method wrap the specific types, e.g.,

class SeriesPlotter(object):
    def __call__(self, kind='line', **kwargs):
        return getattr(self, kind)(**kwargs)

"only one obvious way to do it" is great, but pandas leans a bit more toward practicality.

[onesandzeroes]

I like the idea of having specific plot functions attached to plot, so plot.scatter, plot.bar, while still being able to call plot(kind=...). Would allow specific docstrings (excellent for knowing exactly which keyword args are relevant to the current type), tab completion etc.

If we could divide the plot types into categories like shoyer suggested that would be good too, but the proposed categories don't seem all that obvious/intuitive to me. I wouldn't have thought of a bar chart as a 1D plot (although it makes sense now that I think about it), and isn't line is either 1D or 2D depending on whether we're plotting with the index as x-axis or using a second variable? Would probably create a decent amount of confusion for people who know which kind of plot they want to find their way through to it.

[shoyer]

It sounds like there is support for preserving the kind argument to plot, while also making plot an accessor with more specific sub-methods?