From 4e61636bfb612d2a09bfbb9442c1086c7bb0bcf3 Mon Sep 17 00:00:00 2001
From: TomAugspurger <thomas-augspurger@uiowa.edu>
Date: Fri, 22 Nov 2013 15:52:06 -0600
Subject: [PATCH] DOC: Series/Frame.reorder_level() can take names

TST: reorder was untested

DOC/TST reorder_levels takes names
---
 pandas/core/frame.py        |  4 ++--
 pandas/core/series.py       |  2 +-
 pandas/tests/test_frame.py  | 40 +++++++++++++++++++++++++++++++++++++
 pandas/tests/test_series.py | 38 +++++++++++++++++++++++++++++++++++
 4 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index d84c0dd9ea5f7..e1dafc60e64d8 100644
--- a/pandas/core/frame.py
+++ b/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.
 
diff --git a/pandas/core/series.py b/pandas/core/series.py
index 9a2eb9da3a6a4..14c932dbe93f2 100644
--- a/pandas/core/series.py
+++ b/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
diff --git a/pandas/tests/test_frame.py b/pandas/tests/test_frame.py
index 5762171b38918..280b0476efe98 100644
--- a/pandas/tests/test_frame.py
+++ b/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'])
diff --git a/pandas/tests/test_series.py b/pandas/tests/test_series.py
index c44ede057adb2..5a6f790d5851e 100644
--- a/pandas/tests/test_series.py
+++ b/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')