Merge pull request #5573 from TomAugspurger/reorder_docstring

DOC/TST: Series.reorder_levels() can take names; added tests

Author: hayd

pandas/core/frame.py

@@ -2794,9 +2794,9 @@ def reorder_levels(self, order, axis=0):
 
         Parameters
         ----------
-        order : list of int
+        order : list of int or list of str
             List representing new level order. Reference level by number
-            not by key.
+            (position) or by key (label).
         axis : int
             Where to reorder levels.
 

pandas/core/series.py

@@ -1869,7 +1869,7 @@ def reorder_levels(self, order):
         Parameters
         ----------
         order: list of int representing new level order.
-               (reference level by number not by key)
+               (reference level by number or key)
         axis: where to reorder levels
 
         Returns

pandas/tests/test_frame.py

@@ -9185,6 +9185,46 @@ def test_select(self):
 
         assert_frame_equal(result, expected, check_names=False)  # TODO should reindex check_names?
 
+    def test_reorder_levels(self):
+        index = MultiIndex(levels=[['bar'], ['one', 'two', 'three'], [0, 1]],
+                           labels=[[0, 0, 0, 0, 0, 0],
+                                   [0, 1, 2, 0, 1, 2],
+                                   [0, 1, 0, 1, 0, 1]],
+                           names=['L0', 'L1', 'L2'])
+        df = DataFrame({'A': np.arange(6), 'B': np.arange(6)}, index=index)
+
+        # no change, position
+        result = df.reorder_levels([0, 1, 2])
+        assert_frame_equal(df, result)
+
+        # no change, labels
+        result = df.reorder_levels(['L0', 'L1', 'L2'])
+        assert_frame_equal(df, result)
+
+        # rotate, position
+        result = df.reorder_levels([1, 2, 0])
+        e_idx = MultiIndex(levels=[['one', 'two', 'three'], [0, 1], ['bar']],
+                           labels=[[0, 1, 2, 0, 1, 2],
+                                   [0, 1, 0, 1, 0, 1],
+                                   [0, 0, 0, 0, 0, 0]],
+                           names=['L1', 'L2', 'L0'])
+        expected = DataFrame({'A': np.arange(6), 'B': np.arange(6)},
+                             index=e_idx)
+        assert_frame_equal(result, expected)
+
+        result = df.reorder_levels([0, 0, 0])
+        e_idx = MultiIndex(levels=[['bar'], ['bar'], ['bar']],
+                           labels=[[0, 0, 0, 0, 0, 0],
+                                   [0, 0, 0, 0, 0, 0],
+                                   [0, 0, 0, 0, 0, 0]],
+                           names=['L0', 'L0', 'L0'])
+        expected = DataFrame({'A': np.arange(6), 'B': np.arange(6)},
+                             index=e_idx)
+        assert_frame_equal(result, expected)
+
+        result = df.reorder_levels(['L0', 'L0', 'L0'])
+        assert_frame_equal(result, expected)
+
     def test_sort_index(self):
         frame = DataFrame(np.random.randn(4, 4), index=[1, 2, 3, 4],
                           columns=['A', 'B', 'C', 'D'])

pandas/tests/test_series.py

@@ -1854,6 +1854,44 @@ def test_argsort_stable(self):
         self.assert_(np.array_equal(qindexer, qexpected))
         self.assert_(not np.array_equal(qindexer, mindexer))
 
+    def test_reorder_levels(self):
+        index = MultiIndex(levels=[['bar'], ['one', 'two', 'three'], [0, 1]],
+                           labels=[[0, 0, 0, 0, 0, 0],
+                                   [0, 1, 2, 0, 1, 2],
+                                   [0, 1, 0, 1, 0, 1]],
+                           names=['L0', 'L1', 'L2'])
+        s = Series(np.arange(6), index=index)
+
+        # no change, position
+        result = s.reorder_levels([0, 1, 2])
+        assert_series_equal(s, result)
+
+        # no change, labels
+        result = s.reorder_levels(['L0', 'L1', 'L2'])
+        assert_series_equal(s, result)
+
+        # rotate, position
+        result = s.reorder_levels([1, 2, 0])
+        e_idx = MultiIndex(levels=[['one', 'two', 'three'], [0, 1], ['bar']],
+                           labels=[[0, 1, 2, 0, 1, 2],
+                                   [0, 1, 0, 1, 0, 1],
+                                   [0, 0, 0, 0, 0, 0]],
+                           names=['L1', 'L2', 'L0'])
+        expected = Series(np.arange(6), index=e_idx)
+        assert_series_equal(result, expected)
+
+        result = s.reorder_levels([0, 0, 0])
+        e_idx = MultiIndex(levels=[['bar'], ['bar'], ['bar']],
+                           labels=[[0, 0, 0, 0, 0, 0],
+                                   [0, 0, 0, 0, 0, 0],
+                                   [0, 0, 0, 0, 0, 0]],
+                           names=['L0', 'L0', 'L0'])
+        expected = Series(range(6), index=e_idx)
+        assert_series_equal(result, expected)
+
+        result = s.reorder_levels(['L0', 'L0', 'L0'])
+        assert_series_equal(result, expected)
+
     def test_cumsum(self):
         self._check_accum_op('cumsum')