Skip to main content
`Ctrl`+`K`

# pandas.DataFrame.mask

DataFrame.mask(cond, other=<no_default>, *, inplace=False, axis=None, level=None)

  Replace values where the condition is True.

  Where `cond` is True, the result takes the value from `other`; where False, it keeps the original value. Inverse of `where()`. Useful for replacing invalid or sentinel values.

  Parameters:
    cond bool Series/DataFrame, array-like, or callable

      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).

    other scalar, Series/DataFrame, or callable

      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). If not specified, entries will be filled with the corresponding NULL value (`np.nan` for numpy dtypes, `pd.NA` for extension dtypes).

    inplace bool, default False

      Whether to perform the operation in place on the data.

    axis int, default None

      Alignment axis, used only when aligning other with the calling object; it has no effect on the alignment of cond, which is always aligned on the calling object’s labels. For Series this parameter is unused and defaults to 0.

    level int, default None

      Alignment level, used only when aligning other with the calling object; it has no effect on the alignment of cond.

  Returns:
    Series or DataFrame

      When applied to a Series, the function will return a Series, and when applied to a DataFrame, it will return a DataFrame.

  See also

  `DataFrame.where()`

    Return an object of same shape as caller.

  `Series.where()`

    Return an object of same shape as caller.

  Notes

  The mask method is an application of the if-then idiom. For each element in the caller, if `cond` is `False` the element is used; otherwise the corresponding element from `other` is used. If the axis of `cond` does not align with the caller Series/DataFrame, the values of `cond` on misaligned index positions will be filled with True.

  The signature for `Series.where()` or `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.

  The dtype of the object takes precedence. The fill value is casted to the object’s dtype, if this can be done losslessly.

  Examples

      >>> s = pd.Series(range(5))
      >>> s.where(s > 0)
      0    NaN
      1    1.0
      2    2.0
      3    3.0
      4    4.0
      dtype: float64
      >>> s.mask(s > 0)
      0    0.0
      1    NaN
      2    NaN
      3    NaN
      4    NaN
      dtype: float64

      >>> s = pd.Series(range(5))
      >>> t = pd.Series([True, False])
      >>> s.where(t, 99)
      0     0
      1    99
      2    99
      3    99
      4    99
      dtype: int64
      >>> s.mask(t, 99)
      0    99
      1     1
      2    99
      3    99
      4    99
      dtype: int64

      >>> s.where(s > 1, 10)
      0    10
      1    10
      2    2
      3    3
      4    4
      dtype: int64
      >>> s.mask(s > 1, 10)
      0     0
      1     1
      2    10
      3    10
      4    10
      dtype: int64

      >>> df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=["A", "B"])
      >>> df
         A  B
      0  0  1
      1  2  3
      2  4  5
      3  6  7
      4  8  9
      >>> m = df % 3 == 0
      >>> df.where(m, -df)
         A  B
      0  0 -1
      1 -2  3
      2 -4 -5
      3  6 -7
      4 -8  9
      >>> df.where(m, -df) == np.where(m, df, -df)
            A     B
      0  True  True
      1  True  True
      2  True  True
      3  True  True
      4  True  True
      >>> df.where(m, -df) == df.mask(~m, -df)
            A     B
      0  True  True
      1  True  True
      2  True  True
      3  True  True
      4  True  True