original API detection & warning

support for isinstance / numeric ops

support for comparison ops

Author: jreback

doc/source/timeseries.rst

@@ -68,7 +68,7 @@ Resample:
 .. ipython:: python
 
    # Daily means
-   ts.resample('D', how='mean')
+   ts.resample('D').mean()
 
 
 .. _timeseries.overview:
@@ -1091,7 +1091,7 @@ An example of how holidays and holiday calendars are defined:
 Using this calendar, creating an index or doing offset arithmetic skips weekends
 and holidays (i.e., Memorial Day/July 4th).  For example, the below defines
 a custom business day offset using the ``ExampleCalendar``.  Like any other offset,
-it can be used to create a ``DatetimeIndex`` or added to ``datetime`` 
+it can be used to create a ``DatetimeIndex`` or added to ``datetime``
 or ``Timestamp`` objects.
 
 .. ipython:: python
@@ -1211,6 +1211,11 @@ Converting to Python datetimes
 Resampling
 ----------
 
+.. warning::
+
+   The interface to ``.resample`` has changed in 0.18.0 to be more groupby-like and hence more flexible.
+   See the :ref:`whatsnew docs <whatsnew_0180.breaking.resample>` for a comparison with prior versions.
+
 Pandas has a simple, powerful, and efficient functionality for
 performing resampling operations during frequency conversion (e.g., converting
 secondly data into 5-minutely data). This is extremely common in, but not
@@ -1226,7 +1231,7 @@ See some :ref:`cookbook examples <cookbook.resample>` for some advanced strategi
 
    ts = Series(randint(0, 500, len(rng)), index=rng)
 
-   ts.resample('5Min', how='sum')
+   ts.resample('5Min').sum()
 
 The ``resample`` function is very flexible and allows you to specify many
 different parameters to control the frequency conversion and resampling
@@ -1237,11 +1242,11 @@ an array and produces aggregated values:
 
 .. ipython:: python
 
-   ts.resample('5Min') # default is mean
+   ts.resample('5Min').mean()
 
-   ts.resample('5Min', how='ohlc')
+   ts.resample('5Min').ohlc()
 
-   ts.resample('5Min', how=np.max)
+   ts.resample('5Min').max()
 
 Any function available via :ref:`dispatching <groupby.dispatch>` can be given to
 the ``how`` parameter by name, including ``sum``, ``mean``, ``std``, ``sem``,
@@ -1284,18 +1289,17 @@ frequency periods.
 Up Sampling
 ~~~~~~~~~~~
 
-For upsampling, the ``fill_method`` and ``limit`` parameters can be specified
-to interpolate over the gaps that are created:
+For upsampling, you can specify an way to upsample and the ``limit`` parameter to interpolate over the gaps that are created:
 
 .. ipython:: python
 
    # from secondly to every 250 milliseconds
 
-   ts[:2].resample('250L')
+   ts[:2].resample('250L').upsample()
 
-   ts[:2].resample('250L', fill_method='pad')
+   ts[:2].resample('250L').ffill()
 
-   ts[:2].resample('250L', fill_method='pad', limit=2)
+   ts[:2].resample('250L').ffill(limit=2)
 
 Sparse Resampling
 ~~~~~~~~~~~~~~~~~
@@ -1317,7 +1321,7 @@ If we want to resample to the full range of the series
 
 .. ipython:: python
 
-    ts.resample('3T',how='sum')
+    ts.resample('3T').sum()
 
 We can instead only resample those groups where we have points as follows:
 

doc/source/whatsnew/v0.10.0.txt

@@ -70,16 +70,59 @@ nfrequencies are unaffected. The prior defaults were causing a great deal of
 confusion for users, especially resampling data to daily frequency (which
 labeled the aggregated group with the end of the interval: the next day).
 
-Note:
-
-.. ipython:: python
-
-    dates = pd.date_range('1/1/2000', '1/5/2000', freq='4h')
-    series = Series(np.arange(len(dates)), index=dates)
-    series
-    series.resample('D', how='sum')
-    # old behavior
-    series.resample('D', how='sum', closed='right', label='right')
+.. code-block:: python
+
+   In [1]: dates = pd.date_range('1/1/2000', '1/5/2000', freq='4h')
+
+   In [2]: series = Series(np.arange(len(dates)), index=dates)
+
+   In [3]: series
+   Out[3]:
+   2000-01-01 00:00:00     0
+   2000-01-01 04:00:00     1
+   2000-01-01 08:00:00     2
+   2000-01-01 12:00:00     3
+   2000-01-01 16:00:00     4
+   2000-01-01 20:00:00     5
+   2000-01-02 00:00:00     6
+   2000-01-02 04:00:00     7
+   2000-01-02 08:00:00     8
+   2000-01-02 12:00:00     9
+   2000-01-02 16:00:00    10
+   2000-01-02 20:00:00    11
+   2000-01-03 00:00:00    12
+   2000-01-03 04:00:00    13
+   2000-01-03 08:00:00    14
+   2000-01-03 12:00:00    15
+   2000-01-03 16:00:00    16
+   2000-01-03 20:00:00    17
+   2000-01-04 00:00:00    18
+   2000-01-04 04:00:00    19
+   2000-01-04 08:00:00    20
+   2000-01-04 12:00:00    21
+   2000-01-04 16:00:00    22
+   2000-01-04 20:00:00    23
+   2000-01-05 00:00:00    24
+   Freq: 4H, dtype: int64
+
+   In [4]: series.resample('D', how='sum')
+   Out[4]:
+   2000-01-01     15
+   2000-01-02     51
+   2000-01-03     87
+   2000-01-04    123
+   2000-01-05     24
+   Freq: D, dtype: int64
+
+   In [5]: # old behavior
+   In [6]: series.resample('D', how='sum', closed='right', label='right')
+   Out[6]:
+   2000-01-01      0
+   2000-01-02     21
+   2000-01-03     57
+   2000-01-04     93
+   2000-01-05    129
+   Freq: D, dtype: int64
 
 - Infinity and negative infinity are no longer treated as NA by ``isnull`` and
   ``notnull``. That they every were was a relic of early pandas. This behavior
@@ -354,4 +397,3 @@ Adding experimental support for Panel4D and factory functions to create n-dimens
 See the :ref:`full release notes
 <release>` or issue tracker
 on GitHub for a complete list.
-

doc/source/whatsnew/v0.18.0.txt

@@ -203,12 +203,12 @@ other anchored offsets like ``MonthBegin`` and ``YearBegin``.
    d + pd.offsets.QuarterBegin(n=0, startingMonth=2)
 
 
-.. _whatsnew_0180.enhancements.resample:
+.. _whatsnew_0180.breaking.resample:
 
 Resample API
 ^^^^^^^^^^^^
 
-Like the change in the window functions API `above :ref:whatsnew_0180.enhancements.moments:`, ``.resample(...)`` is changing to have
+Like the change in the window functions API :ref:`above <whatsnew_0180.enhancements.moments>`, ``.resample(...)`` is changing to have
 a more groupy-like API. (:issue:`11732`).
 
 .. ipython:: python
@@ -219,7 +219,10 @@ a more groupy-like API. (:issue:`11732`).
                      index=pd.date_range('2010-01-01 09:00:00', periods=10, freq='s'))
    df
 
-Previously you would write a resampling operations:
+
+**Previous API**:
+
+You would write a resampling operation that immediately evaluates.
 
 This defaults to ``how='mean'``
 
@@ -234,7 +237,7 @@ This defaults to ``how='mean'``
    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
+You could also specify a ``how`` directly
 
 .. code-block:: python
 
@@ -247,6 +250,37 @@ You can also specify a ``how`` directly
    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
 
+.. warning::
+
+   This change will allow the existing API to work with a deprecation warning in most cases. Here is a typical use case:
+
+   .. code-block:: python
+
+      In [4]: r = df.resample('2s')
+
+      In [6]: r*10
+      pandas/tseries/resample.py:80: FutureWarning: .resample() is now a deferred operation
+      use .resample(...).mean() instead of .resample(...)
+
+      Out[6]:
+                            A         B         C         D
+      2010-01-01 09:00:00  4.857476  4.473507  3.570960  7.936154
+      2010-01-01 09:00:02  8.208011  7.943173  3.640340  5.310957
+      2010-01-01 09:00:04  4.339846  3.145823  4.241039  6.257326
+      2010-01-01 09:00:06  6.249881  6.097384  6.331650  6.124518
+      2010-01-01 09:00:08  5.104699  5.343172  5.732009  8.069486
+
+   Assignment operations will raise a ``ValueError``:
+
+   .. code-block:: python
+
+      In [7]: r.iloc[0] = 5
+      ValueError: .resample() is now a deferred operation
+            use .resample(...).mean() instead of .resample(...)
+            assignment will have no effect as you are working on a copy
+
+**New API**:
+
 Now, you write ``.resample`` as a 2-stage operation like groupby, which
 yields a ``Resampler``.
 
@@ -269,13 +303,13 @@ These are downsampling operations (going from a lower frequency to a higher one)
 
    r.sum()
 
-Furthermore, resample now supports ``getitem`` operations to selectively perform the resample.
+Furthermore, resample now supports ``getitem`` operations to perform the resample on specific columns.
 
 .. ipython:: python
 
    r[['A','C']].mean()
 
- and ``.aggregate`` type of operations.
+and ``.aggregate`` type operations.
 
 .. ipython:: python
 
@@ -290,8 +324,11 @@ These accessors can of course, be combined
 Upsampling
 ''''''''''
 
+.. currentmodule:: pandas.tseries.resample
+
 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.
+performed with the ``Resampler`` objects with :meth:`~Resampler.pad`,
+:meth:`~Resampler.ffill`, and :meth:`~Resampler.upsample` methods.
 
 .. ipython:: python
 
@@ -326,7 +363,7 @@ New API
 
    s.resample('M').ffill()
 
-:: note:
+.. 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.
 

doc/source/whatsnew/v0.9.1.txt

@@ -112,14 +112,21 @@ API changes
   - Upsampling data with a PeriodIndex will result in a higher frequency
     TimeSeries that spans the original time window
 
-    .. ipython:: python
-
-        prng = period_range('2012Q1', periods=2, freq='Q')
+    .. code-block:: python
 
-        s = Series(np.random.randn(len(prng)), prng)
+       In [1]: prng = period_range('2012Q1', periods=2, freq='Q')
 
-        s.resample('M')
+       In [2]: s = Series(np.random.randn(len(prng)), prng)
 
+       In [4]: s.resample('M')
+       Out[4]:
+       2012-01   -1.471992
+       2012-02         NaN
+       2012-03         NaN
+       2012-04   -0.493593
+       2012-05         NaN
+       2012-06         NaN
+       Freq: M, dtype: float64
 
   - Period.end_time now returns the last nanosecond in the time interval
     (:issue:`2124`, :issue:`2125`, :issue:`1764`)

pandas/core/groupby.py

@@ -302,6 +302,7 @@ def f(self):
 
 class _GroupBy(PandasObject, SelectionMixin):
     _group_selection = None
+    _apply_whitelist = frozenset([])
 
     def __init__(self, obj, keys=None, axis=0, level=None,
                  grouper=None, exclusions=None, selection=None, as_index=True,
@@ -2697,6 +2698,7 @@ def true_and_notnull(x, *args, **kwargs):
         return filtered
 
     def nunique(self, dropna=True):
+        """ Returns number of unique elements in the group """
         ids, _, _ = self.grouper.group_info
         val = self.obj.get_values()