DEPR: Index.is_monotonic for Index.is_monotonic_increasing (#45422)

Author: mroeschke

asv_bench/benchmarks/index_cached_properties.py

@@ -56,9 +56,6 @@ def time_values(self, index_type):
     def time_shape(self, index_type):
         self.idx.shape
 
-    def time_is_monotonic(self, index_type):
-        self.idx.is_monotonic
-
     def time_is_monotonic_decreasing(self, index_type):
         self.idx.is_monotonic_decreasing
 

asv_bench/benchmarks/multiindex_object.py

@@ -112,7 +112,7 @@ def time_get_indexer_and_pad(self):
         self.mi_int.get_indexer(self.other_mi_many_mismatches, method="pad")
 
     def time_is_monotonic(self):
-        self.mi_int.is_monotonic
+        self.mi_int.is_monotonic_increasing
 
 
 class Duplicated:

doc/source/whatsnew/v1.5.0.rst

@@ -148,6 +148,7 @@ Other Deprecations
 - Deprecated behavior of :meth:`SparseArray.astype`, :meth:`Series.astype`, and :meth:`DataFrame.astype` with :class:`SparseDtype` when passing a non-sparse ``dtype``. In a future version, this will cast to that non-sparse dtype instead of wrapping it in a :class:`SparseDtype` (:issue:`34457`)
 - Deprecated behavior of :meth:`DatetimeIndex.intersection` and :meth:`DatetimeIndex.symmetric_difference` (``union`` behavior was already deprecated in version 1.3.0) with mixed timezones; in a future version both will be cast to UTC instead of object dtype (:issue:`39328`, :issue:`45357`)
 - Deprecated :meth:`DataFrame.iteritems`, :meth:`Series.iteritems`, :meth:`HDFStore.iteritems` in favor of :meth:`DataFrame.items`, :meth:`Series.items`, :meth:`HDFStore.items`  (:issue:`45321`)
+- Deprecated :meth:`Series.is_monotonic` and :meth:`Index.is_monotonic` in favor of :meth:`Series.is_monotonic_increasing` and :meth:`Index.is_monotonic_increasing` (:issue:`45422`, :issue:`21335`)
 - Deprecated the ``__array_wrap__`` method of DataFrame and Series, rely on standard numpy ufuncs instead (:issue:`45451`)
 -
 

pandas/core/base.py

@@ -16,6 +16,7 @@
     final,
     overload,
 )
+import warnings
 
 import numpy as np
 
@@ -35,6 +36,7 @@
     cache_readonly,
     doc,
 )
+from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
     is_categorical_dtype,
@@ -1050,17 +1052,27 @@ def is_monotonic(self) -> bool:
         -------
         bool
         """
-        from pandas import Index
-
-        return Index(self).is_monotonic
+        warnings.warn(
+            "is_monotonic is deprecated and will be removed in a future version. "
+            "Use is_monotonic_increasing instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.is_monotonic_increasing
 
     @property
     def is_monotonic_increasing(self) -> bool:
         """
-        Alias for is_monotonic.
+        Return boolean if values in the object are
+        monotonic_increasing.
+
+        Returns
+        -------
+        bool
         """
-        # mypy complains if we alias directly
-        return self.is_monotonic
+        from pandas import Index
+
+        return Index(self).is_monotonic_increasing
 
     @property
     def is_monotonic_decreasing(self) -> bool:

pandas/core/generic.py

@@ -7161,7 +7161,7 @@ def asof(self, where, subset=None):
         if isinstance(where, str):
             where = Timestamp(where)
 
-        if not self.index.is_monotonic:
+        if not self.index.is_monotonic_increasing:
             raise ValueError("asof requires a sorted index")
 
         is_series = isinstance(self, ABCSeries)

pandas/core/groupby/grouper.py

@@ -400,7 +400,7 @@ def _set_grouper(self, obj: NDFrame, sort: bool = False):
                         raise ValueError(f"The level {level} is not valid")
 
         # possibly sort
-        if (self.sort or sort) and not ax.is_monotonic:
+        if (self.sort or sort) and not ax.is_monotonic_increasing:
             # use stable sort to support first, last, nth
             # TODO: why does putting na_position="first" fix datetimelike cases?
             indexer = self.indexer = ax.array.argsort(

pandas/core/groupby/ops.py

@@ -823,7 +823,7 @@ def groups(self) -> dict[Hashable, np.ndarray]:
     @cache_readonly
     def is_monotonic(self) -> bool:
         # return if my group orderings are monotonic
-        return Index(self.group_info[0]).is_monotonic
+        return Index(self.group_info[0]).is_monotonic_increasing
 
     @cache_readonly
     def group_info(self) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp], int]:

pandas/core/indexes/base.py

@@ -2200,6 +2200,12 @@ def is_monotonic(self) -> bool:
         """
         Alias for is_monotonic_increasing.
         """
+        warnings.warn(
+            "is_monotonic is deprecated and will be removed in a future version. "
+            "Use is_monotonic_increasing instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
         return self.is_monotonic_increasing
 
     @property
@@ -3263,8 +3269,8 @@ def _union(self, other: Index, sort):
 
         if (
             sort is None
-            and self.is_monotonic
-            and other.is_monotonic
+            and self.is_monotonic_increasing
+            and other.is_monotonic_increasing
             and not (self.has_duplicates and other.has_duplicates)
             and self._can_use_libjoin
         ):
@@ -3302,7 +3308,7 @@ def _union(self, other: Index, sort):
         else:
             result = lvals
 
-        if not self.is_monotonic or not other.is_monotonic:
+        if not self.is_monotonic_increasing or not other.is_monotonic_increasing:
             # if both are monotonic then result should already be sorted
             result = _maybe_try_sort(result, sort)
 
@@ -3407,7 +3413,11 @@ def _intersection(self, other: Index, sort=False):
         """
         intersection specialized to the case with matching dtypes.
         """
-        if self.is_monotonic and other.is_monotonic and self._can_use_libjoin:
+        if (
+            self.is_monotonic_increasing
+            and other.is_monotonic_increasing
+            and self._can_use_libjoin
+        ):
             try:
                 result = self._inner_indexer(other)[0]
             except TypeError:
@@ -4503,15 +4513,15 @@ def join(
         if not self.is_unique and not other.is_unique:
             return self._join_non_unique(other, how=how)
         elif not self.is_unique or not other.is_unique:
-            if self.is_monotonic and other.is_monotonic:
+            if self.is_monotonic_increasing and other.is_monotonic_increasing:
                 if self._can_use_libjoin:
                     # otherwise we will fall through to _join_via_get_indexer
                     return self._join_monotonic(other, how=how)
             else:
                 return self._join_non_unique(other, how=how)
         elif (
-            self.is_monotonic
-            and other.is_monotonic
+            self.is_monotonic_increasing
+            and other.is_monotonic_increasing
             and self._can_use_libjoin
             and (
                 not isinstance(self, ABCMultiIndex)

pandas/core/indexes/multi.py

@@ -1557,7 +1557,7 @@ def is_monotonic_increasing(self) -> bool:
         if any(-1 in code for code in self.codes):
             return False
 
-        if all(level.is_monotonic for level in self.levels):
+        if all(level.is_monotonic_increasing for level in self.levels):
             # If each level is sorted, we can operate on the codes directly. GH27495
             return libalgos.is_lexsorted(
                 [x.astype("int64", copy=False) for x in self.codes]
@@ -1574,11 +1574,11 @@ def is_monotonic_increasing(self) -> bool:
             #  int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float,
             #  complex, str, bytes]]]"  [arg-type]
             sort_order = np.lexsort(values)  # type: ignore[arg-type]
-            return Index(sort_order).is_monotonic
+            return Index(sort_order).is_monotonic_increasing
         except TypeError:
 
             # we have mixed types and np.lexsort is not happy
-            return Index(self._values).is_monotonic
+            return Index(self._values).is_monotonic_increasing
 
     @cache_readonly
     def is_monotonic_decreasing(self) -> bool:
@@ -1946,15 +1946,15 @@ def _sort_levels_monotonic(self) -> MultiIndex:
                     ('b', 'bb')],
                    )
         """
-        if self._is_lexsorted() and self.is_monotonic:
+        if self._is_lexsorted() and self.is_monotonic_increasing:
             return self
 
         new_levels = []
         new_codes = []
 
         for lev, level_codes in zip(self.levels, self.codes):
 
-            if not lev.is_monotonic:
+            if not lev.is_monotonic_increasing:
                 try:
                     # indexer to reorder the levels
                     indexer = lev.argsort()

pandas/core/missing.py

@@ -161,7 +161,7 @@ def clean_interp_method(method: str, index: Index, **kwargs) -> str:
         raise ValueError(f"method must be one of {valid}. Got '{method}' instead.")
 
     if method in ("krogh", "piecewise_polynomial", "pchip"):
-        if not index.is_monotonic:
+        if not index.is_monotonic_increasing:
             raise ValueError(
                 f"{method} interpolation requires that the index be monotonic."
             )