How to Replace Certain Values in a Polars Series?

In Polars, replacing certain values in a Series refers to the process of finding specific values within the Series and substituting them with new values. This operation is essential when working with data, frequently applied for tasks such as data cleaning, standardization, error correction, or converting categorical data into numerical values. In Polars, it can be accomplished in several ways using the replace() method.

In this article, I will explain the replace() method in Polars Series, covering its syntax, parameters, usage, and how to returns a new Series with the specified values replaced

Key Points –

Use the replace() method to replace specific values in a Polars Series.
Use the Series.replace() method to substitute one or more specific values in a Series.
You can replace a single value by passing the target value and the replacement value.
You can replace multiple values by passing sequences (lists) of old and new values of the same length.
The replace() method returns a new Series and does not modify the original Series.
To replace nulls (None), use the fill_null() method instead of replace().
Apply conditional logic using Boolean masks with the set(mask, new_value) method.
Combine Boolean masks with set() for multiple conditional replacements.

Polars Series replace() Introduction

Let’s know the syntax of the series replace() method.


# Syntax of series replace()
Series.replace(
    old: IntoExpr | Sequence[Any] | Mapping[Any, Any],
    new: IntoExpr | Sequence[Any] | NoDefault = ,
    *,
    default: IntoExpr | NoDefault = ,
    return_dtype: PolarsDataType | None = None
) → Self

Parameters of the Polars Series replace()

Following are the parameters of the series replace() method.

old (IntoExpr | Sequence[Any] | Mapping[Any, Any]) - The value(s) to replace.
- Single value (e.g., 85)
- Sequence of values (e.g., [85, 70]).
- Mapping (e.g., {85: 90, 70: 75}) where keys are old values and values are their replacements.
new (IntoExpr | Sequence[Any] | NoDefault) - The value(s) to replace old with.
- Single value (e.g., 90).
- Sequence of values, must match the length of old when old is a list.
- Optional if old is a mapping.
default (IntoExpr | NoDefault) - Value to replace missing values (if old doesn't match any entry).
return_dtype (PolarsDataType | None) - Optionally, specify the data type of the returned Series.

Return Value

This function returns a new Series with the specified replacements applied.

Usage of Polars Series replace() Method

The Series.replace() method in Polars is used to substitute specific values in a Series with new values. It allows you to modify values in a clean and efficient way, either by matching them directly or using a mapping.

To run some examples of how to replace certain values in a Polars Series, let’s create a Polars Series.


import polars as pl 

ser = pl.Series("numbers", [10, 15, 20, 25, 30])
print("Original Series:\n", ser)

Yields below output.

To replace a single value in a Polars Series, you can use the replace() method. For instance, the following example demonstrates how to substitute a specific value (like 20) in the Series with a new value (such as 99).


# Replace the value 20 with 99
ser_replaced = ser.replace(20, 99)
print("Series after replacing 20 with 99:\n", ser_replaced)

Here,

The replace() method will search for the value 20 in the Series and replace it with 99.
The new series (ser_replaced) has the value 99 at the position where 20 was previously.

Replace Using a Mapping

To replace multiple values in a Polars Series using a mapping, you can pass a Python dictionary to the replace() method. The keys in the dictionary represent the values you want to replace, and the values represent what to replace them with.


# Replace values using a mapping
# Replace 15 → 100, 25 → 200
ser_replaced = ser.replace({15: 100, 25: 200})
print("Series after replacement using mapping:\n", ser_replaced)

# Replace using a mapping
mapping = {15: 100, 25: 200}
result = ser.replace(mapping)
print("Series after replacement using mapping:\n", result)

# Output:
# Series after replacement using mapping:
# shape: (5,)
# Series: 'numbers' [i64]
# [
#	10
#	100
#	20
#	200
#	30
# ]

Here,

The dictionary {15: 100, 25: 200} instructs Polars to replace the value 15 with 100 and the value 25 with 200.
Other values (10, 20, 30) remain unchanged.
The original Series is untouched; a new Series is returned.

Replace Multiple Values in a Series Using replace()

To replace multiple values in a Polars Series, you can pass both a sequence of old values and a sequence of new values to the replace() method. This allows you to replace multiple specific values at once.


# Replace multiple values using sequences
# Replace 10 → 99, 30 → 500
ser_replaced = ser.replace([10, 30], [99, 500])
print("Series after replacing multiple values:\n", ser_replaced)

# Output:
# Series after replacing multiple values:
# shape: (5,)
# Series: 'numbers' [i64]
# [
#	99
#	15
#	20
#	25
#	500
# ]

Here,

Old Values: The sequence [10, 30] represents the values we want to replace.
New Values: The list [99, 500] contains the replacement values. Here, 10 is replaced by 99, and 30 is replaced by 500.
Other values (15, 20, 25) remain unchanged.

Replace Using a Dictionary

Replacing values using a dictionary in a Polars Series is one of the cleanest and most readable approaches when you want to map specific values to new ones.


# Replace values using a dictionary
replace_map = {10: 1000, 20: 2000, 30: 3000}
ser_replaced = ser.replace(replace_map)
print("Series after replacing using a dictionary:\n", ser_replaced)

# Output:
# Series after replacing using a dictionary:
# shape: (5,)
# Series: 'numbers' [i64]
# [
#	1000
#	15
#	2000
#	25
#	3000
# ]

Here,

The dictionary {10: 1000, 20: 2000, 30: 3000} directs Polars to replace 10 with 1000, 20 with 2000, and 30 with 3000.
Any value not listed in the dictionary (like 15 or 25) remains unchanged.

Replace using a Boolean Mask with set()

Replacing values using a Boolean mask in Polars gives you flexibility to apply conditional logic.


# Create a Boolean mask (e.g., replace values greater than 20)
mask = ser > 20

# Use set() to replace those values with 999
ser_replaced = ser.set(mask, 999)
print("Replaced Series (values > 20 set to 999):\n", ser_replaced)

# Output:
# Replaced Series (values > 20 set to 999):
# shape: (5,)
# Series: 'numbers' [i64]
# [
#	10
#	15
#	20
#	999
#	999
# ]

Here,

mask = ser > 20 creates a Boolean Series: [False, False, False, True, True]
set(mask, 999) replaces values where the mask is True

Replace Nulls with a Value Using fill_null()

Replacing null values in a Polars Series is a common step in data cleaning, and Polars makes it straightforward with the fill_null() method. This method lets you substitute any None (null or missing) values in the Series with a value you specify.


import polars as pl

# Create a Series with null values
ser = pl.Series("values", [10, None, 20, None, 30])

# Replace nulls with 0
ser_filled = ser.fill_null(0)
print("Nulls Replaced with 0:\n", ser_filled)

# Output:
# Nulls Replaced with 0:
# shape: (5,)
# Series: 'values' [i64]
# [
#	10
#	0
#	20
#	0
#	30
# ]

Here,

The original Series contains None (null) values at index 1 and 3.
The fill_null(0) method replaces all None values with 0.
As a result, the new Series has 0 wherever None was present.

Conclusion

In conclusion, replacing certain values in a Polars Series is a powerful and flexible feature that helps with data cleaning, transformation, and standardization. Whether you're replacing a single value, multiple values using a dictionary, or handling missing data, the replace() method makes it simple and efficient.

Happy Learning!!

References

https://docs.pola.rs/api/python/stable/reference/series/api/polars.Series.rank.html

How to Replace Certain Values in a Polars Series?

Polars Series replace() Introduction

Parameters of the Polars Series replace()

Return Value

Usage of Polars Series replace() Method

Replace Using a Mapping

Replace Multiple Values in a Series Using replace()

Replace Using a Dictionary

Replace using a Boolean Mask with set()

Replace Nulls with a Value Using fill_null()

Conclusion

Related Articles

References