wesm/pandas — Issue #413: Making plot methods more uniform in their options
Author: wesm
Created: 2011-11-24 19:21:01+00:00
State: open
Labels: Enhancement, Refactor

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 familiair with matplotlib too, in general allign 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=,
**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
```