What is the pandas mask() method in Python?

Key takeaways:

  1. The mask() method in pandas replaces elements in a DataFrame or series based on a condition, allowing selective data manipulation.

  2. The syntax of the mask() method is DataFrame.mask(cond, other=np.nan, inplace=False).

  3. The parameters of the mask() method are:

    1. cond: A boolean condition or a callable that returns boolean values.

    2. other: The value to replace elements where cond is True (default is np.nan).

    3. inplace: If True, it modifies the DataFrame directly; if False, it returns a new DataFrame (the default is False).

  4. Condition evaluation method evaluates each element using an if-then approach; elements remain unchanged if the condition evaluates to False.

  5. Aligned axes ensure that the DataFrame or series used for cond has aligned axes (index and columns) with the DataFrame being masked to avoid unexpected results.

  6. The mask() method can also take callable functions (like Lambda functions) for conditions, enabling more complex logical checks (e.g., replacing odd numbers).

The mask() method in pandas replaces specific elements in a DataFrame or series with another value based on a condition. It allows us to selectively change values in a DataFrame or series where a condition is true, leaving other elements unchanged.

Syntax

Here’s the syntax of the mask() method:

DataFrame.mask(cond, other=np.nan, inplace=False)

Parameters

  • DataFrame: This is the pandas DataFrame object.

  • cond: This is a boolean condition or a callable functionIt is used to determine if an object is callable or not. It returns True if the object appears callable, which means it can be invoked like a function. It returns True; if not, it returns False. that returns boolean values. Elements where the condition is True will be replaced.

  • other: The value to replace elements where the condition is True. By default, it’s set to np.nan.

  • inplace: If True, modifies the DataFrame in place; if False, returns a new DataFrame without modifying the original (default is False).

Note: The mask() method uses the if-then approach to evaluate each element in the callable DataFrame. If the condition (cond) evaluates to False for an element, that element remains unchanged; if the condition is True, the element is replaced by the corresponding element from another DataFrame. It’s crucial to ensure that the DataFrame or series used for the condition (cond) has aligned axes (index and columns) with those of the DataFrame being masked. Misaligned index positions can cause unexpected results.

Applying the mask() method with axis or level parameters

Here’s a code example that demonstrates the above note:

import pandas as pd
import numpy as np
# Create a sample DataFrame
df = pd.DataFrame({
    'A': [1, 2, 3, 4],
    'B': [5, 6, 7, 8]
})
# Create a condition DataFrame
cond = pd.DataFrame({
    'A': [True, False, True, False],
    'B': [False, True, False, True]
})
# Create another DataFrame for replacement
replacement = pd.DataFrame({
    'A': [10, 20, 30, 40],
    'B': [50, 60, 70, 80]
})
# Use the mask method
result = df.mask(cond, replacement)
print("Original DataFrame:")
print(df)
print("\nCondition DataFrame:")
print(cond)
print("\nReplacement DataFrame:")
print(replacement)
print("\nResulting DataFrame after applying mask:")
print(result)
# Example with axis parameter
# Create a new condition DataFrame for axis example
cond_axis = pd.DataFrame({
    'A': [False, True, False, True],
    'B': [True, False, True, False]
})
# Create another DataFrame for replacement
replacement_axis = pd.DataFrame({
    'A': [100, 200, 300, 400],
    'B': [500, 600, 700, 800]
})
# Apply mask along the rows (axis=0)
result_axis_0 = df.mask(cond_axis, replacement_axis, axis=0)
# Apply mask along the columns (axis=1)
result_axis_1 = df.mask(cond_axis, replacement_axis, axis=1)
print("\nResulting DataFrame after applying mask with axis=0:")
print(result_axis_0)
print("\nResulting DataFrame after applying mask with axis=1:")
print(result_axis_1)
# Example with level parameter
# Create a multi-index DataFrame
arrays = [
    ['A', 'A', 'B', 'B'],
    ['one', 'two', 'one', 'two']
]
index = pd.MultiIndex.from_arrays(arrays, names=('upper', 'lower'))
df_multi = pd.DataFrame(np.random.randn(4, 4), index=index)
# Create a condition DataFrame for multi-index
cond_multi = pd.DataFrame({
    'A': [True, False, True, False],
    'B': [False, True, False, True]
}, index=index)
# Create another DataFrame for replacement
replacement_multi = pd.DataFrame({
    'A': [10, 20, 30, 40],
    'B': [50, 60, 70, 80]
}, index=index)
# Apply mask along the 'upper' level
result_multi = df_multi.mask(cond_multi, replacement_multi, level='upper')
print("\nMulti-index DataFrame:")
print(df_multi)
print("\nCondition DataFrame for multi-index:")
print(cond_multi)
print("\nReplacement DataFrame for multi-index:")
print(replacement_multi)
print("\nResulting DataFrame after applying mask with level='upper':")
print(result_multi)

In this example, for each element in the df DataFrame, if the corresponding element in the cond, then the DataFrame is True. The corresponding element in the replacement DataFrame replaces the element in df. If the element in cond is False, the element in df remains unchanged.

Key points

  • Ensure the cond DataFrame or series has the same shape and aligned axes as the original DataFrame.

  • Misalignment in index or column positions can cause the mask method to produce unexpected results.

  • The mask() method is useful for conditional element replacement in a DataFrame.

Mask and replace values

Let’s start by creating a simple DataFrame for demonstration:

import pandas as pd
import numpy as np
data = {
    'X': [5, 8, 6, 3, 1],
    'Y': [10, 7, 3, 1, 15],
    'Z': [18, 4, 9, 8, 13]
}
df = pd.DataFrame(data)
print(df)

Now, let’s use the mask() method to replace elements in column 'Y' where the value is greater than 7 with a specific value, say -1:

df['Y'].mask(df['Y'] > 7, -1,inplace=True)
print(df)

In this example, elements in column 'Y' greater than 7 have been replaced with -1, while the rest of the DataFrame remains unchanged.

Using a callable condition

We can also use a callable function as the condition in the mask() method. The callable function is a Lambda function in the following code that checks whether each element is odd (n % 2 != 0). For instance, replacing elements in the column 'X' where the value is odd:

df['X'].mask(lambda n: n % 2 != 0, 'Odd', inplace=True)
print(df)

In the provided code example, a callable function refers to the Lambda function, lambda, used as the condition inside the mask() method. Specifically, the lambda function checks whether each element in column 'X' is odd by evaluating the condition n % 2 != 0, where n represents each element in column 'X'. If elements in column 'X' are odd, they will be replaced with the string 'Odd'.

Conclusion

The mask() method in pandas is a powerful tool for selectively replacing values in a DataFrame or series based on a specified condition. Whether using boolean arrays, callable functions, or other conditions, mask() allows for flexible and efficient data manipulation.

Free Resources

Copyright ©2026 Educative, Inc. All rights reserved