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)