deprecate multiindex.is_lexsorted

Author: MarcoGorelli

doc/source/whatsnew/v1.3.0.rst

@@ -149,7 +149,7 @@ Deprecations
 - Deprecating allowing scalars passed to the :class:`Categorical` constructor (:issue:`38433`)
 - Deprecated allowing subclass-specific keyword arguments in the :class:`Index` constructor, use the specific subclass directly instead (:issue:`14093`,:issue:`21311`,:issue:`22315`,:issue:`26974`)
 - Deprecated ``astype`` of datetimelike (``timedelta64[ns]``, ``datetime64[ns]``, ``Datetime64TZDtype``, ``PeriodDtype``) to integer dtypes, use ``values.view(...)`` instead (:issue:`38544`)
--
+- Deprecated :meth:`MultiIndex.is_lexsorted` as a public method, users should use :meth:`MultiIndex.is_monotonic_increasing` instead (:issue:`32259`)
 -
 
 .. ---------------------------------------------------------------------------

pandas/core/indexes/multi.py

@@ -1809,6 +1809,15 @@ def _is_all_dates(self) -> bool:
         return False
 
     def is_lexsorted(self) -> bool:
+        warnings.warn(
+            "MultiIndex.is_lexsorted is deprecated as a public function, "
+            "users should use MultiIndex.is_monotonic_increasing instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return self._is_lexsorted()
+
+    def _is_lexsorted(self) -> bool:
         """
         Return True if the codes are lexicographically sorted.
 
@@ -1821,23 +1830,23 @@ def is_lexsorted(self) -> bool:
         In the below examples, the first level of the MultiIndex is sorted because
         a<b<c, so there is no need to look at the next level.
 
-        >>> pd.MultiIndex.from_arrays([['a', 'b', 'c'], ['d', 'e', 'f']]).is_lexsorted()
+        >>> pd.MultiIndex.from_arrays([['a', 'b'], ['d', 'e']])._is_lexsorted()
         True
-        >>> pd.MultiIndex.from_arrays([['a', 'b', 'c'], ['d', 'f', 'e']]).is_lexsorted()
+        >>> pd.MultiIndex.from_arrays([['a', 'b'], ['d', 'f']])._is_lexsorted()
         True
 
         In case there is a tie, the lexicographical sorting looks
         at the next level of the MultiIndex.
 
-        >>> pd.MultiIndex.from_arrays([[0, 1, 1], ['a', 'b', 'c']]).is_lexsorted()
+        >>> pd.MultiIndex.from_arrays([[0, 1, 1], ['a', 'b', 'c']])._is_lexsorted()
         True
-        >>> pd.MultiIndex.from_arrays([[0, 1, 1], ['a', 'c', 'b']]).is_lexsorted()
+        >>> pd.MultiIndex.from_arrays([[0, 1, 1], ['a', 'c', 'b']])._is_lexsorted()
         False
         >>> pd.MultiIndex.from_arrays([['a', 'a', 'b', 'b'],
-        ...                            ['aa', 'bb', 'aa', 'bb']]).is_lexsorted()
+        ...                            ['aa', 'bb', 'aa', 'bb']])._is_lexsorted()
         True
         >>> pd.MultiIndex.from_arrays([['a', 'a', 'b', 'b'],
-        ...                            ['bb', 'aa', 'aa', 'bb']]).is_lexsorted()
+        ...                            ['bb', 'aa', 'aa', 'bb']])._is_lexsorted()
         False
         """
         return self.lexsort_depth == self.nlevels
@@ -1898,7 +1907,7 @@ def _sort_levels_monotonic(self):
                     ('b', 'bb')],
                    )
         """
-        if self.is_lexsorted() and self.is_monotonic:
+        if self._is_lexsorted() and self.is_monotonic:
             return self
 
         new_levels = []
@@ -3344,7 +3353,7 @@ def _reorder_indexer(
         """
         # If the index is lexsorted and the list_like label in seq are sorted
         # then we do not need to sort
-        if self.is_lexsorted():
+        if self._is_lexsorted():
             need_sort = False
             for i, k in enumerate(seq):
                 if is_list_like(k):

pandas/core/reshape/reshape.py

@@ -617,7 +617,7 @@ def _convert_level_number(level_num, columns):
             roll_columns = roll_columns.swaplevel(lev1, lev2)
         this.columns = roll_columns
 
-    if not this.columns.is_lexsorted():
+    if not this.columns._is_lexsorted():
         # Workaround the edge case where 0 is one of the column names,
         # which interferes with trying to sort based on the first
         # level

pandas/tests/frame/methods/test_drop.py

@@ -162,7 +162,7 @@ def test_drop_multiindex_not_lexsorted(self):
             [("a", ""), ("b1", "c1"), ("b2", "c2")], names=["b", "c"]
         )
         lexsorted_df = DataFrame([[1, 3, 4]], columns=lexsorted_mi)
-        assert lexsorted_df.columns.is_lexsorted()
+        assert lexsorted_df.columns._is_lexsorted()
 
         # define the non-lexsorted version
         not_lexsorted_df = DataFrame(
@@ -172,7 +172,7 @@ def test_drop_multiindex_not_lexsorted(self):
             index="a", columns=["b", "c"], values="d"
         )
         not_lexsorted_df = not_lexsorted_df.reset_index()
-        assert not not_lexsorted_df.columns.is_lexsorted()
+        assert not not_lexsorted_df.columns._is_lexsorted()
 
         # compare the results
         tm.assert_frame_equal(lexsorted_df, not_lexsorted_df)

pandas/tests/frame/methods/test_sort_index.py

@@ -24,7 +24,7 @@ def test_sort_index_and_reconstruction_doc_example(self):
                 levels=[["a", "b"], ["bb", "aa"]], codes=[[0, 0, 1, 1], [0, 1, 0, 1]]
             ),
         )
-        assert df.index.is_lexsorted()
+        assert df.index._is_lexsorted()
         assert not df.index.is_monotonic
 
         # sort it
@@ -35,15 +35,15 @@ def test_sort_index_and_reconstruction_doc_example(self):
             ),
         )
         result = df.sort_index()
-        assert result.index.is_lexsorted()
+        assert result.index._is_lexsorted()
         assert result.index.is_monotonic
 
         tm.assert_frame_equal(result, expected)
 
         # reconstruct
         result = df.sort_index().copy()
         result.index = result.index._sort_levels_monotonic()
-        assert result.index.is_lexsorted()
+        assert result.index._is_lexsorted()
         assert result.index.is_monotonic
 
         tm.assert_frame_equal(result, expected)
@@ -524,14 +524,14 @@ def test_sort_index_and_reconstruction(self):
                 [(0.5, "a"), (0.5, "b"), (0.8, "a"), (0.8, "b")]
             ),
         )
-        assert expected.index.is_lexsorted()
+        assert expected.index._is_lexsorted()
 
         result = DataFrame(
             [[1, 1], [2, 2], [1, 1], [2, 2]],
             index=MultiIndex.from_product([[0.5, 0.8], list("ab")]),
         )
         result = result.sort_index()
-        assert result.index.is_lexsorted()
+        assert result.index._is_lexsorted()
         assert result.index.is_monotonic
 
         tm.assert_frame_equal(result, expected)
@@ -543,14 +543,14 @@ def test_sort_index_and_reconstruction(self):
             ),
         )
         result = result.sort_index()
-        assert result.index.is_lexsorted()
+        assert result.index._is_lexsorted()
 
         tm.assert_frame_equal(result, expected)
 
         concatted = pd.concat([df, df], keys=[0.8, 0.5])
         result = concatted.sort_index()
 
-        assert result.index.is_lexsorted()
+        assert result.index._is_lexsorted()
         assert result.index.is_monotonic
 
         tm.assert_frame_equal(result, expected)
@@ -567,13 +567,13 @@ def test_sort_index_and_reconstruction(self):
         df.columns = df.columns.set_levels(
             pd.to_datetime(df.columns.levels[1]), level=1
         )
-        assert not df.columns.is_lexsorted()
+        assert not df.columns._is_lexsorted()
         assert not df.columns.is_monotonic
         result = df.sort_index(axis=1)
-        assert result.columns.is_lexsorted()
+        assert result.columns._is_lexsorted()
         assert result.columns.is_monotonic
         result = df.sort_index(axis=1, level=1)
-        assert result.columns.is_lexsorted()
+        assert result.columns._is_lexsorted()
         assert result.columns.is_monotonic
 
     # TODO: better name, de-duplicate with test_sort_index_level above

pandas/tests/groupby/test_groupby.py

@@ -1571,7 +1571,7 @@ def test_groupby_multiindex_not_lexsorted():
         [("a", ""), ("b1", "c1"), ("b2", "c2")], names=["b", "c"]
     )
     lexsorted_df = DataFrame([[1, 3, 4]], columns=lexsorted_mi)
-    assert lexsorted_df.columns.is_lexsorted()
+    assert lexsorted_df.columns._is_lexsorted()
 
     # define the non-lexsorted version
     not_lexsorted_df = DataFrame(
@@ -1581,7 +1581,7 @@ def test_groupby_multiindex_not_lexsorted():
         index="a", columns=["b", "c"], values="d"
     )
     not_lexsorted_df = not_lexsorted_df.reset_index()
-    assert not not_lexsorted_df.columns.is_lexsorted()
+    assert not not_lexsorted_df.columns._is_lexsorted()
 
     # compare the results
     tm.assert_frame_equal(lexsorted_df, not_lexsorted_df)
@@ -1596,7 +1596,7 @@ def test_groupby_multiindex_not_lexsorted():
     df = DataFrame(
         {"x": ["a", "a", "b", "a"], "y": [1, 1, 2, 2], "z": [1, 2, 3, 4]}
     ).set_index(["x", "y"])
-    assert not df.index.is_lexsorted()
+    assert not df.index._is_lexsorted()
 
     for level in [0, 1, [0, 1]]:
         for sort in [False, True]:

pandas/tests/indexes/multi/test_drop.py

@@ -126,7 +126,7 @@ def test_drop_not_lexsorted():
     # define the lexsorted version of the multi-index
     tuples = [("a", ""), ("b1", "c1"), ("b2", "c2")]
     lexsorted_mi = MultiIndex.from_tuples(tuples, names=["b", "c"])
-    assert lexsorted_mi.is_lexsorted()
+    assert lexsorted_mi._is_lexsorted()
 
     # and the not-lexsorted version
     df = pd.DataFrame(
@@ -135,7 +135,7 @@ def test_drop_not_lexsorted():
     df = df.pivot_table(index="a", columns=["b", "c"], values="d")
     df = df.reset_index()
     not_lexsorted_mi = df.columns
-    assert not not_lexsorted_mi.is_lexsorted()
+    assert not not_lexsorted_mi._is_lexsorted()
 
     # compare the results
     tm.assert_index_equal(lexsorted_mi, not_lexsorted_mi)

pandas/tests/indexes/multi/test_sorting.py

@@ -131,27 +131,27 @@ def test_unsortedindex_doc_examples():
     with pytest.raises(UnsortedIndexError, match=msg):
         dfm.loc[(0, "y"):(1, "z")]
 
-    assert not dfm.index.is_lexsorted()
+    assert not dfm.index._is_lexsorted()
     assert dfm.index.lexsort_depth == 1
 
     # sort it
     dfm = dfm.sort_index()
     dfm.loc[(1, "z")]
     dfm.loc[(0, "y"):(1, "z")]
 
-    assert dfm.index.is_lexsorted()
+    assert dfm.index._is_lexsorted()
     assert dfm.index.lexsort_depth == 2
 
 
 def test_reconstruct_sort():
 
     # starts off lexsorted & monotonic
     mi = MultiIndex.from_arrays([["A", "A", "B", "B", "B"], [1, 2, 1, 2, 3]])
-    assert mi.is_lexsorted()
+    assert mi._is_lexsorted()
     assert mi.is_monotonic
 
     recons = mi._sort_levels_monotonic()
-    assert recons.is_lexsorted()
+    assert recons._is_lexsorted()
     assert recons.is_monotonic
     assert mi is recons
 
@@ -163,11 +163,11 @@ def test_reconstruct_sort():
         [("z", "a"), ("x", "a"), ("y", "b"), ("x", "b"), ("y", "a"), ("z", "b")],
         names=["one", "two"],
     )
-    assert not mi.is_lexsorted()
+    assert not mi._is_lexsorted()
     assert not mi.is_monotonic
 
     recons = mi._sort_levels_monotonic()
-    assert not recons.is_lexsorted()
+    assert not recons._is_lexsorted()
     assert not recons.is_monotonic
 
     assert mi.equals(recons)
@@ -179,11 +179,11 @@ def test_reconstruct_sort():
         codes=[[0, 1, 0, 2], [2, 0, 0, 1]],
         names=["col1", "col2"],
     )
-    assert not mi.is_lexsorted()
+    assert not mi._is_lexsorted()
     assert not mi.is_monotonic
 
     recons = mi._sort_levels_monotonic()
-    assert not recons.is_lexsorted()
+    assert not recons._is_lexsorted()
     assert not recons.is_monotonic
 
     assert mi.equals(recons)

pandas/tests/indexing/multiindex/test_sorted.py

@@ -50,16 +50,16 @@ def test_frame_getitem_not_sorted2(self, key):
         with tm.assert_produces_warning(FutureWarning):
             return_value = df2.index.set_codes([0, 1, 0, 2], level="col1", inplace=True)
         assert return_value is None
-        assert not df2.index.is_lexsorted()
+        assert not df2.index._is_lexsorted()
         assert not df2.index.is_monotonic
 
         assert df2_original.index.equals(df2.index)
         expected = df2.sort_index(key=key)
-        assert expected.index.is_lexsorted()
+        assert expected.index._is_lexsorted()
         assert expected.index.is_monotonic
 
         result = df2.sort_index(level=0, key=key)
-        assert result.index.is_lexsorted()
+        assert result.index._is_lexsorted()
         assert result.index.is_monotonic
         tm.assert_frame_equal(result, expected)
 

pandas/tests/test_multilevel.py

@@ -401,11 +401,11 @@ def test_sort_non_lexsorted(self):
         )
 
         df = DataFrame({"col": range(len(idx))}, index=idx, dtype="int64")
-        assert df.index.is_lexsorted() is False
+        assert df.index._is_lexsorted() is False
         assert df.index.is_monotonic is False
 
         sorted = df.sort_index()
-        assert sorted.index.is_lexsorted() is True
+        assert sorted.index._is_lexsorted() is True
         assert sorted.index.is_monotonic is True
 
         expected = DataFrame(
@@ -417,3 +417,9 @@ def test_sort_non_lexsorted(self):
         )
         result = sorted.loc[pd.IndexSlice["B":"C", "a":"c"], :]
         tm.assert_frame_equal(result, expected)
+
+
+def test_is_lexsorted_deprecation():
+    # GH 32259
+    with tm.assert_produces_warning():
+        MultiIndex.from_arrays([["a", "b", "c"], ["d", "f", "e"]]).is_lexsorted()