deprecate reduce

Author: jreback

doc/source/whatsnew/v0.23.0.txt

@@ -524,6 +524,7 @@ Deprecations
 - ``IntervalIndex.from_intervals`` is deprecated in favor of the :class:`IntervalIndex` constructor (:issue:`19263`)
 - :func:``DataFrame.from_items`` is deprecated. Use :func:``DataFrame.from_dict()`` instead, or :func:``DataFrame.from_dict(OrderedDict())`` if you wish to preserve the key order (:issue:`17320`)
 - The ``broadcast`` parameter of ``.apply()`` is removed in favor of ``result_type='broadcast'`` (:issue:`18577`)
+- The ``reduce`` parameter of ``.apply()`` is removed in favor of ``result_type='reduce'`` (:issue:`18577`)
 
 .. _whatsnew_0230.prior_deprecations:
 

pandas/core/apply.py

@@ -35,7 +35,6 @@ def __init__(self, obj, func, broadcast, raw, reduce, result_type,
                  ignore_failures, args, kwds):
         self.obj = obj
         self.raw = raw
-        self.reduce = reduce
         self.ignore_failures = ignore_failures
         self.args = args or ()
         self.kwds = kwds or {}
@@ -49,6 +48,20 @@ def __init__(self, obj, func, broadcast, raw, reduce, result_type,
             if broadcast:
                 result_type = 'broadcast'
 
+        if reduce is not None:
+            warnings.warn("The reduce argument is deprecated and will "
+                          "be removed in a future version. You can specify "
+                          "result_type='reduce' to try to reduce the result "
+                          "to the original dimensions",
+                          FutureWarning, stacklevel=4)
+            if reduce:
+
+                if result_type is not None:
+                    raise ValueError(
+                        "cannot pass both reduce=True and result_type")
+
+                result_type = 'reduce'
+
         self.result_type = result_type
 
         # curry if needed
@@ -126,11 +139,16 @@ def apply_empty_result(self):
         series in order to see if this is a reduction function
         """
 
-        from pandas import Series
-        reduce = self.reduce
+        # we are not asked to reduce or infer reduction
+        # so just return a copy of the existing object
+        if self.result_type not in ['reduce', None]:
+            return self.obj.copy()
 
-        if reduce is None:
-            reduce = False
+        # we may need to infer
+        reduce = self.result_type == 'reduce'
+
+        from pandas import Series
+        if not reduce:
 
             EMPTY_SERIES = Series([])
             try:
@@ -191,18 +209,14 @@ def apply_broadcast(self, target):
         return result
 
     def apply_standard(self):
-        reduce = self.reduce
-        if reduce is None:
-            reduce = True
 
         # try to reduce first (by default)
         # this only matters if the reduction in values is of different dtype
         # e.g. if we want to apply to a SparseFrame, then can't directly reduce
 
         # we cannot reduce using non-numpy dtypes,
         # as demonstrated in gh-12244
-        if (reduce and
-                self.result_type is None and
+        if (self.result_type in ['reduce', None] and
                 not self.dtypes.apply(is_extension_type).any()):
 
             # Create a dummy Series from an empty array

pandas/core/frame.py

@@ -4871,9 +4871,15 @@ def apply(self, func, axis=0, broadcast=None, raw=False, reduce=None,
             reduce is True a Series will always be returned, and if False a
             DataFrame will always be returned.
 
-        result_type : {'expand', 'broadcast, None}
+            .. deprecated:: 0.23.0
+               This argument will be removed in a future version, replaced
+               by result_type='reduce'.
+
+        result_type : {'expand', 'reduce', 'broadcast, None}
             These only act when axis=1 {columns}
             * 'expand' : list-like results will be turned into columns
+            * 'reduce' : return a Series if possible rather than expanding
+              list-like results. This is the opposite to 'expand'
             * 'broadcast' : scalar results will be broadcast to all columns
             * None : list-like results will be returned as a list
               in a single column. However if the apply function
@@ -5686,7 +5692,7 @@ def f(x):
                         from pandas.core.apply import frame_apply
                         opa = frame_apply(self,
                                           func=f,
-                                          reduce=False,
+                                          result_type='expand',
                                           ignore_failures=True)
                         result = opa.get_result()
                         if result.ndim == self.ndim:

pandas/core/sparse/frame.py

@@ -835,7 +835,7 @@ def notna(self):
         return self._apply_columns(lambda x: x.notna())
     notnull = notna
 
-    def apply(self, func, axis=0, broadcast=None, reduce=False,
+    def apply(self, func, axis=0, broadcast=None, reduce=None,
               result_type=None):
         """
         Analogous to DataFrame.apply, for SparseDataFrame
@@ -853,9 +853,24 @@ def apply(self, func, axis=0, broadcast=None, reduce=False,
                This argument will be removed in a future version, replaced
                by result_type='broadcast'.
 
-        result_type : {'expand', 'broadcast, None}
+        reduce : boolean or None, default None
+            Try to apply reduction procedures. If the DataFrame is empty,
+            apply will use reduce to determine whether the result should be a
+            Series or a DataFrame. If reduce is None (the default), apply's
+            return value will be guessed by calling func an empty Series (note:
+            while guessing, exceptions raised by func will be ignored). If
+            reduce is True a Series will always be returned, and if False a
+            DataFrame will always be returned.
+
+            .. deprecated:: 0.23.0
+               This argument will be removed in a future version, replaced
+               by result_type='reduce'.
+
+        result_type : {'expand', 'reduce', 'broadcast, None}
             These only act when axis=1 {columns}
             * 'expand' : list-like results will be turned into columns
+            * 'reduce' : return a Series if possible rather than expanding
+              list-like results. This is the opposite to 'expand'
             * 'broadcast' : scalar results will be broadcast to all columns
             * None : list-like results will be returned as a list
               in a single column. However if the apply function

pandas/tests/frame/test_apply.py

@@ -82,24 +82,30 @@ def test_apply_empty(self):
         rs = xp.apply(lambda x: x['a'], axis=1)
         assert_frame_equal(xp, rs)
 
+    def test_apply_with_reduce_empty(self):
         # reduce with an empty DataFrame
         x = []
-        result = self.empty.apply(x.append, axis=1, reduce=False)
+        result = self.empty.apply(x.append, axis=1, result_type='expand')
         assert_frame_equal(result, self.empty)
-        result = self.empty.apply(x.append, axis=1, reduce=True)
+        result = self.empty.apply(x.append, axis=1, result_type='reduce')
         assert_series_equal(result, Series(
             [], index=pd.Index([], dtype=object)))
 
         empty_with_cols = DataFrame(columns=['a', 'b', 'c'])
-        result = empty_with_cols.apply(x.append, axis=1, reduce=False)
+        result = empty_with_cols.apply(x.append, axis=1, result_type='expand')
         assert_frame_equal(result, empty_with_cols)
-        result = empty_with_cols.apply(x.append, axis=1, reduce=True)
+        result = empty_with_cols.apply(x.append, axis=1, result_type='reduce')
         assert_series_equal(result, Series(
             [], index=pd.Index([], dtype=object)))
 
         # Ensure that x.append hasn't been called
         assert x == []
 
+    def test_apply_deprecate_reduce(self):
+        with warnings.catch_warnings(record=True):
+            x = []
+            self.empty.apply(x.append, axis=1, result_type='reduce')
+
     def test_apply_standard_nonunique(self):
         df = DataFrame(
             [[1, 2, 3], [4, 5, 6], [7, 8, 9]], index=['a', 'a', 'c'])
@@ -419,9 +425,9 @@ def test_apply_dict(self):
         fn = lambda x: x.to_dict()
 
         for df, dicts in [(A, A_dicts), (B, B_dicts)]:
-            reduce_true = df.apply(fn, reduce=True)
-            reduce_false = df.apply(fn, reduce=False)
-            reduce_none = df.apply(fn, reduce=None)
+            reduce_true = df.apply(fn, result_type='reduce')
+            reduce_false = df.apply(fn, result_type='expand')
+            reduce_none = df.apply(fn)
 
             assert_series_equal(reduce_true, dicts)
             assert_frame_equal(reduce_false, df)