diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/reference/maskedarray.baseclass.rst | 111 | ||||
| -rw-r--r-- | doc/source/reference/maskedarray.generic.rst | 46 | ||||
| -rw-r--r-- | doc/source/reference/routines.ma.rst | 3 |
3 files changed, 122 insertions, 38 deletions
diff --git a/doc/source/reference/maskedarray.baseclass.rst b/doc/source/reference/maskedarray.baseclass.rst index bef16b100..66418541f 100644 --- a/doc/source/reference/maskedarray.baseclass.rst +++ b/doc/source/reference/maskedarray.baseclass.rst @@ -47,12 +47,19 @@ defines several constants. The :class:`MaskedArray` class ============================== + +.. class:: MaskedArray + + A subclass of :class:`~numpy.ndarray` designed to manipulate numerical array with missing data. + + + 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`. +* The :attr:`~MaskedArray.data`, as a regular :class:`numpy.ndarray` of any shape or datatype (the data). +* A boolean :attr:`~numpy.ma.MaskedArray.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 :const:`nomask` is also acceptable for arrays without named fields, and indicates that no data is invalid. +* A :attr:`~numpy.ma.MaskedArray.fill_value`, a value that may be used to replace the invalid entries in order to return a standard :class:`numpy.ndarray`. @@ -79,7 +86,7 @@ Attributes and properties of masked arrays .. 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. + as the data, but where all fields are atomically booleans. A value of ``True`` indicates an invalid entry. @@ -100,7 +107,7 @@ Attributes and properties of masked arrays 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 + or a 0d-ndarray with the same :attr:`dtype` as the masked array if it has named fields. The default filling value depends on the datatype of the array: @@ -120,7 +127,7 @@ Attributes and properties of masked arrays .. attribute:: MaskedArray.baseclass - Returns the class of the underlying data.:: + Returns the class of the underlying data. >>> x = ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 0], [1, 0]]) >>> x.baseclass @@ -129,9 +136,9 @@ Attributes and properties of masked arrays .. attribute:: MaskedArray.sharedmask - Returns whether the mask of the array is shared between several arrays. + Returns whether the mask of the array is shared between several masked arrays. If this is the case, any modification to the mask of one array will be - propagated to the other masked arrays. + propagated to the others. .. attribute:: MaskedArray.hardmask @@ -145,20 +152,22 @@ As :class:`MaskedArray` is a subclass of :class:`~numpy.ndarray`, a masked array .. autosummary:: :toctree: generated/ + MaskedArray.base + MaskedArray.ctypes + MaskedArray.dtype MaskedArray.flags - MaskedArray.shape - MaskedArray.strides - MaskedArray.ndim - MaskedArray.size + MaskedArray.itemsize MaskedArray.nbytes - MaskedArray.base - MaskedArray.dtype - MaskedArray.T - MaskedArray.real + MaskedArray.ndim + MaskedArray.shape + MaskedArray.size + MaskedArray.strides + MaskedArray.imag + MaskedArray.real + MaskedArray.flat - MaskedArray.ctypes MaskedArray.__array_priority__ @@ -175,8 +184,17 @@ Conversion .. autosummary:: :toctree: generated/ + MaskedArray.__float__ + MaskedArray.__hex__ + MaskedArray.__int__ + MaskedArray.__long__ + MaskedArray.__oct__ + MaskedArray.view MaskedArray.astype + MaskedArray.byteswap + + MaskedArray.compressed MaskedArray.filled MaskedArray.tofile MaskedArray.toflex @@ -201,6 +219,7 @@ replaced with ``n`` integers which will be interpreted as an n-tuple. MaskedArray.squeeze MaskedArray.swapaxes MaskedArray.transpose + MaskedArray.T Item selection and manipulation @@ -214,10 +233,14 @@ the operation should proceed. .. autosummary:: :toctree: generated/ + MaskedArray.argmax + MaskedArray.argmin MaskedArray.argsort MaskedArray.choose MaskedArray.compress MaskedArray.diagonal + MaskedArray.fill + MaskedArray.item MaskedArray.nonzero MaskedArray.put MaskedArray.repeat @@ -226,6 +249,17 @@ the operation should proceed. MaskedArray.take +Pickling and copy +----------------- + +.. autosummary:: + :toctree: generated/ + + MaskedArray.copy + MaskedArray.dump + MaskedArray.dumps + + Calculations ------------ @@ -235,15 +269,16 @@ Calculations MaskedArray.all MaskedArray.anom MaskedArray.any - MaskedArray.argmax - MaskedArray.argmin MaskedArray.clip MaskedArray.conj + MaskedArray.conjugate MaskedArray.cumprod MaskedArray.cumsum + MaskedArray.max MaskedArray.mean MaskedArray.min MaskedArray.prod + MaskedArray.product MaskedArray.ptp MaskedArray.round MaskedArray.std @@ -285,20 +320,35 @@ Arithmetic: .. autosummary:: :toctree: generated/ + MaskedArray.__abs__ MaskedArray.__add__ + MaskedArray.__radd__ MaskedArray.__sub__ + MaskedArray.__rsub__ MaskedArray.__mul__ + MaskedArray.__rmul__ MaskedArray.__div__ + MaskedArray.__rdiv__ MaskedArray.__truediv__ + MaskedArray.__rtruediv__ MaskedArray.__floordiv__ + MaskedArray.__rfloordiv__ MaskedArray.__mod__ + MaskedArray.__rmod__ MaskedArray.__divmod__ + MaskedArray.__rdivmod__ MaskedArray.__pow__ + MaskedArray.__rpow__ MaskedArray.__lshift__ + MaskedArray.__rlshift__ MaskedArray.__rshift__ + MaskedArray.__rrshift__ MaskedArray.__and__ + MaskedArray.__rand__ MaskedArray.__or__ + MaskedArray.__ror__ MaskedArray.__xor__ + MaskedArray.__rxor__ Arithmetic, in-place: @@ -322,6 +372,18 @@ Arithmetic, in-place: MaskedArray.__ixor__ +Representation +-------------- + +.. autosummary:: + :toctree: generated/ + + MaskedArray.__repr__ + MaskedArray.__str__ + + MaskedArray.ids + MaskedArray.iscontiguous + Special methods --------------- @@ -333,6 +395,7 @@ For standard library functions: MaskedArray.__copy__ MaskedArray.__deepcopy__ + MaskedArray.__getstate__ MaskedArray.__reduce__ MaskedArray.__setstate__ @@ -353,6 +416,7 @@ Container customization: (see :ref:`Indexing <arrays.indexing>`) MaskedArray.__len__ MaskedArray.__getitem__ MaskedArray.__setitem__ + MaskedArray.__delitem__ MaskedArray.__getslice__ MaskedArray.__setslice__ MaskedArray.__contains__ @@ -371,6 +435,8 @@ manipulate the mask. .. autosummary:: :toctree: generated/ + MaskedArray.__setmask__ + MaskedArray.harden_mask MaskedArray.soften_mask MaskedArray.unshare_mask @@ -387,9 +453,12 @@ Handling the `fill_value` MaskedArray.set_fill_value + +Counting the missing elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. autosummary:: :toctree: generated/ - MaskedArray.compressed MaskedArray.count diff --git a/doc/source/reference/maskedarray.generic.rst b/doc/source/reference/maskedarray.generic.rst index ba6b97deb..70d94bdad 100644 --- a/doc/source/reference/maskedarray.generic.rst +++ b/doc/source/reference/maskedarray.generic.rst @@ -47,7 +47,7 @@ The :mod:`numpy.ma` module -------------------------- -The main feature of the :mod:`numpy.ma` module is the :class:`~numpy.ma.MaskedArray` class, which is a subclass of :class:`numpy.ndarray`. +The main feature of the :mod:`numpy.ma` module is the :class:`MaskedArray` class, which is a subclass of :class:`numpy.ndarray`. The class, its attributes and methods are described in more details in the :ref:`MaskedArray class <maskedarray.baseclass>` section. @@ -95,13 +95,19 @@ There are several ways to construct a masked array. * A third option is to take the view of an existing array. In that case, the mask of the view is set to :attr:`nomask` if the array has no named fields, - or an array of boolean with the same structure as the array otherwise.:: + or an array of boolean with the same structure as the array otherwise. >>> x = np.array([1, 2, 3]) >>> x.view(ma.MaskedArray) masked_array(data = [1 2 3], mask = False, fill_value = 999999) + >>> x = np.array([(1, 1.), (2, 2.)], dtype=[('a',int), ('b', float)]) + >>> x.view(ma.MaskedArray) + masked_array(data = [(1, 1.0) (2, 2.0)], + mask = [(False, False) (False, False)], + fill_value = (999999, 1e+20), + dtype = [('a', '<i4'), ('b', '<f8')]) * Yet another possibility is to use any of the following functions: @@ -131,13 +137,13 @@ Accessing the data The underlying data of a masked array can be accessed through several ways: -* through the :attr:`data` attribute. The output is a view of the array as +* through the :attr:`~MaskedArray.data` attribute. The output is a view of the array as a :class:`numpy.ndarray` or one of its subclasses, depending on the type of the underlying data at the masked array creation. * through the :meth:`~MaskedArray.__array__` method. The output is then a :class:`numpy.ndarray`. -* by directly taking a view of the masked array as a :class:`numpy.ndarray` or one of its subclass (which is actually what using the :attr:`data` attribute does). +* by directly taking a view of the masked array as a :class:`numpy.ndarray` or one of its subclass (which is actually what using the :attr:`~MaskedArray.data` attribute does). * by using the :func:`getdata` function. @@ -150,7 +156,7 @@ If a representation of the array is needed without any masked entries, it is rec Accessing the mask ------------------ -The mask of a masked array is accessible through its :attr:`mask` attribute. +The mask of a masked array is accessible through its :attr:`~MaskedArray.mask` attribute. We must keep in mind that a ``True`` entry in the mask indicates an *invalid* data. Another possibility is to use the :func:`getmask` and :func:`getmaskarray` functions. :func:`getmask(x)` outputs the mask of ``x`` if ``x`` is a masked array, and the special value :data:`nomask` otherwise. @@ -171,11 +177,15 @@ To retrieve only the valid entries, we can use the inverse of the mask as an ind mask = [False False], fill_value = 999999) -Another way to retrieve the valid data is to use the :meth:`compressed` method, which returns a one-dimensional :class:`~numpy.ndarray` (or one of its subclasses, depending on the value of the :attr:`baseclass` attribute):: +Another way to retrieve the valid data is to use the :meth:`compressed` method, +which returns a one-dimensional :class:`~numpy.ndarray` (or one of its subclasses, +depending on the value of the :attr:`~MaskedArray.baseclass` attribute):: - >>> x.compressed + >>> x.compressed() array([1, 4]) +Note that the output of :meth:`compressed` is always 1D. + Modifying the mask @@ -212,7 +222,8 @@ The recommended way to mark one or several specific entries of a masked array as fill_value = 999999) -A second possibility is to modify the mask directly, but this usage is discouraged. +A second possibility is to modify the :attr:`~MaskedArray.mask` directly, +but this usage is discouraged. .. note:: When creating a new masked array with a simple, non-structured datatype, the mask is initially set to the special value :attr:`nomask`, that corresponds roughly to the boolean ``False``. Trying to set an element of :attr:`nomask` will fail with a :exc:`TypeError` exception, as a boolean does not support item assignment. @@ -254,7 +265,7 @@ To unmask one or several specific entries, we can just assign one or several new .. note:: Unmasking an entry by direct assignment will not work if the masked array - has a *hard* mask, as shown by the :attr:`hardmask`. + has a *hard* mask, as shown by the :attr:`~MaskedArray.hardmask` attribute. This feature was introduced to prevent the overwriting of the mask. To force the unmasking of an entry in such circumstance, the mask has first to be softened with the :meth:`soften_mask` method before the allocation, @@ -326,7 +337,7 @@ If the masked array has named fields, accessing a single entry returns a dtype = [('a', '<i4'), ('b', '<i4')]) -When accessing a slice, the output is a masked array whose :attr:`data` attribute is a view of the original data, and whose mask is either :attr:`nomask` (if there was no invalid entries in the original array) or a copy of the corresponding slice of the original mask. The copy is required to avoid propagation of any modification of the mask to the original. +When accessing a slice, the output is a masked array whose :attr:`~MaskedArray.data` attribute is a view of the original data, and whose mask is either :attr:`nomask` (if there was no invalid entries in the original array) or a copy of the corresponding slice of the original mask. The copy is required to avoid propagation of any modification of the mask to the original. >>> x = ma.array([1, 2, 3, 4, 5], mask=[0, 1, 0, 0, 1]) >>> mx = x[:3] @@ -353,11 +364,18 @@ Operations on masked arrays --------------------------- Arithmetic and comparison operations are supported by masked arrays. -As much as possible, invalid entries of a masked array are not processed, meaning that the corresponding :attr:`data` entries *should* be the same before and after the operation. -We need to stress that this behavior may not be systematic, that invalid data may actually be affected by the operation in some cases and once again that invalid data should not be relied on. +As much as possible, invalid entries of a masked array are not processed, +meaning that the corresponding :attr:`~MaskedArray.data` entries *should* be +the same before and after the operation. + +.. warning:: + We need to stress that this behavior may not be systematic, that invalid + data may actually be affected by the operation in some cases and once again + that invalid data should not be relied on. The :mod:`numpy.ma` module comes with a specific implementation of most -ufuncs. Unary and binary functions that have a validity domain (such as :func:`~numpy.log` or :func:`~numpy.divide`) return the :data:`masked` constant whenever the input is masked or falls outside the validity domain:: +ufuncs. +Unary and binary functions that have a validity domain (such as :func:`~numpy.log` or :func:`~numpy.divide`) return the :data:`masked` constant whenever the input is masked or falls outside the validity domain:: >>> ma.log([-1, 0, 1, 2]) masked_array(data = [-- -- 0.0 0.69314718056], @@ -422,6 +440,6 @@ Ignoring extreme values ----------------------- Let's consider an array ``d`` of random floats between 0 and 1. -We wish to compute the average of the values of ``d`` while ignoring any data outside the range [0.1, 0.9]:: +We wish to compute the average of the values of ``d`` while ignoring any data outside the range ``[0.1, 0.9]``:: >>> print ma.masked_outside(d, 0.1, 0.9).mean() diff --git a/doc/source/reference/routines.ma.rst b/doc/source/reference/routines.ma.rst index ce3f14e42..e6173407b 100644 --- a/doc/source/reference/routines.ma.rst +++ b/doc/source/reference/routines.ma.rst @@ -12,9 +12,6 @@ Constants .. autosummary:: :toctree: generated/ - ma.masked - ma.nomask - ma.MaskType |