How to Use mask() in pandas: Syntax and Examples

In pandas, mask() replaces values where a condition is True with specified values or NaN by default. It works like a filter that hides data matching the condition, letting you selectively change or hide data in a DataFrame or Series.

Syntax

The mask() function has this basic form:

• cond: A condition (boolean array or expression) where True means replace the value.
• other: The value to replace with (default is np.nan).
• inplace: If True, modifies the original data instead of returning a new one.
• axis: Axis to apply the mask on (optional).

python

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

Example

This example shows how to replace all values greater than 3 with NaN in a DataFrame using mask().

python

import pandas as pd
import numpy as np

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

# Replace values greater than 3 with NaN
masked_df = df.mask(df > 3)
print(masked_df)

Output

     A    B
0  1.0  NaN
1  NaN  2.0
2  3.0  NaN
3  NaN  1.0

Common Pitfalls

One common mistake is confusing mask() with where(). mask() replaces values where the condition is True, while where() keeps values where the condition is True and replaces others.

Also, forgetting to assign the result back or use inplace=True means the original data stays unchanged.

python

import pandas as pd

df = pd.DataFrame({'A': [1, 4, 3, 6]})

# Wrong: mask returns a new DataFrame, original unchanged
mask_result = df.mask(df['A'] > 3)
print(df)  # Original unchanged

# Right: assign back or use inplace

df = df.mask(df['A'] > 3)
print(df)

Output

   A
0  1
1  4
2  3
3  6
     A
0  1.0
1  NaN
2  3.0
3  NaN

Quick Reference

Remember these key points about mask():

• Replaces values where condition is True.
• Default replacement is NaN, but you can specify any value.
• Opposite of where() which keeps values where condition is True.
• Use inplace=True to modify original data.

Key Takeaways

Use pandas mask() to replace values where a condition is true, defaulting to NaN.

mask() is the opposite of where(): mask replaces where true, where keeps where true.

Always assign the result or use inplace=True to change the original DataFrame or Series.

You can replace with any value, not just NaN, by setting the other parameter.

mask() works on both DataFrames and Series for flexible conditional replacement.