ENH: .resample API to groupby-like class, pandas-dev#11732

Author: jreback

doc/source/release.rst

@@ -48,7 +48,12 @@ users upgrade to this version.
 
 Highlights include:
 
-See the :ref:`v0.17.0 Whatsnew <whatsnew_0180>` overview for an extensive list
+Highlights include:
+
+- Window functions are now methods on ``.groupby`` like objects, see :ref:`here <whatsnew_0180.enhancements.moments>`.
+- API breaking ``.resample`` changes to make it more ``.groupby`` like, see :ref:`here <whatsnew_0180.resample>`.
+
+See the :ref:`v0.18.0 Whatsnew <whatsnew_0180>` overview for an extensive list
 of all enhancements and bugs that have been fixed in 0.17.1.
 
 Thanks

doc/source/whatsnew/v0.18.0.txt

@@ -14,6 +14,7 @@ users upgrade to this version.
 Highlights include:
 
 - Window functions are now methods on ``.groupby`` like objects, see :ref:`here <whatsnew_0180.enhancements.moments>`.
+- API breaking ``.resample`` changes to make it more ``.groupby`` like, see :ref:`here <whatsnew_0180.resample>`.
 
 Check the :ref:`API Changes <whatsnew_0180.api>` and :ref:`deprecations <whatsnew_0180.deprecations>` before updating.
 
@@ -202,6 +203,134 @@ other anchored offsets like ``MonthBegin`` and ``YearBegin``.
    d + pd.offsets.QuarterBegin(n=0, startingMonth=2)
 
 
+.. _whatsnew_0180.enhancements.resample:
+
+Resample API
+^^^^^^^^^^^^
+
+Like the change in the window functions API `above :ref:whatsnew_0180.enhancements.moments:`, ``.resample(...)`` is changing to have
+a more groupy-like API. (:issue:`11732`).
+
+.. ipython:: python
+
+   np.random.seed(1234)
+   df = pd.DataFrame(np.random.rand(10,4),
+                     columns=list('ABCD'),
+                     index=pd.date_range('2010-01-01 09:00:00', periods=10, freq='s'))
+   df
+
+Previously you would write a resampling operations:
+
+This defaults to ``how='mean'``
+
+.. code-block:: python
+
+   In [6]: df.resample('2s')
+   Out[6]:
+                            A         B         C         D
+   2010-01-01 09:00:00  0.485748  0.447351  0.357096  0.793615
+   2010-01-01 09:00:02  0.820801  0.794317  0.364034  0.531096
+   2010-01-01 09:00:04  0.433985  0.314582  0.424104  0.625733
+   2010-01-01 09:00:06  0.624988  0.609738  0.633165  0.612452
+   2010-01-01 09:00:08  0.510470  0.534317  0.573201  0.806949
+
+You can also specify a ``how`` directly
+
+.. code-block:: python
+
+   In [7]: df.resample('2s',how='sum')
+   Out[7]:
+                            A         B         C         D
+   2010-01-01 09:00:00  0.971495  0.894701  0.714192  1.587231
+   2010-01-01 09:00:02  1.641602  1.588635  0.728068  1.062191
+   2010-01-01 09:00:04  0.867969  0.629165  0.848208  1.251465
+   2010-01-01 09:00:06  1.249976  1.219477  1.266330  1.224904
+   2010-01-01 09:00:08  1.020940  1.068634  1.146402  1.613897
+
+Now, you write ``.resample`` as a 2-stage operation like groupby, which
+yields a ``Resampler``.
+
+.. ipython:: python
+
+   r = df.resample('2s')
+   r
+
+Downsampling
+''''''''''''
+
+You can then use this object to perform similar operations.
+These are downsampling operations (going from a lower frequency to a higher one).
+
+.. ipython:: python
+
+   r.mean()
+
+.. ipython:: python
+
+   r.sum()
+
+Furthermore, resample now supports ``getitem`` operations to selectively perform the resample.
+
+.. ipython:: python
+
+   r[['A','C']].mean()
+
+ and ``.aggregate`` type of operations.
+
+.. ipython:: python
+
+   r.agg({'A' : 'mean', 'B' : 'sum'})
+
+These accessors can of course, be combined
+
+.. ipython:: python
+
+   r[['A','B']].agg(['mean','sum'])
+
+Upsampling
+''''''''''
+
+Upsampling operations take you from a higher frequency to a lower frequency. These are now
+performed with the ``Resampler`` objects with pad/fill/upsample methods.
+
+.. ipython:: python
+
+   s = Series(np.arange(5,dtype='int64'),
+              index=date_range('2010-01-01', periods=5, freq='Q'))
+   s
+
+Previously
+
+.. code-block:: python
+
+   In [6]: s.resample('M', fill_method='ffill')
+   Out[6]:
+   2010-03-31    0
+   2010-04-30    0
+   2010-05-31    0
+   2010-06-30    1
+   2010-07-31    1
+   2010-08-31    1
+   2010-09-30    2
+   2010-10-31    2
+   2010-11-30    2
+   2010-12-31    3
+   2011-01-31    3
+   2011-02-28    3
+   2011-03-31    4
+   Freq: M, dtype: int64
+
+New API
+
+.. ipython:: python
+
+   s.resample('M').ffill()
+
+:: note:
+
+   In the new API, you can either downsample OR upsample. The prior implementation would allow you to pass an aggregator function (like ``mean``) even though you were upsampling, provide a bit of confusion.
+
+
 Other API Changes
 ^^^^^^^^^^^^^^^^^
 

pandas/core/generic.py

@@ -3556,22 +3556,14 @@ def resample(self, rule, how=None, axis=0, fill_method=None,
         ----------
         rule : string
             the offset string or object representing target conversion
-        how : string
-            method for down- or re-sampling, default to 'mean' for
-            downsampling
         axis : int, optional, default 0
-        fill_method : string, default None
-            fill_method for upsampling
         closed : {'right', 'left'}
             Which side of bin interval is closed
         label : {'right', 'left'}
             Which bin edge label to label bucket with
         convention : {'start', 'end', 's', 'e'}
-        kind : "period"/"timestamp"
         loffset : timedelta
             Adjust the resampled time labels
-        limit : int, default None
-            Maximum size gap to when reindexing with fill_method
         base : int, default 0
             For frequencies that evenly subdivide 1 day, the "origin" of the
             aggregated intervals. For example, for '5min' frequency, base could
@@ -3600,7 +3592,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None,
         Downsample the series into 3 minute bins and sum the values
         of the timestamps falling into a bin.
 
-        >>> series.resample('3T', how='sum')
+        >>> series.resample('3T').sum()
         2000-01-01 00:00:00     3
         2000-01-01 00:03:00    12
         2000-01-01 00:06:00    21
@@ -3616,7 +3608,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None,
         To include this value close the right side of the bin interval as
         illustrated in the example below this one.
 
-        >>> series.resample('3T', how='sum', label='right')
+        >>> series.resample('3T', label='right').sum()
         2000-01-01 00:03:00     3
         2000-01-01 00:06:00    12
         2000-01-01 00:09:00    21
@@ -3625,7 +3617,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None,
         Downsample the series into 3 minute bins as above, but close the right
         side of the bin interval.
 
-        >>> series.resample('3T', how='sum', label='right', closed='right')
+        >>> series.resample('3T', label='right', closed='right').sum()
         2000-01-01 00:00:00     0
         2000-01-01 00:03:00     6
         2000-01-01 00:06:00    15
@@ -3634,7 +3626,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None,
 
         Upsample the series into 30 second bins.
 
-        >>> series.resample('30S')[0:5] #select first 5 rows
+        >>> series.resample('30S').upsample()[0:5] #select first 5 rows
         2000-01-01 00:00:00     0
         2000-01-01 00:00:30   NaN
         2000-01-01 00:01:00     1
@@ -3645,7 +3637,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None,
         Upsample the series into 30 second bins and fill the ``NaN``
         values using the ``pad`` method.
 
-        >>> series.resample('30S', fill_method='pad')[0:5]
+        >>> series.resample('30S').pad()[0:5]
         2000-01-01 00:00:00    0
         2000-01-01 00:00:30    0
         2000-01-01 00:01:00    1
@@ -3656,34 +3648,62 @@ def resample(self, rule, how=None, axis=0, fill_method=None,
         Upsample the series into 30 second bins and fill the
         ``NaN`` values using the ``bfill`` method.
 
-        >>> series.resample('30S', fill_method='bfill')[0:5]
+        >>> series.resample('30S').bfill()[0:5]
         2000-01-01 00:00:00    0
         2000-01-01 00:00:30    1
         2000-01-01 00:01:00    1
         2000-01-01 00:01:30    2
         2000-01-01 00:02:00    2
         Freq: 30S, dtype: int64
 
-        Pass a custom function to ``how``.
+        Pass a custom function via ``apply``
 
         >>> def custom_resampler(array_like):
         ...     return np.sum(array_like)+5
 
-        >>> series.resample('3T', how=custom_resampler)
+        >>> series.resample('3T').apply(custom_resampler)
         2000-01-01 00:00:00     8
         2000-01-01 00:03:00    17
         2000-01-01 00:06:00    26
         Freq: 3T, dtype: int64
 
         """
+        from pandas.tseries.resample import resample
 
-        from pandas.tseries.resample import TimeGrouper
         axis = self._get_axis_number(axis)
-        sampler = TimeGrouper(rule, label=label, closed=closed, how=how,
-                              axis=axis, kind=kind, loffset=loffset,
-                              fill_method=fill_method, convention=convention,
-                              limit=limit, base=base)
-        return sampler.resample(self).__finalize__(self)
+        r = resample(self, freq=rule, label=label, closed=closed,
+                     axis=axis, kind=kind, loffset=loffset,
+                     fill_method=fill_method, convention=convention,
+                     limit=limit, base=base)
+
+        # deprecation warning
+        # but call the method anyhow
+        if fill_method is not None:
+            args = "limit={0}".format(limit) if limit is not None else ""
+            warnings.warn("fill_method is deprecated to .resample()\nthe new syntax is "
+                          ".resample(...).{fill_method}({args})".format(fill_method=fill_method,
+                                                                        args=args),
+                          FutureWarning, stacklevel=2)
+            return r.aggregate(fill_method, limit=limit)
+
+        # deprecation warning
+        # but call the method anyhow
+        if how is not None:
+
+            # .resample(..., how='sum')
+            if isinstance(how, compat.string_types):
+                method = "{0}()".format(how)
+
+            # .resample(..., how=lambda x: ....)
+            else:
+                method = ".apply(<func>)"
+
+            warnings.warn("how in .resample() is deprecated\nthe new syntax is "
+                          ".resample(...).{method}".format(method=method),
+                          FutureWarning, stacklevel=2)
+            return r.aggregate(how)
+
+        return r
 
     def first(self, offset):
         """