ZetCode

Pandas where and mask

last modified November 17, 2026 Python 3.15

A boolean mask is a set of True and False values that marks which elements we are interested in. The Pandas methods where and mask use such a mask to replace values while keeping the original shape of the data. They are opposites: where keeps the values where the condition is true and replaces the rest, while mask replaces the values where the condition is true.

This article works through both methods on Series and DataFrames, shows how to supply a replacement value with other, how a condition is applied across a whole table, and how conditions can be chained. All examples were run with pandas 3.1.1.

where on a Series

Calling where with a condition keeps each value for which the condition is True and substitutes NaN (the standard marker for a missing value) everywhere the condition is False. Because NaN is a floating-point value, the resulting Series has a float64 dtype even though the input held integers.

where_series.py
import pandas as pd

s = pd.Series([1, 2, 3, 4, 5])
print(s.where(s > 2))

The condition s > 2 is true for 3, 4 and 5, so those three values survive. The values 1 and 2 become NaN, shown at index positions 0 and 1.

$ python where_series.py
0    NaN
1    NaN
2    3.0
3    4.0
4    5.0
dtype: float64

Providing a replacement with other

The second argument, other, supplies the replacement instead of NaN. We write s.where(condition, other) to put our own value wherever the condition is false. Since the replacement here is the integer 0, the result stays an integer Series.

where_other.py
import pandas as pd

s = pd.Series([1, 2, 3, 4, 5])
print(s.where(s > 2, 0))

The first two entries have been replaced by 0, while 3, 4 and 5 are left as they were. The other argument can also be a Series or a DataFrame whose labels line up with the data, not just a single number.

$ python where_other.py
0    0
1    0
2    3
3    4
4    5
dtype: int64

mask

mask is the mirror image of where: it replaces the values where the condition is True and keeps the rest. Like where it accepts an other argument, so we can choose the replacement rather than getting NaN. In the example we run it both ways.

mask_series.py
import pandas as pd

s = pd.Series([1, 2, 3, 4, 5])
print(s.mask(s > 2))
print()
print(s.mask(s > 2, -1))

The first result keeps 1 and 2 and turns 3, 4 and 5 into NaN; the second keeps 1 and 2 and writes -1 in their place. Compare this with the where output above: the two methods select opposite halves of the same Series.

$ python mask_series.py
0    1.0
1    2.0
2    NaN
3    NaN
4    NaN
dtype: float64

0    1
1    2
2   -1
3   -1
4   -1
dtype: int64

Boolean masks on a DataFrame

A condition built from a DataFrame produces another DataFrame of booleans with the same shape. Applying where with that mask carries out the replacement cell by cell across the whole table. This cell-by-cell application of one rule to every element is what we mean by broadcasting the mask over the DataFrame.

where_dataframe.py
import pandas as pd

df = pd.DataFrame({'A': [1, 5, 3], 'B': [4, 2, 6]})
print(df.where(df > 2, 0))

Every value greater than 2 is kept and every other value becomes 0. In column A the leading 1 is replaced; in column B the middle 2 is replaced. The three rows and two columns of the original table are preserved.

$ python where_dataframe.py
   A  B
0  0  4
1  5  0
2  3  6

Chained conditions

Conditions can be joined with the & (and) and | (or) operators. Each part must be wrapped in parentheses because these operators bind differently from the comparison operators. The combined boolean mask is then passed to where in the usual way.

where_chained.py
import pandas as pd

df = pd.DataFrame({'A': [1, 5, 3, 7], 'B': [4, 2, 6, 8]})
cond = (df > 2) & (df < 7)
print(df.where(cond, 0))

Here a cell is kept only when it lies strictly between 2 and 7. The value 7 in column A and the value 8 in column B fail the upper bound and are replaced by 0, as are the small values 1 and 2.

$ python where_chained.py
   A  B
0  0  4
1  5  0
2  3  6
3  0  0

How this differs from boolean indexing

Boolean indexing uses a mask to select rows, so it throws away the rows that fail the test and changes the number of rows. where and mask never drop rows: they keep the table the same size and change only the cell values. The rename and replace methods, covered in the rename and replace tutorial, work differently again: they substitute values or labels that match a given name or mapping, rather than testing a boolean condition. The example contrasts row filtering with where on the same DataFrame.

where_vs_boolean.py
import pandas as pd

df = pd.DataFrame({'A': [1, 5, 3], 'B': [4, 2, 6]})
print(df[df['A'] > 2])
print()
print(df.where(df > 2, 0))

The boolean index returns two rows, those with index 1 and 2, and keeps their values untouched. The where call returns all three rows with the failing cells set to 0. Choose the first form when you want fewer rows and the second when you want to clean values in place.

$ python where_vs_boolean.py
   A  B
1  5  2
2  3  6

   A  B
0  0  4
1  5  0
2  3  6

Source

Pandas DataFrame.where Documentation, Pandas DataFrame.mask Documentation, and Pandas Indexing Documentation

In this article we have kept values with where, replaced values with mask, supplied custom replacements through other, broadcast conditions over a DataFrame, chained tests with &, and seen how these methods differ from row filtering. For selecting rows see Pandas boolean indexing, and for name-based substitutions see Pandas rename and replace.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Pandas tutorials.