update docs per review

doc/source/computation.rst

@@ -610,14 +610,6 @@ aggregation with, outputting a DataFrame:
 
    r['A'].agg([np.sum, np.mean, np.std])
 
-If a dict is passed, the keys will be used to name the columns. Otherwise the
-function's name (stored in the function object) will be used.
-
-.. ipython:: python
-
-   r['A'].agg({'result1' : np.sum,
-               'result2' : np.mean})
-
 On a widowed DataFrame, you can pass a list of functions to apply to each
 column, which produces an aggregated result with a hierarchical index:
 

doc/source/groupby.rst

@@ -502,31 +502,43 @@ index are the group names and whose values are the sizes of each group.
 Applying multiple functions at once
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-With grouped Series you can also pass a list or dict of functions to do
+With grouped ``Series`` you can also pass a list or dict of functions to do
 aggregation with, outputting a DataFrame:
 
 .. ipython:: python
 
    grouped = df.groupby('A')
    grouped['C'].agg([np.sum, np.mean, np.std])
 
-If a dict is passed, the keys will be used to name the columns. Otherwise the
-function's name (stored in the function object) will be used.
+On a grouped ``DataFrame``, you can pass a list of functions to apply to each
+column, which produces an aggregated result with a hierarchical index:
 
 .. ipython:: python
 
-   grouped['D'].agg({'result1' : np.sum,
-                     'result2' : np.mean})
+   grouped.agg([np.sum, np.mean, np.std])
 
-On a grouped DataFrame, you can pass a list of functions to apply to each
-column, which produces an aggregated result with a hierarchical index:
+
+The resulting aggregations are named for the functions themselves. If you
+need to rename, then you can add in a chained operation for a ``Series`` like this:
 
 .. ipython:: python
 
-   grouped.agg([np.sum, np.mean, np.std])
+   (grouped['C'].agg([np.sum, np.mean, np.std])
+                .rename(columns={'sum': 'foo',
+                                 'mean': 'bar',
+                                 'std': 'baz'})
+   )
+
+For a grouped ``DataFrame``, you can rename in a similar manner:
+
+.. ipython:: python
+
+   (grouped.agg([np.sum, np.mean, np.std])
+           .rename(columns={'sum': 'foo',
+                            'mean': 'bar',
+                            'std': 'baz'})
+    )
 
-Passing a dict of functions has different behavior by default, see the next
-section.
 
 Applying different functions to DataFrame columns
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/source/timeseries.rst

@@ -1549,14 +1549,6 @@ You can pass a list or dict of functions to do aggregation with, outputting a Da
 
    r['A'].agg([np.sum, np.mean, np.std])
 
-If a dict is passed, the keys will be used to name the columns. Otherwise the
-function's name (stored in the function object) will be used.
-
-.. ipython:: python
-
-   r['A'].agg({'result1' : np.sum,
-               'result2' : np.mean})
-
 On a resampled DataFrame, you can pass a list of functions to apply to each
 column, which produces an aggregated result with a hierarchical index:
 

doc/source/whatsnew/v0.20.0.txt

@@ -466,12 +466,12 @@ list, and a dict of column names to scalars or lists. This provides a useful syn
 (potentially different) aggregations.
 
 However, ``.agg(..)`` can *also* accept a dict that allows 'renaming' of the result columns. This is a complicated and confusing syntax, as well as not consistent
-between ``Series`` and ``DataFrame``. We are deprecating this 'renaming' functionarility.
+between ``Series`` and ``DataFrame``. We are deprecating this 'renaming' functionaility.
 
 1) We are deprecating passing a dict to a grouped/rolled/resampled ``Series``. This allowed
 one to ``rename`` the resulting aggregation, but this had a completely different
 meaning than passing a dictionary to a grouped ``DataFrame``, which accepts column-to-aggregations.
-2) We are deprecating passing a dict-of-dict to a grouped/rolled/resampled ``DataFrame`` in a similar manner.
+2) We are deprecating passing a dict-of-dicts to a grouped/rolled/resampled ``DataFrame`` in a similar manner.
 
 This is an illustrative example:
 
@@ -488,17 +488,15 @@ columns and applying the list of functions. This returns a ``MultiIndex`` for th
 
 .. ipython:: python
 
-   df.groupby('A').agg({'B': ['sum', 'max'],
-                        'C': ['count', 'min']})
-
+   df.groupby('A').agg({'B': 'sum', 'C': 'min'})
 
 Here's an example of the first deprecation (1), passing a dict to a grouped ``Series``. This
 is a combination aggregation & renaming:
 
 .. code-block:: ipython
 
    In [6]: df.groupby('A').B.agg({'foo': 'count'})
-   FutureWarning: using a dictionary on a Series for aggregation
+   FutureWarning: using a dict on a Series for aggregation
    is deprecated and will be removed in a future version
 
    Out[6]:
@@ -518,24 +516,27 @@ Here's an example of the second deprecation (2), passing a dict-of-dict to a gro
 
 .. code-block:: python
 
-   In [23]: df.groupby('A').agg({'B': {'foo': ['sum', 'max']}, 'C': {'bar': ['count', 'min']}})
-   FutureWarning: using a dictionary on a Series for aggregation
-   is deprecated and will be removed in a future version
+   In [23]: (df.groupby('A')
+               .agg({'B': {'foo': 'sum'}, 'C': {'bar': 'min'}})
+            )
+   FutureWarning: using a dict with renaming is deprecated and will be removed in a future version
 
    Out[23]:
-     foo       bar
-     sum max count min
+        B   C
+      foo bar
    A
-   1   3   2     3   0
-   2   7   4     2   3
+   1   3   0
+   2   7   3
 
-You can accomplish the same by:
+
+You can accomplish nearly the same by:
 
 .. ipython:: python
 
-   r = df.groupby('A').agg({'B': ['sum', 'max'], 'C': ['count', 'min']})
-   r.columns = r.columns.set_levels(['foo', 'bar'], level=0)
-   r
+   (df.groupby('A')
+      .agg({'B': 'sum', 'C': 'min'})
+      .rename(columns={'B': 'foo', 'C': 'bar'})
+   )
 
 .. _whatsnew.api_breaking.io_compat:
 

pandas/core/base.py

@@ -292,8 +292,11 @@ class SelectionMixin(object):
 
     @property
     def _selection_name(self):
-        """ return a name for myself; this would ideally be the 'name' property, but
-        we cannot conflict with the Series.name property which can be set """
+        """
+        return a name for myself; this would ideally be called
+        the 'name' property, but we cannot conflict with the
+        Series.name property which can be set
+        """
         if self._selection is None:
             return None  # 'result'
         else:
@@ -502,7 +505,7 @@ def _aggregate(self, arg, *args, **kwargs):
                             ("using a dict with renaming "
                              "is deprecated and will be removed in a future "
                              "version"),
-                            FutureWarning, stacklevel=3)
+                            FutureWarning, stacklevel=4)
 
                 arg = new_arg
 
@@ -516,7 +519,7 @@ def _aggregate(self, arg, *args, **kwargs):
                         ("using a dict with renaming "
                          "is deprecated and will be removed in a future "
                          "version"),
-                        FutureWarning, stacklevel=3)
+                        FutureWarning, stacklevel=4)
 
             from pandas.tools.concat import concat
 

pandas/core/groupby.py

@@ -2843,7 +2843,7 @@ def _aggregate_multiple_funcs(self, arg, _level):
                     ("using a dict on a Series for aggregation\n"
                      "is deprecated and will be removed in a future "
                      "version"),
-                    FutureWarning, stacklevel=7)
+                    FutureWarning, stacklevel=4)
 
             columns = list(arg.keys())
             arg = list(arg.items())

pandas/tests/groupby/test_aggregate.py

@@ -316,6 +316,10 @@ def test_agg_dict_renaming_deprecation(self):
                                  'C': {'bar': ['count', 'min']}})
             assert "using a dict with renaming" in str(w[0].message)
 
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            df.groupby('A')[['B', 'C']].agg({'ma': 'max'})
+
         with tm.assert_produces_warning(FutureWarning,
                                         check_stacklevel=False) as w:
             df.groupby('A').B.agg({'foo': 'count'})