diff options
Diffstat (limited to 'doc/source/reference/maskedarray.baseclass.rst')
| -rw-r--r-- | doc/source/reference/maskedarray.baseclass.rst | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/doc/source/reference/maskedarray.baseclass.rst b/doc/source/reference/maskedarray.baseclass.rst new file mode 100644 index 000000000..bef16b100 --- /dev/null +++ b/doc/source/reference/maskedarray.baseclass.rst @@ -0,0 +1,395 @@ + +.. currentmodule:: numpy.ma + + +.. _numpy.ma.constants: + +Constants of the :mod:`numpy.ma` module +======================================= + +In addition to the :class:`MaskedArray` class, the :mod:`numpy.ma` module +defines several constants. + +.. data:: masked + + The :attr:`masked` constant is a special case of :class:`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 = ma.array([1, 2, 3], mask=[0, 1, 0]) + >>> x[1] is ma.masked + True + >>> x[-1] = ma.masked + >>> x + masked_array(data = [1 -- --], + mask = [False True True], + fill_value = 999999) + + +.. data:: nomask + + Value indicating that a masked array has no invalid entry. + :attr:`nomask` is used internally to speed up computations when the mask + is not needed. + + +.. data:: masked_print_options + + String used in lieu of missing data when a masked array is printed. + By default, this string is ``'--'``. + + + + +.. _maskedarray.baseclass: + +The :class:`MaskedArray` class +============================== + + An instance of :class:`MaskedArray` can be thought as the combination of several elements: + +* The :attr:`data`, as a regular :class:`numpy.ndarray` of any shape or datatype (the data). +* A boolean :attr:`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 :attr:`nomask` is also acceptable for arrays without named fields, and indicates that no data is invalid. +* A :attr:`fill_value`, a value that may be used to replace the invalid entries in order to return a standard :class:`numpy.ndarray`. + + + +Attributes and properties of masked arrays +------------------------------------------ + +.. seealso:: :ref:`Array Attributes <arrays.ndarray.attributes>` + + +.. attribute:: MaskedArray.data + + Returns the underlying data, as a view of the masked array. + If the underlying data is a subclass of :class:`numpy.ndarray`, it is + returned as such. + + >>> x = 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 :attr:`baseclass` + attribute. + +.. attribute:: MaskedArray.mask + + Returns the underlying mask, as an array with the same shape and structure + as the data, but where all fields are booleans. + A value of ``True`` indicates an invalid entry. + + +.. attribute:: MaskedArray.recordmask + + Returns 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 = 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], dtype=bool) + + +.. attribute:: MaskedArray.fill_value + + Returns the value used to fill the invalid entries of a masked array. + The value is either a scalar (if the masked array has no named fields), + or a 0d-ndarray with the same datatype as the masked array if it has + named fields. + + The default filling value depends on the datatype of the array: + + ======== ======== + datatype default + ======== ======== + bool True + int 999999 + float 1.e20 + complex 1.e20+0j + object '?' + string 'N/A' + ======== ======== + + + +.. attribute:: MaskedArray.baseclass + + Returns the class of the underlying data.:: + + >>> x = ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 0], [1, 0]]) + >>> x.baseclass + <class 'numpy.core.defmatrix.matrix'> + + +.. attribute:: MaskedArray.sharedmask + + Returns whether the mask of the array is shared between several arrays. + If this is the case, any modification to the mask of one array will be + propagated to the other masked arrays. + + +.. attribute:: MaskedArray.hardmask + + Returns whether the mask is hard (``True``) or soft (``False``). + When the mask is hard, masked entries cannot be unmasked. + + +As :class:`MaskedArray` is a subclass of :class:`~numpy.ndarray`, a masked array also inherits all the attributes and properties of a :class:`~numpy.ndarray` instance. + +.. autosummary:: + :toctree: generated/ + + MaskedArray.flags + MaskedArray.shape + MaskedArray.strides + MaskedArray.ndim + MaskedArray.size + MaskedArray.itemsize + MaskedArray.nbytes + MaskedArray.base + MaskedArray.dtype + MaskedArray.T + MaskedArray.real + MaskedArray.imag + MaskedArray.flat + MaskedArray.ctypes + MaskedArray.__array_priority__ + + + +:class:`MaskedArray` methods +============================ + +.. seealso:: :ref:`Array methods <array.ndarray.methods>` + + +Conversion +---------- + +.. autosummary:: + :toctree: generated/ + + MaskedArray.view + MaskedArray.astype + MaskedArray.filled + MaskedArray.tofile + MaskedArray.toflex + MaskedArray.tolist + MaskedArray.torecords + MaskedArray.tostring + + +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. + +.. autosummary:: + :toctree: generated/ + + MaskedArray.flatten + MaskedArray.ravel + MaskedArray.reshape + MaskedArray.resize + MaskedArray.squeeze + MaskedArray.swapaxes + MaskedArray.transpose + + +Item selection and manipulation +------------------------------- + +For array methods that take an *axis* keyword, it defaults to +:const:`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. + +.. autosummary:: + :toctree: generated/ + + MaskedArray.argsort + MaskedArray.choose + MaskedArray.compress + MaskedArray.diagonal + MaskedArray.nonzero + MaskedArray.put + MaskedArray.repeat + MaskedArray.searchsorted + MaskedArray.sort + MaskedArray.take + + +Calculations +------------ + +.. autosummary:: + :toctree: generated/ + + MaskedArray.all + MaskedArray.anom + MaskedArray.any + MaskedArray.argmax + MaskedArray.argmin + MaskedArray.clip + MaskedArray.conj + MaskedArray.cumprod + MaskedArray.cumsum + MaskedArray.mean + MaskedArray.min + MaskedArray.prod + MaskedArray.ptp + MaskedArray.round + MaskedArray.std + MaskedArray.sum + MaskedArray.trace + MaskedArray.var + + +Arithmetic and comparison operations +------------------------------------ + +.. index:: comparison, arithmetic, operation, operator + +Comparison operators: +~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__lt__ + MaskedArray.__le__ + MaskedArray.__gt__ + MaskedArray.__ge__ + MaskedArray.__eq__ + MaskedArray.__ne__ + +Truth value of an array (:func:`bool()`): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__nonzero__ + + +Arithmetic: +~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__add__ + MaskedArray.__sub__ + MaskedArray.__mul__ + MaskedArray.__div__ + MaskedArray.__truediv__ + MaskedArray.__floordiv__ + MaskedArray.__mod__ + MaskedArray.__divmod__ + MaskedArray.__pow__ + MaskedArray.__lshift__ + MaskedArray.__rshift__ + MaskedArray.__and__ + MaskedArray.__or__ + MaskedArray.__xor__ + + +Arithmetic, in-place: +~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__iadd__ + MaskedArray.__isub__ + MaskedArray.__imul__ + MaskedArray.__idiv__ + MaskedArray.__itruediv__ + MaskedArray.__ifloordiv__ + MaskedArray.__imod__ + MaskedArray.__ipow__ + MaskedArray.__ilshift__ + MaskedArray.__irshift__ + MaskedArray.__iand__ + MaskedArray.__ior__ + MaskedArray.__ixor__ + + + +Special methods +--------------- + +For standard library functions: + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__copy__ + MaskedArray.__deepcopy__ + MaskedArray.__reduce__ + MaskedArray.__setstate__ + +Basic customization: + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__new__ + MaskedArray.__array__ + MaskedArray.__array_wrap__ + +Container customization: (see :ref:`Indexing <arrays.indexing>`) + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__len__ + MaskedArray.__getitem__ + MaskedArray.__setitem__ + MaskedArray.__getslice__ + MaskedArray.__setslice__ + MaskedArray.__contains__ + + + +Specific methods +---------------- + +Handling the mask +~~~~~~~~~~~~~~~~~ + +The following methods can be used to access information about the mask or to +manipulate the mask. + +.. autosummary:: + :toctree: generated/ + + MaskedArray.harden_mask + MaskedArray.soften_mask + MaskedArray.unshare_mask + MaskedArray.shrink_mask + + +Handling the `fill_value` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + + MaskedArray.get_fill_value + MaskedArray.set_fill_value + + +.. autosummary:: + :toctree: generated/ + + MaskedArray.compressed + MaskedArray.count + |