DOC: add docstring for MultiIndex.fillna (pandas-dev#18018) (pandas-dev#18269)

ghasemnaddaf · No-Stream · commit ffb6200bf239 · 2017-11-13T15:01:12.000-08:00
ENH: gb.is_monotonic_increasing pandas-dev#17015 fix rebase conflicts parametrized tests for gb.is_monotonic_increasing/decreasing ENH: gb.is_monotonic_increasing, is_monotonic_decreasing pandas-dev#17015 added tests for gb.is_monotonically_increasing()/decreasing parametrized tests for gb.is_monotonic_increasing/decreasing ENH: gb.is_monotonic_increasing pandas-dev#17015 fix rebase conflicts ENH: gb.is_monotonic_increasing pandas-dev#17015 fix rebase conflicts rebase and cleanup simplified test format fixed whatsnew to include method tags
diff --git a/doc/source/api.rst b/doc/source/api.rst
@@ -2096,6 +2096,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.
 
diff --git a/doc/source/whatsnew/v0.21.0.txt b/doc/source/whatsnew/v0.21.0.txt
@@ -1172,4 +1172,3 @@ Other
 ^^^^^
 - Bug where some inplace operators were not being wrapped and produced a copy when invoked (:issue:`12962`)
 - Bug in :func:`eval` where the ``inplace`` parameter was being incorrectly handled (:issue:`16732`)
-
diff --git a/doc/source/whatsnew/v0.21.1.txt b/doc/source/whatsnew/v0.21.1.txt
@@ -22,7 +22,7 @@ Other Enhancements
 ^^^^^^^^^^^^^^^^^^
 
 - :meth:`Timestamp.timestamp` is now available in Python 2.7. (:issue:`17329`)
--
+- :meth: groupby.is_monotonic_increasing and :meth: .is_monotonic_decreasing extend :meth: Series.is_monotonic_increasing to groups, returning whether each group is monotonically increasing or decreasing, respectively. (:issue:`17015`)
 -
 
 .. _whatsnew_0211.deprecations:
diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py
@@ -1742,6 +1742,55 @@ def pipe(self, func, *args, **kwargs):
         """
         return _pipe(self, func, *args, **kwargs)
 
+    @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()
 
diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
@@ -820,9 +820,10 @@ def duplicated(self, keep='first'):
 
         return duplicated_int64(ids, keep)
 
-    @Appender(ibase._index_shared_docs['fillna'])
     def fillna(self, value=None, downcast=None):
-        # isna is not implemented for MultiIndex
+        """
+        fillna is not implemented for MultiIndex
+        """
         raise NotImplementedError('isna is not defined for MultiIndex')
 
     @Appender(_index_shared_docs['dropna'])
diff --git a/pandas/tests/groupby/test_groupby.py b/pandas/tests/groupby/test_groupby.py
@@ -2591,6 +2591,58 @@ 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()
+        expected = pd.Series(index=list('abcd'), name='B')
+        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()
+        expected = pd.Series(index=list('abcd'), name='B')
+        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
diff --git a/pandas/tests/groupby/test_whitelist.py b/pandas/tests/groupby/test_whitelist.py
@@ -239,17 +239,18 @@ def test_groupby_blacklist(df_letters):
 def test_tab_completion(mframe):
     grp = mframe.groupby(level='second')
     results = set([v for v in dir(grp) if not v.startswith('_')])
-    expected = {
-        'A', 'B', 'C', 'agg', 'aggregate', 'apply', 'boxplot', 'filter',
-        'first', 'get_group', 'groups', 'hist', 'indices', 'last', 'max',
-        'mean', 'median', 'min', 'ngroups', 'nth', 'ohlc', 'plot',
-        'prod', 'size', 'std', 'sum', 'transform', 'var', 'sem', 'count',
-        'nunique', 'head', 'describe', 'cummax', 'quantile',
-        'rank', 'cumprod', 'tail', 'resample', 'cummin', 'fillna',
-        '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'}
+    expected = set(
+        ['A', 'B', 'C', 'agg', 'aggregate', 'apply', 'boxplot', 'filter',
+         'first', 'get_group', 'groups', 'hist', 'indices', 'last', 'max',
+         'mean', 'median', 'min', 'ngroups', 'nth', 'ohlc', 'plot',
+         'prod', 'size', 'std', 'sum', 'transform', 'var', 'sem', 'count',
+         'nunique', 'head', 'describe', 'cummax', 'quantile',
+         'rank', 'cumprod', 'tail', 'resample', 'cummin', 'fillna',
+         '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',
+         'is_monotonic_increasing', 'is_monotonic_decreasing'])
     assert results == expected
 
 

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ Other Enhancements`
`22`	`22`	`^^^^^^^^^^^^^^^^^^`
`23`	`23`
`24`	`24`	- :meth:`Timestamp.timestamp` is now available in Python 2.7. (:issue:`17329`)
`25`		`--`
	`25`	+- :meth: groupby.is_monotonic_increasing and :meth: .is_monotonic_decreasing extend :meth: Series.is_monotonic_increasing to groups, returning whether each group is monotonically increasing or decreasing, respectively. (:issue:`17015`)
`26`	`26`	`-`
`27`	`27`
`28`	`28`	`.. _whatsnew_0211.deprecations:`