ENH: gb.is_monotonic_increasing #17015

doc/source/api.rst

@@ -2240,6 +2240,8 @@ The following methods are available only for ``SeriesGroupBy`` objects.
  SeriesGroupBy.nunique
  SeriesGroupBy.unique
  SeriesGroupBy.value_counts
+ SeriesGroupBy.is_monotonic_increasing
+ SeriesGroupBy.is_monotonic_decreasing
 
 The following methods are available only for ``DataFrameGroupBy`` objects.
 

doc/source/whatsnew/v0.23.0.txt

@@ -323,6 +323,7 @@ Other Enhancements
 
 - ``IntervalIndex.astype`` now supports conversions between subtypes when passed an ``IntervalDtype`` (:issue:`19197`)
 - :class:`IntervalIndex` and its associated constructor methods (``from_arrays``, ``from_breaks``, ``from_tuples``) have gained a ``dtype`` parameter (:issue:`19262`)
+- :func: groupby.is_monotonic_increasing and :func: .is_monotonic_decreasing extend :func: Series.is_monotonic_increasing to groups, returning whether each group is monotonically increasing or decreasing, respectively. (:issue:`17015`)
 
 .. _whatsnew_0230.api_breaking:
 

pandas/core/groupby.py

@@ -336,7 +336,9 @@
 ]) | _plotting_methods
 
 _series_apply_whitelist = ((_common_apply_whitelist |
- {'nlargest', 'nsmallest'}) -
+ {'nlargest', 'nsmallest',
+ 'is_monotonic_increasing',
+ 'is_monotonic_decreasing'}) -
  {'boxplot'}) | frozenset(['dtype', 'unique'])
 
 _dataframe_apply_whitelist = ((_common_apply_whitelist |

pandas/tests/groupby/test_groupby.py

@@ -2639,7 +2639,7 @@ def test_group_shift_with_null_key(self):
  # Generate a moderately large dataframe with occasional missing
  # values in column `B`, and then group by [`A`, `B`]. This should
  # force `-1` in `labels` array of `g.grouper.group_info` exactly
- # at those places, where the group-by key is partilly missing.
+ # at those places, where the group-by key is partially missing.
  df = DataFrame([(i % 12, i % 3 if i % 3 else np.nan, i)
  for i in range(n_rows)], dtype=float,
  columns=["A", "B", "Z"], index=None)
@@ -2764,6 +2764,65 @@ def test_cummin_cummax(self):
  expected = pd.Series([1, 2, 1], name='b')
  tm.assert_series_equal(result, expected)
 
+ @pytest.mark.parametrize('in_vals, out_vals', [
+
+ # Basics: strictly increasing (T), strictly decreasing (F),
+ # abs val increasing (F), non-strictly increasing (T)
+ ([1, 2, 5, 3, 2, 0, 4, 5, -6, 1, 1],
+ [True, False, False, True]),
+
+ # Test with inf vals
+ ([1, 2.1, np.inf, 3, 2, np.inf, -np.inf, 5, 11, 1, -np.inf],
+ [True, False, True, False]),
+
+ # Test with nan vals; should always be False
+ ([1, 2, np.nan, 3, 2, np.nan, np.nan, 5, -np.inf, 1, np.nan],
+ [False, False, False, False]),
+ ])
+ def test_is_monotonic_increasing(self, in_vals, out_vals):
+ # GH 17015
+ source_dict = {
+ 'A': ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11'],
+ 'B': ['a', 'a', 'a', 'b', 'b', 'b', 'c', 'c', 'c', 'd', 'd'],
+ 'C': in_vals}
+ df = pd.DataFrame(source_dict)
+ result = df.groupby('B').C.is_monotonic_increasing
+ index = Index(list('abcd'), name='B')
+ expected = pd.Series(index=index, data=out_vals, name='C')
+ tm.assert_series_equal(result, expected)
+
+ # Also check result equal to manually taking x.is_monotonic_increasing.
+ expected = (
+ df.groupby(['B']).C.apply(lambda x: x.is_monotonic_increasing))
+ tm.assert_series_equal(result, expected)
+
+ @pytest.mark.parametrize('in_vals, out_vals', [
+ # Basics: strictly decreasing (T), strictly increasing (F),
+ # abs val decreasing (F), non-strictly increasing (T)
+ ([10, 9, 7, 3, 4, 5, -3, 2, 0, 1, 1],
+ [True, False, False, True]),
+
+ # Test with inf vals
+ ([np.inf, 1, -np.inf, np.inf, 2, -3, -np.inf, 5, -3, -np.inf, -np.inf],
+ [True, True, False, True]),
+
+ # Test with nan vals; should always be False
+ ([1, 2, np.nan, 3, 2, np.nan, np.nan, 5, -np.inf, 1, np.nan],
+ [False, False, False, False]),
+ ])
+ def test_is_monotonic_decreasing(self, in_vals, out_vals):
+ # GH 17015
+ source_dict = {
+ 'A': ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11'],
+ 'B': ['a', 'a', 'a', 'b', 'b', 'b', 'c', 'c', 'c', 'd', 'd'],
+ 'C': in_vals}
+
+ df = pd.DataFrame(source_dict)
+ result = df.groupby('B').C.is_monotonic_decreasing
+ index = Index(list('abcd'), name='B')
+ expected = pd.Series(index=index, data=out_vals, name='C')
+ tm.assert_series_equal(result, expected)
+
  def test_apply_numeric_coercion_when_datetime(self):
  # In the past, group-by/apply operations have been over-eager
  # in converting dtypes to numeric, in the presence of datetime

pandas/tests/groupby/test_whitelist.py

@@ -88,6 +88,8 @@
  'unique',
  'nlargest',
  'nsmallest',
+ 'is_monotonic_increasing',
+ 'is_monotonic_decreasing',
 ])
 
 
@@ -184,7 +186,7 @@ def test_regression_whitelist_methods(
  axis, skipna, sort):
  # GH6944
  # GH 17537
- # explicitly test the whitelest methods
+ # explicitly test the whitelist methods
 
  if axis == 0:
  frame = raw_frame
@@ -249,7 +251,8 @@ def test_tab_completion(mframe):
  'cumsum', 'cumcount', 'ngroup', 'all', 'shift', 'skew',
  'take', 'tshift', 'pct_change', 'any', 'mad', 'corr', 'corrwith',
  'cov', 'dtypes', 'ndim', 'diff', 'idxmax', 'idxmin',
- 'ffill', 'bfill', 'pad', 'backfill', 'rolling', 'expanding', 'pipe'}
+ 'ffill', 'bfill', 'pad', 'backfill', 'rolling', 'expanding', 'pipe',
+ }
  assert results == expected