Deprecate passing reduction kernels to groupby.agg

Author: rhshadrach

pandas/core/groupby/generic.py

@@ -21,6 +21,7 @@
     Union,
     cast,
 )
+import warnings
 
 import numpy as np
 
@@ -32,6 +33,7 @@
     Substitution,
     doc,
 )
+from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
     ensure_int64,
@@ -62,6 +64,10 @@
 import pandas.core.common as com
 from pandas.core.frame import DataFrame
 from pandas.core.groupby import base
+from pandas.core.groupby.base import (
+    reduction_kernels,
+    transformation_kernels,
+)
 from pandas.core.groupby.groupby import (
     GroupBy,
     GroupByPlot,
@@ -326,6 +332,14 @@ def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs)
             kwargs = {}
 
         if isinstance(func, str):
+            if func not in reduction_kernels and not self._grouper._is_resample:
+                meth = "transform" if func in transformation_kernels else "apply"
+                warnings.warn(
+                    f"In the future, using the non-aggregation {func=} will raise a "
+                    f"ValueError, use this function with {type(self).__name__}.{meth}",
+                    category=DeprecationWarning,
+                    stacklevel=find_stack_level(),
+                )
             if maybe_use_numba(engine) and engine is not None:
                 # Not all agg functions support numba, only propagate numba kwargs
                 # if user asks for numba, and engine is not None
@@ -1562,6 +1576,19 @@ def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs)
             kwargs["engine"] = engine
             kwargs["engine_kwargs"] = engine_kwargs
 
+        if (
+            isinstance(func, str)
+            and func not in reduction_kernels
+            and not self._grouper._is_resample
+        ):
+            meth = "transform" if func in transformation_kernels else "apply"
+            warnings.warn(
+                f"In the future, using the non-aggregation {func=} will raise a "
+                f"ValueError, use this function with {type(self).__name__}.{meth}",
+                category=DeprecationWarning,
+                stacklevel=find_stack_level(),
+            )
+
         op = GroupByApply(self, func, args=args, kwargs=kwargs)
         result = op.agg()
         if not is_dict_like(func) and result is not None:

pandas/tests/groupby/aggregate/test_aggregate.py

@@ -48,28 +48,29 @@ def test_agg_regression1(tsframe):
 
 def test_agg_must_agg(df):
     grouped = df.groupby("A")["C"]
-    expected = pd.Series(
+    expected = Series(
         {
             "bar": df[df.A == "bar"]["C"].describe(),
             "foo": df[df.A == "foo"]["C"].describe(),
         },
-        index=pd.Index(["bar", "foo"], name="A"),
+        index=Index(["bar", "foo"], name="A"),
         name="C",
     )
     result = grouped.agg(lambda x: x.describe())
     tm.assert_series_equal(result, expected)
 
-    expected = pd.Series(
+    expected = Series(
         {
             "bar": df[df.A == "bar"]["C"].index[:2],
             "foo": df[df.A == "foo"]["C"].index[:2],
         },
-        index=pd.Index(["bar", "foo"], name="A"),
+        index=Index(["bar", "foo"], name="A"),
         name="C",
     )
     result = grouped.agg(lambda x: x.index[:2])
     tm.assert_series_equal(result, expected)
 
+
 def test_agg_ser_multi_key(df):
     f = lambda x: x.sum()
     results = df.C.groupby([df.A, df.B]).aggregate(f)
@@ -485,6 +486,9 @@ def test_groupby_agg_dict_dup_columns():
     tm.assert_frame_equal(result, expected)
 
 
+@pytest.mark.filterwarnings(
+    "ignore:In the future, using the non-aggregation func:DeprecationWarning"
+)
 @pytest.mark.parametrize(
     "op",
     [
@@ -564,7 +568,9 @@ def test_order_aggregate_multiple_funcs():
     # GH 25692
     df = DataFrame({"A": [1, 1, 2, 2], "B": [1, 2, 3, 4]})
 
-    res = df.groupby("A").agg(["sum", "max", "mean", "ohlc", "min"])
+    msg = "using the non-aggregation func='ohlc' will raise"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        res = df.groupby("A").agg(["sum", "max", "mean", "ohlc", "min"])
     result = res.columns.levels[1]
 
     expected = Index(["sum", "max", "mean", "ohlc", "min"])
@@ -1377,9 +1383,14 @@ def test_nonagg_agg():
     df = DataFrame({"a": [1, 1, 2, 2], "b": [1, 2, 2, 1]})
     g = df.groupby("a")
 
-    result = g.agg(["cumsum"])
+    msg = "using the non-aggregation func='cumsum' will raise"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        result = g.agg(["cumsum"])
     result.columns = result.columns.droplevel(-1)
-    expected = g.agg("cumsum")
+
+    msg = "using the non-aggregation func='cumsum' will raise"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        expected = g.agg("cumsum")
 
     tm.assert_frame_equal(result, expected)
 
@@ -1450,8 +1461,12 @@ def test_groupby_agg_precision(any_real_numeric_dtype):
         }
     )
 
-    expected = DataFrame({"key3": [df["key3"]]},
-                         index=pd.MultiIndex(levels=[["a"], ["b"]], codes=[[0], [0]], names=["key1", "key2"]))
+    expected = DataFrame(
+        {"key3": [df["key3"]]},
+        index=MultiIndex(
+            levels=[["a"], ["b"]], codes=[[0], [0]], names=["key1", "key2"]
+        ),
+    )
 
     result = df.groupby(["key1", "key2"]).agg(lambda x: x)
     tm.assert_frame_equal(result, expected)
@@ -1547,10 +1562,8 @@ def test_agg_of_mode_list(test, values):
     # Mode usually only returns 1 value, but can return a list in the case of a tie.
 
     expected = DataFrame(
-        [
-            [df1[df1[0] == value][1].mode()] for value in values
-        ],
-        index=pd.Index(values, name=0),
+        [[df1[df1[0] == value][1].mode()] for value in values],
+        index=Index(values, name=0),
         columns=[1],
     )
 
@@ -1659,7 +1672,9 @@ def test_groupby_agg_extension_timedelta_cumsum_with_named_aggregation():
         }
     )
     gb = df.groupby("grps")
-    result = gb.agg(td=("td", "cumsum"))
+    msg = "using the non-aggregation func='cumsum' will raise"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        result = gb.agg(td=("td", "cumsum"))
     tm.assert_frame_equal(result, expected)
 
 

pandas/tests/groupby/aggregate/test_cython.py

@@ -21,6 +21,7 @@
     bdate_range,
 )
 import pandas._testing as tm
+from pandas.core.groupby.base import reduction_kernels
 
 
 @pytest.mark.parametrize(
@@ -287,8 +288,16 @@ def test_read_only_buffer_source_agg(agg):
     )
     df._mgr.arrays[0].flags.writeable = False
 
-    result = df.groupby(["species"]).agg({"sepal_length": agg})
-    expected = df.copy().groupby(["species"]).agg({"sepal_length": agg})
+    if agg in reduction_kernels:
+        warn = None
+        msg = ""
+    else:
+        warn = DeprecationWarning
+        msg = f"using the non-aggregation func='{agg}' will raise"
+    with tm.assert_produces_warning(warn, match=msg):
+        result = df.groupby(["species"]).agg({"sepal_length": agg})
+    with tm.assert_produces_warning(warn, match=msg):
+        expected = df.copy().groupby(["species"]).agg({"sepal_length": agg})
 
     tm.assert_equal(result, expected)
 

pandas/tests/groupby/test_groupby.py

@@ -2467,7 +2467,7 @@ def test_by_column_values_with_same_starting_value(dtype):
     result = df.groupby(["Name"]).agg(aggregate_details)
     expected_result = DataFrame(
         {
-            "Mood": [pd.Series(["happy", "sad"]), pd.Series(["happy"])],
+            "Mood": [Series(["happy", "sad"]), Series(["happy"])],
             "Credit": [2500, 900],
             "Name": ["Thomas", "Thomas John"],
         }
@@ -2935,9 +2935,12 @@ def test_groupby_dropna_with_nunique_unique():
     # GH#42016
     df = [[1, 1, 1, "A"], [1, None, 1, "A"], [1, None, 2, "A"], [1, None, 3, "A"]]
     df_dropna = DataFrame(df, columns=["a", "b", "c", "partner"])
-    result = df_dropna.groupby(["a", "b", "c"], dropna=False).agg(
-        {"partner": ["nunique", "unique"]}
-    )
+
+    msg = "using the non-aggregation func='unique' will raise"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        result = df_dropna.groupby(["a", "b", "c"], dropna=False).agg(
+            {"partner": ["nunique", "unique"]}
+        )
 
     index = MultiIndex.from_tuples(
         [(1, 1.0, 1), (1, np.nan, 1), (1, np.nan, 2), (1, np.nan, 3)],

pandas/tests/groupby/test_raises.py

@@ -15,6 +15,7 @@
     Series,
 )
 import pandas._testing as tm
+from pandas.core.groupby.base import reduction_kernels
 from pandas.tests.groupby import get_groupby_method_args
 
 
@@ -84,8 +85,10 @@ def df_with_cat_col():
     return df
 
 
-def _call_and_check(klass, msg, how, gb, groupby_func, args, warn_msg=""):
-    warn_klass = None if warn_msg == "" else FutureWarning
+def _call_and_check(
+    klass, msg, how, gb, groupby_func, args, warn_msg="", warn_category=FutureWarning
+):
+    warn_klass = None if warn_msg == "" else warn_category
     with tm.assert_produces_warning(warn_klass, match=warn_msg, check_stacklevel=False):
         if klass is None:
             if how == "method":
@@ -183,9 +186,23 @@ def test_groupby_raises_string(
     if groupby_func == "fillna":
         kind = "Series" if groupby_series else "DataFrame"
         warn_msg = f"{kind}GroupBy.fillna is deprecated"
+    elif groupby_func not in reduction_kernels and how == "agg":
+        warn_msg = (
+            f"In the future, using the non-aggregation func='{groupby_func}' will "
+            "raise a ValueError"
+        )
     else:
         warn_msg = ""
-    _call_and_check(klass, msg, how, gb, groupby_func, args, warn_msg)
+    _call_and_check(
+        klass,
+        msg,
+        how,
+        gb,
+        groupby_func,
+        args,
+        warn_msg,
+        warn_category=DeprecationWarning,
+    )
 
 
 @pytest.mark.parametrize("how", ["agg", "transform"])
@@ -287,12 +304,30 @@ def test_groupby_raises_datetime(
 
     if groupby_func in ["any", "all"]:
         warn_msg = f"'{groupby_func}' with datetime64 dtypes is deprecated"
+        warn_category = FutureWarning
     elif groupby_func == "fillna":
         kind = "Series" if groupby_series else "DataFrame"
         warn_msg = f"{kind}GroupBy.fillna is deprecated"
+        warn_category = FutureWarning
+    elif groupby_func not in reduction_kernels and how == "agg":
+        warn_msg = (
+            f"In the future, using the non-aggregation func='{groupby_func}' will "
+            "raise a ValueError"
+        )
+        warn_category = DeprecationWarning
     else:
         warn_msg = ""
-    _call_and_check(klass, msg, how, gb, groupby_func, args, warn_msg=warn_msg)
+        warn_category = FutureWarning
+    _call_and_check(
+        klass,
+        msg,
+        how,
+        gb,
+        groupby_func,
+        args,
+        warn_msg=warn_msg,
+        warn_category=warn_category,
+    )
 
 
 @pytest.mark.parametrize("how", ["agg", "transform"])
@@ -487,9 +522,19 @@ def test_groupby_raises_category(
     if groupby_func == "fillna":
         kind = "Series" if groupby_series else "DataFrame"
         warn_msg = f"{kind}GroupBy.fillna is deprecated"
+        warn_category = FutureWarning
+    elif groupby_func not in reduction_kernels and how == "agg":
+        warn_msg = (
+            f"In the future, using the non-aggregation func='{groupby_func}' "
+            "will raise a ValueError"
+        )
+        warn_category = DeprecationWarning
     else:
         warn_msg = ""
-    _call_and_check(klass, msg, how, gb, groupby_func, args, warn_msg)
+        warn_category = FutureWarning
+    _call_and_check(
+        klass, msg, how, gb, groupby_func, args, warn_msg, warn_category=warn_category
+    )
 
 
 @pytest.mark.parametrize("how", ["agg", "transform"])
@@ -660,6 +705,13 @@ def test_groupby_raises_category_on_category(
     if groupby_func == "fillna":
         kind = "Series" if groupby_series else "DataFrame"
         warn_msg = f"{kind}GroupBy.fillna is deprecated"
+        warn_category = FutureWarning
+    elif groupby_func not in reduction_kernels and how == "agg":
+        warn_msg = f"using the non-aggregation func='{groupby_func}' will raise"
+        warn_category = DeprecationWarning
     else:
         warn_msg = ""
-    _call_and_check(klass, msg, how, gb, groupby_func, args, warn_msg)
+        warn_category = FutureWarning
+    _call_and_check(
+        klass, msg, how, gb, groupby_func, args, warn_msg, warn_category=warn_category
+    )