DOC: update groupby docs for using pd.Grouper

Author: jreback

doc/source/groupby.rst

@@ -707,6 +707,52 @@ can be used as group keys. If so, the order of the levels will be preserved:
 
    data.groupby(factor).mean()
 
+.. _groupby.specify:
+
+Grouping with a Grouper specification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your may need to specify a bit more data to properly group. You can
+use the ``pd.Grouper`` to provide this local control.
+
+.. ipython:: python
+
+   import datetime as DT
+
+   df = DataFrame({
+          'Branch' : 'A A A A A A A B'.split(),
+          'Buyer': 'Carl Mark Carl Carl Joe Joe Joe Carl'.split(),
+          'Quantity': [1,3,5,1,8,1,9,3],
+          'Date' : [
+                DT.datetime(2013,1,1,13,0),
+                DT.datetime(2013,1,1,13,5),
+                DT.datetime(2013,10,1,20,0),
+                DT.datetime(2013,10,2,10,0),
+                DT.datetime(2013,10,1,20,0),
+                DT.datetime(2013,10,2,10,0),
+                DT.datetime(2013,12,2,12,0),
+                DT.datetime(2013,12,2,14,0),
+                ]})
+
+   df
+
+Groupby a specific column with the desired frequency. This is like resampling.
+
+.. ipython:: python
+
+   df.groupby([pd.Grouper(freq='1M',key='Date'),'Buyer']).sum()
+
+You have an ambiguous specification in that you have a named index and a column
+that could be potential groupers.
+
+.. ipython:: python
+
+   df = df.set_index('Date')
+   df['Date'] = df.index + pd.offsets.MonthEnd(2)
+   df.groupby([pd.Grouper(freq='6M',key='Date'),'Buyer']).sum()
+
+   df.groupby([pd.Grouper(freq='6M',level='Date'),'Buyer']).sum()
+
 
 Taking the first rows of each group
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -753,7 +799,7 @@ To select from a DataFrame or Series the nth item, use the nth method:
 
    g.nth(-1)
 
-If you want to select the nth not-null method, use the dropna kwarg. For a DataFrame this should be either 'any' or 'all' just like you would pass to dropna, for a Series this just needs to be truthy. 
+If you want to select the nth not-null method, use the dropna kwarg. For a DataFrame this should be either 'any' or 'all' just like you would pass to dropna, for a Series this just needs to be truthy.
 
 .. ipython:: python
 
@@ -808,7 +854,7 @@ column index name will be used as the name of the inserted column:
         'b':  [0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1],
         'c':  [1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0],
         'd':  [0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1],
-        }) 
+        })
 
    def compute_metrics(x):
        result = {'b_sum': x['b'].sum(), 'c_mean': x['c'].mean()}

doc/source/release.rst

@@ -125,6 +125,8 @@ API Changes
     ``DataFrame.stack`` operations where the name of the column index is used as
     the name of the inserted column containing the pivoted data.
 
+- Allow specification of a more complex groupby, via ``pd.Groupby`` (:issue:`3794`)
+
 Experimental Features
 ~~~~~~~~~~~~~~~~~~~~~
 

doc/source/v0.14.0.txt

@@ -90,6 +90,8 @@ These are out-of-bounds selections
 
      g.nth(0, dropna='any')  # similar to old behaviour
 
+- Allow specification of a more complex groupby via ``pd.Groupby``, See :ref:`the docs <groupby.specify>`. (:issue:`3794`)
+
 - Local variable usage has changed in
   :func:`pandas.eval`/:meth:`DataFrame.eval`/:meth:`DataFrame.query`
   (:issue:`5987`). For the :class:`~pandas.DataFrame` methods, two things have

pandas/tests/test_groupby.py

@@ -2933,7 +2933,7 @@ def test_timegrouper_with_reg_groups(self):
                 DT.datetime(2013,12,31,0,0),
                 DT.datetime(2013,12,31,0,0),
                 ]}).set_index(['Date','Buyer'])
-        result = df.groupby([pd.TimeGrouper('A'),'Buyer']).sum()
+        result = df.groupby([pd.Grouper(freq='A'),'Buyer']).sum()
         assert_frame_equal(result,expected)
 
         expected = DataFrame({
@@ -2946,7 +2946,7 @@ def test_timegrouper_with_reg_groups(self):
                 DT.datetime(2013,7,1,0,0),
                 ]}).set_index(['Date','Buyer'])
 
-        result = df.groupby([pd.TimeGrouper('6MS'),'Buyer']).sum()
+        result = df.groupby([pd.Grouper(freq='6MS'),'Buyer']).sum()
         assert_frame_equal(result,expected)
 
         df = DataFrame({
@@ -2975,10 +2975,10 @@ def test_timegrouper_with_reg_groups(self):
                 DT.datetime(2013,10,2,0,0),
                 ]}).set_index(['Date','Buyer'])
 
-        result = df.groupby([pd.TimeGrouper('1D'),'Buyer']).sum()
+        result = df.groupby([pd.Grouper(freq='1D'),'Buyer']).sum()
         assert_frame_equal(result,expected)
 
-        result = df.groupby([pd.TimeGrouper('1M'),'Buyer']).sum()
+        result = df.groupby([pd.Grouper(freq='1M'),'Buyer']).sum()
         expected = DataFrame({
             'Buyer': 'Carl Joe Mark'.split(),
             'Quantity': [10,18,3],