numpy.ma.core:

* introduced baseclass, sharedmask and hardmask as readonly properties of MaskedArray
* docstrings update

numpy.ma.extras:
* docstring updates

docs/reference
* introduced maskedarray, maskedarray.baseclass, maskedarray.generic

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
+