Home Original page

Constants of the numpy.ma module — NumPy v2.5.dev0 Manual

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:

>>> 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[source]#

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#

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

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 methods#

Conversion#

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.

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.

Pickling and copy#

Calculations#

Arithmetic and comparison operations#

Comparison operators:#

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

Arithmetic:#

Arithmetic, in-place:#

Representation#

Special methods#

For standard library functions:

Basic customization:

Container customization: (see Indexing)

Specific methods#

Handling the mask#

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

Handling the fill_value#

Counting the missing elements#