Mastering the pandas.Series.where() method (7 examples)

Updated: February 18, 2024 By: Guest Contributor Post a comment


The pandas.Series.where() method is a powerful yet sometimes underutilized function that can significantly simplify the process of manipulating and analyzing data within a Series object in the pandas library. This tutorial aims to demystify this method through seven practical examples, ranging from basic to advanced uses. By the end, you’ll have a solid understanding of how to leverage pandas.Series.where() in your data analysis tasks.

Syntax & Parameters

The where() method in pandas allows for conditional selection and replacement within a Series. Essentially, it provides a way to replace values in a Series based on a condition. The syntax is:

Series.where(cond, other=nan, inplace=False, axis=None, level=None, errors='raise', try_cast=False)

Parameters in brief:

  • cond: Condition on which the replacement is based.
  • other: The value to insert where the condition is False.
  • inplace: If True, modifies the Series in place.
  • axis: Not applicable for Series as it’s a 1D structure.
  • level: If the Series has a multi-level index, apply change at this level.
  • errors: Controls error raising on invalid arguments.
  • try_cast: Tries to cast the result back to the input data type.

Example 1: Basic Usage

import pandas as pd

s = pd.Series([20, 15, 30, 25])
s.where(s > 18, 'Adult')


0       20
1    Adult
2       30
3       25
dtype: object

In the basic example above, we’ve replaced all values that are not greater than 18 with ‘Adult’.

Example 2: Using other as Series

import pandas as pd

s1 = pd.Series([20, 15, 30, 25])
s2 = pd.Series(['A', 'B', 'C', 'D'])
s1.where(s1 > 18, s2)


0    20
1     B
2    30
3    25
dtype: object

Here, we replace elements not matching the condition with corresponding values from another Series.

Example 3: Inplace Replacement

import pandas as pd

s = pd.Series([2, 4, 6, 8, 10])
s.where(s > 5, 0, inplace=True)


0     0
1     0
2     6
3     8
4    10
dtype: int64

This example directly modifies the original Series, replacing values not greater than 5 with 0.

Example 4: Working with NaN

import pandas as pd
import numpy as np

s = pd.Series([1, np.nan, 2, np.nan, 3])
s.where(pd.notnull(s), 'Missing')


0         1
1   Missing
2         2
3   Missing
4         3
dtype: object

NaN values are replaced with ‘Missing’, showcasing how pandas.Series.where() can be used to handle missing data.

Example 5: With a Callable as Condition

import pandas as pd

s = pd.Series(range(1, 6))
s.where(lambda x: x % 2 == 0, 'Even')


0    Even
1       2
2    Even
3       4
4    Even
dtype: object

In this more advanced example, we use a lambda function as the condition. It selects even numbers, replacing others with ‘Even’.

Example 6: Conditional Replacement with DataFrame

import pandas as pd

s = pd.Series([1, 2, 3, 4, 5])
df = pd.DataFrame({'A': [1, 2, 3, 'x', 'y'], 'B': ['a', 'b', 'c', 1, 2]})
s.where(s.isin(df['A']), 'Not in A')


0           1
1           2
2           3
3    Not in A
4    Not in A
dtype: object

This example demonstrates a slightly more complex use case, comparing Series with DataFrame column ‘A’ and replacing non-matching values.

Example 7: Applying Multiple Conditions

import pandas as pd
import numpy as np

s = pd.Series(np.arange(10))
condition = (s % 2 == 0) & (s > 4)
s.where(condition, 'Does not meet')


0    Does not meet
1    Does not meet
2    Does not meet
3    Does not meet
4    Does not meet
5    Does not meet
6               6
7    Does not meet
8               8
9    Does not meet
dtype: object

Through this example, we illustrate handling multiple conditions, showcasing the method’s flexibility.


The pandas.Series.where() method is a versatile tool for data transformation and selection based on conditions. As demonstrated through these examples, it can handle a wide range of scenarios from simple replacements to complex, condition-based manipulations. Mastering the use of where() can significantly enhance your data wrangling capabilities in pandas.