docs & fix window test

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -428,7 +428,6 @@ Using ``.iloc``. Here we will get the location of the 'A' column, then use *posi
   df.iloc[[0, 2], df.columns.get_loc('A')]
 
 
-<<<<<<< c25fbde09272f369f280212e5216441d5975687c
 .. _whatsnew_0200.api_breaking.deprecate_panel:
 
 Deprecate Panel
@@ -461,33 +460,41 @@ Convert to an xarray DataArray
 Deprecate groupby.agg() with a dictionary when renaming
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``.groupby(..).agg(..)`` syntax can accept a variable of inputs, including scalars, list, and a dictionary of column names to scalars or lists.
-This provides a useful syntax for constructing multiple (potentially different) aggregations for a groupby.
+The ``.groupby(..).agg(..)``, ``.rolling(..).agg(..)``, and ``.resample(..).agg(..)``  syntax can accept a variable of inputs, including scalars,
+list, and a dict of column names to scalars or lists. This provides a useful syntax for constructing multiple
+(potentially different) aggregations.
 
-1) We are deprecating passing a dictionary to a grouped ``Series``. This allowed one to ``rename`` the resulting aggregation, but this had a completely different
-meaning that passing a dictionary to a grouped ``DataFrame``, which accepts column-to-aggregations.
-2) We are deprecating passing a dict-of-dict to a grouped ``DataFrame`` in a similar manner.
+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.
 
-Here's an example of 1), passing a dict to a grouped ``Series``:
+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.
+
+This is an illustrative example:
 
 .. ipython:: python
 
     df = pd.DataFrame({'A': [1, 1, 1, 2, 2],
                        'B': range(5),
-                       'C':range(5)})
+                       'C': range(5)})
     df
 
-Aggregating a DataFrame with column selection.
+Here is a typical useful syntax for computing different aggregations for different columns. This
+is a natural (and useful) syntax. We aggregate from the dict-to-list by taking the specified
+columns and applying the list of functions. This returns a ``MultiIndex`` for the columns.
 
 .. ipython:: python
 
    df.groupby('A').agg({'B': ['sum', 'max'],
                         'C': ['count', 'min']})
 
 
-We are deprecating the following
+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. Which 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
@@ -506,7 +513,7 @@ You can accomplish the same operation, more idiomatically by:
    df.groupby('A').B.agg(['count']).rename({'count': 'foo'})
 
 
-Here's an example of 2), passing a dict-of-dict to a grouped ``DataFrame``:
+Here's an example of the second deprecation (2), passing a dict-of-dict to a grouped ``DataFrame``:
 
 .. code-block:: python
 

pandas/core/base.py

@@ -497,6 +497,7 @@ def _aggregate(self, arg, *args, **kwargs):
                                                      'dictionary'.format(k))
 
                         # deprecation of nested renaming
+                        # GH 15931
                         warnings.warn(
                             ("using a dict with renaming "
                              "is deprecated and will be removed in a future "
@@ -506,7 +507,8 @@ def _aggregate(self, arg, *args, **kwargs):
                 arg = new_arg
 
             else:
-                # we may have renaming keys
+                # deprecation of renaming keys
+                # GH 15931
                 keys = list(compat.iterkeys(arg))
                 if (isinstance(obj, ABCDataFrame) and
                         len(obj.columns.intersection(keys)) != len(keys)):

pandas/core/groupby.py

@@ -2837,6 +2837,7 @@ def _aggregate_multiple_funcs(self, arg, _level):
 
             # show the deprecation, but only if we
             # have not shown a higher level one
+            # GH 15931
             if isinstance(self._selected_obj, Series) and _level <= 1:
                 warnings.warn(
                     ("using a dict on a Series for aggregation\n"

pandas/tests/test_window.py

@@ -134,16 +134,18 @@ def test_agg(self):
         expected.columns = ['mean', 'sum']
         tm.assert_frame_equal(result, expected)
 
-        result = r.aggregate({'A': {'mean': 'mean', 'sum': 'sum'}})
+        with catch_warnings(record=True):
+            result = r.aggregate({'A': {'mean': 'mean', 'sum': 'sum'}})
         expected = pd.concat([a_mean, a_sum], axis=1)
         expected.columns = pd.MultiIndex.from_tuples([('A', 'mean'),
                                                       ('A', 'sum')])
         tm.assert_frame_equal(result, expected, check_like=True)
 
-        result = r.aggregate({'A': {'mean': 'mean',
-                                    'sum': 'sum'},
-                              'B': {'mean2': 'mean',
-                                    'sum2': 'sum'}})
+        with catch_warnings(record=True):
+            result = r.aggregate({'A': {'mean': 'mean',
+                                        'sum': 'sum'},
+                                  'B': {'mean2': 'mean',
+                                        'sum2': 'sum'}})
         expected = pd.concat([a_mean, a_sum, b_mean, b_sum], axis=1)
         exp_cols = [('A', 'mean'), ('A', 'sum'), ('B', 'mean2'), ('B', 'sum2')]
         expected.columns = pd.MultiIndex.from_tuples(exp_cols)
@@ -195,12 +197,14 @@ def f():
                               r['B'].std()], axis=1)
         expected.columns = pd.MultiIndex.from_tuples([('ra', 'mean'), (
             'ra', 'std'), ('rb', 'mean'), ('rb', 'std')])
-        result = r[['A', 'B']].agg({'A': {'ra': ['mean', 'std']},
-                                    'B': {'rb': ['mean', 'std']}})
+        with catch_warnings(record=True):
+            result = r[['A', 'B']].agg({'A': {'ra': ['mean', 'std']},
+                                        'B': {'rb': ['mean', 'std']}})
         tm.assert_frame_equal(result, expected, check_like=True)
 
-        result = r.agg({'A': {'ra': ['mean', 'std']},
-                        'B': {'rb': ['mean', 'std']}})
+        with catch_warnings(record=True):
+            result = r.agg({'A': {'ra': ['mean', 'std']},
+                            'B': {'rb': ['mean', 'std']}})
         expected.columns = pd.MultiIndex.from_tuples([('A', 'ra', 'mean'), (
             'A', 'ra', 'std'), ('B', 'rb', 'mean'), ('B', 'rb', 'std')])
         tm.assert_frame_equal(result, expected, check_like=True)