ENH: gb.is_monotonic_increasing, is_monotonic_decreasing pandas-dev#17015

Author: No-Stream

doc/source/whatsnew/v0.21.0.txt

@@ -130,7 +130,7 @@ Other Enhancements
 - `read_*` methods can now infer compression from non-string paths, such as ``pathlib.Path`` objects (:issue:`17206`).
 - :func:`pd.read_sas()` now recognizes much more of the most frequently used date (datetime) formats in SAS7BDAT files (:issue:`15871`).
 - :func:`DataFrame.items` and :func:`Series.items` is now present in both Python 2 and 3 and is lazy in all cases (:issue:`13918`, :issue:`17213`)
-
+- :func: groupby.is_monotonic_increasing and .is_monotonic_decreasing extend Series.is_monotonic_increasing to groups, returning whether each group is monotonically increasing or decreasing, respectively. (:issue:`17015`)
 
 
 .. _whatsnew_0210.api_breaking:

pandas/core/groupby.py

@@ -1686,6 +1686,55 @@ def tail(self, n=5):
         mask = self._cumcount_array(ascending=False) < n
         return self._selected_obj[mask]
 
+    @Substitution(name='groupby')
+    @Appender(_doc_template)
+    def is_monotonic_increasing(self):
+        """
+        Returns whether each group is monotonically increasing.
+
+        Equivalent to ``.apply(lambda x: x.is_monotonic_increasing)``.
+
+        Examples
+        --------
+        >>> source_dict = {
+        ...    'A': ['this', 'col', 'is', 'entirely', 'irrelevant', '.'],
+        ...    'B': ['cat_a', 'cat_a', 'cat_a', 'cat_b', 'cat_b', 'cat_b'],
+        ...    'C': [1, 2, 3, 2, 2, 0]}
+
+        >>> df = pd.DataFrame(source_dict)
+        ...    df.groupby(['B']).C.is_monotonic_increasing()
+        B
+        cat_a    True
+        cat_b    False
+        Name: C, dtype: bool
+
+        """
+        return self.apply(lambda x: x.is_monotonic_increasing)
+
+    @Substitution(name='groupby')
+    @Appender(_doc_template)
+    def is_monotonic_decreasing(self):
+        """
+        Returns whether each group is monotonically decreasing.
+
+        Equivalent to ``.apply(lambda x: x.is_monotonic_decreasing)``.
+
+        Examples
+        --------
+        >>> source_dict = {
+        ...    'A': ['this', 'col', 'is', 'entirely', 'irrelevant', '.'],
+        ...    'B': ['cat_a', 'cat_a', 'cat_a', 'cat_b', 'cat_b', 'cat_b'],
+        ...    'C': [1, 2, 3, 2, 2, 0]}
+
+        >>> df = pd.DataFrame(source_dict)
+        ...    df.groupby(['B']).C.is_monotonic_decreasing()
+        B
+        cat_a    False
+        cat_b    True
+        Name: C, dtype: bool
+        """
+        return self.apply(lambda x: x.is_monotonic_decreasing)
+
 
 GroupBy._add_numeric_operations()
 

pandas/tests/groupby/test_whitelist.py

@@ -241,7 +241,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'])
+         'ffill', 'bfill', 'pad', 'backfill', 'rolling', 'expanding',
+         'is_monotonic_increasing', 'is_monotonic_decreasing'])
     assert results == expected