numpy.ma doc update

4 files changed, 125 insertions, 43 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
 
 
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
index 4364a2ce0..4efbac61e 100644
--- a/numpy/ma/core.py
+++ b/numpy/ma/core.py
@@ -419,8 +419,8 @@ get_data = getdata
 
 def fix_invalid(a, mask=nomask, copy=True, fill_value=None):
     """
-    Return (a copy of) a where invalid data (nan/inf) are masked
-    and replaced by fill_value.
+    Return (a copy of) `a` where invalid data (nan/inf) are masked
+    and replaced by `fill_value`.
 
     Note that a copy is performed by default (just in case...).
 
@@ -1265,9 +1265,7 @@ def masked_object(x, value, copy=True, shrink=True):
 def masked_values(x, value, rtol=1.e-5, atol=1.e-8, copy=True, shrink=True):
     """
     Mask the array x where the data are approximately equal in
-    value, i.e.
-
-    (abs(x - value) <= atol+rtol*abs(value))
+    value, i.e. ``(abs(x - value) <= atol+rtol*abs(value))``
 
     Suitable only for floating points. For integers, please use
     :func:`masked_equal`.  The mask is set to ``nomask`` if posible.