WIP/ENH: plot methods accessors

shoyer · shoyer · commit bc7f851776cf · 2015-01-20T23:07:43.000-08:00
Fixes pandas-dev#9124 This PR adds plotting sub-methods like `df.plot.scatter()` as an alternative to using `df.plot(kind='scatter')`. I've added meaningful function signatures and documentation for a few of these methods, but I would greatly appreciate help to fill in the rest -- this is a lot of documentation to write! The entire point of this PR, of course, is to have better introspection and docstrings. Todo list: - [ ] Function signatures - [ ] `area` - [ ] `line` - [ ] `bar` - [ ] `barh` - [x] `box` - [x] `hexbin` - [x] `hist` - [ ] `kde`/`density` - [ ] `pie` - [x] `scatter` - [ ] Docstrings - [ ] `area` - [ ] `line` - [ ] `bar` - [ ] `barh` - [ ] `box` - [ ] `hexbin` - [x] `hist` - [ ] `kde`/`density` - [ ] `pie` - [ ] `scatter` - [ ] Tests (just a few) - [ ] Plotting docs - [ ] API docs - [ ] Release notes
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -45,8 +45,8 @@
                           OrderedDict, raise_with_traceback)
 from pandas import compat
 from pandas.sparse.array import SparseArray
-from pandas.util.decorators import deprecate, Appender, Substitution, \
-    deprecate_kwarg
+from pandas.util.decorators import (cache_readonly, deprecate, Appender,
+                                    Substitution, deprecate_kwarg)
 
 from pandas.tseries.period import PeriodIndex
 from pandas.tseries.index import DatetimeIndex
@@ -5001,7 +5001,7 @@ def _put_str(s, space):
 
 import pandas.tools.plotting as gfx
 
-DataFrame.plot = gfx.plot_frame
+DataFrame.plot = cache_readonly(gfx.FramePlotMethods)
 DataFrame.hist = gfx.hist_frame
 
 
diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -2702,7 +2702,7 @@ def _try_cast(arr, take_fast_path):
 
 import pandas.tools.plotting as _gfx
 
-Series.plot = _gfx.plot_series
+Series.plot = cache_readonly(_gfx.SeriesPlotMethods)
 Series.hist = _gfx.hist_series
 
 # Add arithmetic!
diff --git a/pandas/tools/plotting.py b/pandas/tools/plotting.py
@@ -11,6 +11,7 @@
 import numpy as np
 
 from pandas.util.decorators import cache_readonly, deprecate_kwarg
+from pandas.core.base import PandasObject
 import pandas.core.common as com
 from pandas.core.generic import _shared_docs, _shared_doc_kwargs
 from pandas.core.index import Index, MultiIndex
@@ -2461,60 +2462,12 @@ def _plot(data, x=None, y=None, subplots=False,
 
     """
 
-@Appender(_shared_docs['plot'] % _shared_doc_df_kwargs)
-def plot_frame(data, x=None, y=None, kind='line', ax=None,                 # Dataframe unique
-               subplots=False, sharex=True, sharey=False, layout=None,     # Dataframe unique
-               figsize=None, use_index=True, title=None, grid=None,
-               legend=True, style=None, logx=False, logy=False, loglog=False,
-               xticks=None, yticks=None, xlim=None, ylim=None,
-               rot=None, fontsize=None, colormap=None, table=False,
-               yerr=None, xerr=None,
-               secondary_y=False, sort_columns=False,        # Dataframe unique
-               **kwds):
-    return _plot(data, kind=kind, x=x, y=y, ax=ax,
-                 subplots=subplots, sharex=sharex, sharey=sharey,
-                 layout=layout, figsize=figsize, use_index=use_index,
-                 title=title, grid=grid, legend=legend,
-                 style=style, logx=logx, logy=logy, loglog=loglog,
-                 xticks=xticks, yticks=yticks, xlim=xlim, ylim=ylim,
-                 rot=rot, fontsize=fontsize, colormap=colormap, table=table,
-                 yerr=yerr, xerr=xerr,
-                 secondary_y=secondary_y, sort_columns=sort_columns,
-                 **kwds)
-
-
-@Appender(_shared_docs['plot'] % _shared_doc_series_kwargs)
-def plot_series(data, kind='line', ax=None,                    # Series unique
-                figsize=None, use_index=True, title=None, grid=None,
-                legend=False, style=None, logx=False, logy=False, loglog=False,
-                xticks=None, yticks=None, xlim=None, ylim=None,
-                rot=None, fontsize=None, colormap=None, table=False,
-                yerr=None, xerr=None,
-                label=None, secondary_y=False,                 # Series unique
-                **kwds):
 
-    import matplotlib.pyplot as plt
-    """
-    If no axes is specified, check whether there are existing figures
-    If there is no existing figures, _gca() will
-    create a figure with the default figsize, causing the figsize=parameter to
-    be ignored.
-    """
-    if ax is None and len(plt.get_fignums()) > 0:
-        ax = _gca()
-        ax = getattr(ax, 'left_ax', ax)
-    # is there harm in this?
-    if label is None:
-        label = data.name
-    return _plot(data, kind=kind, ax=ax,
-                 figsize=figsize, use_index=use_index, title=title,
-                 grid=grid, legend=legend,
-                 style=style, logx=logx, logy=logy, loglog=loglog,
-                 xticks=xticks, yticks=yticks, xlim=xlim, ylim=ylim,
-                 rot=rot, fontsize=fontsize, colormap=colormap, table=table,
-                 yerr=yerr, xerr=xerr,
-                 label=label, secondary_y=secondary_y,
-                 **kwds)
+def plot_frame(data, *args, **kwargs):
+    """Depreated; use data.plot instead"""
+    return data.plot(*args, **kwargs)
+
+plot_series = plot_frame
 
 
 _shared_docs['boxplot'] = """
@@ -3361,6 +3314,150 @@ def _set_ticks_props(axes, xlabelsize=None, xrot=None,
     return axes
 
 
+class BasePlotMethods(PandasObject):
+    def __init__(self, data):
+        self._data = data
+
+    def __call__(self, *args, **kwargs):
+        raise NotImplementedError
+
+    # WIP: Each of these methods needs to be updated to add specific keyword
+    # arguments. Some of these methods should probably be moved to the more
+    # specific SeriesPlotMethods/FramePlotMethods below. Help would be
+    # appreciated!
+
+    def line(self, *args, **kwargs):
+        """Needs docstring"""
+        return self(*args, kind='line', **kwargs)
+
+    def bar(self, *args, **kwargs):
+        """Needs docstring"""
+        return self(*args, kind='bar', **kwargs)
+
+    def barh(self, *args, **kwargs):
+        """Needs docstring"""
+        return self(*args, kind='barh', **kwargs)
+
+    def box(self, column=None, by=None, ax=None, fontsize=None, rot=0,
+            grid=True, figsize=None, layout=None, return_type=None, **kwds):
+        """Needs docstring"""
+        return self(kind='box', column=column, by=by, ax=ax, fontsize=fontsize,
+                    rot=rot, grid=grid, figsize=figsize, layout=layout,
+                    return_type=return_type, **kwds)
+
+    def kde(self, *args, **kwargs):
+        """Needs docstring"""
+        return self(*args, kind='kde', **kwargs)
+
+    density = kde
+
+    def area(self, *args, **kwargs):
+        """Needs docstring"""
+        return self(*args, kind='area', **kwargs)
+
+    def pie(self, *args, **kwargs):
+        """Needs docstring"""
+        return self(*args, kind='pie', **kwargs)
+
+
+class SeriesPlotMethods(BasePlotMethods):
+    """Series plotting accessor
+
+    Examples
+    --------
+    >>> s.plot.line()
+    >>> s.plot.bar()
+    >>> s.plot.hist()
+
+    The plotting methods can also be accessed by directly calling the
+    accessor with the ``kind`` argument:
+    ``s.plot(kind='line')`` is equivalent to ``s.plot.line()``
+    """
+    @Appender(_shared_docs['plot'] % _shared_doc_series_kwargs)
+    def __call__(self, kind='line', ax=None, figsize=None, use_index=True,
+                 title=None, grid=None, legend=False, style=None, logx=False,
+                 logy=False, loglog=False, xticks=None, yticks=None, xlim=None,
+                 ylim=None, rot=None, fontsize=None, colormap=None,
+                 table=False, yerr=None, xerr=None, label=None,
+                 secondary_y=False, **kwds):
+        import matplotlib.pyplot as plt
+        # If no axes is specified, check whether there are existing figures If
+        # there is no existing figures, _gca() will create a figure with the
+        # default figsize, causing the figsize=parameter to be ignored.
+        if ax is None and len(plt.get_fignums()) > 0:
+            ax = _gca()
+            ax = getattr(ax, 'left_ax', ax)
+        # is there harm in this?
+        if label is None:
+            label = self._data.name
+        return _plot(self._data, kind=kind, ax=ax,
+                     figsize=figsize, use_index=use_index, title=title,
+                     grid=grid, legend=legend,
+                     style=style, logx=logx, logy=logy, loglog=loglog,
+                     xticks=xticks, yticks=yticks, xlim=xlim, ylim=ylim,
+                     rot=rot, fontsize=fontsize, colormap=colormap, table=table,
+                     yerr=yerr, xerr=xerr,
+                     label=label, secondary_y=secondary_y,
+                     **kwds)
+
+    def hist(self, by=None, ax=None, grid=True, xlabelsize=None, xrot=None,
+             ylabelsize=None, yrot=None, figsize=None, bins=10, **kwds):
+        return self(kind='hist', by=by, ax=ax, grid=grid,
+                    xlabelsize=xlabelsize, xrot=xrot, ylabelsize=ylabelsize,
+                    yrot=yrot, figsize=figsize, bins=bins, **kwds)
+    hist.__doc__ = hist_series.__doc__
+
+
+class FramePlotMethods(BasePlotMethods):
+    """DataFrameFrame plotting accessor
+
+    Examples
+    --------
+    >>> df.plot.line()
+    >>> df.plot.scatter('x', 'y')
+    >>> df.plot.hexbin()
+
+    The plotting methods can also be accessed by directly calling the
+    accessor with the ``kind`` argument:
+    ``df.plot(kind='line')`` is equivalent to ``df.plot.line()``
+    """
+    @Appender(_shared_docs['plot'] % _shared_doc_df_kwargs)
+    def __call__(self, x=None, y=None, kind='line', ax=None, subplots=False,
+                 sharex=True, sharey=False, layout=None, figsize=None,
+                 use_index=True, title=None, grid=None, legend=True,
+                 style=None, logx=False, logy=False, loglog=False, xticks=None,
+                 yticks=None, xlim=None, ylim=None, rot=None, fontsize=None,
+                 colormap=None, table=False, yerr=None, xerr=None,
+                 secondary_y=False, sort_columns=False, **kwds):
+        return _plot(self._data, kind=kind, x=x, y=y, ax=ax,
+                     subplots=subplots, sharex=sharex, sharey=sharey,
+                     layout=layout, figsize=figsize, use_index=use_index,
+                     title=title, grid=grid, legend=legend,
+                     style=style, logx=logx, logy=logy, loglog=loglog,
+                     xticks=xticks, yticks=yticks, xlim=xlim, ylim=ylim,
+                     rot=rot, fontsize=fontsize, colormap=colormap, table=table,
+                     yerr=yerr, xerr=xerr,
+                     secondary_y=secondary_y, sort_columns=sort_columns,
+                     **kwds)
+
+    def hist(self, column=None, by=None, grid=True, xlabelsize=None,
+             xrot=None, ylabelsize=None, yrot=None, ax=None, sharex=False,
+             sharey=False, figsize=None, layout=None, bins=10, **kwds):
+        return self(kind='hist', column=column, by=by, grid=grid,
+                    xlabelsize=xlabelsize, xrot=xrot, ylabelsize=ylabelsize,
+                    yrot=yrot, ax=ax, sharex=sharex, sharey=sharey,
+                    figsize=figsize, layout=layout, bins=bins, **kwds)
+    hist.__doc__ = hist_frame.__doc__
+
+    def scatter(self, x, y, c=None, **kwargs):
+        """Needs docstring"""
+        return self(kind='scatter', x=x, y=y, c=c, **kwargs)
+
+    def hexbin(self, x, y, C=None, **kwargs):
+        """Needs docstring"""
+        return self(kind='hexbin', x=x, y=y, C=C, **kwargs)
+
+
 if __name__ == '__main__':
     # import pandas.rpy.common as com
     # sales = com.load_data('sanfrancisco.home.sales', package='nutshell')
