ENH: add Index.is_monotonic_decreasing and Index.is_monotonic_increasing

Index.is_monotonic will have a performance degradation (still O(n) time) in
cases where the Index is decreasing monotonic. If necessary, we could work
around this, but I think we can probably get away with this because the fall-
back options are much slower and in many cases (e.g., for slice indexing) the
next thing we'll want to know is if it's decreasing monotonic, anyways.

see GH7860

Author: shoyer

pandas/core/index.py

@@ -573,8 +573,22 @@ def _mpl_repr(self):
 
     @property
     def is_monotonic(self):
-        """ return if the index has monotonic (only equaly or increasing) values """
-        return self._engine.is_monotonic
+        """ alias for is_monotonic_increasing (deprecated) """
+        return self._engine.is_monotonic_increasing
+
+    @property
+    def is_monotonic_increasing(self):
+        """ return if the index is monotonic increasing (only equal or
+        increasing) values
+        """
+        return self._engine.is_monotonic_increasing
+
+    @property
+    def is_monotonic_decreasing(self):
+        """ return if the index is monotonic decreasing (only equal or
+        decreasing values
+        """
+        return self._engine.is_monotonic_decreasing
 
     def is_lexsorted_for_tuple(self, tup):
         return True

pandas/index.pyx

@@ -77,7 +77,7 @@ cdef class IndexEngine:
         bint over_size_threshold
 
     cdef:
-        bint unique, monotonic
+        bint unique, monotonic_inc, monotonic_dec
         bint initialized, monotonic_check, unique_check
 
     def __init__(self, vgetter, n):
@@ -89,7 +89,8 @@ cdef class IndexEngine:
         self.monotonic_check = 0
 
         self.unique = 0
-        self.monotonic = 0
+        self.monotonic_inc = 0
+        self.monotonic_dec = 0
 
     def __contains__(self, object val):
         self._ensure_mapping_populated()
@@ -134,7 +135,7 @@ cdef class IndexEngine:
         if is_definitely_invalid_key(val):
             raise TypeError
 
-        if self.over_size_threshold and self.is_monotonic:
+        if self.over_size_threshold and self.is_monotonic_increasing:
             if not self.is_unique:
                 return self._get_loc_duplicates(val)
             values = self._get_index_values()
@@ -158,7 +159,7 @@ cdef class IndexEngine:
         cdef:
             Py_ssize_t diff
 
-        if self.is_monotonic:
+        if self.is_monotonic_increasing:
             values = self._get_index_values()
             left = values.searchsorted(val, side='left')
             right = values.searchsorted(val, side='right')
@@ -210,25 +211,35 @@ cdef class IndexEngine:
 
             return self.unique == 1
 
-    property is_monotonic:
+    property is_monotonic_increasing:
 
         def __get__(self):
             if not self.monotonic_check:
                 self._do_monotonic_check()
 
-            return self.monotonic == 1
+            return self.monotonic_inc == 1
+
+    property is_monotonic_decreasing:
+
+        def __get__(self):
+            if not self.monotonic_check:
+                self._do_monotonic_check()
+
+            return self.monotonic_dec == 1
 
     cdef inline _do_monotonic_check(self):
         try:
             values = self._get_index_values()
-            self.monotonic, unique = self._call_monotonic(values)
+            self.monotonic_inc, self.monotonic_dec, unique = \
+                self._call_monotonic(values)
 
             if unique is not None:
                 self.unique = unique
                 self.unique_check = 1
 
         except TypeError:
-            self.monotonic = 0
+            self.monotonic_inc = 0
+            self.monotonic_dec = 0
         self.monotonic_check = 1
 
     cdef _get_index_values(self):
@@ -506,7 +517,7 @@ cdef class DatetimeEngine(Int64Engine):
         return 'M8[ns]'
 
     def __contains__(self, object val):
-        if self.over_size_threshold and self.is_monotonic:
+        if self.over_size_threshold and self.is_monotonic_increasing:
             if not self.is_unique:
                 return self._get_loc_duplicates(val)
             values = self._get_index_values()
@@ -529,7 +540,7 @@ cdef class DatetimeEngine(Int64Engine):
 
         # Welcome to the spaghetti factory
 
-        if self.over_size_threshold and self.is_monotonic:
+        if self.over_size_threshold and self.is_monotonic_increasing:
             if not self.is_unique:
                 val = _to_i8(val)
                 return self._get_loc_duplicates(val)

pandas/src/generate_code.py

@@ -543,27 +543,33 @@ def is_monotonic_%(name)s(ndarray[%(c_type)s] arr):
     '''
     Returns
     -------
-    is_monotonic, is_unique
+    is_monotonic_inc, is_monotonic_dec, is_unique
     '''
     cdef:
         Py_ssize_t i, n
         %(c_type)s prev, cur
         bint is_unique = 1
+        bint is_monotonic_inc = 1
+        bint is_monotonic_dec = 1
 
     n = len(arr)
 
     if n < 2:
-        return True, True
+        return True, True, True
 
     prev = arr[0]
     for i in range(1, n):
         cur = arr[i]
         if cur < prev:
-            return False, None
+            is_monotonic_inc = 0
+        elif cur > prev:
+            is_monotonic_dec = 0
         elif cur == prev:
             is_unique = 0
+        if not is_monotonic_inc and not is_monotonic_dec:
+            return False, False, None
         prev = cur
-    return True, is_unique
+    return is_monotonic_inc, is_monotonic_dec, is_unique
 """
 
 map_indices_template = """@cython.wraparound(False)

pandas/src/generated.pyx

@@ -1803,162 +1803,198 @@ def is_monotonic_float64(ndarray[float64_t] arr):
     '''
     Returns
     -------
-    is_monotonic, is_unique
+    is_monotonic_inc, is_monotonic_dec, is_unique
     '''
     cdef:
         Py_ssize_t i, n
         float64_t prev, cur
         bint is_unique = 1
+        bint is_monotonic_inc = 1
+        bint is_monotonic_dec = 1
 
     n = len(arr)
 
     if n < 2:
-        return True, True
+        return True, True, True
 
     prev = arr[0]
     for i in range(1, n):
         cur = arr[i]
         if cur < prev:
-            return False, None
+            is_monotonic_inc = 0
+        elif cur > prev:
+            is_monotonic_dec = 0
         elif cur == prev:
             is_unique = 0
+        if not is_monotonic_inc and not is_monotonic_dec:
+            return False, False, None
         prev = cur
-    return True, is_unique
+    return is_monotonic_inc, is_monotonic_dec, is_unique
 @cython.boundscheck(False)
 @cython.wraparound(False)
 def is_monotonic_float32(ndarray[float32_t] arr):
     '''
     Returns
     -------
-    is_monotonic, is_unique
+    is_monotonic_inc, is_monotonic_dec, is_unique
     '''
     cdef:
         Py_ssize_t i, n
         float32_t prev, cur
         bint is_unique = 1
+        bint is_monotonic_inc = 1
+        bint is_monotonic_dec = 1
 
     n = len(arr)
 
     if n < 2:
-        return True, True
+        return True, True, True
 
     prev = arr[0]
     for i in range(1, n):
         cur = arr[i]
         if cur < prev:
-            return False, None
+            is_monotonic_inc = 0
+        elif cur > prev:
+            is_monotonic_dec = 0
         elif cur == prev:
             is_unique = 0
+        if not is_monotonic_inc and not is_monotonic_dec:
+            return False, False, None
         prev = cur
-    return True, is_unique
+    return is_monotonic_inc, is_monotonic_dec, is_unique
 @cython.boundscheck(False)
 @cython.wraparound(False)
 def is_monotonic_object(ndarray[object] arr):
     '''
     Returns
     -------
-    is_monotonic, is_unique
+    is_monotonic_inc, is_monotonic_dec, is_unique
     '''
     cdef:
         Py_ssize_t i, n
         object prev, cur
         bint is_unique = 1
+        bint is_monotonic_inc = 1
+        bint is_monotonic_dec = 1
 
     n = len(arr)
 
     if n < 2:
-        return True, True
+        return True, True, True
 
     prev = arr[0]
     for i in range(1, n):
         cur = arr[i]
         if cur < prev:
-            return False, None
+            is_monotonic_inc = 0
+        elif cur > prev:
+            is_monotonic_dec = 0
         elif cur == prev:
             is_unique = 0
+        if not is_monotonic_inc and not is_monotonic_dec:
+            return False, False, None
         prev = cur
-    return True, is_unique
+    return is_monotonic_inc, is_monotonic_dec, is_unique
 @cython.boundscheck(False)
 @cython.wraparound(False)
 def is_monotonic_int32(ndarray[int32_t] arr):
     '''
     Returns
     -------
-    is_monotonic, is_unique
+    is_monotonic_inc, is_monotonic_dec, is_unique
     '''
     cdef:
         Py_ssize_t i, n
         int32_t prev, cur
         bint is_unique = 1
+        bint is_monotonic_inc = 1
+        bint is_monotonic_dec = 1
 
     n = len(arr)
 
     if n < 2:
-        return True, True
+        return True, True, True
 
     prev = arr[0]
     for i in range(1, n):
         cur = arr[i]
         if cur < prev:
-            return False, None
+            is_monotonic_inc = 0
+        elif cur > prev:
+            is_monotonic_dec = 0
         elif cur == prev:
             is_unique = 0
+        if not is_monotonic_inc and not is_monotonic_dec:
+            return False, False, None
         prev = cur
-    return True, is_unique
+    return is_monotonic_inc, is_monotonic_dec, is_unique
 @cython.boundscheck(False)
 @cython.wraparound(False)
 def is_monotonic_int64(ndarray[int64_t] arr):
     '''
     Returns
     -------
-    is_monotonic, is_unique
+    is_monotonic_inc, is_monotonic_dec, is_unique
     '''
     cdef:
         Py_ssize_t i, n
         int64_t prev, cur
         bint is_unique = 1
+        bint is_monotonic_inc = 1
+        bint is_monotonic_dec = 1
 
     n = len(arr)
 
     if n < 2:
-        return True, True
+        return True, True, True
 
     prev = arr[0]
     for i in range(1, n):
         cur = arr[i]
         if cur < prev:
-            return False, None
+            is_monotonic_inc = 0
+        elif cur > prev:
+            is_monotonic_dec = 0
         elif cur == prev:
             is_unique = 0
+        if not is_monotonic_inc and not is_monotonic_dec:
+            return False, False, None
         prev = cur
-    return True, is_unique
+    return is_monotonic_inc, is_monotonic_dec, is_unique
 @cython.boundscheck(False)
 @cython.wraparound(False)
 def is_monotonic_bool(ndarray[uint8_t] arr):
     '''
     Returns
     -------
-    is_monotonic, is_unique
+    is_monotonic_inc, is_monotonic_dec, is_unique
     '''
     cdef:
         Py_ssize_t i, n
         uint8_t prev, cur
         bint is_unique = 1
+        bint is_monotonic_inc = 1
+        bint is_monotonic_dec = 1
 
     n = len(arr)
 
     if n < 2:
-        return True, True
+        return True, True, True
 
     prev = arr[0]
     for i in range(1, n):
         cur = arr[i]
         if cur < prev:
-            return False, None
+            is_monotonic_inc = 0
+        elif cur > prev:
+            is_monotonic_dec = 0
         elif cur == prev:
             is_unique = 0
+        if not is_monotonic_inc and not is_monotonic_dec:
+            return False, False, None
         prev = cur
-    return True, is_unique
+    return is_monotonic_inc, is_monotonic_dec, is_unique
 
 @cython.wraparound(False)
 @cython.boundscheck(False)