DOC: Improve the docstrings of CategoricalIndex.map

pandas/core/arrays/categorical.py

@@ -1081,20 +1081,26 @@ def remove_unused_categories(self, inplace=False):
             return cat
 
     def map(self, mapper):
-        """Apply mapper function to its categories (not codes).
+        """
+        Map categories (not codes) using input correspondence (a dict,
+        Series, or function).
+
+        Maps the categories to new categories. If the mapping
+        correspondence maps each original category to a different new category
+        the result is a Categorical which has the same order property as
+        the original, otherwise an np.ndarray is returned.
+
+        If a dictionary or Series is used any unmapped category is mapped to
+        NA. Note that if this happens an np.ndarray will be returned.
 
         Parameters
         ----------
         mapper : callable
-            Function to be applied. When all categories are mapped
-            to different categories, the result will be Categorical which has
-            the same order property as the original. Otherwise, the result will
-            be np.ndarray.
+            Function to be applied.
 
         Returns
         -------
         applied : Categorical or Index.
-
         """
         new_categories = self.categories.map(mapper)
         try:

pandas/core/indexes/base.py

@@ -3121,22 +3121,23 @@ def groupby(self, values):
         return result
 
     def map(self, mapper, na_action=None):
-        """Map values of Series using input correspondence
+        """
+        Map values using input correspondence (a dict, Series, or function).
 
         Parameters
         ----------
         mapper : function, dict, or Series
+            Mapping correspondence.
         na_action : {None, 'ignore'}
             If 'ignore', propagate NA values, without passing them to the
-            mapping function
+            mapping correspondence.
 
         Returns
         -------
         applied : Union[Index, MultiIndex], inferred
             The output of the mapping function applied to the index.
             If the function returns a tuple with more than one element
             a MultiIndex will be returned.
-
         """
 
         from .multi import MultiIndex

pandas/core/indexes/category.py

@@ -661,20 +661,58 @@ def is_dtype_equal(self, other):
     take_nd = take
 
     def map(self, mapper):
-        """Apply mapper function to its categories (not codes).
+        """
+        Map index values using input correspondence (a dict, Series, or
+        function).
+
+        Maps the values (their categories, not the codes) of the index to new
+        categories. If the mapping correspondence maps each original category
+        to a different new category the result is a CategoricalIndex which has
+        the same order property as the original, otherwise an Index is
+        returned.
+
+        If a dictionary or Series is used any unmapped category is mapped to
+        NA. Note that if this happens an Index will be returned.
 
         Parameters
         ----------
-        mapper : callable
-            Function to be applied. When all categories are mapped
-            to different categories, the result will be a CategoricalIndex
-            which has the same order property as the original. Otherwise,
-            the result will be a Index.
+        mapper : function, dict, or Series
+            Mapping correspondence.
 
         Returns
         -------
-        applied : CategoricalIndex or Index
+        CategoricalIndex or Index
+            Mapped index.
 
+        See Also
+        --------
+        Index.map : Apply a mapping correspondence on an Index.
+        Series.map : Apply a mapping correspondence on a Series.
+        Series.apply : Apply more complex functions on a Series.
+
+        Examples
+        --------
+        >>> idx = pd.CategoricalIndex(['a', 'b', 'c'])
+        >>> idx
+        CategoricalIndex(['a', 'b', 'c'], categories=['a', 'b', 'c'],
+                         ordered=False, dtype='category')
+        >>> idx.map(lambda x: x.upper())
+        CategoricalIndex(['A', 'B', 'C'], categories=['A', 'B', 'C'],
+                         ordered=False, dtype='category')
+        >>> idx.map({'a': 'first', 'b': 'second', 'c': 'third'})
+        CategoricalIndex(['first', 'second', 'third'], categories=['first',
+                         'second', 'third'], ordered=False, dtype='category')
+
+        If the mapping is not bijective an Index is returned:
+
+        >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'})
+        Index(['first', 'second', 'first'], dtype='object')
+
+        If a dictionary is used, all unmapped categories are mapped to NA and
+        the result is an Index:
+
+        >>> idx.map({'a': 'first', 'b': 'second'})
+        Index(['first', 'second', nan], dtype='object')
         """
         return self._shallow_copy_with_infer(self.values.map(mapper))
 

pandas/core/series.py

@@ -2423,25 +2423,26 @@ def unstack(self, level=-1, fill_value=None):
 
     def map(self, arg, na_action=None):
         """
-        Map values of Series using input correspondence (which can be
-        a dict, Series, or function)
+        Map values of Series using input correspondence (a dict, Series, or
+        function).
 
         Parameters
         ----------
         arg : function, dict, or Series
+            Mapping correspondence.
         na_action : {None, 'ignore'}
             If 'ignore', propagate NA values, without passing them to the
-            mapping function
+            mapping correspondence.
 
         Returns
         -------
         y : Series
-            same index as caller
+            Same index as caller.
 
         Examples
         --------
 
-        Map inputs to outputs (both of type `Series`)
+        Map inputs to outputs (both of type `Series`):
 
         >>> x = pd.Series([1,2,3], index=['one', 'two', 'three'])
         >>> x
@@ -2492,9 +2493,9 @@ def map(self, arg, na_action=None):
 
         See Also
         --------
-        Series.apply: For applying more complex functions on a Series
-        DataFrame.apply: Apply a function row-/column-wise
-        DataFrame.applymap: Apply a function elementwise on a whole DataFrame
+        Series.apply : For applying more complex functions on a Series.
+        DataFrame.apply : Apply a function row-/column-wise.
+        DataFrame.applymap : Apply a function elementwise on a whole DataFrame.
 
         Notes
         -----