The where method in pandas is used to replace values in a DataFrame where a specified condition is False. The default behavior is to replace non-matching values with NaN, but a custom replacement value can be provided.

Syntax and Parameters

The method signature is:

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

• cond: A boolean Series, DataFrame, or callable. Elements where cond is True remain unchanged.
• other: The scalar, Series, DataFrame, or callable value to replace elements where cond is False. Default is NaN.
• inplace: If True, performs the operation in-place and returns None. Default is False.
• axis: Alignment axis if needed. Usually not required.
• level: For MultiIndex DataFrames, the level to align the condition.
• errors: Controls raising exceptions on invalid data. Options are 'raise' or 'ignore'.
• try_cast: Attempts to cast the result back to the original dtype.

Basic Examples

Example 1: Replace non-matching values with NaN

import pandas as pd

sample_df = pd.DataFrame({'Column1': [10, 20, 30, 40], 'Column2': [50, 60, 70, 80]})
result_df = sample_df.where(sample_df > 25)
print(result_df)

Output:

   Column1  Column2
0      NaN      NaN
1      NaN      NaN
2     30.0     70.0
3     40.0     80.0

Values less than or equal to 25 are replaced with NaN.

Example 2: Replace non-matching values with a specific scalar

sample_df = pd.DataFrame({'Column1': [10, 20, 30, 40], 'Column2': [50, 60, 70, 80]})
result_df = sample_df.where(sample_df > 25, other=-1)
print(result_df)

Output:

   Column1  Column2
0       -1       -1
1       -1       -1
2       30       70
3       40       80

Example 3: Using a callable condition

sample_df = pd.DataFrame({'X': [5, 15, 25], 'Y': [35, 45, 55]})
# Condition: Keep values where the sum of the row is greater than 50
result_df = sample_df.where(lambda d: d.sum(axis=1) > 50, other=0)
print(result_df)

Output:

   X   Y
0  0   0
1  0  45
2 25  55

Advanced Usage with Other Objects

The other parameter can accept objects that align with the DataFrame.

Example 4: Replacement using a Series

sample_df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]}, index=['r1', 'r2', 'r3'])
replacement_series = pd.Series([100, 200, 300], index=['r1', 'r2', 'r3'])
# Replace values in column 'A' where they are less than 3 with the Series values
result_df = sample_df.where(sample_df['A'] >= 3, other=replacement_series, axis=0)
print(result_df)

Output:

      A  B
r1  100  4
r2  200  5
r3    3  6

Example 5: Replacement using another DataFrame

df_original = pd.DataFrame({'Val1': [7, 8, 9], 'Val2': [10, 11, 12]})
df_replacement = pd.DataFrame({'Val1': [70, 80, 90], 'Val2': [100, 110, 120]})
# Keep values where original is greater than 8, else use replacement df
result_df = df_original.where(df_original > 8, other=df_replacement)
print(result_df)

Output:

   Val1  Val2
0    70   100
1    80   110
2     9    12

Key Considerations

• The inplace=True parameter modifies the original DataFrame and returns None. Use with caution.
• Missing values (NaN) evaluate to False in boolean conditiosn. Use pd.isna() or pd.notna() for explicit checks.
• For performance with large datasets, consider if vectorized operations or np.where might be more efficient.
• The condition cond and the other argument are usually aligned with the DataFrame's index and columns.