API: Making plot methods more uniform in their options · Issue #413 · pandas-dev/pandas (original) (raw)

from @lodagro:

Been thinking a bit on uniformering signatures for plot, hist, boxplot and what they do/return.
For reference, below an overview what pandas and matplotlib.pyplot have.

some things that come to mind

• +1 for what you did with boxplot, by and column are handy, this could also be used for other kind of plots.
• bar-plot goes through plot, why not bar() itself.
• maybe pie() to?
• plot offers possibility to control sharex and sharey, others don not have this control.
• not all functions use the same subplot layout approach. DataFrame.plot() can plot all lines on a single axis or a nx1 layout. DataFrame.hist() uses nxn layout and DataFrame.boxplot is clever and can do nxm, but the user has no control. Maybe add nrow, ncol arguments? Default to None, meaning pandas can control layout, if either one defined pandas should compute the other one. Can get tricky for plot(), need to do something with subplots argument
• usage of **kwds, e.g boxplot has it, does not use this. maybe add subplot_kw and figure_kw arguments for dispatching argmuments -- like matplotlib does.
• Series.plot has style, DataFrame.plot not -- later could maybe use style/colum (like formatters in to_string)?
• rot not used everywhere
• probably many users of pandas are familiar with matplotlib too, in general align plotting signatures and return objects with matplotlib would be a good thing to do?

Maybe if i stare at it a bit longer i may have some more ideas, but this is getting long already. What do you think?

for reference

Series:

plot(self, label=None, kind='line', use_index=True, rot=30, ax=None, style='-',
     grid=True, **kwds)

hist(self, ax=None, grid=True, **kwds)

DataFrame:

boxplot(self, column=None, by=None, ax=None, fontsize=None,
            rot=0, grid=True, **kwds)

plot(self, subplots=False, sharex=True, sharey=False, use_index=True,
         figsize=None, grid=True, legend=True, rot=30, ax=None,
         kind='line', **kwds)

def hist(self, grid=True, **kwds):

matplotlib.pyplot

figure(num=None, figsize=None, dpi=None, facecolor=None, edgecolor=None,
             frameon=True, FigureClass=<class 'matplotlib.figure.Figure'>,
             **kwargs)

fig, ax = subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
                   subplot_kw=None, **fig_kw)
---> always creates a new figure

plot(*args, **kwargs)
    returns list of matplotlib.lines.Line2D

boxplot(x, notch=0, sym='b+', vert=1, whis=1.5, positions=None,
            widths=None, patch_artist=False, bootstrap=None, hold=None)
    Returns a dictionary, mapping each component of the boxplot
    to a list of the :class:`matplotlib.lines.Line2D`
    instances created.

plt.pie(x, explode=None, labels=None, colors=None, autopct=None,
        pctdistance=0.6, shadow=False, labeldistance=1.1, hold=None)
   Return value:
      If *autopct* is None, return the tuple (*patches*, *texts*):

        - *patches* is a sequence of
          :class:`matplotlib.patches.Wedge` instances

        - *texts* is a list of the label
          :class:`matplotlib.text.Text` instances.

      If *autopct* is *None*, return the tuple (*patches*, *texts*)
      If *autopct* is not *None*, return the tuple (*patches*, *texts*, *autotexts*)

plt.bar(left, height, width=0.8, bottom=None, hold=None, **kwargs)
    Return value is a list of matplotlib.patches.Rectangle instances