Categorical.rename_categories can take a callable

Author: tp

doc/source/whatsnew/v0.22.0.txt

@@ -139,6 +139,7 @@ Other Enhancements
 - :func:`read_excel()` has gained the ``nrows`` parameter (:issue:`16645`)
 - :func:``DataFrame.to_json`` and ``Series.to_json`` now accept an ``index`` argument which allows the user to exclude the index from the JSON output (:issue:`17394`)
 - ``IntervalIndex.to_tuples()`` has gained the ``na_tuple`` parameter to control whether NA is returned as a tuple of NA, or NA itself (:issue:`18756`)
+- ``Categorical.rename_categories`` can how take a callable as its argument (:issue:`18862`)
 
 .. _whatsnew_0220.api_breaking:
 

pandas/core/categorical.py

@@ -844,7 +844,7 @@ def rename_categories(self, new_categories, inplace=False):
 
         Parameters
         ----------
-        new_categories : list-like or dict-like
+        new_categories : list-like, dict-like or callable
 
            * list-like: all items must be unique and the number of items in
              the new categories must match the existing number of categories.
@@ -854,6 +854,10 @@ def rename_categories(self, new_categories, inplace=False):
              are passed through and extra categories in the mapping are
              ignored. *New in version 0.21.0*.
 
+           * callable : a callable that is called on all items in the old
+             categories and whose return values comprise the new categories.
+             *New in version 0.22.0*.
+
            .. warning::
 
               Currently, Series are considered list like. In a future version
@@ -890,6 +894,12 @@ def rename_categories(self, new_categories, inplace=False):
         >>> c.rename_categories({'a': 'A', 'c': 'C'})
         [A, A, b]
         Categories (2, object): [A, b]
+
+        You may also provide a callable to create the new categories
+
+        >>> c.rename_categories(lambda x: x.upper())
+        [A, A, B]
+        Categories (2, object): [A, B]
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')
         cat = self if inplace else self.copy()
@@ -906,6 +916,8 @@ def rename_categories(self, new_categories, inplace=False):
         if is_dict_like(new_categories):
             cat.categories = [new_categories.get(item, item)
                               for item in cat.categories]
+        elif callable(new_categories):
+            cat.categories = [new_categories(item) for item in cat.categories]
         else:
             cat.categories = new_categories
         if not inplace:

pandas/tests/categorical/test_api.py

@@ -71,9 +71,14 @@ def test_rename_categories(self):
 
         exp_cat = Index(["a", "b", "c"])
         tm.assert_index_equal(cat.categories, exp_cat)
-        res = cat.rename_categories([1, 2, 3], inplace=True)
+
+        # GH18862
+        result = cat.rename_categories(lambda x: x.upper())
+        expected = Categorical(["A", "B", "C", "A"])
+        tm.assert_categorical_equal(result, expected)
 
         # and now inplace
+        res = cat.rename_categories([1, 2, 3], inplace=True)
         assert res is None
         tm.assert_numpy_array_equal(cat.__array__(), np.array([1, 2, 3, 1],
                                                               dtype=np.int64))