pandas.Categorical.map — pandas 3.0.0rc0+33.g1fd184de2a documentation (original) (raw)

Categorical.map(mapper, na_action=None)[source]#

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 Indexis 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 Indexwill be returned.

Parameters:

mapperfunction, 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.

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']