DOC add groupby head and tail to docs

Author: hayd

doc/source/groupby.rst

@@ -707,6 +707,38 @@ can be used as group keys. If so, the order of the levels will be preserved:
 
    data.groupby(factor).mean()
 
+
+Taking the first rows of each group
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just like for a DataFrame or Series you can call head and tail on a groupby:
+
+.. ipython:: python
+
+   df = DataFrame([[1, 2], [1, 4], [5, 6]], columns=['A', 'B'])
+   df
+
+   g = df.groupby('A')
+   g.head(1)
+
+   g.tail(1)
+
+This shows the first or last n rows from each group.
+
+.. warning::
+
+   Before 0.14.0 this was implemented with a fall-through apply,
+   so the result would incorrectly respect the as_index flag:
+
+   .. code-block:: python
+
+       >>> g.head(1):  # was equivalent to g.apply(lambda x: x.head(1))
+             A  B
+        A
+        1 0  1  2
+        5 2  5  6
+
+
 Enumerate group items
 ~~~~~~~~~~~~~~~~~~~~~
 

doc/source/v0.14.0.txt

@@ -61,6 +61,24 @@ These are out-of-bounds selections
      s.year
      s.index.year
 
+- More consistent behaviour for some groupby methods:
+   - groupby head and tail now act more like filter rather than an aggregation:
+
+  .. ipython:: python
+
+     df = pd.DataFrame([[1, 2], [1, 4], [5, 6]], columns=['A', 'B'])
+     g = df.groupby('A')
+     g.head(1)  # filters DataFrame
+
+     g.apply(lambda x: x.head(1))  # used to simply fall-through
+
+   - groupby head and tail respect column selection:
+
+  .. ipython:: python
+
+     g[['B']].head(1)
+
+
 - 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/core/groupby.py

@@ -587,7 +587,8 @@ def head(self, n=5):
         """
         Returns first n rows of each group.
 
-        Essentially equivalent to ``.apply(lambda x: x.head(n))`` except ignores as_index flag.
+        Essentially equivalent to ``.apply(lambda x: x.head(n))``,
+        except ignores as_index flag.
 
         Example
         -------
@@ -614,7 +615,8 @@ def tail(self, n=5):
         """
         Returns last n rows of each group
 
-        Essentially equivalent to ``.apply(lambda x: x.tail(n))``
+        Essentially equivalent to ``.apply(lambda x: x.tail(n))``,
+        except ignores as_index flag.
 
         Example
         -------