Skip to main content
`Ctrl`+`K`

# pandas.Categorical.map

Categorical.map(mapper, na_action=None)

  Map categories using an input mapping or function.

  Maps the categories to new categories. If the mapping correspondence is one-to-one the result is a `Categorical` which has the same order property as the original, otherwise a `Index` is returned. NaN values are unaffected.

  If a dict or `Series` is used any unmapped category is mapped to NaN. Note that if this happens an `Index` will be returned.

  Parameters:
    mapper function, dict, or Series

      Mapping correspondence.

    na_action{None, ‘ignore’}, default None

      If ‘ignore’, propagate NaN values, without passing them to the mapping correspondence.

  Returns:
    pandas.Categorical or pandas.Index

      Mapped categorical.

  See also

  `CategoricalIndex.map`

    Apply a mapping correspondence on a `CategoricalIndex`.

  `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

      >>> cat = pd.Categorical(["a", "b", "c"])
      >>> cat
      ['a', 'b', 'c']
      Categories (3, str): ['a', 'b', 'c']
      >>> cat.map(lambda x: x.upper(), na_action=None)
      ['A', 'B', 'C']
      Categories (3, str): ['A', 'B', 'C']
      >>> cat.map({"a": "first", "b": "second", "c": "third"}, na_action=None)
      ['first', 'second', 'third']
      Categories (3, str): ['first', 'second', 'third']

  If the mapping is one-to-one the ordering of the categories is preserved:

      >>> cat = pd.Categorical(["a", "b", "c"], ordered=True)
      >>> cat
      ['a', 'b', 'c']
      Categories (3, str): ['a' < 'b' < 'c']
      >>> cat.map({"a": 3, "b": 2, "c": 1}, na_action=None)
      [3, 2, 1]
      Categories (3, int64): [3 < 2 < 1]

  If the mapping is not one-to-one an `Index` is returned:

      >>> cat.map({"a": "first", "b": "second", "c": "first"}, na_action=None)
      Index(['first', 'second', 'first'], dtype='str')

  If a dict is used, all unmapped categories are mapped to NaN and the result is an `Index`:

      >>> cat.map({"a": "first", "b": "second"}, na_action=None)
      Index(['first', 'second', nan], dtype='str')

  The mapping function is applied to categories, not to each value. It is therefore only called once per unique category, and the result reused for all occurrences:

      >>> cat = pd.Categorical(["a", "a", "b"])
      >>> calls = []
      >>> def f(x):
      ...     calls.append(x)
      ...     return x.upper()
      >>> result = cat.map(f)
      >>> result
      ['A', 'A', 'B']
      Categories (2, str): ['A', 'B']
      >>> calls
      ['a', 'b']