Skip to main content
`Ctrl`+`K`

# Constants of the `numpy.ma` module

In addition to the `MaskedArray` class, the `numpy.ma` module defines several constants.

numpy.ma.masked

  The `masked` constant is a special case of `MaskedArray`, with a float datatype and a null shape. It is used to test whether a specific entry of a masked array is masked, or to mask one or several entries of a masked array:

      .. try_examples::

      >>> import numpy as np

      >>> x = np.ma.array([1, 2, 3], mask=[0, 1, 0])
      >>> x[1] is np.ma.masked
      True
      >>> x[-1] = np.ma.masked
      >>> x
      masked_array(data=[1, --, --],
                   mask=[False,  True,  True],
             fill_value=999999)

numpy.ma.nomask

  Value indicating that a masked array has no invalid entry. `nomask` is used internally to speed up computations when the mask is not needed. It is represented internally as `np.False_`.

numpy.ma.masked_print_option

  String used in lieu of missing data when a masked array is printed. By default, this string is `'--'`.

  Use `set_display()` to change the default string. Example usage: `numpy.ma.masked_print_option.set_display('X')` replaces missing data with `'X'`.

# The `MaskedArray` class

class numpy.ma.MaskedArray

A subclass of `ndarray` designed to manipulate numerical arrays with missing data.

An instance of `MaskedArray` can be thought as the combination of several elements:

- The `data`, as a regular `numpy.ndarray` of any shape or datatype (the data).

- A boolean `mask` with the same shape as the data, where a `True` value indicates that the corresponding element of the data is invalid. The special value `nomask` is also acceptable for arrays without named fields, and indicates that no data is invalid.

- A `fill_value`, a value that may be used to replace the invalid entries in order to return a standard `numpy.ndarray`.

## Attributes and properties of masked arrays

See also

Array Attributes

ma.MaskedArray.data

  Returns the underlying data, as a view of the masked array.

  If the underlying data is a subclass of `numpy.ndarray`, it is returned as such.

      >>> x = np.ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
      >>> x.data
      matrix([[1, 2],
              [3, 4]])

  The type of the data can be accessed through the `baseclass` attribute.

ma.MaskedArray.mask

  Current mask.

ma.MaskedArray.recordmask

  Get or set the mask of the array if it has no named fields. For structured arrays, returns a ndarray of booleans where entries are `True` if all the fields are masked, `False` otherwise:

      >>> x = np.ma.array([(1, 1), (2, 2), (3, 3), (4, 4), (5, 5)],
      ...         mask=[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
      ...        dtype=[('a', int), ('b', int)])
      >>> x.recordmask
      array([False, False,  True, False, False])

ma.MaskedArray.fill_value

  The filling value of the masked array is a scalar. When setting, None will set to a default based on the data type.

  Examples

      >>> import numpy as np
      >>> for dt in [np.int32, np.int64, np.float64, np.complex128]:
      ...     np.ma.array([0, 1], dtype=dt).get_fill_value()
      ...
      np.int64(999999)
      np.int64(999999)
      np.float64(1e+20)
      np.complex128(1e+20+0j)

      >>> x = np.ma.array([0, 1.], fill_value=-np.inf)
      >>> x.fill_value
      np.float64(-inf)
      >>> x.fill_value = np.pi
      >>> x.fill_value
      np.float64(3.1415926535897931)

  Reset to default:

      >>> x.fill_value = None
      >>> x.fill_value
      np.float64(1e+20)

ma.MaskedArray.baseclass

  Class of the underlying data (read-only).

ma.MaskedArray.sharedmask

  Share status of the mask (read-only).

ma.MaskedArray.hardmask

  Specifies whether values can be unmasked through assignments.

  By default, assigning definite values to masked array entries will unmask them. When `hardmask` is `True`, the mask will not change through assignments.

  See also

  `ma.MaskedArray.harden_mask`
  `ma.MaskedArray.soften_mask`

  Examples

      >>> import numpy as np
      >>> x = np.arange(10)
      >>> m = np.ma.masked_array(x, x>5)
      >>> assert not m.hardmask

  Since m has a soft mask, assigning an element value unmasks that element:

      >>> m[8] = 42
      >>> m
      masked_array(data=[0, 1, 2, 3, 4, 5, --, --, 42, --],
                   mask=[False, False, False, False, False, False,
                         True, True, False, True],
             fill_value=999999)

  After hardening, the mask is not affected by assignments:

      >>> hardened = np.ma.harden_mask(m)
      >>> assert m.hardmask and hardened is m
      >>> m[:] = 23
      >>> m
      masked_array(data=[23, 23, 23, 23, 23, 23, --, --, 23, --],
                   mask=[False, False, False, False, False, False,
                         True, True, False, True],
             fill_value=999999)

As `MaskedArray` is a subclass of `ndarray`, a masked array also inherits all the attributes and properties of a `ndarray` instance.

`MaskedArray.base` | Base object if memory is from some other object.
`MaskedArray.ctypes` | An object to simplify the interaction of the array with the ctypes module.
`MaskedArray.dtype` | Data-type of the array's elements.
`MaskedArray.flags` | Information about the memory layout of the array.
`MaskedArray.itemsize` | Length of one array element in bytes.
`MaskedArray.nbytes` | Total bytes consumed by the elements of the array.
`MaskedArray.ndim` | Number of array dimensions.
`MaskedArray.shape` | Tuple of array dimensions.
`MaskedArray.size` | Number of elements in the array.
`MaskedArray.strides` | Tuple of bytes to step in each dimension when traversing an array.
`MaskedArray.imag` | The imaginary part of the masked array.
`MaskedArray.real` | The real part of the masked array.
`MaskedArray.flat` | Return a flat iterator, or set a flattened version of self to value.
`MaskedArray.__array_priority__` |

# `MaskedArray` methods

See also

Array methods

## Conversion

`MaskedArray.__float__`() | Convert to float.
`MaskedArray.__int__`() | Convert to int.
`MaskedArray.view`([dtype, type, fill_value]) | Return a view of the MaskedArray data.
`MaskedArray.astype`(dtype[, order, casting, ...]) | Copy of the array, cast to a specified type.
`MaskedArray.byteswap`([inplace]) | Swap the bytes of the array elements
`MaskedArray.compressed`() | Return all the non-masked data as a 1-D array.
`MaskedArray.filled`([fill_value]) | Return a copy of self, with masked values filled with a given value.
`MaskedArray.tofile`(fid[, sep, format]) | Save a masked array to a file in binary format.
`MaskedArray.toflex`() | Transforms a masked array into a flexible-type array.
`MaskedArray.tolist`([fill_value]) | Return the data portion of the masked array as a hierarchical Python list.
`MaskedArray.torecords`() | Transforms a masked array into a flexible-type array.
`MaskedArray.tobytes`([fill_value, order]) | Return the array data as a string containing the raw bytes in the array.

## Shape manipulation

For reshape, resize, and transpose, the single tuple argument may be replaced with `n` integers which will be interpreted as an n-tuple.

`MaskedArray.flatten`([order]) | Return a copy of the array collapsed into one dimension.
`MaskedArray.ravel`([order]) | Returns a 1D version of self, as a view.
`MaskedArray.reshape`(*s, **kwargs) | Give a new shape to the array without changing its data.
`MaskedArray.resize`(newshape[, refcheck, order]) |
`MaskedArray.squeeze`([axis]) | Remove axes of length one from a.
`MaskedArray.swapaxes`(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
`MaskedArray.transpose`(*axes) | Returns a view of the array with axes transposed.
`MaskedArray.T` | View of the transposed array.

## Item selection and manipulation

For array methods that take an `axis` keyword, it defaults to None. If axis is None, then the array is treated as a 1-D array. Any other value for `axis` represents the dimension along which the operation should proceed.

`MaskedArray.argmax`([axis, fill_value, out, ...]) | Returns array of indices of the maximum values along the given axis.
`MaskedArray.argmin`([axis, fill_value, out, ...]) | Return array of indices to the minimum values along the given axis.
`MaskedArray.argsort`([axis, kind, order, ...]) | Return an ndarray of indices that sort the array along the specified axis.
`MaskedArray.choose`(choices[, out, mode]) | Use an index array to construct a new array from a set of choices.
`MaskedArray.compress`(condition[, axis, out]) | Return a where condition is `True`.
`MaskedArray.diagonal`([offset, axis1, axis2]) | Return specified diagonals.
`MaskedArray.fill`(value) | Fill the array with a scalar value.
`MaskedArray.item`(*args) | Copy an element of an array to a standard Python scalar and return it.
`MaskedArray.nonzero`() | Return the indices of unmasked elements that are not zero.
`MaskedArray.put`(indices, values[, mode]) | Set storage-indexed locations to corresponding values.
`MaskedArray.repeat`(repeats[, axis]) | Repeat elements of an array.
`MaskedArray.searchsorted`(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
`MaskedArray.sort`([axis, kind, order, ...]) | Sort the array, in-place
`MaskedArray.take`(indices[, axis, out, mode]) | Take elements from a masked array along an axis.

## Pickling and copy

`MaskedArray.copy`([order]) | Return a copy of the array.
`MaskedArray.dump`(file) | Dump a pickle of the array to the specified file.
`MaskedArray.dumps`() | Returns the pickle of the array as a string.

## Calculations

`MaskedArray.all`([axis, out, keepdims]) | Returns True if all elements evaluate to True.
`MaskedArray.anom`([axis, dtype]) | Compute the anomalies (deviations from the arithmetic mean) along the given axis.
`MaskedArray.any`([axis, out, keepdims]) | Returns True if any of the elements of a evaluate to True.
`MaskedArray.clip`([min, max, out]) | Return an array whose values are limited to `[min, max]`.
`MaskedArray.conj`() | Complex-conjugate all elements.
`MaskedArray.conjugate`() | Return the complex conjugate, element-wise.
`MaskedArray.cumprod`([axis, dtype, out]) | Return the cumulative product of the array elements over the given axis.
`MaskedArray.cumsum`([axis, dtype, out]) | Return the cumulative sum of the array elements over the given axis.
`MaskedArray.max`([axis, out, fill_value, ...]) | Return the maximum along a given axis.
`MaskedArray.mean`([axis, dtype, out, keepdims]) | Returns the average of the array elements along given axis.
`MaskedArray.min`([axis, out, fill_value, ...]) | Return the minimum along a given axis.
`MaskedArray.prod`([axis, dtype, out, keepdims]) | Return the product of the array elements over the given axis.
`MaskedArray.product`([axis, dtype, out, keepdims]) | Return the product of the array elements over the given axis.
`MaskedArray.ptp`([axis, out, fill_value, ...]) | Return (maximum - minimum) along the given dimension (i.e. peak-to-peak value).
`MaskedArray.round`([decimals, out]) | Return each element rounded to the given number of decimals.
`MaskedArray.std`([axis, dtype, out, ddof, ...]) | Returns the standard deviation of the array elements along given axis.
`MaskedArray.sum`([axis, dtype, out, keepdims]) | Return the sum of the array elements over the given axis.
`MaskedArray.trace`([offset, axis1, axis2, ...]) | Return the sum along diagonals of the array.
`MaskedArray.var`([axis, dtype, out, ddof, ...]) | Compute the variance along the specified axis.

## Arithmetic and comparison operations

### Comparison operators:

`MaskedArray.__lt__`(other) | Return self<value.
`MaskedArray.__le__`(other) | Return self<=value.
`MaskedArray.__gt__`(other) | Return self>value.
`MaskedArray.__ge__`(other) | Return self>=value.
`MaskedArray.__eq__`(other) | Check whether other equals self elementwise.
`MaskedArray.__ne__`(other) | Check whether other does not equal self elementwise.

### Truth value of an array (`bool()`):

`MaskedArray.__bool__`(/) | True if self else False

### Arithmetic:

`MaskedArray.__abs__`(self) |
`MaskedArray.__add__`(other) | Add self to other, and return a new masked array.
`MaskedArray.__radd__`(other) | Add other to self, and return a new masked array.
`MaskedArray.__sub__`(other) | Subtract other from self, and return a new masked array.
`MaskedArray.__rsub__`(other) | Subtract self from other, and return a new masked array.
`MaskedArray.__mul__`(other) | Multiply self by other, and return a new masked array.
`MaskedArray.__rmul__`(other) | Multiply other by self, and return a new masked array.
`MaskedArray.__truediv__`(other) | Divide other into self, and return a new masked array.
`MaskedArray.__rtruediv__`(other) | Divide self into other, and return a new masked array.
`MaskedArray.__floordiv__`(other) | Divide other into self, and return a new masked array.
`MaskedArray.__rfloordiv__`(other) | Divide self into other, and return a new masked array.
`MaskedArray.__mod__`(value, /) | Return self%value.
`MaskedArray.__rmod__`(value, /) | Return value%self.
`MaskedArray.__divmod__`(value, /) | Return divmod(self, value).
`MaskedArray.__rdivmod__`(value, /) | Return divmod(value, self).
`MaskedArray.__pow__`(other) | Raise self to the power other, masking the potential NaNs/Infs
`MaskedArray.__rpow__`(other) | Raise other to the power self, masking the potential NaNs/Infs
`MaskedArray.__lshift__`(value, /) | Return self<<value.
`MaskedArray.__rlshift__`(value, /) | Return value<<self.
`MaskedArray.__rshift__`(value, /) | Return self>>value.
`MaskedArray.__rrshift__`(value, /) | Return value>>self.
`MaskedArray.__and__`(value, /) | Return self&value.
`MaskedArray.__rand__`(value, /) | Return value&self.
`MaskedArray.__or__`(value, /) | Return self|value.
`MaskedArray.__ror__`(value, /) | Return value|self.
`MaskedArray.__xor__`(value, /) | Return self^value.
`MaskedArray.__rxor__`(value, /) | Return value^self.

### Arithmetic, in-place:

`MaskedArray.__iadd__`(other) | Add other to self in-place.
`MaskedArray.__isub__`(other) | Subtract other from self in-place.
`MaskedArray.__imul__`(other) | Multiply self by other in-place.
`MaskedArray.__itruediv__`(other) | True divide self by other in-place.
`MaskedArray.__ifloordiv__`(other) | Floor divide self by other in-place.
`MaskedArray.__imod__`(value, /) | Return self%=value.
`MaskedArray.__ipow__`(other) | Raise self to the power other, in place.
`MaskedArray.__ilshift__`(value, /) | Return self<<=value.
`MaskedArray.__irshift__`(value, /) | Return self>>=value.
`MaskedArray.__iand__`(value, /) | Return self&=value.
`MaskedArray.__ior__`(value, /) | Return self|=value.
`MaskedArray.__ixor__`(value, /) | Return self^=value.

## Representation

`MaskedArray.__repr__`() | Literal string representation.
`MaskedArray.__str__`() | Return str(self).
`MaskedArray.ids`() | Return the addresses of the data and mask areas.
`MaskedArray.iscontiguous`() | Return a boolean indicating whether the data is contiguous.

## Special methods

For standard library functions:

`MaskedArray.__copy__`() | Used if `copy.copy` is called on an array.
`MaskedArray.__deepcopy__`(memo, /) | Used if `copy.deepcopy` is called on an array.
`MaskedArray.__getstate__`() | Return the internal state of the masked array, for pickling purposes.
`MaskedArray.__reduce__`() | Return a 3-tuple for pickling a MaskedArray.
`MaskedArray.__setstate__`(state) | Restore the internal state of the masked array, for pickling purposes.

Basic customization:

`MaskedArray.__new__`(cls[, data, mask, ...]) | Create a new masked array from scratch.
`MaskedArray.__array__`([dtype], *[, copy]) | For `dtype` parameter it returns a new reference to self if `dtype` is not given or it matches array's data type.
`MaskedArray.__array_wrap__`(obj[, context, ...]) | Special hook for ufuncs.

Container customization: (see Indexing)

`MaskedArray.__len__`(/) | Return len(self).
`MaskedArray.__getitem__`(indx) | x.__getitem__(y) <==> x[y]
`MaskedArray.__setitem__`(indx, value) | x.__setitem__(i, y) <==> x[i]=y
`MaskedArray.__delitem__`(key, /) | Delete self[key].
`MaskedArray.__contains__`(key, /) | Return bool(key in self).

## Specific methods

### Handling the mask

The following methods can be used to access information about the mask or to manipulate the mask.

`MaskedArray.__setmask__`(mask[, copy]) | Set the mask.
`MaskedArray.harden_mask`() | Force the mask to hard, preventing unmasking by assignment.
`MaskedArray.soften_mask`() | Force the mask to soft (default), allowing unmasking by assignment.
`MaskedArray.unshare_mask`() | Copy the mask and set the sharedmask flag to `False`.
`MaskedArray.shrink_mask`() | Reduce a mask to nomask when possible.

### Handling the fill_value

`MaskedArray.get_fill_value`() | The filling value of the masked array is a scalar.
`MaskedArray.set_fill_value`([value]) |

### Counting the missing elements

`MaskedArray.count`([axis, keepdims]) | Count the non-masked elements of the array along the given axis.