Pandas Series: mask() function

Last update on September 15 2022 12:57:53 (UTC/GMT +8 hours)

Replace values in Pandas Series

The mask() function is used to replace values where the condition is True.

Syntax:

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

Parameters:

Name	Description	Type/Default Value	Required / Optional
cond	Where cond is False, keep the original value. Where True, replace with corresponding value from other. If cond is callable, it is computed on the Series/DataFrame and should return boolean Series/DataFrame or array. The callable must not change input Series/DataFrame (though pandas doesn’t check it).	boolean Series/DataFrame, array-like, or callable	Required
other	Entries where cond is True are replaced with corresponding value from other. If other is callable, it is computed on the Series/DataFrame and should return scalar or Series/DataFrame. The callable must not change input Series/DataFrame (though pandas doesn’t check it).	scalar, Series/DataFrame, or callable	Required
inplace	Whether to perform the operation in place on the data.	bool Default Value: False	Required
axis	Alignment axis if needed.	int Default Value: None	Required
level	Alignment level if needed.	int Default Value: None	Required
errors	Note that currently this parameter won’t affect the results and will always coerce to a suitable dtype. ‘raise’ : allow exceptions to be raised. ‘ignore’ : suppress exceptions. On error return original object.	str, {‘raise’, ‘ignore’} Default Value: ‘raise’	Required
try_cast	Try to cast the result back to the input type (if possible).	bool Default Value: False	Required

Returns: Same type as caller

Notes: The mask method is an application of the if-then idiom. For each element in the calling DataFrame, if cond is False the element is used; otherwise the corresponding element from the DataFrame other is used.
The signature for DataFrame.where() differs from numpy.where(). Roughly df1.where(m, df2) is equivalent to np.where(m, df1, df2).

For further details and examples see the mask documentation in indexing.

Example:

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(range(6))
s.where(s > 0)

Output:

0    NaN
1    1.0
2    2.0
3    3.0
4    4.0
5    5.0
dtype: float64

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(range(6))
s.mask(s > 0)

Output:

0    0.0
1    NaN
2    NaN
3    NaN
4    NaN
5    NaN
dtype: float64

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(range(6))
s.where(s > 1, 10)

Output:

0    10
1    10
2     2
3     3
4     4
5     5
dtype: int64

Python-Pandas Code:

import numpy as np
import pandas as pd
df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=['P', 'Q'])
df

Output:

Python-Pandas Code:

import numpy as np
import pandas as pd
df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=['P', 'Q'])
m = df % 3 == 0
df.where(m, -df)

Output:

Python-Pandas Code:

import numpy as np
import pandas as pd
df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=['P', 'Q'])
m = df % 3 == 0
df.where(m, -df) == np.where(m, df, -df)

Output:

     P	       Q
0	True	True
1	True	True
2	True	True
3	True	True
4	True	True

Python-Pandas Code:

import numpy as np
import pandas as pd
df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=['P', 'Q'])
m = df % 3 == 0
df.where(m, -df) == df.mask(~m, -df)

Output:

     P	    Q
0	True	True
1	True	True
2	True	True
3	True	True
4	True	True

Previous: Series-where() function
Next: Prefix labels with string prefix in Pandas series