add doc-strings, rename sort_monotonic -> sort_levels_monotonic

pandas/core/frame.py

@@ -3349,7 +3349,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
 
             # make sure that the axis is lexsorted to start
             # if not we need to reconstruct to get the correct indexer
-            labels = labels.sort_monotonic()
+            labels = labels.sort_levels_monotonic()
 
             indexer = lexsort_indexer(labels.labels, orders=ascending,
                                       na_position=na_position)

pandas/core/series.py

@@ -1762,7 +1762,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
                                                  sort_remaining=sort_remaining)
         elif isinstance(index, MultiIndex):
             from pandas.core.sorting import lexsort_indexer
-            labels = index.sort_monotonic()
+            labels = index.sort_levels_monotonic()
             indexer = lexsort_indexer(labels.labels, orders=ascending)
         else:
             from pandas.core.sorting import nargsort

pandas/indexes/multi.py

@@ -1173,14 +1173,15 @@ def from_product(cls, iterables, sortorder=None, names=None):
         labels = cartesian_product(labels)
         return MultiIndex(levels, labels, sortorder=sortorder, names=names)
 
-    def sort_monotonic(self):
+    def sort_levels_monotonic(self):
         """
         .. versionadded:: 0.20.0
 
         This is an *internal* function.
 
         create a new MultiIndex from the current to monotonically sorted
-        items IN the levels
+        items IN the levels. This does not actually make the entire MultiIndex
+        monotonic, JUST the levels.
 
         The resulting MultiIndex will have the same outward
         appearance, meaning the same .values and ordering. It will also
@@ -1190,6 +1191,19 @@ def sort_monotonic(self):
         -------
         MultiIndex
 
+        Examples
+        --------
+
+        >>> i = pd.MultiIndex(levels=[['a', 'b'], ['bb', 'aa']],
+                              labels=[[0, 0, 1, 1], [0, 1, 0, 1]])
+        >>> i
+        MultiIndex(levels=[['a', 'b'], ['bb', 'aa']],
+                   labels=[[0, 0, 1, 1], [0, 1, 0, 1]])
+
+        >>> i.sort_monotonic()
+        MultiIndex(levels=[['a', 'b'], ['aa', 'bb']],
+                   labels=[[0, 0, 1, 1], [1, 0, 1, 0]])
+
         """
 
         if self.is_lexsorted() and self.is_monotonic:
@@ -1237,7 +1251,7 @@ def remove_unused_levels(self):
 
         Examples
         --------
-        >>> i = MultiIndex.from_product([range(2), list('ab')])
+        >>> i = pd.MultiIndex.from_product([range(2), list('ab')])
         MultiIndex(levels=[[0, 1], ['a', 'b']],
                    labels=[[0, 0, 1, 1], [0, 1, 0, 1]])
 

pandas/tests/indexes/test_multi.py

@@ -2420,7 +2420,7 @@ def test_reconstruct_sort(self):
         assert mi.is_lexsorted()
         assert mi.is_monotonic
 
-        recons = mi.sort_monotonic()
+        recons = mi.sort_levels_monotonic()
         assert recons.is_lexsorted()
         assert recons.is_monotonic
         assert mi is recons
@@ -2435,7 +2435,7 @@ def test_reconstruct_sort(self):
         assert not mi.is_lexsorted()
         assert not mi.is_monotonic
 
-        recons = mi.sort_monotonic()
+        recons = mi.sort_levels_monotonic()
         assert not recons.is_lexsorted()
         assert not recons.is_monotonic
 
@@ -2449,7 +2449,7 @@ def test_reconstruct_sort(self):
         assert not mi.is_lexsorted()
         assert not mi.is_monotonic
 
-        recons = mi.sort_monotonic()
+        recons = mi.sort_levels_monotonic()
         assert not recons.is_lexsorted()
         assert not recons.is_monotonic
 

pandas/tests/test_multilevel.py

@@ -2582,7 +2582,7 @@ def test_sort_index_and_reconstruction_doc_example(self):
 
         # reconstruct
         result = df.sort_index().copy()
-        result.index = result.index.sort_monotonic()
+        result.index = result.index.sort_levels_monotonic()
         assert result.index.is_lexsorted()
         assert result.index.is_monotonic
 

pandas/tests/tools/test_hashing.py

@@ -91,7 +91,7 @@ def test_multiindex_objects(self):
         mi = MultiIndex(levels=[['b', 'd', 'a'], [1, 2, 3]],
                         labels=[[0, 1, 0, 2], [2, 0, 0, 1]],
                         names=['col1', 'col2'])
-        recons = mi.sort_monotonic()
+        recons = mi.sort_levels_monotonic()
 
         # these are equal
         assert mi.equals(recons)