DEPR: numeric_only default in resampler ops (#47177)

Author: rhshadrach

doc/source/whatsnew/v1.5.0.rst

@@ -605,7 +605,7 @@ In the case where ``df.columns`` is not unique, use :meth:`DataFrame.isetitem`:
 ``numeric_only`` default value
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Across the DataFrame and DataFrameGroupBy operations such as
+Across the :class:`DataFrame`, :class:`.DataFrameGroupBy`, and :class:`.Resampler` operations such as
 ``min``, ``sum``, and ``idxmax``, the default
 value of the ``numeric_only`` argument, if it exists at all, was inconsistent.
 Furthermore, operations with the default value ``None`` can lead to surprising
@@ -644,6 +644,11 @@ gained the ``numeric_only`` argument.
 - :meth:`.GroupBy.std`
 - :meth:`.GroupBy.sem`
 - :meth:`.DataFrameGroupBy.quantile`
+- :meth:`.Resampler.mean`
+- :meth:`.Resampler.median`
+- :meth:`.Resampler.sem`
+- :meth:`.Resampler.std`
+- :meth:`.Resampler.var`
 
 .. _whatsnew_150.deprecations.other:
 

pandas/core/resample.py

@@ -393,7 +393,7 @@ def transform(self, arg, *args, **kwargs):
         """
         return self._selected_obj.groupby(self.groupby).transform(arg, *args, **kwargs)
 
-    def _downsample(self, f):
+    def _downsample(self, f, **kwargs):
         raise AbstractMethodError(self)
 
     def _upsample(self, f, limit=None, fill_value=None):
@@ -937,25 +937,28 @@ def asfreq(self, fill_value=None):
         """
         return self._upsample("asfreq", fill_value=fill_value)
 
-    def std(self, ddof=1, *args, **kwargs):
+    def std(self, ddof=1, numeric_only: bool = False, *args, **kwargs):
         """
         Compute standard deviation of groups, excluding missing values.
 
         Parameters
         ----------
         ddof : int, default 1
             Degrees of freedom.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
 
         Returns
         -------
         DataFrame or Series
             Standard deviation of values within each group.
         """
         nv.validate_resampler_func("std", args, kwargs)
-        # error: Unexpected keyword argument "ddof" for "_downsample"
-        return self._downsample("std", ddof=ddof)  # type: ignore[call-arg]
+        return self._downsample("std", ddof=ddof, numeric_only=numeric_only)
 
-    def var(self, ddof=1, *args, **kwargs):
+    def var(self, ddof=1, numeric_only: bool = False, *args, **kwargs):
         """
         Compute variance of groups, excluding missing values.
 
@@ -964,14 +967,18 @@ def var(self, ddof=1, *args, **kwargs):
         ddof : int, default 1
             Degrees of freedom.
 
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
         Returns
         -------
         DataFrame or Series
             Variance of values within each group.
         """
         nv.validate_resampler_func("var", args, kwargs)
-        # error: Unexpected keyword argument "ddof" for "_downsample"
-        return self._downsample("var", ddof=ddof)  # type: ignore[call-arg]
+        return self._downsample("var", ddof=ddof, numeric_only=numeric_only)
 
     @doc(GroupBy.size)
     def size(self):
@@ -1027,53 +1034,94 @@ def quantile(self, q=0.5, **kwargs):
             Return a DataFrame, where the coulmns are groupby columns,
             and the values are its quantiles.
         """
-        # error: Unexpected keyword argument "q" for "_downsample"
-        # error: Too many arguments for "_downsample"
-        return self._downsample("quantile", q=q, **kwargs)  # type: ignore[call-arg]
+        return self._downsample("quantile", q=q, **kwargs)
 
 
-# downsample methods
-for method in ["sum", "prod", "min", "max", "first", "last"]:
+def _add_downsample_kernel(
+    name: str, args: tuple[str, ...], docs_class: type = GroupBy
+) -> None:
+    """
+    Add a kernel to Resampler.
+
+    Arguments
+    ---------
+    name : str
+        Name of the kernel.
+    args : tuple
+        Arguments of the method.
+    docs_class : type
+        Class to get kernel docstring from.
+    """
+    assert args in (
+        ("numeric_only", "min_count"),
+        ("numeric_only",),
+        ("ddof", "numeric_only"),
+        (),
+    )
 
-    def f(
-        self,
-        _method: str = method,
-        numeric_only: bool | lib.NoDefault = lib.no_default,
-        min_count: int = 0,
-        *args,
-        **kwargs,
-    ):
-        if numeric_only is lib.no_default:
-            if _method != "sum":
+    # Explicitly provide args rather than args/kwargs for API docs
+    if args == ("numeric_only", "min_count"):
+
+        def f(
+            self,
+            numeric_only: bool | lib.NoDefault = lib.no_default,
+            min_count: int = 0,
+            *args,
+            **kwargs,
+        ):
+            nv.validate_resampler_func(name, args, kwargs)
+            if numeric_only is lib.no_default and name != "sum":
                 # For DataFrameGroupBy, set it to be False for methods other than `sum`.
                 numeric_only = False
 
-        nv.validate_resampler_func(_method, args, kwargs)
-        return self._downsample(_method, numeric_only=numeric_only, min_count=min_count)
-
-    f.__doc__ = getattr(GroupBy, method).__doc__
-    setattr(Resampler, method, f)
-
+            return self._downsample(
+                name, numeric_only=numeric_only, min_count=min_count
+            )
 
-# downsample methods
-for method in ["mean", "sem", "median", "ohlc"]:
+    elif args == ("numeric_only",):
+        # error: All conditional function variants must have identical signatures
+        def f(  # type: ignore[misc]
+            self, numeric_only: bool | lib.NoDefault = lib.no_default, *args, **kwargs
+        ):
+            nv.validate_resampler_func(name, args, kwargs)
+            return self._downsample(name, numeric_only=numeric_only)
+
+    elif args == ("ddof", "numeric_only"):
+        # error: All conditional function variants must have identical signatures
+        def f(  # type: ignore[misc]
+            self,
+            ddof: int = 1,
+            numeric_only: bool | lib.NoDefault = lib.no_default,
+            *args,
+            **kwargs,
+        ):
+            nv.validate_resampler_func(name, args, kwargs)
+            return self._downsample(name, ddof=ddof, numeric_only=numeric_only)
 
-    def g(self, _method=method, *args, **kwargs):
-        nv.validate_resampler_func(_method, args, kwargs)
-        return self._downsample(_method)
+    else:
+        # error: All conditional function variants must have identical signatures
+        def f(  # type: ignore[misc]
+            self,
+            *args,
+            **kwargs,
+        ):
+            nv.validate_resampler_func(name, args, kwargs)
+            return self._downsample(name)
 
-    g.__doc__ = getattr(GroupBy, method).__doc__
-    setattr(Resampler, method, g)
+    f.__doc__ = getattr(docs_class, name).__doc__
+    setattr(Resampler, name, f)
 
 
-# series only methods
+for method in ["sum", "prod", "min", "max", "first", "last"]:
+    _add_downsample_kernel(method, ("numeric_only", "min_count"))
+for method in ["mean", "median"]:
+    _add_downsample_kernel(method, ("numeric_only",))
+for method in ["sem"]:
+    _add_downsample_kernel(method, ("ddof", "numeric_only"))
+for method in ["ohlc"]:
+    _add_downsample_kernel(method, ())
 for method in ["nunique"]:
-
-    def h(self, _method=method):
-        return self._downsample(_method)
-
-    h.__doc__ = getattr(SeriesGroupBy, method).__doc__
-    setattr(Resampler, method, h)
+    _add_downsample_kernel(method, (), SeriesGroupBy)
 
 
 class _GroupByMixin(PandasObject):

pandas/tests/resample/test_resample_api.py

@@ -814,6 +814,7 @@ def test_end_and_end_day_origin(
 
 
 @pytest.mark.parametrize(
+    # expected_data is a string when op raises a ValueError
     "method, numeric_only, expected_data",
     [
         ("sum", True, {"num": [25]}),
@@ -834,6 +835,21 @@ def test_end_and_end_day_origin(
         ("last", True, {"num": [20]}),
         ("last", False, {"cat": ["cat_2"], "num": [20]}),
         ("last", lib.no_default, {"cat": ["cat_2"], "num": [20]}),
+        ("mean", True, {"num": [12.5]}),
+        ("mean", False, {"num": [12.5]}),
+        ("mean", lib.no_default, {"num": [12.5]}),
+        ("median", True, {"num": [12.5]}),
+        ("median", False, {"num": [12.5]}),
+        ("median", lib.no_default, {"num": [12.5]}),
+        ("std", True, {"num": [10.606601717798213]}),
+        ("std", False, "could not convert string to float"),
+        ("std", lib.no_default, {"num": [10.606601717798213]}),
+        ("var", True, {"num": [112.5]}),
+        ("var", False, "could not convert string to float"),
+        ("var", lib.no_default, {"num": [112.5]}),
+        ("sem", True, {"num": [7.5]}),
+        ("sem", False, "could not convert string to float"),
+        ("sem", lib.no_default, {"num": [7.5]}),
     ],
 )
 def test_frame_downsample_method(method, numeric_only, expected_data):
@@ -845,20 +861,32 @@ def test_frame_downsample_method(method, numeric_only, expected_data):
     resampled = df.resample("Y")
 
     func = getattr(resampled, method)
-    if method == "prod" and numeric_only is not True:
+    if numeric_only is lib.no_default and method not in (
+        "min",
+        "max",
+        "first",
+        "last",
+        "prod",
+    ):
         warn = FutureWarning
-        msg = "Dropping invalid columns in DataFrameGroupBy.prod is deprecated"
-    elif method == "sum" and numeric_only is lib.no_default:
+        msg = (
+            f"default value of numeric_only in DataFrameGroupBy.{method} is deprecated"
+        )
+    elif method in ("prod", "mean", "median") and numeric_only is not True:
         warn = FutureWarning
-        msg = "The default value of numeric_only in DataFrameGroupBy.sum is deprecated"
+        msg = f"Dropping invalid columns in DataFrameGroupBy.{method} is deprecated"
     else:
         warn = None
         msg = ""
     with tm.assert_produces_warning(warn, match=msg):
-        result = func(numeric_only=numeric_only)
-
-    expected = DataFrame(expected_data, index=expected_index)
-    tm.assert_frame_equal(result, expected)
+        if isinstance(expected_data, str):
+            klass = TypeError if method == "var" else ValueError
+            with pytest.raises(klass, match=expected_data):
+                _ = func(numeric_only=numeric_only)
+        else:
+            result = func(numeric_only=numeric_only)
+            expected = DataFrame(expected_data, index=expected_index)
+            tm.assert_frame_equal(result, expected)
 
 
 @pytest.mark.parametrize(