Mapping a Python Dict to a Polars Series

Mapping a Python dictionary to a Polars Series allows you to replace specific values in the Series based on a key-value relationship defined in the dictionary. This is a useful technique for transforming or cleaning data, particularly when you need to convert categorical values to numerical representations, standardize inconsistent labels, or perform other types of value replacement.

Mapping a Python Dictionary to a Polars Series refers to the process of replacing specific values in a Polars Series based on a dictionary mapping. In this process, the keys in the dictionary correspond to the values in the Series, and the dictionary values are used to replace the matching Series values. In this article, I will explain how to map a Python dict to a polars series.

Key Points –

• replace_strict() is the primary method used to map dictionary keys to Series values in Polars.
• Exact match is required when using replace_strict(); only values present in the dictionary keys will be replaced.
• Unmatched values can be handled using the default parameter, which assigns a fallback value when a Series value isn't found in the dictionary.
• Mapping can be applied inside a DataFrame column using with_columns().
• pl.Series.replace() allows flexible value replacement based on a dictionary.
• If a Series value is not found in the dictionary, the result will be null unless a default is provided.
• The dictionary keys must match the data type of the Series values for mapping to occur correctly.
• This method is useful for converting categorical data (like string labels) into numeric values.

<a id="h-usage-of-mapping-a-dict-to-a-polars-series"></a>

Usage of Mapping a Dict to a Polars Series

Mapping a dictionary to a Polars Series allows you to replace specific values in the Series based on a key-value mapping from the dictionary. It's commonly used to convert categorical data (e.g., string labels) to numeric representations or to update the Series with predefined values.

To run some examples of mapping a dictionary to a Polars Series, let’s create a Polars Series.

import polars as pl

# Sample Series
ser = pl.Series(["a", "b", "c", "d"])
print("Original Series:\n", ser)

Yields below output.

You can perform basic mapping on a Series using the replace_strict() method, which allows you to replace specific values within the Series. The replace_strict() function performs replacements based on a strict mapping, meaning it only replaces values exactly matching those specified in the map.

# Mapping dictionary
mapping = {
    "a": 1,
    "b": 2,
    "c": 3,
}

# Replace using the dictionary
result = ser.replace_strict(mapping, default=None)
print("Series After Mapping:\n", result)

Here,

• "a", "b", and "c" are replaced using the dictionary.
• "d" is not in the dictionary, replaced with null because default=None.

<a id="h-mapping-string-keys-to-numeric-values"></a>

Mapping String Keys to Numeric Values

You can easily map string keys to numeric values in a Polars Series using a dictionary with replace_strict() function. This is a common technique for converting categorical data (such as string labels) into numeric representations, which is often required for tasks like machine learning.

import polars as pl

# Sample Series with string keys
ser = pl.Series(["apple", "banana", "cherry", "date", "elderberry"])

# Mapping dictionary for string keys to numeric values
mapping = {
    "apple": 1,
    "banana": 2,
    "cherry": 3,
    "elderberry": 5
}

# Replace using the dictionary with string keys and numeric values
result = ser.replace_strict(mapping, default=-1)
print("Mapped Series (String Keys to Numeric Values):\n", result)

# Output:
# Mapped Series (String Keys to Numeric Values):
# shape: (5,)
# Series: '' [i64]
# [
#	1
#	2
#	3
#	-1
#	5
# ]

Here,

• "apple", "banana", "cherry", and "elderberry" are replaced by their corresponding numeric values from the dictionary.
• "date" is not found in the dictionary, so it is replaced with -1 (the custom default value).

<a id="h-mapping-boolean-to-integer"></a>

Mapping Boolean to Integer

You can map Boolean values (True/False) to integer values (such as 1 and 0) in a Polars Series using a dictionary with replace_strict().

import polars as pl

# Sample Series with Boolean values
ser = pl.Series([True, False, True, False, True])

# Mapping dictionary for Boolean to Integer
mapping = {
    True: 1,
    False: 0
}

# Replace using the dictionary to map Boolean to Integer
result = ser.replace_strict(mapping)
print("Mapped Series (Boolean to Integer):\n", result)

# Output:
# Mapped Series (Boolean to Integer):
# shape: (5,)
# Series: '' [i64]
# [
#	1
#	0
#	1
#	0
#	1
# ]

Here,

• True values are mapped to 1.
• False values are mapped to 0.
• The mapping uses the dictionary mapping = {True: 1, False: 0}.

<a id="h-mapping-with-multiple-keys"></a>

Mapping with Multiple Keys

To map multiple keys in a Polars Series with a dictionary, you can directly replace values for each key using the replace_strict() function.

import polars as pl

# Sample Series
ser = pl.Series(["a", "b", "c", "d", "e", "f"])

# Mapping dictionary with multiple keys
mapping = {"a": 1,"b": 2,"c": 3,"e": 5,"f": 6,}

# Replace using the dictionary with multiple keys
result = ser.replace_strict(mapping, default=None)
print("Mapped Series with Multiple Keys:\n", result)

# Output:
# Mapped Series with Multiple Keys:
# shape: (6,)
# Series: '' [i64]
# [
#	1
#	2
#	3
#	null
#	5
#	6
# ]

Here,

• "a", "b", "c", "e", and "f" are replaced by their corresponding values from the dictionary.
• "d" is not in the dictionary, so it is replaced with null (since the default is None).

<a id="h-use-replace-strict-for-exact-matches"></a>

Use replace_strict() for Exact Matches

replace_strict() in Polars is specifically designed for exact matches. It ensures that only values exactly present in the dictionary keys are replaced; no partial or fuzzy matching is performed.

import polars as pl

# Sample Series
ser = pl.Series(["Spark", "Panda", "Pandas", "pandas", "Polars", "Spark"])

# Mapping dictionary (case-sensitive)
mapping = {
    "Spark": "Pyspark",
    "Pandas": "Python"
}

# Apply replace_strict (case-sensitive exact matching)
result = ser.replace_strict(mapping, default="Unknown")
print("Mapped Series (Exact Match):\n", result)

# Output:
# Mapped Series (Exact Match):
# shape: (6,)
# Series: '' [str]
# [
#	"Pyspark"
#	"Unknown"
#	"Python"
#	"Unknown"
#	"Unknown"
#	"Pyspark"
# ]

Here,

• "Spark" and "Pandas" are replaced because they exactly match the keys in the dictionary.
• "Panda", "pandas", and "Polars" do not match due to case differences, so they fall back to the "Unknown" default.

<a id="h-replacing-values-in-a-dataframe-column"></a>

Replacing Values in a DataFrame Column

You can apply dictionary-based replacement to a specific column in a Polars DataFrame using the with_columns() method along with replace_strict() inside an expression.

import polars as pl

# Sample DataFrame
df = pl.DataFrame({
    "status": ["yes", "no", "yes", "maybe", "no"]
})

# Mapping dictionary
mapping = {
    "yes": 1,
    "no": 0
}

# Replace values in 'status' column using the mapping
result = df.with_columns(
    pl.col("status").replace_strict(mapping, default=-1).alias("status_mapped")
)
print("Mapped DataFrame:\n", result)

# Output:
# Mapped DataFrame:
# shape: (5, 2)
┌────────┬───────────────┐
│ status ┆ status_mapped │
│ ---    ┆ ---           │
│ str    ┆ i64           │
╞════════╪═══════════════╡
│ yes    ┆ 1             │
│ no     ┆ 0             │
│ yes    ┆ 1             │
│ maybe  ┆ -1            │
│ no     ┆ 0             │
└────────┴───────────────┘

Here,

• The replacement is scoped to the "status" column only.
• Unmapped values (like "maybe") are assigned a custom default (-1).
• The result is added as a new column (status_mapped), preserving the original.

<a id="h-conclusion"></a>

Conclusion

In conclusion, mapping a dictionary to a Polars Series provides a powerful and efficient way to transform and manipulate data. It allows you to replace specific values in a Series with corresponding values from a dictionary, which is particularly useful for converting categorical data, standardizing values, and preparing datasets for tasks like machine learning.

Happy Learning!!

<a id="h-related-articles"></a>

Related Articles

• Polars Series Unique Values
• Polars Series max() Function
• Convert Polars Series to List
• Polars Series rename() – by Examples
• Polars Series tail() Usage & Examples
• Polars Series cast() – Usage & Examples
• Polars Series head() Method with Examples
• Polars Series filter() Method with Examples
• Polars Series min() – Explained by Examples
• How to Replace Certain Values in a Polars Series?
• How to Convert Polars Series to Pandas Series in Python?

<a id="h-reference"></a>

Reference

• https://docs.pola.rs/docs/python/version/0.18/reference/series/api/polars.Series.pct_change.html