ENH: level keyword in rename (GH4160)

Author: jorisvandenbossche

doc/source/whatsnew/v0.20.0.txt

@@ -345,6 +345,8 @@ Other Enhancements
 - The ``skiprows`` argument in ``pd.read_csv()`` now accepts a callable function as a value  (:issue:`10882`)
 - The ``nrows`` and ``chunksize`` arguments in ``pd.read_csv()`` are supported if both are passed (:issue:`6774`, :issue:`15755`)
 - ``pd.DataFrame.plot`` now prints a title above each subplot if ``suplots=True`` and ``title`` is a list of strings (:issue:`14753`)
+- Addition of a ``level`` keyword to ``DataFrame/Series.rename`` to rename
+  labels in the specified level of a MultiIndex (:issue:`4160`).
 - ``pd.Series.interpolate`` now supports timedelta as an index type with ``method='time'`` (:issue:`6424`)
 - ``Timedelta.isoformat`` method added for formatting Timedeltas as an `ISO 8601 duration`_. See the :ref:`Timedelta docs <timedeltas.isoformat>` (:issue:`15136`)
 - ``.select_dtypes()`` now allows the string 'datetimetz' to generically select datetimes with tz (:issue:`14910`)

pandas/core/generic.py

@@ -634,6 +634,9 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         inplace : boolean, default False
             Whether to return a new %(klass)s. If True then value of copy is
             ignored.
+        level : int or level name, default None
+            In case of a MultiIndex, only rename labels in the specified
+            level.
 
         Returns
         -------
@@ -690,6 +693,7 @@ def rename(self, *args, **kwargs):
         axes, kwargs = self._construct_axes_from_arguments(args, kwargs)
         copy = kwargs.pop('copy', True)
         inplace = kwargs.pop('inplace', False)
+        level = kwargs.pop('level', None)
 
         if kwargs:
             raise TypeError('rename() got an unexpected keyword '
@@ -723,7 +727,10 @@ def f(x):
             f = _get_rename_function(v)
 
             baxis = self._get_block_manager_axis(axis)
-            result._data = result._data.rename_axis(f, axis=baxis, copy=copy)
+            if level is not None:
+                level = self.axes[axis]._get_level_number(level)
+            result._data = result._data.rename_axis(f, axis=baxis, copy=copy,
+                                                    level=level)
             result._clear_item_cache()
 
         if inplace:

pandas/core/internals.py

@@ -2833,7 +2833,7 @@ def set_axis(self, axis, new_labels):
 
         self.axes[axis] = new_labels
 
-    def rename_axis(self, mapper, axis, copy=True):
+    def rename_axis(self, mapper, axis, copy=True, level=None):
         """
         Rename one of axes.
 
@@ -2842,10 +2842,11 @@ def rename_axis(self, mapper, axis, copy=True):
         mapper : unary callable
         axis : int
         copy : boolean, default True
+        level : int, default None
 
         """
         obj = self.copy(deep=copy)
-        obj.set_axis(axis, _transform_index(self.axes[axis], mapper))
+        obj.set_axis(axis, _transform_index(self.axes[axis], mapper, level))
         return obj
 
     def add_prefix(self, prefix):
@@ -4731,15 +4732,20 @@ def _safe_reshape(arr, new_shape):
     return arr
 
 
-def _transform_index(index, func):
+def _transform_index(index, func, level=None):
     """
     Apply function to all values found in index.
 
     This includes transforming multiindex entries separately.
+    Only apply function to one level of the MultiIndex if level is specified.
 
     """
     if isinstance(index, MultiIndex):
-        items = [tuple(func(y) for y in x) for x in index]
+        if level is not None:
+            items = [tuple(func(y) if i == level else y
+                           for i, y in enumerate(x)) for x in index]
+        else:
+            items = [tuple(func(y) for y in x) for x in index]
         return MultiIndex.from_tuples(items, names=index.names)
     else:
         items = [func(x) for x in index]

pandas/tests/frame/test_alter_axes.py

@@ -400,15 +400,18 @@ def test_rename(self):
                               pd.Index(['bar', 'foo'], name='name'))
         self.assertEqual(renamed.index.name, renamer.index.name)
 
-        # MultiIndex
+    def test_rename_multiindex(self):
+
         tuples_index = [('foo1', 'bar1'), ('foo2', 'bar2')]
         tuples_columns = [('fizz1', 'buzz1'), ('fizz2', 'buzz2')]
         index = MultiIndex.from_tuples(tuples_index, names=['foo', 'bar'])
         columns = MultiIndex.from_tuples(
             tuples_columns, names=['fizz', 'buzz'])
-        renamer = DataFrame([(0, 0), (1, 1)], index=index, columns=columns)
-        renamed = renamer.rename(index={'foo1': 'foo3', 'bar2': 'bar3'},
-                                 columns={'fizz1': 'fizz3', 'buzz2': 'buzz3'})
+        df = DataFrame([(0, 0), (1, 1)], index=index, columns=columns)
+
+        ## without specifying level -> accross all levels
+        renamed = df.rename(index={'foo1': 'foo3', 'bar2': 'bar3'},
+                            columns={'fizz1': 'fizz3', 'buzz2': 'buzz3'})
         new_index = MultiIndex.from_tuples([('foo3', 'bar1'),
                                             ('foo2', 'bar3')],
                                            names=['foo', 'bar'])
@@ -417,8 +420,57 @@ def test_rename(self):
                                              names=['fizz', 'buzz'])
         self.assert_index_equal(renamed.index, new_index)
         self.assert_index_equal(renamed.columns, new_columns)
-        self.assertEqual(renamed.index.names, renamer.index.names)
-        self.assertEqual(renamed.columns.names, renamer.columns.names)
+        self.assertEqual(renamed.index.names, df.index.names)
+        self.assertEqual(renamed.columns.names, df.columns.names)
+
+        ## with specifying a level
+
+        # dict
+        new_columns = MultiIndex.from_tuples([('fizz3', 'buzz1'),
+                                              ('fizz2', 'buzz2')],
+                                             names=['fizz', 'buzz'])
+        renamed = df.rename(columns={'fizz1': 'fizz3', 'buzz2': 'buzz3'},
+                            level=0)
+        self.assert_index_equal(renamed.columns, new_columns)
+        renamed = df.rename(columns={'fizz1': 'fizz3', 'buzz2': 'buzz3'},
+                            level='fizz')
+        self.assert_index_equal(renamed.columns, new_columns)
+
+        new_columns = MultiIndex.from_tuples([('fizz1', 'buzz1'),
+                                              ('fizz2', 'buzz3')],
+                                             names=['fizz', 'buzz'])
+        renamed = df.rename(columns={'fizz1': 'fizz3', 'buzz2': 'buzz3'},
+                            level=1)
+        self.assert_index_equal(renamed.columns, new_columns)
+        renamed = df.rename(columns={'fizz1': 'fizz3', 'buzz2': 'buzz3'},
+                            level='buzz')
+        self.assert_index_equal(renamed.columns, new_columns)
+
+        # function
+        func = str.upper
+        new_columns = MultiIndex.from_tuples([('FIZZ1', 'buzz1'),
+                                              ('FIZZ2', 'buzz2')],
+                                             names=['fizz', 'buzz'])
+        renamed = df.rename(columns=func, level=0)
+        self.assert_index_equal(renamed.columns, new_columns)
+        renamed = df.rename(columns=func, level='fizz')
+        self.assert_index_equal(renamed.columns, new_columns)
+
+        new_columns = MultiIndex.from_tuples([('fizz1', 'BUZZ1'),
+                                              ('fizz2', 'BUZZ2')],
+                                             names=['fizz', 'buzz'])
+        renamed = df.rename(columns=func, level=1)
+        self.assert_index_equal(renamed.columns, new_columns)
+        renamed = df.rename(columns=func, level='buzz')
+        self.assert_index_equal(renamed.columns, new_columns)
+
+        # index
+        new_index = MultiIndex.from_tuples([('foo3', 'bar1'),
+                                            ('foo2', 'bar2')],
+                                           names=['foo', 'bar'])
+        renamed = df.rename(index={'foo1': 'foo3', 'bar2': 'bar3'},
+                            level=0)
+        self.assert_index_equal(renamed.index, new_index)
 
     def test_rename_nocopy(self):
         renamed = self.frame.rename(columns={'C': 'foo'}, copy=False)