add doc-strings, rename sort_monotonic -> sort_levels_monotonic

Author: jreback

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)