ENH: Implement strictly monotonic methods

Simply checks if the index is monotonic and unique.

Author: TomAugspurger

doc/source/api.rst

@@ -1285,6 +1285,8 @@ Attributes
    Index.is_monotonic
    Index.is_monotonic_increasing
    Index.is_monotonic_decreasing
+   Index.is_strictly_monotonic_increasing
+   Index.is_strictly_monotonic_decreasing
    Index.is_unique
    Index.has_duplicates
    Index.dtype

pandas/core/indexes/base.py

@@ -1191,6 +1191,15 @@ def is_monotonic_increasing(self):
         """
         return if the index is monotonic increasing (only equal or
         increasing) values.
+
+        Examples
+        --------
+        >>> Index([1, 2, 3]).is_monotonic_increasing
+        True
+        >>> Index([1, 2, 2]).is_monotonic_increasing
+        True
+        >>> Index([1, 3, 2]).is_monotonic_increasing
+        False
         """
         return self._engine.is_monotonic_increasing
 
@@ -1199,6 +1208,15 @@ def is_monotonic_decreasing(self):
         """
         return if the index is monotonic decreasing (only equal or
         decreasing) values.
+
+        Examples
+        --------
+        >>> Index([3, 2, 1]).is_monotonic_decreasing
+        True
+        >>> Index([3, 2, 2]).is_monotonic_decreasing
+        True
+        >>> Index([3, 1, 2]).is_monotonic_decreasing
+        False
         """
         return self._engine.is_monotonic_decreasing
 

pandas/tests/indexes/test_base.py

@@ -1330,8 +1330,10 @@ def test_tuple_union_bug(self):
 
     def test_is_monotonic_incomparable(self):
         index = Index([5, datetime.now(), 7])
-        assert not index.is_monotonic
+        assert not index.is_monotonic_increasing
         assert not index.is_monotonic_decreasing
+        assert not index.is_strictly_monotonic_increasing
+        assert not index.is_strictly_monotonic_decreasing
 
     def test_get_set_value(self):
         values = np.random.randn(100)
@@ -2030,6 +2032,8 @@ def test_is_monotonic_na(self):
         for index in examples:
             assert not index.is_monotonic_increasing
             assert not index.is_monotonic_decreasing
+            assert not index.is_strictly_monotonic_increasing
+            assert not index.is_strictly_monotonic_decreasing
 
     def test_repr_summary(self):
         with cf.option_context('display.max_seq_items', 10):

pandas/tests/indexes/test_multi.py

@@ -2373,22 +2373,30 @@ def test_is_monotonic(self):
         i = MultiIndex.from_product([np.arange(10),
                                      np.arange(10)], names=['one', 'two'])
         assert i.is_monotonic
+        assert i.is_strictly_monotonic_increasing
         assert Index(i.values).is_monotonic
+        assert i.is_strictly_monotonic_increasing
 
         i = MultiIndex.from_product([np.arange(10, 0, -1),
                                      np.arange(10)], names=['one', 'two'])
         assert not i.is_monotonic
+        assert not i.is_strictly_monotonic_increasing
         assert not Index(i.values).is_monotonic
+        assert not Index(i.values).is_strictly_monotonic_increasing
 
         i = MultiIndex.from_product([np.arange(10),
                                      np.arange(10, 0, -1)],
                                     names=['one', 'two'])
         assert not i.is_monotonic
+        assert not i.is_strictly_monotonic_increasing
         assert not Index(i.values).is_monotonic
+        assert not Index(i.values).is_strictly_monotonic_increasing
 
         i = MultiIndex.from_product([[1.0, np.nan, 2.0], ['a', 'b', 'c']])
         assert not i.is_monotonic
+        assert not i.is_strictly_monotonic_increasing
         assert not Index(i.values).is_monotonic
+        assert not Index(i.values).is_strictly_monotonic_increasing
 
         # string ordering
         i = MultiIndex(levels=[['foo', 'bar', 'baz', 'qux'],
@@ -2397,15 +2405,17 @@ def test_is_monotonic(self):
                                [0, 1, 2, 0, 1, 1, 2, 0, 1, 2]],
                        names=['first', 'second'])
         assert not i.is_monotonic
-        assert not Index(i.values).is_monotonic
+        assert not i.is_strictly_monotonic_increasing
+        assert not Index(i.values).is_strictly_monotonic_increasing
 
         i = MultiIndex(levels=[['bar', 'baz', 'foo', 'qux'],
                                ['mom', 'next', 'zenith']],
                        labels=[[0, 0, 0, 1, 1, 2, 2, 3, 3, 3],
                                [0, 1, 2, 0, 1, 1, 2, 0, 1, 2]],
                        names=['first', 'second'])
         assert i.is_monotonic
-        assert Index(i.values).is_monotonic
+        assert i.is_strictly_monotonic_increasing
+        assert Index(i.values).is_strictly_monotonic_increasing
 
         # mixed levels, hits the TypeError
         i = MultiIndex(
@@ -2416,6 +2426,20 @@ def test_is_monotonic(self):
             names=['household_id', 'asset_id'])
 
         assert not i.is_monotonic
+        assert not i.is_strictly_monotonic_increasing
+
+    def test_is_strictly_monotonic(self):
+        idx = pd.MultiIndex(levels=[['bar', 'baz'], ['mom', 'next']],
+                            labels=[[0, 0, 1, 1], [0, 0, 0, 1]])
+        assert idx.is_monotonic_increasing
+        assert not idx.is_strictly_monotonic_increasing
+
+    @pytest.mark.xfail(reason="buggy MultiIndex.is_monotonic_decresaing.")
+    def test_is_strictly_monotonic_decreasing(self):
+        idx = pd.MultiIndex(levels=[['baz', 'bar'], ['next', 'mom']],
+                            labels=[[0, 0, 1, 1], [0, 0, 0, 1]])
+        assert idx.is_monotonic_decreasing
+        assert not idx.is_strictly_monotonic_decreasing
 
     def test_reconstruct_sort(self):
 

pandas/tests/indexes/test_numeric.py

@@ -465,16 +465,36 @@ def test_view(self):
     def test_is_monotonic(self):
         assert self.index.is_monotonic
         assert self.index.is_monotonic_increasing
+        assert self.index.is_strictly_monotonic_increasing
         assert not self.index.is_monotonic_decreasing
+        assert not self.index.is_strictly_monotonic_decreasing
 
         index = self._holder([4, 3, 2, 1])
         assert not index.is_monotonic
-        assert index.is_monotonic_decreasing
+        assert not index.is_strictly_monotonic_increasing
+        assert index.is_strictly_monotonic_decreasing
 
         index = self._holder([1])
         assert index.is_monotonic
         assert index.is_monotonic_increasing
         assert index.is_monotonic_decreasing
+        assert index.is_strictly_monotonic_increasing
+        assert index.is_strictly_monotonic_decreasing
+
+    def test_is_strictly_monotonic(self):
+        index = self._holder([1, 1, 2, 3])
+        assert index.is_monotonic_increasing
+        assert not index.is_strictly_monotonic_increasing
+
+        index = self._holder([3, 2, 1, 1])
+        assert index.is_monotonic_decreasing
+        assert not index.is_strictly_monotonic_decreasing
+
+        index = self._holder([1, 1])
+        assert index.is_monotonic_increasing
+        assert index.is_monotonic_decreasing
+        assert not index.is_strictly_monotonic_increasing
+        assert not index.is_strictly_monotonic_decreasing
 
     def test_logical_compat(self):
         idx = self.create_index()

pandas/tests/indexes/test_range.py

@@ -331,25 +331,31 @@ def test_is_monotonic(self):
         assert self.index.is_monotonic
         assert self.index.is_monotonic_increasing
         assert not self.index.is_monotonic_decreasing
+        assert self.index.is_strictly_monotonic_increasing
+        assert not self.index.is_strictly_monotonic_decreasing
 
         index = RangeIndex(4, 0, -1)
         assert not index.is_monotonic
+        assert not index.is_strictly_monotonic_increasing
         assert index.is_monotonic_decreasing
+        assert index.is_strictly_monotonic_decreasing
 
         index = RangeIndex(1, 2)
         assert index.is_monotonic
         assert index.is_monotonic_increasing
         assert index.is_monotonic_decreasing
+        assert index.is_strictly_monotonic_increasing
+        assert index.is_strictly_monotonic_decreasing
 
         index = RangeIndex(2, 1)
         assert index.is_monotonic
-        assert index.is_monotonic_increasing
-        assert index.is_monotonic_decreasing
+        assert index.is_strictly_monotonic_increasing
+        assert index.is_strictly_monotonic_decreasing
 
         index = RangeIndex(1, 1)
         assert index.is_monotonic
-        assert index.is_monotonic_increasing
-        assert index.is_monotonic_decreasing
+        assert index.is_strictly_monotonic_increasing
+        assert index.is_strictly_monotonic_decreasing
 
     def test_equals_range(self):
         equiv_pairs = [(RangeIndex(0, 9, 2), RangeIndex(0, 10, 2)),