HOWTO · Pandas
Pandas Map Python
This tutorial explains how we can replace values of a Pandas Series with another value using the Series.map() method.
On this page
Series.map() transforms each value in a pandas Series and returns a new Series. The returned object keeps the input index, so mapping changes values rather than index labels. Use it for a function, dictionary-like lookup, or another Series; see the Series.map() reference for the full API details.
How Series.map() transforms values
The argument determines how each input value is translated. A callable receives each value; a dictionary uses input values as keys; and a mapping Series uses its index as lookup keys and its values as replacements. The result retains the index of the Series being mapped, even when a lookup produces a missing result. This makes it possible to keep the mapped values aligned with the original rows. The input Series is not changed by the call; store the return value or assign it where you need the transformed data. The result dtype follows the mapped values, so a lookup that introduces missing values or returns strings can have a different dtype from the input.
Choose a mapping function, dictionary, or Series
Use a callable for a rule, a dictionary for a fixed lookup table, or a Series when the mapping table is already stored as labeled data. Dictionary keys without a corresponding entry produce a missing result. For a mapping Series, match against its index, not its values.
Handle missing values with na_action
By default, a callable is applied to missing values too, which can be unsuitable for operations such as calling .upper(). Set na_action="ignore" to leave an input missing value untouched while mapping the other values. This option does not remove missing rows. A value with no dictionary or Series mapping also becomes missing, regardless of whether the input itself was present.
Map a DataFrame column
Selecting one column from a DataFrame returns a Series, so you can call map() on that column and assign the returned Series back. Other columns remain as they were. Because assignment aligns by index, the returned Series retains the selected column’s row labels.
Run and verify the examples
Install pandas in your Python environment before running this self-contained example. It prints each mapping result so you can inspect values and indexes locally. The output below is the captured result for this code.
Run this example:
import pandas as pd
scores = pd.Series([85, 87, 90], index=["a", "b", "c"])
print("Callable:")
print(scores.map(lambda value: value + 5))
labels = {85: "pass", 90: "excellent"}
print("Dictionary:")
print(scores.map(labels))
label_table = pd.Series({85: "pass", 87: "review", 90: "excellent"})
print("Series lookup:")
print(scores.map(label_table))
names = pd.Series(["ada", pd.NA, "lin"])
print("Ignore missing values:")
print(names.map(lambda value: value.upper(), na_action="ignore"))
table = pd.DataFrame({"score": [85, 90], "student": ["Ada", "Lin"]}, index=["a", "b"])
table["grade"] = table["score"].map({85: "pass", 90: "excellent"})
print("Mapped DataFrame column:")
print(table)
Callable:
a 90
b 92
c 95
dtype: int64
Dictionary:
a pass
b NaN
c excellent
dtype: str
Series lookup:
a pass
b review
c excellent
dtype: str
Ignore missing values:
0 ADA
1 NaN
2 LIN
dtype: str
Mapped DataFrame column:
score student grade
a 85 Ada pass
b 90 Lin excellent