[Scipy-svn] r3390 - trunk/scipy/sandbox/maskedarray

scipy-svn@scip... scipy-svn@scip...
Tue Oct 2 20:46:32 CDT 2007


Author: pierregm
Date: 2007-10-02 20:46:24 -0500 (Tue, 02 Oct 2007)
New Revision: 3390

Modified:
   trunk/scipy/sandbox/maskedarray/core.py
   trunk/scipy/sandbox/maskedarray/extras.py
   trunk/scipy/sandbox/maskedarray/morestats.py
   trunk/scipy/sandbox/maskedarray/mrecords.py
   trunk/scipy/sandbox/maskedarray/mstats.py
   trunk/scipy/sandbox/maskedarray/testutils.py
Log:
Updated documentation.
core : the transpose/reshape/resize functions now return a MaskedArray instance systematically.

Modified: trunk/scipy/sandbox/maskedarray/core.py
===================================================================
--- trunk/scipy/sandbox/maskedarray/core.py	2007-10-03 00:06:40 UTC (rev 3389)
+++ trunk/scipy/sandbox/maskedarray/core.py	2007-10-03 01:46:24 UTC (rev 3390)
@@ -21,6 +21,8 @@
 __revision__ = "$Revision$"
 __date__     = '$Date$'
 
+__docformat__ = "restructuredtext en" 
+
 __all__ = ['MAError', 'MaskType', 'MaskedArray',
            'bool_', 'complex_', 'float_', 'int_', 'object_',
            'abs', 'absolute', 'add', 'all', 'allclose', 'allequal', 'alltrue',
@@ -119,7 +121,8 @@
     min_filler.update([(numpy.float128, numpy.inf)])
 
 def default_fill_value(obj):
-    "Calculates the default fill value for an object `obj`."
+    """Calculates the default fill value for the argument object.
+    """
     if hasattr(obj,'dtype'):
         defval = default_filler[obj.dtype.kind]
     elif isinstance(obj, numeric.dtype):
@@ -137,7 +140,7 @@
     return defval
 
 def minimum_fill_value(obj):
-    "Calculates the default fill value suitable for taking the minimum of `obj`."
+    "Calculates the default fill value suitable for taking the minimum of ``obj``."
     if hasattr(obj, 'dtype'):
         objtype = obj.dtype
         filler = min_filler[objtype]
@@ -156,7 +159,7 @@
         raise TypeError, 'Unsuitable type for calculating minimum.'
 
 def maximum_fill_value(obj):
-    "Calculates the default fill value suitable for taking the maximum of `obj`."
+    "Calculates the default fill value suitable for taking the maximum of ``obj``."
     if hasattr(obj, 'dtype'):
         objtype = obj.dtype
         filler = max_filler[objtype]
@@ -175,13 +178,19 @@
         raise TypeError, 'Unsuitable type for calculating minimum.'
 
 def set_fill_value(a, fill_value):
-    "Sets the fill value of `a` if it is a masked array."
+    """Sets the filling value of a, if a is a masked array.
+Otherwise, does nothing.
+    
+*Returns*:
+    None
+    """
     if isinstance(a, MaskedArray):
         a.set_fill_value(fill_value)
+    return
 
 def get_fill_value(a):
-    """Returns the fill value of `a`, if any.
-    Otherwise, returns the default fill value for that type.
+    """Returns the filling value of a, if any.
+Otherwise, returns the default filling value for that type.
     """
     if isinstance(a, MaskedArray):
         result = a.fill_value
@@ -190,7 +199,8 @@
     return result
 
 def common_fill_value(a, b):
-    "Returns the common fill_value of `a` and `b`, if any, or `None`."
+    """Returns the common filling value of a and b, if any.
+    If a and b have different filling values, returns None."""
     t1 = get_fill_value(a)
     t2 = get_fill_value(b)
     if t1 == t2:
@@ -201,8 +211,17 @@
 def filled(a, value = None):
     """Returns a as an array with masked data replaced by value.
 If value is None, get_fill_value(a) is used instead.
+If a is already a ndarray, a itself is returned.
 
-If a is already a ndarray, a itself is returned.
+*Parameters*:
+    a : {var}
+        An input object.
+    value : {var}, optional
+        Filling value. If not given, the output of get_fill_value(a) is used instead.
+        
+*Returns*:
+    A ndarray.
+
     """
     if hasattr(a, 'filled'):
         return a.filled(value)
@@ -215,8 +234,8 @@
 
 #####--------------------------------------------------------------------------
 def get_masked_subclass(*arrays):
-    """Returns the youngest subclass of MaskedArray from a list of arrays,
- or MaskedArray. In case of siblings, the first takes over."""
+    """Returns the youngest subclass of MaskedArray from a list of (masked) arrays. 
+In case of siblings, the first takes over."""
     if len(arrays) == 1:
         arr = arrays[0]
         if isinstance(arr, MaskedArray):
@@ -237,11 +256,11 @@
 def get_data(a, subok=True):
     """Returns the _data part of a (if any), or a as a ndarray.
     
-:Parameters:
-    a : ndarray
+*Parameters* :
+    a : {ndarray}
         A ndarray or a subclass of.
-    subok : boolean *[True]*
-        Whether to force a to a 'pure' ndarray (False) or to return a subclass
+    subok : {boolean}
+        Whether to force the output to a 'pure' ndarray (False) or to return a subclass
         of ndarray if approriate (True). 
     """
     data = getattr(a, '_data', numpy.array(a, subok=subok))
@@ -252,17 +271,19 @@
 
 def fix_invalid(a, copy=False, fill_value=None):
     """Returns (a copy of) a where invalid data (nan/inf) are masked and replaced
-    by fill_value.
-    If fill_value is None, a.fill_value is used instead.
+by fill_value.
     
-:Parameters:
-    a : ndarray
-        A ndarray or a subclass of.
-    copy : boolean *[False]*
+*Parameters*:
+    a : {ndarray}
+        A (subclass of) ndarray.
+    copy : {boolean}
         Whether to use a copy of a (True) or to fix a in place (False).
-    fill_value : var *[None]*
-        Value used for fixing invalid data. If None, use a default based on the
-        datatype.
+    fill_value : {var}, optional
+        Value used for fixing invalid data. 
+        If not given, the output of get_fill_value(a) is used instead.
+        
+*Returns* :
+    MaskedArray object
     """
     a = masked_array(a, copy=copy, subok=True)
     invalid = (numpy.isnan(a._data) | numpy.isinf(a._data))
@@ -280,9 +301,9 @@
 ufunc_domain = {}
 ufunc_fills = {}
 
-class domain_check_interval:
-    """Defines a valid interval,
-so that `domain_check_interval(a,b)(x) = true` where `x < a` or `x > b`."""
+class _DomainCheckInterval:
+    """Defines a valid interval, so that :
+``domain_check_interval(a,b)(x) = true`` where ``x < a`` or ``x > b``."""
     def __init__(self, a, b):
         "domain_check_interval(a,b)(x) = true where x < a or y > b"
         if (a > b):
@@ -295,9 +316,9 @@
         return umath.logical_or(umath.greater (x, self.b),
                                 umath.less(x, self.a))
 #............................
-class domain_tan:
-    """Defines a valid interval for the `tan` function,
-so that `domain_tan(eps) = True where `abs(cos(x)) < eps`"""
+class _DomainTan:
+    """Defines a valid interval for the `tan` function, so that:
+``domain_tan(eps) = True`` where ``abs(cos(x)) < eps``"""
     def __init__(self, eps):
         "domain_tan(eps) = true where abs(cos(x)) < eps)"
         self.eps = eps
@@ -305,27 +326,27 @@
         "Executes the call behavior."
         return umath.less(umath.absolute(umath.cos(x)), self.eps)
 #............................
-class domain_safe_divide:
+class _DomainSafeDivide:
     """Defines a domain for safe division."""
     def __init__ (self, tolerance=divide_tolerance):
         self.tolerance = tolerance
     def __call__ (self, a, b):
         return umath.absolute(a) * self.tolerance >= umath.absolute(b)
 #............................
-class domain_greater:
-    "domain_greater(v)(x) = true where x <= v"
+class _DomainGreater:
+    "DomainGreater(v)(x) = true where x <= v"
     def __init__(self, critical_value):
-        "domain_greater(v)(x) = true where x <= v"
+        "DomainGreater(v)(x) = true where x <= v"
         self.critical_value = critical_value
 
     def __call__ (self, x):
         "Executes the call behavior."
         return umath.less_equal(x, self.critical_value)
 #............................
-class domain_greater_equal:
-    "domain_greater_equal(v)(x) = true where x < v"
+class _DomainGreaterEqual:
+    "DomainGreaterEqual(v)(x) = true where x < v"
     def __init__(self, critical_value):
-        "domain_greater_equal(v)(x) = true where x < v"
+        "DomainGreaterEqual(v)(x) = true where x < v"
         self.critical_value = critical_value
 
     def __call__ (self, x):
@@ -333,9 +354,8 @@
         return umath.less(x, self.critical_value)
     
 #..............................................................................
-class masked_unary_operation:
-    """Defines masked version of unary operations,
-where invalid values are pre-masked.
+class _MaskedUnaryOperation:
+    """Defines masked version of unary operations, where invalid values are pre-masked.
 
 :IVariables:
     f : function.
@@ -343,7 +363,7 @@
     domain : Default domain *[None]*.
     """
     def __init__ (self, mufunc, fill=0, domain=None):
-        """ masked_unary_operation(aufunc, fill=0, domain=None)
+        """ _MaskedUnaryOperation(aufunc, fill=0, domain=None)
             aufunc(fill) must be defined
             self(x) returns aufunc(x)
             with masked values where domain(x) is true or getmask(x) is true.
@@ -384,7 +404,7 @@
         return "Masked version of %s. [Invalid values are masked]" % str(self.f)
     
 #..............................................................................
-class masked_binary_operation:
+class _MaskedBinaryOperation:
     """Defines masked version of binary operations,
 where invalid values are pre-masked.
 
@@ -478,10 +498,9 @@
         return "Masked version of " + str(self.f)
     
 #..............................................................................
-class domained_binary_operation:
+class _DomainedBinaryOperation:
     """Defines binary operations that have a domain, like divide.
 
-These are complicated so they are a separate class.
 They have no reduce, outer or accumulate.
 
 :IVariables:
@@ -528,70 +547,75 @@
 
 #..............................................................................
 # Unary ufuncs
-exp = masked_unary_operation(umath.exp)
-conjugate = masked_unary_operation(umath.conjugate)
-sin = masked_unary_operation(umath.sin)
-cos = masked_unary_operation(umath.cos)
-tan = masked_unary_operation(umath.tan)
-arctan = masked_unary_operation(umath.arctan)
-arcsinh = masked_unary_operation(umath.arcsinh)
-sinh = masked_unary_operation(umath.sinh)
-cosh = masked_unary_operation(umath.cosh)
-tanh = masked_unary_operation(umath.tanh)
-abs = absolute = masked_unary_operation(umath.absolute)
-fabs = masked_unary_operation(umath.fabs)
-negative = masked_unary_operation(umath.negative)
-floor = masked_unary_operation(umath.floor)
-ceil = masked_unary_operation(umath.ceil)
-around = masked_unary_operation(fromnumeric.round_)
-logical_not = masked_unary_operation(umath.logical_not)
+exp = _MaskedUnaryOperation(umath.exp)
+conjugate = _MaskedUnaryOperation(umath.conjugate)
+sin = _MaskedUnaryOperation(umath.sin)
+cos = _MaskedUnaryOperation(umath.cos)
+tan = _MaskedUnaryOperation(umath.tan)
+arctan = _MaskedUnaryOperation(umath.arctan)
+arcsinh = _MaskedUnaryOperation(umath.arcsinh)
+sinh = _MaskedUnaryOperation(umath.sinh)
+cosh = _MaskedUnaryOperation(umath.cosh)
+tanh = _MaskedUnaryOperation(umath.tanh)
+abs = absolute = _MaskedUnaryOperation(umath.absolute)
+fabs = _MaskedUnaryOperation(umath.fabs)
+negative = _MaskedUnaryOperation(umath.negative)
+floor = _MaskedUnaryOperation(umath.floor)
+ceil = _MaskedUnaryOperation(umath.ceil)
+around = _MaskedUnaryOperation(fromnumeric.round_)
+logical_not = _MaskedUnaryOperation(umath.logical_not)
 # Domained unary ufuncs .......................................................
-sqrt = masked_unary_operation(umath.sqrt, 0.0, domain_greater_equal(0.0))
-log = masked_unary_operation(umath.log, 1.0, domain_greater(0.0))
-log10 = masked_unary_operation(umath.log10, 1.0, domain_greater(0.0))
-tan = masked_unary_operation(umath.tan, 0.0, domain_tan(1.e-35))
-arcsin = masked_unary_operation(umath.arcsin, 0.0,
-                                domain_check_interval(-1.0, 1.0))
-arccos = masked_unary_operation(umath.arccos, 0.0,
-                                domain_check_interval(-1.0, 1.0))
-arccosh = masked_unary_operation(umath.arccosh, 1.0, domain_greater_equal(1.0))
-arctanh = masked_unary_operation(umath.arctanh, 0.0,
-                                 domain_check_interval(-1.0+1e-15, 1.0-1e-15))
+sqrt = _MaskedUnaryOperation(umath.sqrt, 0.0, 
+                             _DomainGreaterEqual(0.0))
+log = _MaskedUnaryOperation(umath.log, 1.0, 
+                            _DomainGreater(0.0))
+log10 = _MaskedUnaryOperation(umath.log10, 1.0, 
+                              _DomainGreater(0.0))
+tan = _MaskedUnaryOperation(umath.tan, 0.0, 
+                            _DomainTan(1.e-35))
+arcsin = _MaskedUnaryOperation(umath.arcsin, 0.0,
+                               _DomainCheckInterval(-1.0, 1.0))
+arccos = _MaskedUnaryOperation(umath.arccos, 0.0,
+                               _DomainCheckInterval(-1.0, 1.0))
+arccosh = _MaskedUnaryOperation(umath.arccosh, 1.0, 
+                                _DomainGreaterEqual(1.0))
+arctanh = _MaskedUnaryOperation(umath.arctanh, 0.0,
+                                _DomainCheckInterval(-1.0+1e-15, 1.0-1e-15))
 # Binary ufuncs ...............................................................
-add = masked_binary_operation(umath.add)
-subtract = masked_binary_operation(umath.subtract)
-multiply = masked_binary_operation(umath.multiply, 1, 1)
-arctan2 = masked_binary_operation(umath.arctan2, 0.0, 1.0)
-equal = masked_binary_operation(umath.equal)
+add = _MaskedBinaryOperation(umath.add)
+subtract = _MaskedBinaryOperation(umath.subtract)
+multiply = _MaskedBinaryOperation(umath.multiply, 1, 1)
+arctan2 = _MaskedBinaryOperation(umath.arctan2, 0.0, 1.0)
+equal = _MaskedBinaryOperation(umath.equal)
 equal.reduce = None
-not_equal = masked_binary_operation(umath.not_equal)
+not_equal = _MaskedBinaryOperation(umath.not_equal)
 not_equal.reduce = None
-less_equal = masked_binary_operation(umath.less_equal)
+less_equal = _MaskedBinaryOperation(umath.less_equal)
 less_equal.reduce = None
-greater_equal = masked_binary_operation(umath.greater_equal)
+greater_equal = _MaskedBinaryOperation(umath.greater_equal)
 greater_equal.reduce = None
-less = masked_binary_operation(umath.less)
+less = _MaskedBinaryOperation(umath.less)
 less.reduce = None
-greater = masked_binary_operation(umath.greater)
+greater = _MaskedBinaryOperation(umath.greater)
 greater.reduce = None
-logical_and = masked_binary_operation(umath.logical_and)
-alltrue = masked_binary_operation(umath.logical_and, 1, 1).reduce
-logical_or = masked_binary_operation(umath.logical_or)
+logical_and = _MaskedBinaryOperation(umath.logical_and)
+alltrue = _MaskedBinaryOperation(umath.logical_and, 1, 1).reduce
+logical_or = _MaskedBinaryOperation(umath.logical_or)
 sometrue = logical_or.reduce
-logical_xor = masked_binary_operation(umath.logical_xor)
-bitwise_and = masked_binary_operation(umath.bitwise_and)
-bitwise_or = masked_binary_operation(umath.bitwise_or)
-bitwise_xor = masked_binary_operation(umath.bitwise_xor)
-hypot = masked_binary_operation(umath.hypot)
+logical_xor = _MaskedBinaryOperation(umath.logical_xor)
+bitwise_and = _MaskedBinaryOperation(umath.bitwise_and)
+bitwise_or = _MaskedBinaryOperation(umath.bitwise_or)
+bitwise_xor = _MaskedBinaryOperation(umath.bitwise_xor)
+hypot = _MaskedBinaryOperation(umath.hypot)
 # Domained binary ufuncs ......................................................
-divide = domained_binary_operation(umath.divide, domain_safe_divide(), 0, 1)
-true_divide = domained_binary_operation(umath.true_divide,
-                                        domain_safe_divide(), 0, 1)
-floor_divide = domained_binary_operation(umath.floor_divide,
-                                         domain_safe_divide(), 0, 1)
-remainder = domained_binary_operation(umath.remainder,
-                                      domain_safe_divide(), 0, 1)
-fmod = domained_binary_operation(umath.fmod, domain_safe_divide(), 0, 1)
+divide = _DomainedBinaryOperation(umath.divide, _DomainSafeDivide(), 0, 1)
+true_divide = _DomainedBinaryOperation(umath.true_divide,
+                                        _DomainSafeDivide(), 0, 1)
+floor_divide = _DomainedBinaryOperation(umath.floor_divide,
+                                         _DomainSafeDivide(), 0, 1)
+remainder = _DomainedBinaryOperation(umath.remainder,
+                                      _DomainSafeDivide(), 0, 1)
+fmod = _DomainedBinaryOperation(umath.fmod, _DomainSafeDivide(), 0, 1)
 
 
 #####--------------------------------------------------------------------------
@@ -599,12 +623,13 @@
 #####--------------------------------------------------------------------------
 def get_mask(a):
     """Returns the mask of a, if any, or nomask.
-To get a full array of booleans of the same shape as a, use getmaskarray."""
+To get a full array of booleans of the same shape as a, use getmaskarray.
+    """
     return getattr(a, '_mask', nomask)
 getmask = get_mask
 
 def getmaskarray(a):
-    """Returns the mask of a, if any, or an array of the shape of a, full of False.
+    """Returns the mask of a, if any, or a boolean array of the shape of a, full of False.
     """
     m = getmask(a)
     if m is nomask:
@@ -621,17 +646,16 @@
         return False
 #
 def make_mask(m, copy=False, shrink=True, flag=None):
-    """make_mask(m, copy=0, shrink=0)
-Returns m as a mask, creating a copy if necessary or requested.
+    """Returns m as a mask, creating a copy if necessary or requested.
 The function can accept any sequence of integers or nomask.
 Does not check that contents must be 0s and 1s.
 
-:Parameters:
-    m : ndarray
+*Parameters*:
+    m : {ndarray}
         Potential mask.
-    copy : boolean *[False]*
-        Whether to return a copy of m.
-    shrink : boolean *[True]*
+    copy : {boolean}
+        Whether to return a copy of m (True) or m itself (False).
+    shrink : {boolean}
         Whether to shrink m to nomask if all its values are False.
     """
     if flag is not None:
@@ -660,8 +684,8 @@
 def make_mask_none(s):
     """Returns a mask of shape s, filled with False.
     
-:Parameters:
-    s : tuple
+*Parameters*:
+    s : {tuple}
         A tuple indicating the shape of the final mask.
     """
     result = numeric.zeros(s, dtype=MaskType)
@@ -672,14 +696,14 @@
 The masks are combined with the *logical_or* operator, treating nomask as False.
 The result may equal m1 or m2 if the other is nomask.
 
-:Parameters:
-    m1 : ndarray
+*Parameters*:
+    m1 : {ndarray}
         First mask.
-    m2 : ndarray
+    m2 : {ndarray}
         Second mask
-    copy : boolean *[False]*
+    copy : {boolean}
         Whether to return a copy.
-    shrink : boolean *[True]*
+    shrink : {boolean}
         Whether to shrink m to nomask if all its values are False.
      """
     if m1 is nomask:
@@ -697,13 +721,13 @@
     """Returns a as an array masked where condition is true.
 Masked values of a or condition are kept.
 
-:Parameters:
-    condition : ndarray
+*Parameters*:
+    condition : {ndarray}
         Masking condition.
-    a : ndarray
+    a : {ndarray}
         Array to mask.
-    copy : boolean *[True]*
-        Whether to return a copy of a.
+    copy : {boolean}
+        Whether to return a copy of a (True) or modify a in place.
     """
     cond = filled(condition,1)
     a = narray(a, copy=copy, subok=True)
@@ -748,9 +772,12 @@
 #    return array(d, mask=m, copy=copy)
 
 def masked_inside(x, v1, v2, copy=True):
-    """Shortcut to masked_where, where condition is True for x inside
-the interval [v1,v2] (v1 <= x <= v2).
+    """Shortcut to masked_where, where condition is True for x inside the interval
+[v1,v2] (v1 <= x <= v2).
 The boundaries v1 and v2 can be given in either order.
+    
+*Note*: 
+    The array x is prefilled with its filling value.
     """
     if v2 < v1:
         (v1, v2) = (v2, v1)
@@ -759,9 +786,12 @@
     return masked_where(condition, x, copy=copy)
 
 def masked_outside(x, v1, v2, copy=True):
-    """Shortcut to masked_where, where condition is True for x outside
-the interval [v1,v2] (x < v1)|(x > v2).
+    """Shortcut to masked_where, where condition is True for x outside the interval
+[v1,v2] (x < v1)|(x > v2).
 The boundaries v1 and v2 can be given in either order.
+    
+*Note*: 
+    The array x is prefilled with its filling value.
     """
     if v2 < v1:
         (v1, v2) = (v2, v1)
@@ -772,9 +802,12 @@
 #
 def masked_object(x, value, copy=True):
     """Masks the array x where the data are exactly equal to value.
-This function is suitable only for object arrays: for floating point,
-please use masked_values instead.
-The mask is set to `nomask` if posible.
+    
+This function is suitable only for object arrays: for floating point, please use
+``masked_values`` instead.
+
+*Notes*:
+    The mask is set to `nomask` if posible.
     """
     if isMaskedArray(x):
         condition = umath.equal(x._data, value)
@@ -788,19 +821,19 @@
 def masked_values(x, value, rtol=1.e-5, atol=1.e-8, copy=True):
     """Masks the array x where the data are approximately equal to value
 (abs(x - value) <= atol+rtol*abs(value)).
-Suitable only for floating points. For integers, please use masked_equal.
+Suitable only for floating points. For integers, please use ``masked_equal``.
 The mask is set to nomask if posible.
 
-:Parameters:
-    x : ndarray
+*Parameters*:
+    x : {ndarray}
         Array to fill.
-    value : float
+    value : {float}
         Masking value.
-    rtol : float *[1e-5]*
+    rtol : {float}
         Tolerance parameter.
-    atol : float, *[1e-8]*
+    atol : {float}, *[1e-8]*
         Tolerance parameter.
-    copy : boolean *[True]*
+    copy : {boolean}
         Whether to return a copy of x.
     """
     abs = umath.absolute
@@ -870,16 +903,16 @@
 #...............................................................................
 class _arraymethod(object):
     """Defines a wrapper for basic array methods.
-Upon call, returns a masked array, where the new _data array is the output
-of the corresponding method called on the original _data.
+Upon call, returns a masked array, where the new _data array is the output of
+the corresponding method called on the original _data.
 
-If onmask is True, the new mask is the output of the method called on the initial mask.
-If onmask is False, the new mask is just a reference to the initial mask.
+If onmask is True, the new mask is the output of the method called on the initial 
+mask. Otherwise, the new mask is just a reference to the initial mask.
 
 :IVariables:
     _name : String
         Name of the function to apply on data.
-    _onmask : Boolean *[True]*
+    _onmask : {boolean} *[True]*
         Whether the mask must be processed also (True) or left alone (False).
     obj : Object
         The object calling the arraymethod
@@ -920,7 +953,7 @@
         return result
 #..........................................................
 
-class flatiter(object):
+class FlatIter(object):
     "Defines an interator."
     def __init__(self, ma):
         self.ma = ma
@@ -954,28 +987,29 @@
     x = MaskedArray(data, mask=nomask, dtype=None, copy=True, fill_value=None,
               mask = nomask, fill_value=None, shrink=True)
 
-:Parameters:
-    data : var
+*Parameters*:
+    data : {var}
         Input data.
-    mask : sequence *[nomask]*
+    mask : {nomask, sequence}
         Mask. 
         Must be convertible to an array of booleans with the same shape as data:
         True indicates a masked (eg., invalid) data.
-    dtype : dtype *[None]*
+    dtype : {dtype}
         Data type of the output. If None, the type of the data argument is used.
         If dtype is not None and different from data.dtype, a copy is performed.
-    copy : boolean *[False]*
+    copy : {boolean}
         Whether to copy the input data (True), or to use a reference instead.
-    fill_value : var *[None]*
+        Note: data are NOT copied by default.
+    fill_value : {var}
         Value used to fill in the masked values when necessary. If None, a default 
         based on the datatype is used.
-    keep_mask : boolean *[True]*
+    keep_mask : {True, boolean}
         Whether to combine mask with the mask of the input data, if any (True),
         or to use only mask for the output (False).
-    hard_mask : boolean *[False]*
+    hard_mask : {False, boolean}
         Whether to use a hard mask or not. With a hard mask, masked values cannot
         be unmasked.
-    subok : boolean *[True]*
+    subok : {True, boolean}
         Whether to return a subclass of MaskedArray (if possible) or a plain
         MaskedArray.
     """
@@ -988,9 +1022,8 @@
     def __new__(cls, data=None, mask=nomask, dtype=None, copy=False, fill_value=None,
                 keep_mask=True, hard_mask=False, flag=None,
                 subok=True, **options):
-        """array(data, dtype=None, copy=True, mask=nomask, fill_value=None)
-
-If `data` is already a ndarray, its dtype becomes the default value of dtype.
+        """Creates a new masked array from scratch.
+    Note: you can also create an array with the .view(MaskedArray) method...
         """
         if flag is not None:
             warnings.warn("The flag 'flag' is now called 'shrink'!",
@@ -1127,7 +1160,7 @@
     #.............................................
     def __getitem__(self, indx):
         """x.__getitem__(y) <==> x[y]
-Returns the item described by i. Not a copy as in previous versions.
+Returns the item described by i, as a masked array.
         """
         # This test is useful, but we should keep things light...
 #        if getmask(indx) is not nomask:
@@ -1200,14 +1233,14 @@
     #............................................
     def __getslice__(self, i, j):
         """x.__getslice__(i, j) <==> x[i:j]
-Returns the slice described by i, j.
+Returns the slice described by (i, j).
 The use of negative indices is not supported."""
         return self.__getitem__(slice(i,j))
     #........................
     def __setslice__(self, i, j, value):
         """x.__setslice__(i, j, value) <==> x[i:j]=value
-Sets a slice i:j to `value`.
-If `value` is masked, masks those locations."""
+Sets the slice (i,j) of a to value. If value is masked, masks those locations.
+        """
         self.__setitem__(slice(i,j), value)
     #............................................
     def __setmask__(self, mask, copy=False):
@@ -1262,27 +1295,27 @@
             
     #............................................
     def _get_data(self):
-        "Returns the current data (as a view of the original underlying data)>"
+        "Returns the current data, as a view of the original underlying data."
         return self.view(self._baseclass)
     _data = property(fget=_get_data)        
     data = property(fget=_get_data)
     
     def raw_data(self):
-        """Returns the `_data` part of the MaskedArray.
-You should really use `data` instead..."""
+        """Returns the _data part of the MaskedArray.
+DEPRECATED: You should really use ``.data`` instead..."""
         return self._data
     #............................................
     def _get_flat(self):
         "Returns a flat iterator."
-        return flatiter(self)
+        return FlatIter(self)
     #
     def _set_flat (self, value):
         "Sets a flattened version of self to value."
-        "x.flat = value"
         y = self.ravel()
         y[:] = value
     #
-    flat = property(fget=_get_flat, fset=_set_flat, doc="Flat version")
+    flat = property(fget=_get_flat, fset=_set_flat, 
+                    doc="Flat version of the array.")
     #............................................
     def get_fill_value(self):
         "Returns the filling value."
@@ -1292,27 +1325,30 @@
 
     def set_fill_value(self, value=None):
         """Sets the filling value to value.
-If None, uses a default based on the data type."""
+If value is None, uses a default based on the data type."""
         if value is None:
             value = default_fill_value(self)
         self._fill_value = value
 
     fill_value = property(fget=get_fill_value, fset=set_fill_value,
-                          doc="Filling value")
+                          doc="Filling value.")
 
     def filled(self, fill_value=None):
         """Returns a copy of self._data, where masked values are filled with 
-    fill_value. If fill_value is None, self.fill_value is used instead.
-    Subclassing is preserved. 
-    Note : the result is NOT a MaskedArray !
+fill_value. 
     
-Examples
---------
->>> x = array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
->>> x.filled()
-array([1,2,-999,4,-999])
->>> type(x.filled())
-<type 'numpy.ndarray'>
+If fill_value is None, self.fill_value is used instead.
+
+*Note*: 
+    + Subclassing is preserved
+    + The result is NOT a MaskedArray !
+    
+*Examples*:
+    >>> x = array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
+    >>> x.filled()
+    array([1,2,-999,4,-999])
+    >>> type(x.filled())
+    <type 'numpy.ndarray'>
         """
         m = self._mask
         if m is nomask or not m.any():
@@ -1353,9 +1389,7 @@
 
     #............................................
     def __str__(self):
-        """x.__str__() <==> str(x)
-Calculates the string representation, using masked for fill if it is enabled.
-Otherwise, fills with fill value.
+        """Calculates the string representation.
         """
         if masked_print_option.enabled():
             f = masked_print_option
@@ -1381,9 +1415,7 @@
         return str(res)
 
     def __repr__(self):
-        """x.__repr__() <==> repr(x)
-Calculates the repr representation, using masked for fill if it is enabled.
-Otherwise fill with fill value.
+        """Calculates the repr representation.
         """
         with_mask = """\
 masked_%(name)s(data =
@@ -1497,10 +1529,18 @@
         return int(self.item())
     #............................................
     def count(self, axis=None):
-        """Counts the non-masked elements of the array along a given axis,
-and returns a masked array where the mask is True where all data are masked.
-If axis is None, counts all the non-masked elements, and returns either a
-scalar or the masked singleton."""
+        """Counts the non-masked elements of the array along the given axis.
+
+*Parameters*:
+    axis : {integer}, optional
+        Axis along which to count the non-masked elements. If not given, all the
+        non masked elements are counted.
+
+*Returns*:
+     A masked array where the mask is True where all data are masked.
+     If axis is None, returns either a scalar ot the masked singleton if all values
+     are masked.
+        """
         m = self._mask
         s = self.shape
         ls = len(s)
@@ -1538,8 +1578,13 @@
     #
     def reshape (self, *s):
         """Reshapes the array to shape s.
-    Returns a new masked array.
-    If you want to modify the shape in place, please use a.shape = s"""
+
+*Returns*:
+    A new masked array. 
+
+*Notes:
+    If you want to modify the shape in place, please use ``a.shape = s``
+        """
         result = self._data.reshape(*s).view(type(self))
         result.__dict__.update(self.__dict__)
         if result._mask is not nomask:
@@ -1548,9 +1593,12 @@
         return result
     #
     def resize(self, newshape, refcheck=True, order=False):
-        """Attempts to modify size and shape of self inplace.
-    The array must own its own memory and not be referenced by other arrays.
-    Returns None.
+        """Attempts to modify the size and the shape of the array in place.
+
+The array must own its own memory and not be referenced by other arrays.
+
+*Returns*:
+    None.
         """
         try:
             self._data.resize(newshape, refcheck, order)
@@ -1564,10 +1612,11 @@
     #
     def put(self, indices, values, mode='raise'):
         """Sets storage-indexed locations to corresponding values.
-    a.put(values, indices, mode) sets a.flat[n] = values[n] for each n in indices.
-    If values is shorter than indices then it will repeat.
-    If values has some masked values, the initial mask is updated in consequence,
-    else the corresponding values are unmasked.
+        
+a.put(values, indices, mode) sets a.flat[n] = values[n] for each n in indices.
+If values is shorter than indices then it will repeat.
+If values has some masked values, the initial mask is updated in consequence,
+else the corresponding values are unmasked.
         """
         m = self._mask
         # Hard mask: Get rid of the values/indices that fall on masked data
@@ -1597,42 +1646,86 @@
         return (self.ctypes.data, self._mask.ctypes.data)    
     #............................................
     def all(self, axis=None, out=None):
-        """a.all(axis) returns True if all entries along the axis are True.
-    Returns False otherwise. If axis is None, uses the flatten array.
-    Masked values are considered as True during computation.
-    Outputs a masked array, where the mask is True if all data are masked along the axis.
-    Note: the out argument is not really operational...
+        """Returns True if all entries along the given axis are True, False otherwise.
+Masked values are considered as True during computation.
+        
+*Parameters*
+    axis : {integer}, optional
+        Axis along which the operation is performed. 
+        If None, the operation is performed on a flatten array
+    out : {MaskedArray}, optional
+        Alternate optional output.
+        If not None, out should be a valid MaskedArray of the same shape as the
+        output of self._data.all(axis).
+
+*Returns*
+    A masked array, where the mask is True if all data along the axis are masked.
+    
+*Notes*
+    An exception is raised if ``out`` is not None and not of the same type as self.
         """
-        d = self.filled(True).all(axis=axis, out=out).view(type(self))
-        if d.ndim > 0:
-            d.__setmask__(self._mask.all(axis))
-        return d
+        if out is None:
+            d = self.filled(True).all(axis=axis).view(type(self))
+            if d.ndim > 0:
+                d.__setmask__(self._mask.all(axis))
+            return d
+        elif type(out) is not type(self):
+            raise TypeError("The external array should have a type %s (got %s instead)" %\
+                            (type(self), type(out)))
+        self.filled(True).all(axis=axis, out=out)
+        if out.ndim:
+            out.__setmask__(self._mask.all(axis))
+        return out
+            
 
     def any(self, axis=None, out=None):
-        """a.any(axis) returns True if some or all entries along the axis are True.
-    Returns False otherwise. If axis is None, uses the flatten array.
-    Masked data are considered as False during computation.
-    Outputs a masked array, where the mask is True if all data are masked along the axis.
-    Note: the out argument is not really operational...
+        """Returns True if at least one entry along the given axis is True.
+
+Returns False if all entries are False.
+Masked values are considered as True during computation.
+        
+*Parameters*
+    axis : {integer}, optional
+        Axis along which the operation is performed. 
+        If None, the operation is performed on a flatten array
+    out : {MaskedArray}, optional
+        Alternate optional output.
+        If not None, out should be a valid MaskedArray of the same shape as the
+        output of self._data.all(axis).
+
+*Returns*
+    A masked array, where the mask is True if all data along the axis are masked.
+    
+*Notes*
+    An exception is raised if ``out`` is not None and not of the same type as self.
         """
-        d = self.filled(False).any(axis=axis, out=out).view(type(self))
-        if d.ndim > 0:
-            d.__setmask__(self._mask.all(axis))
-        return d
+        if out is None:
+            d = self.filled(True).any(axis=axis).view(type(self))
+            if d.ndim > 0:
+                d.__setmask__(self._mask.all(axis))
+            return d
+        elif type(out) is not type(self):
+            raise TypeError("The external array should have a type %s (got %s instead)" %\
+                            (type(self), type(out)))
+        self.filled(True).any(axis=axis, out=out)
+        if out.ndim:
+            out.__setmask__(self._mask.all(axis))
+        return out
+
     
     def nonzero(self):
-        """a.nonzero() returns the indices of the elements of a that are not 
-    zero nor masked, as a tuple of arrays.
+        """Returns the indices of the elements of a that are not zero nor masked,
+as a tuple of arrays.
 
-    There are as many tuples as dimensions of a, each tuple contains the indices
-    of the non-zero elements in that dimension.  The corresponding non-zero values 
-    can be obtained with
-        a[a.nonzero()].
+There are as many tuples as dimensions of a, each tuple contains the indices of
+the non-zero elements in that dimension.  The corresponding non-zero values can
+be obtained with ``a[a.nonzero()]``.
 
-    To group the indices by element, rather than dimension, use
-        transpose(a.nonzero())
-    instead. The result of this is always a 2d array, with a row for
-    each non-zero element."""
+To group the indices by element, rather than dimension, use instead:
+``transpose(a.nonzero())``.
+        
+The result of this is always a 2d array, with a row for each non-zero element.
+        """
         return narray(self.filled(0), copy=False).nonzero()
     #............................................
     def trace(self, offset=0, axis1=0, axis2=1, dtype=None, out=None):
@@ -1650,16 +1743,17 @@
             return D.astype(dtype).filled(0).sum(axis=None)
     #............................................
     def sum(self, axis=None, dtype=None):
-        """a.sum(axis=None, dtype=None)
-    Sums the array a over the given axis.
-    Masked elements are set to 0.
+        """Sums the array over the given axis.
+
+Masked elements are set to 0 internally.
     
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
     """
         if self._mask is nomask:
             mask = nomask
@@ -1673,32 +1767,34 @@
         return result
 
     def cumsum(self, axis=None, dtype=None):
-        """a.cumprod(axis=None, dtype=None)
-    Returns the cumulative sum of the elements of a along the given axis.
-    Masked values are set to 0.
+        """Returns the cumulative sum of the elements of the array along the given axis.
+
+Masked values are set to 0 internally.
     
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
         """
         result = self.filled(0).cumsum(axis=axis, dtype=dtype).view(type(self))
         result.__setmask__(self.mask)
         return result
 
     def prod(self, axis=None, dtype=None):
-        """a.prod(axis=None, dtype=None)
-    Returns the product of the elements of a along the given axis.
-    Masked elements are set to 1.
+        """Returns the product of the elements of the array along the given axis.
+
+Masked elements are set to 1 internally.
     
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
         """
         if self._mask is nomask:
             mask = nomask
@@ -1713,34 +1809,34 @@
     product = prod
 
     def cumprod(self, axis=None, dtype=None):
-        """a.cumprod(axis=None, dtype=None)
-    Returns the cumulative product of the elements of a along the given axis.
-    Masked values are set to 1.
+        """Returns the cumulative product of the elements of the array along the given axis.
+
+Masked values are set to 1 internally.
     
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
         """
         result = self.filled(1).cumprod(axis=axis, dtype=dtype).view(type(self))
         result.__setmask__(self.mask)
         return result
 
     def mean(self, axis=None, dtype=None):
-        """a.mean(axis=None, dtype=None)
+        """Averages the array over the given axis.  Equivalent to
 
-    Averages the array over the given axis.  Equivalent to
-
-      a.sum(axis, dtype) / size(a, axis).    
+      a.sum(axis, dtype) / a.size(axis).    
     
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
         """
         if self._mask is nomask:
             return super(MaskedArray, self).mean(axis=axis, dtype=dtype)
@@ -1750,15 +1846,15 @@
             return dsum*1./cnt
 
     def anom(self, axis=None, dtype=None):
-        """a.anom(axis=None, dtype=None)
-    Returns the anomalies, or deviation from the average.
+        """Returns the anomalies (deviations from the average) along the given axis.
     
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
             """
         m = self.mean(axis, dtype)
         if not axis:
@@ -1767,23 +1863,22 @@
             return (self - expand_dims(m,axis))
 
     def var(self, axis=None, dtype=None):
-        """a.var(axis=None, dtype=None)
-Returns the variance, a measure of the spread of a distribution.
+        """Returns the variance, a measure of the spread of a distribution.
+        
 The variance is the average of the squared deviations from the mean,
 i.e. var = mean((x - x.mean())**2).
     
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
-        
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
 
-Notes
------
-The value returned is a biased estimate of the true variance.
-For the more standard unbiased estimate, use varu.        
+*Notes*:
+    The value returned is a biased estimate of the true variance.
+    For the (more standard) unbiased estimate, use varu.        
         """
         if self._mask is nomask:
             # TODO: Do we keep super, or var _data and take a view ?
@@ -1799,24 +1894,22 @@
             return dvar
 
     def std(self, axis=None, dtype=None):
-        """a.std(axis=None, dtype=None)
-Returns the standard deviation, a measure of the spread of a distribution.
+        """Returns the standard deviation, a measure of the spread of a distribution.
 
 The standard deviation is the square root of the average of the squared
 deviations from the mean, i.e. std = sqrt(mean((x - x.mean())**2)).    
 
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    dtype : dtype *[None]*
-        Datatype for the intermediary computation.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. 
+        If not given, the current dtype is used instead.
         
-
-Notes
------
-The value returned is a biased estimate of the true standard deviation.
-For the more standard unbiased estimate, use stdu.        
+*Notes*:
+    The value returned is a biased estimate of the true standard deviation.
+    For the more standard unbiased estimate, use stdu.        
         """
         dvar = self.var(axis,dtype)
         if axis is not None or dvar is not masked:
@@ -1826,30 +1919,30 @@
     #............................................
     def argsort(self, axis=None, fill_value=None, kind='quicksort',
                 order=None):
-        """Returns a ndarray of indices that sort 'a' along the specified axis.
+        """Returns a ndarray of indices that sort the array along the specified axis.
     Masked values are filled beforehand to fill_value.
     Returns a numpy array.
 
-:Parameters:
-    axis : integer *[None]*
-        Axis to be indirectly sorted.
-    fill_value : var *[None]*
-        Value used to fill in the masked values.
-        If None, use self.fill_value instead.
-    kind : String *['quicksort']*
+*Parameters*:
+    axis : {integer}, optional
+        Axis to be indirectly sorted. 
+        If not given, uses a flatten version of the array.
+    fill_value : {var}
+        Value used to fill in the masked values. 
+        If not given, self.fill_value is used instead.
+    kind : {string}
         Sorting algorithm (default 'quicksort')
         Possible values: 'quicksort', 'mergesort', or 'heapsort'
 
-Notes:
-------        
-    This method executes an indirect sort along the given axis using the
-    algorithm specified by the kind keyword. It returns an array of indices of
-    the same shape as 'a' that index data along the given axis in sorted order.
+*Notes*:     
+    This method executes an indirect sort along the given axis using the algorithm
+    specified by the kind keyword. It returns an array of indices of the same shape
+    as 'a' that index data along the given axis in sorted order.
 
-    The various sorts are characterized by average speed, worst case
-    performance, need for work space, and whether they are stable. A stable
-    sort keeps items with the same key in the same relative order. The three
-    available algorithms have the following properties:
+    The various sorts are characterized by average speed, worst case performance
+    need for work space, and whether they are stable.  A stable sort keeps items 
+    with the same key in the same relative order. The three available algorithms 
+    have the following properties:
 
     |------------------------------------------------------|
     |    kind   | speed |  worst case | work space | stable|
@@ -1870,15 +1963,17 @@
     #........................
     def argmin(self, axis=None, fill_value=None):
         """Returns a ndarray of indices for the minimum values of a along the
-    specified axis.
-    Masked values are treated as if they had the value fill_value.
+specified axis.
 
-:Parameters:
-    axis : integer *[None]*
-        Axis to be indirectly sorted.
-    fill_value : var *[None]*
+Masked values are treated as if they had the value fill_value.
+
+*Parameters*:
+    axis : {integer}, optional
+        Axis along which to perform the operation.
+        If None, applies to a flattened version of the array.
+    fill_value : {var}, optional
         Value used to fill in the masked values.
-        If None, use the the output of minimum_fill_value().
+        If None, the output of minimum_fill_value(self._data) is used.
         """
         if fill_value is None:
             fill_value = minimum_fill_value(self)
@@ -1887,15 +1982,17 @@
     #........................
     def argmax(self, axis=None, fill_value=None):
         """Returns the array of indices for the maximum values of `a` along the
-    specified axis.
-    Masked values are treated as if they had the value `fill_value`.
+specified axis.
 
-:Parameters:
-    axis : integer *[None]*
-        Axis to be indirectly sorted.
-    fill_value : var *[None]*
+Masked values are treated as if they had the value fill_value.
+
+*Parameters*:
+    axis : {integer}, optional
+        Axis along which to perform the operation.
+        If None, applies to a flattened version of the array.
+    fill_value : {var}, optional
         Value used to fill in the masked values.
-        If None, use the the output of maximum_fill_value().
+        If None, the output of maximum_fill_value(self._data) is used.
         """
         if fill_value is None:
             fill_value = maximum_fill_value(self._data)
@@ -1906,37 +2003,36 @@
              endwith=True, fill_value=None):
         """Sort a along the given axis.
 
-:Parameters:
-    axis : integer *[-1]*
+*Parameters*:
+    axis : {integer}
         Axis to be indirectly sorted.
-    kind : String *['quicksort']*
+    kind : {string}
         Sorting algorithm (default 'quicksort')
         Possible values: 'quicksort', 'mergesort', or 'heapsort'.
-    order : var *[None]*
+    order : {var}
         If a has fields defined, then the order keyword can be the field
         name to sort on or a list (or tuple) of field names to indicate 
         the order that fields should be used to define the sort.
-    fill_value : var *[None]*
+    fill_value : {var}
         Value used to fill in the masked values.
         If None, use the the output of minimum_fill_value().
-    endwith : boolean *[True]*
+    endwith : {boolean}
         Whether missing values (if any) should be forced in the upper indices 
         (at the end of the array) (True) or lower indices (at the beginning).
 
-:Returns:
+*Returns*:
     When used as method, returns None.
     When used as a function, returns an array.
 
-Notes
------
+*Notes*:
     This method sorts 'a' in place along the given axis using the algorithm
     specified by the kind keyword.
 
-    The various sorts may characterized by average speed, worst case
-    performance, need for work space, and whether they are stable. A stable
-    sort keeps items with the same key in the same relative order and is most
-    useful when used with argsort where the key might differ from the items
-    being sorted. The three available algorithms have the following properties:
+    The various sorts may characterized by average speed, worst case performance
+    need for work space, and whether they are stable.  A stable sort keeps items
+    with the same key in the same relative order and is most useful when used w/
+    argsort where the key might differ from the items being sorted.
+    The three available algorithms have the following properties:
 
     |------------------------------------------------------|
     |    kind   | speed |  worst case | work space | stable|
@@ -1969,13 +2065,14 @@
     #............................................
     def min(self, axis=None, fill_value=None):
         """Returns the minimum of a along the given axis.
-    Masked values are filled with fill_value.
         
-:Parameters:
-    axis : integer *[None]*
+Masked values are filled with fill_value.
+        
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    fill_value : var *[None]*
+    fill_value : {var}, optional
         Value used to fill in the masked values.
         If None, use the the output of minimum_fill_value().        
     """
@@ -2001,13 +2098,14 @@
     #........................
     def max(self, axis=None, fill_value=None):
         """Returns the maximum/a along the given axis.
-    Masked values are filled with fill_value.
+
+Masked values are filled with fill_value.
         
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    fill_value : var *[None]*
+    fill_value : {var}, optional
         Value used to fill in the masked values.
         If None, use the the output of maximum_fill_value().    
         """
@@ -2034,11 +2132,11 @@
     def ptp(self, axis=None, fill_value=None):
         """Returns the visible data range (max-min) along the given axis.
         
-:Parameters:
-    axis : integer *[None]*
+*Parameters*:
+    axis : {integer}, optional
         Axis along which to perform the operation.
         If None, applies to a flattened version of the array.
-    fill_value : var *[None]*
+    fill_value : {var}, optional
         Value used to fill in the masked values.
         If None, the maximum uses the maximum default, the minimum uses 
         the minimum default.
@@ -2062,10 +2160,11 @@
     #--------------------------------------------
     def tolist(self, fill_value=None):
         """Copies the data portion of the array to a hierarchical python list and
-    returns that list. Data items are converted to the nearest compatible Python 
-    type. 
-    Masked values are converted to fill_value. If fill_value is None, the
-    corresponding entries in the output list will be None.
+returns that list. 
+    
+Data items are converted to the nearest compatible Python type. 
+Masked values are converted to fill_value. If fill_value is None, the corresponding
+entries in the output list will be ``None``.
     """
         if fill_value is not None:
             return self.filled(fill_value).tolist()
@@ -2083,21 +2182,17 @@
                 for i in idx[:-1]:
                     tmp = tmp[i]
                 tmp[idx[-1]] = None
-        return result
-            
-            
+        return result           
     #........................
     def tostring(self, fill_value=None, order='C'):
-        """a.tostring(order='C', fill_value=None)
-        
-    Returns a copy of array data as a Python string containing the 
-    raw bytes in the array. 
+        """Returns a copy of array data as a Python string containing the raw
+bytes in the array. 
 
-:Parameters:
-    fill_value : var *[None]*
+*Parameters*:
+    fill_value : {var}, optional
         Value used to fill in the masked values.
         If None, uses self.fill_value instead.
-    order : string *['C']*
+    order : {string}
         Order of the data item in the copy {"C","F","A"}.
         "C"       -- C order (row major)
         "Fortran" -- Fortran order (column major)
@@ -2121,7 +2216,7 @@
     #
     def __setstate__(self, state):
         """Restores the internal state of the masked array, for pickling purposes.
-    `state` is typically the output of the ``__getstate__`` output, and is a 5-tuple:
+``state`` is typically the output of the ``__getstate__`` output, and is a 5-tuple:
     
         - class name
         - a tuple giving the shape of the data
@@ -2419,7 +2514,7 @@
         return x.compressed()
 
 def concatenate(arrays, axis=0):
-    "Concatenates the arrays along the given axis"
+    "Concatenates the arrays along the given axis."
     d = numpy.concatenate([getdata(a) for a in arrays], axis)
     rcls = get_masked_subclass(*arrays)
     data = d.view(rcls)
@@ -2438,12 +2533,12 @@
     return data
 
 def count(a, axis = None):
-    "Count of the non-masked elements in a, or along a certain axis."
     return masked_array(a, copy=False).count(axis)
+count.__doc__ = MaskedArray.count.__doc__
 
 
 def expand_dims(x,axis):
-    """Expands the shape of a by including newaxis before given axis."""
+    "Expands the shape of the array by including a new axis before the given one."
     result = n_expand_dims(x,axis)
     if isinstance(x, MaskedArray):
         new_shape = result.shape
@@ -2455,7 +2550,7 @@
 
 #......................................
 def left_shift (a, n):
-    "Left shift n bits"
+    "Left shift n bits."
     m = getmask(a)
     if m is nomask:
         d = umath.left_shift(filled(a), n)
@@ -2465,7 +2560,7 @@
         return masked_array(d, mask=m)
 
 def right_shift (a, n):
-    "Right shift n bits"
+    "Right shift n bits."
     m = getmask(a)
     if m is nomask:
         d = umath.right_shift(filled(a), n)
@@ -2477,7 +2572,7 @@
 #......................................
 def put(a, indices, values, mode='raise'):
     """Sets storage-indexed locations to corresponding values.
-    Values and indices are filled if necessary."""
+Values and indices are filled if necessary."""
     # We can't use 'frommethod', the order of arguments is different
     try:
         return a.put(indices, values, mode=mode)
@@ -2485,9 +2580,10 @@
         return narray(a, copy=False).put(indices, values, mode=mode)
 
 def putmask(a, mask, values): #, mode='raise'):
-    """`putmask(a, mask, v)` results in `a = v` for all places where `mask` is true.
-If `v` is shorter than `mask`, it will be repeated as necessary.
-In particular `v` can be a scalar or length 1 array."""
+    """Sets a.flat[n] = values[n] for each n where mask.flat[n] is true.  
+    
+If values is not the same size of a and mask then it will repeat as necessary. 
+This gives different behavior than a[mask] = values."""
     # We can't use 'frommethod', the order of arguments is different
     try:
         return a.putmask(values, mask)
@@ -2495,14 +2591,17 @@
         return narray(a, copy=False).putmask(values, mask)
 
 def transpose(a,axes=None):
-    """Returns a view of the array with dimensions permuted according to axes.
-If `axes` is None (default), returns array with dimensions reversed.
+    """Returns a view of the array with dimensions permuted according to axes, 
+as a masked array.
+
+If ``axes`` is None (default), the output view has reversed dimensions compared
+to the original.
     """
     #We can't use 'frommethod', as 'transpose' doesn't take keywords
     try:
         return a.transpose(axes)
     except AttributeError:
-        return narray(a, copy=False).transpose(axes)
+        return narray(a, copy=False).transpose(axes).view(MaskedArray)
 
 def reshape(a, new_shape):
     """Changes the shape of the array a to new_shape."""
@@ -2510,13 +2609,14 @@
     try:
         return a.reshape(new_shape)
     except AttributeError:
-        return narray(a, copy=False).reshape(new_shape)
+        return narray(a, copy=False).reshape(new_shape).view(MaskedArray)
 
 def resize(x, new_shape):
-    """resize(a,new_shape) returns a new array with the specified shape.
-    The total size of the original array can be any size.
-    The new array is filled with repeated copies of a. If a was masked, the new
-    array will be masked, and the new mask will be a repetition of the old one.
+    """Returns a new array with the specified shape.
+
+The total size of the original array can be any size.
+The new array is filled with repeated copies of a. If a was masked, the new array
+will be masked, and the new mask will be a repetition of the old one.
     """
     # We can't use _frommethods here, as N.resize is notoriously whiny.
     m = getmask(x)
@@ -2530,20 +2630,19 @@
 
 #................................................
 def rank(obj):
-    """Gets the rank of sequence a (the number of dimensions, not a matrix rank)
-The rank of a scalar is zero."""
+    "maskedarray version of the numpy function."
     return fromnumeric.rank(getdata(obj))
+rank.__doc__ = numpy.rank.__doc__
 #
 def shape(obj):
-    """Returns the shape of `a` (as a function call which also works on nested sequences).
-    """
+    "maskedarray version of the numpy function."
     return fromnumeric.shape(getdata(obj))
+shape.__doc__ = numpy.shape.__doc__
 #
 def size(obj, axis=None):
-    """Returns the number of elements in the array along the given axis,
-or in the sequence if `axis` is None.
-    """
+    "maskedarray version of the numpy function."
     return fromnumeric.size(getdata(obj), axis)
+size.__doc__ = numpy.size.__doc__
 #................................................
 
 #####--------------------------------------------------------------------------
@@ -2551,16 +2650,23 @@
 #####--------------------------------------------------------------------------
 def where (condition, x=None, y=None):
     """where(condition | x, y)
-    Returns a (subclass of) masked array, shaped like condition, where
-    the elements are x when condition is True, and  y otherwise.
-    condition must be convertible to an integer array.
-    If neither x nor y are given, returns a tuple of indices where condition is
-    True (a la condition.nonzero()).  
+
+Returns a (subclass of) masked array, shaped like condition, where the elements 
+are x when condition is True, and  y otherwise.   If neither x nor y are given, 
+returns a tuple of indices where condition is True (a la condition.nonzero()).  
+    
+*Parameters*:
+    condition : {var}
+        The condition to meet. Must be convertible to an integer array.
+    x : {var}, optional
+        Values of the output when the condition is met
+    y : {var}, optional
+        Values of the output when the condition is not met.
     """
     if x is None and y is None:
         return filled(condition, 0).nonzero()
     elif x is None or y is None:
-        raise ValueError, "Either bioth or neither x and y should be given."
+        raise ValueError, "Either both or neither x and y should be given."
     # Get the condition ...............
     fc = filled(condition, 0).astype(bool_)
     notfc = numpy.logical_not(fc)
@@ -2628,28 +2734,36 @@
     return masked_array(d, mask=m)
 
 def round_(a, decimals=0, out=None):
-    """Returns a copy of a rounded to 'decimals' places.
+    """Returns a copy of a, rounded to 'decimals' places.
+    
+When 'decimals' is negative, it specifies the number of positions to the left of 
+the decimal point.  The real and imaginary parts of complex numbers are rounded 
+separately. Nothing is done if the array is not of float type and 'decimals' is 
+greater than or equal to 0.
 
-:Parameters:
-    decimals : integer *[0]*
+*Parameters*:
+    decimals : {integer}
         Number of decimals to round to. May be negative. 
-    out : ndarray
-        Existing array to use for output (default copy of a).
-
-Notes
------
-    Rounds to the specified number of decimals. When 'decimals' is negative,
-    it specifies the number of positions to the left of the decimal point. 
-    The real and imaginary parts of complex numbers are rounded separately.
-    Nothing is done if the array is not of float type and 'decimals' is greater
-    than or equal to 0."""
-    result = fromnumeric.round_(getdata(a), decimals, out)
-    if isinstance(a,MaskedArray):
-        result = result.view(type(a))
-        result._mask = a._mask
+    out : {ndarray}
+        Existing array to use for output.
+        If not given, returns a default copy of a.
+        
+*Notes*:
+    If out is given and does not have a mask attribute, the mask of a is lost!
+    """
+    if out is None:
+        result = fromnumeric.round_(getdata(a), decimals, out)
+        if isinstance(a,MaskedArray):
+            result = result.view(type(a))
+            result._mask = a._mask
+        else:
+            result = result.view(MaskedArray)
+        return result
     else:
-        result = result.view(MaskedArray)
-    return result
+        fromnumeric.round_(getdata(a), decimals, out)
+        if hasattr(out, '_mask'):
+            out._mask = getmask(a)
+        return out
 
 def arange(stop, start=None, step=1, dtype=None):
     "maskedarray version of the numpy function."
@@ -2665,7 +2779,8 @@
     if len(fb.shape) == 0:
         fb.shape = (1,)
     return numpy.inner(fa, fb).view(MaskedArray)
-inner.__doc__ = numpy.inner.__doc__ + "\nMasked values are replaced by 0."
+inner.__doc__ = numpy.inner.__doc__ 
+inner.__doc__ += "\n*Notes*:\n    Masked values are replaced by 0."
 innerproduct = inner
 
 def outer(a, b):
@@ -2681,12 +2796,13 @@
     mb = getmaskarray(b)
     m = make_mask(1-numeric.outer(1-ma, 1-mb), copy=0)
     return masked_array(d, mask=m)
-outer.__doc__ = numpy.outer.__doc__ + "\nMasked values are replaced by 0."
+outer.__doc__ = numpy.outer.__doc__ 
+outer.__doc__ += "\n*Notes*:\n    Masked values are replaced by 0."
 outerproduct = outer
 
 def allequal (a, b, fill_value=True):
     """Returns True if all entries of  a and b are equal, using fill_value 
-    as a truth value where either or both are masked.
+as a truth value where either or both are masked.
     """
     m = mask_or(getmask(a), getmask(b))
     if m is nomask:
@@ -2722,7 +2838,8 @@
 #..............................................................................
 def asarray(a, dtype=None):
     """asarray(data, dtype) = array(data, dtype, copy=0, subok=0)
-Returns a as a MaskedArray object.
+Returns a as a MaskedArray object of the given dtype.
+If dtype is not given or None, is is set to the dtype of a.
 No copy is performed if a is already an array.
 Subclasses are converted to the base class MaskedArray.
     """
@@ -2731,6 +2848,7 @@
 def asanyarray(a, dtype=None):
     """asanyarray(data, dtype) = array(data, dtype, copy=0, subok=1)
 Returns a as an masked array.
+If dtype is not given or None, is is set to the dtype of a.
 No copy is performed if a is already an array.
 Subclasses are conserved.
     """
@@ -2814,4 +2932,6 @@
     mmyl = array(yl, mask=masky, shrink=True)
     mmzl = array(zl, mask=maskx, shrink=True)
     #
-    z = log(mmxl)
\ No newline at end of file
+    z = empty(3,)
+    mmys.all(0, out=z)
+    
\ No newline at end of file

Modified: trunk/scipy/sandbox/maskedarray/extras.py
===================================================================
--- trunk/scipy/sandbox/maskedarray/extras.py	2007-10-03 00:06:40 UTC (rev 3389)
+++ trunk/scipy/sandbox/maskedarray/extras.py	2007-10-03 01:46:24 UTC (rev 3390)
@@ -50,13 +50,24 @@
     return False
 
 def count_masked(arr, axis=None):
-    """Counts the number of masked elements along the given axis."""
+    """Counts the number of masked elements along the given axis.
+    
+*Parameters*:
+    axis : {integer}, optional
+        Axis along which to count.
+        If None (default), a flattened version of the array is used.
+    """
     m = getmaskarray(arr)
     return m.sum(axis)
 
 def masked_all(shape, dtype=float_):
     """Returns an empty masked array of the given shape and dtype,
-    where all the data are masked."""
+    where all the data are masked.
+    
+*Parameters*:
+    dtype : {dtype}, optional
+        Data type of the output.    
+    """
     a = masked_array(numeric.empty(shape, dtype),
                      mask=numeric.ones(shape, bool_))
     return a
@@ -72,11 +83,20 @@
 #---- --- New methods ---
 #####-------------------------------------------------------------------------- 
 def varu(a, axis=None, dtype=None):
-    """a.var(axis=None, dtype=None)
-    Returns an unbiased estimate of the variance.
+    """Returns an unbiased estimate of the variance.
+    i.e. var = sum((x - x.mean())**2)/(size(x,axis)-1)
     
-    Instead of dividing the sum of squared anomalies (SSA) by n, the number of 
-    elements, the SSA is divided by n-1.
+*Parameters*:
+    axis : {integer}, optional
+        Axis along which to perform the operation.
+        If None, applies to a flattened version of the array.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. If not given, the current dtype
+        is used instead.
+
+*Notes*:
+    The value returned is an unbiased estimate of the true variance.
+    For the (less standard) biased estimate, use var.       
         """
     a = asarray(a)
     cnt = a.count(axis=axis)
@@ -92,11 +112,21 @@
 #                          fill_value=a._fill_value)
             
 def stdu(a, axis=None, dtype=None):
-    """a.var(axis=None, dtype=None)
-    Returns an unbiased estimate of the standard deviation.
+    """Returns an unbiased estimate of the standard deviation.
+    The standard deviation is the square root of the average of the squared
+    deviations from the mean, i.e. stdu = sqrt(varu(x)).    
 
-    Instead of dividing the sum of squared anomalies (SSA) by n, the number of 
-    elements, the SSA is divided by n-1.
+*Parameters*:
+    axis : {integer}, optional
+        Axis along which to perform the operation.
+        If None, applies to a flattened version of the array.
+    dtype : {dtype}, optional
+        Datatype for the intermediary computation. 
+        If not given, the current dtype is used instead.
+        
+*Notes*:
+    The value returned is an unbiased estimate of the true standard deviation.
+    For the (less standard) biased estimate, use std.       
         """
     a = asarray(a)
     dvar = a.varu(axis,dtype)
@@ -124,7 +154,7 @@
     def getdoc(self):
         "Retrieves the __doc__ string from the function."
         return getattr(numpy, self._function).__doc__ +\
-            "(The function is applied to both the _data and the mask, if any.)"
+            "*Notes*:\n    (The function is applied to both the _data and the _mask, if any.)"
     def __call__(self, *args, **params):
         func = getattr(numpy, self._function)
         if len(args)==1:
@@ -260,31 +290,21 @@
         result.fill_value = core.default_fill_value(result)
     return result
 
-def average (a, axis=None, weights=None, returned = 0):
-    """average(a, axis=None weights=None, returned=False)
-
-    Averages the array over the given axis.  If the axis is None, averages
-    over all dimensions of the array.  Equivalent to a.mean(axis)
-
-    If an integer axis is given, this equals:
-        a.sum(axis) * 1.0 / size(a, axis)
-
-    If axis is None, this equals:
-        a.sum(axis) * 1.0 / a.size
-
-    If weights are given, result is:
-        sum(a * weights,axis) / sum(weights,axis),
-    where the weights must have a's shape or be 1D with length the
-    size of a in the given axis. Integer weights are converted to
-    Float.  Not specifying weights is equivalent to specifying
-    weights that are all 1.
-
-    If 'returned' is True, return a tuple: the result and the sum of
-    the weights or count of values. The shape of these two results
-    will be the same.
-
-    Returns masked values instead of ZeroDivisionError if appropriate.
+def average (a, axis=None, weights=None, returned=False):
+    """Averages the array over the given axis.  
     
+*Parameters*:
+    axis : {integer}, optional
+        Axis along which to perform the operation.
+        If None, applies to a flattened version of the array.
+    weights : {sequence}, optional
+        Sequence of weights.
+        The weights must have the shape of a, or be 1D with length the size of a
+        along the given axis.
+        If no weights are given, weights are assumed to be 1.
+    returned : {boolean}
+        Flag indicating whether a tuple (result, sum of weights/counts) should be
+        returned as output (True), or just the result (False).    
     """
     a = asarray(a)
     mask = a.mask
@@ -380,14 +400,17 @@
 #..............................................................................
 def compress_rowcols(x, axis=None):
     """Suppresses the rows and/or columns of a 2D array that contains masked values.
+    
     The suppression behavior is selected with the `axis`parameter.
         - If axis is None, rows and columns are suppressed. 
         - If axis is 0, only rows are suppressed. 
         - If axis is 1 or -1, only columns are suppressed.
-    Returns a *pure* ndarray.    
+        
+*Returns*:        
+    compressed_array : a ndarray.    
     """
     x = asarray(x)
-    if x.ndim <> 2:
+    if x.ndim != 2:
         raise NotImplementedError, "compress2d works for 2D arrays only."
     m = getmask(x)
     # Nothing is masked: return x
@@ -418,9 +441,9 @@
 def mask_rowcols(a, axis=None):
     """Masks whole rows and/or columns of a 2D array that contain masked values.
     The masking behavior is selected with the `axis`parameter.
-        - If axis is None, rows and columns are suppressed. 
-        - If axis is 0, only rows are suppressed. 
-        - If axis is 1 or -1, only columns are suppressed.
+        - If axis is None, rows and columns are masked. 
+        - If axis is 0, only rows are masked. 
+        - If axis is 1 or -1, only columns are masked.
     Returns a *pure* ndarray.    
     """
     a = asarray(a)
@@ -449,13 +472,18 @@
         
 def dot(a,b, strict=False):
     """Returns the dot product of two 2D masked arrays a and b.
-    Like the generic numpy equivalent the product sum is over
-    the last dimension of a and the second-to-last dimension of b.
     
+    Like the generic numpy equivalent, the product sum is over the last dimension 
+    of a and the second-to-last dimension of b.
     If strict is True, masked values are propagated: if a masked value appears 
     in a row or column, the whole row or column is considered masked.
     
-    NB: The first argument is not conjugated.
+*Parameters*:
+    strict : {boolean}
+        Whether masked data are propagated (True) or set to 0 for the computation.
+    
+*Note*:
+    The first argument is not conjugated.
     """
     #TODO: Works only with 2D arrays. There should be a way to get it to run with higher dimension
     if strict and (a.ndim == 2) and (b.ndim == 2):
@@ -471,7 +499,23 @@
 
 #...............................................................................
 def mediff1d(array, to_end=None, to_begin=None):
-    """Array difference with prefixed and/or appended value."""
+    """Returns the differences between consecutive elements of an array, possibly with
+    prefixed and/or appended values.
+
+*Parameters*:
+    array : {array}
+        Input array,  will be flattened before the difference is taken.
+    to_end : {number}, optional
+        If provided, this number will be tacked onto the end of the returned
+        differences.
+    to_begin : {number}, optional
+        If provided, this number will be taked onto the beginning of the
+        returned differences.
+
+*Returns*:
+      ed : {array}
+        The differences. Loosely, this will be (ary[1:] - ary[:-1]).
+    """
     a = masked_array(array, copy=True)
     if a.ndim > 1:
         a.reshape((a.size,))
@@ -585,7 +629,7 @@
     """Translates slice objects to concatenation along the first axis.
 
         For example:
-        >>> r_[array([1,2,3]), 0, 0, array([4,5,6])]
+        >>> mr_[array([1,2,3]), 0, 0, array([4,5,6])]
         array([1, 2, 3, 0, 0, 4, 5, 6])
     """
     def __init__(self):
@@ -598,7 +642,7 @@
 #####--------------------------------------------------------------------------
 
 def flatnotmasked_edges(a):
-    """Finds the indices of the first and last not masked values in a  1D masked array.
+    """Finds the indices of the first and last not masked values in a 1D masked array.
     If all values are masked, returns None.
     """
     m = getmask(a)

Modified: trunk/scipy/sandbox/maskedarray/morestats.py
===================================================================
--- trunk/scipy/sandbox/maskedarray/morestats.py	2007-10-03 00:06:40 UTC (rev 3389)
+++ trunk/scipy/sandbox/maskedarray/morestats.py	2007-10-03 01:46:24 UTC (rev 3390)
@@ -38,20 +38,21 @@
 #####--------------------------------------------------------------------------
 def hdquantiles(data, prob=list([.25,.5,.75]), axis=None, var=False,):
     """Computes quantile estimates with the Harrell-Davis method, where the estimates
-    are calculated as a weighted linear combination of order statistics.
-    If var=True, the variance of the estimate is also returned. 
-    Depending on var, returns a (p,) array of quantiles or a (2,p) array of quantiles
-    and variances.
+are calculated as a weighted linear combination of order statistics.
     
-:Inputs:
-    data: ndarray
+*Parameters* :
+    data: {ndarray}
         Data array.    
-    prob: Sequence
-        List of quantiles to compute.
-    axis : integer *[None]*
+    prob: {sequence}
+        Sequence of quantiles to compute.
+    axis : {integer}
         Axis along which to compute the quantiles. If None, use a flattened array.
-    var : boolean *[False]*
+    var : {boolean}
         Whether to return the variance of the estimate.
+
+*Returns*
+    A (p,) array of quantiles (if ``var`` is False), or a (2,p) array of quantiles
+    and variances (if ``var`` is True), where ``p`` is the number of quantiles.
         
 :Note:
     The function is restricted to 2D arrays.
@@ -101,12 +102,12 @@
 def hdmedian(data, axis=-1, var=False):
     """Returns the Harrell-Davis estimate of the median along the given axis.
     
-:Inputs:
-    data: ndarray
+*Parameters* :
+    data: {ndarray}
         Data array.    
-    axis : integer *[None]*
+    axis : {integer}
         Axis along which to compute the quantiles. If None, use a flattened array.
-    var : boolean *[False]*
+    var : {boolean}
         Whether to return the variance of the estimate.
     """
     result = hdquantiles(data,[0.5], axis=axis, var=var)
@@ -117,19 +118,16 @@
 def hdquantiles_sd(data, prob=list([.25,.5,.75]), axis=None):
     """Computes the standard error of the Harrell-Davis quantile estimates by jackknife.
     
-:Inputs:
-    data: ndarray
+
+*Parameters* :
+    data: {ndarray}
         Data array.    
-    prob: Sequence
-        List of quantiles to compute.
-    axis : integer *[None]*
+    prob: {sequence}
+        Sequence of quantiles to compute.
+    axis : {integer}
         Axis along which to compute the quantiles. If None, use a flattened array.
-    var : boolean *[False]*
-        Whether to return the variance of the estimate.
-    stderr : boolean *[False]*
-        Whether to return the standard error of the estimate.
         
-:Note:
+*Note*:
     The function is restricted to 2D arrays.
     """  
     def _hdsd_1D(data,prob):
@@ -172,18 +170,18 @@
 
 def trimmed_mean_ci(data, proportiontocut=0.2, alpha=0.05, axis=None):
     """Returns the selected confidence interval of the trimmed mean along the
-    given axis.
+given axis.
     
-:Inputs:
-    data : sequence
+*Parameters* :
+    data : {sequence}
         Input data. The data is transformed to a masked array
-    proportiontocut : float *[0.2]*
+    proportiontocut : {float}
         Proportion of the data to cut from each side of the data . 
         As a result, (2*proportiontocut*n) values are actually trimmed.
-    alpha : float *[0.05]*
-        Confidence level of the intervals
-    axis : integer *[None]*
-        Axis along which to cut.
+    alpha : {float}
+        Confidence level of the intervals.
+    axis : {integer}
+        Axis along which to cut. If None, uses a flattened version of the input.
     """
     data = masked_array(data, copy=False)
     trimmed = trim_both(data, proportiontocut=proportiontocut, axis=axis)
@@ -196,15 +194,15 @@
 #..............................................................................
 def mjci(data, prob=[0.25,0.5,0.75], axis=None):
     """Returns the Maritz-Jarrett estimators of the standard error of selected 
-    experimental quantiles of the data.
+experimental quantiles of the data.  
     
-:Input:
-    data : sequence
-        Input data.
-    prob : sequence *[0.25,0.5,0.75]*
-        Sequence of quantiles whose standard error must be estimated.
-    axis : integer *[None]*
-        Axis along which to compute the standard error.
+*Parameters* :
+    data: {ndarray}
+        Data array.    
+    prob: {sequence}
+        Sequence of quantiles to compute.
+    axis : {integer}
+        Axis along which to compute the quantiles. If None, use a flattened array.
     """
     def _mjci_1D(data, p):
         data = data.compressed()
@@ -236,17 +234,17 @@
 #..............................................................................
 def mquantiles_cimj(data, prob=[0.25,0.50,0.75], alpha=0.05, axis=None):
     """Computes the alpha confidence interval for the selected quantiles of the
-    data, with Maritz-Jarrett estimators.
+data, with Maritz-Jarrett estimators.
     
-:Input:
-    data : sequence
-        Input data.
-    prob : sequence *[0.25,0.5,0.75]*
-        Sequence of quantiles whose standard error must be estimated.
-    alpha : float *[0.05]*
-        Confidence degree.
-    axis : integer *[None]*
-        Axis along which to compute the standard error.
+*Parameters* :
+    data: {ndarray}
+        Data array.    
+    prob: {sequence}
+        Sequence of quantiles to compute.
+    alpha : {float}
+        Confidence level of the intervals.        
+    axis : {integer}
+        Axis along which to compute the quantiles. If None, use a flattened array.
     """
     alpha = min(alpha, 1-alpha)
     z = norm.ppf(1-alpha/2.)
@@ -258,13 +256,16 @@
 #.............................................................................
 def median_cihs(data, alpha=0.05, axis=None):
     """Computes the alpha-level confidence interval for the median of the data,
-    following the Hettmasperger-Sheather method.
+following the Hettmasperger-Sheather method.
     
-:Inputs:
-    data : sequence
-        Input data. Masked values are discarded. The input should be 1D only
-    alpha : float *[0.05]*
-        Confidence degree.
+*Parameters* :
+    data : {sequence}
+        Input data. Masked values are discarded. The input should be 1D only, or
+        axis should be set to None.
+    alpha : {float}
+        Confidence level of the intervals.        
+    axis : {integer}
+        Axis along which to compute the quantiles. If None, use a flattened array.
     """
     def _cihs_1D(data, alpha):
         data = numpy.sort(data.compressed())
@@ -294,17 +295,21 @@
 #..............................................................................
 def compare_medians_ms(group_1, group_2, axis=None):
     """Compares the medians from two independent groups along the given axis.
-    Returns an array of p values.
-    The comparison is performed using the McKean-Schrader estimate of the standard
-    error of the medians.    
+
+The comparison is performed using the McKean-Schrader estimate of the standard
+error of the medians.    
     
-:Inputs:
-    group_1 : sequence
+*Parameters* :
+    group_1 : {sequence}
         First dataset.
-    group_2 : sequence
+    group_2 : {sequence}
         Second dataset.
-    axis : integer *[None]*
+    axis : {integer}
         Axis along which the medians are estimated. If None, the arrays are flattened.
+
+*Returns* :
+    A (p,) array of comparison values.
+
     """
     (med_1, med_2) = (mmedian(group_1, axis=axis), mmedian(group_2, axis=axis))
     (std_1, std_2) = (stde_median(group_1, axis=axis), 
@@ -320,21 +325,22 @@
 #..............................................................................
 def rank_data(data, axis=None, use_missing=False):
     """Returns the rank (also known as order statistics) of each data point 
-    along the given axis.
-    If some values are tied, their rank is averaged.
-    If some values are masked, their rank is set to 0 if use_missing is False, or
-    set to the average rank of the unmasked values if use_missing is True.
+along the given axis.
+
+If some values are tied, their rank is averaged.
+If some values are masked, their rank is set to 0 if use_missing is False, or
+set to the average rank of the unmasked values if use_missing is True.
     
-:Inputs:
-    data : sequence
+*Parameters* :
+    data : {sequence}
         Input data. The data is transformed to a masked array
-    axis : integer *[None]*
+    axis : {integer} 
         Axis along which to perform the ranking. If None, the array is first
         flattened. An exception is raised if the axis is specified for arrays
         with a dimension larger than 2
-    use_missing : boolean *[False]*
-        Flag indicating whether the masked values have a rank of 0 (False) or
-        equal to the average rank of the unmasked values (True)    
+    use_missing : {boolean} 
+        Whether the masked values have a rank of 0 (False) or equal to the 
+        average rank of the unmasked values (True).
     """
     #
     def _rank1d(data, use_missing=False):

Modified: trunk/scipy/sandbox/maskedarray/mrecords.py
===================================================================
--- trunk/scipy/sandbox/maskedarray/mrecords.py	2007-10-03 00:06:40 UTC (rev 3389)
+++ trunk/scipy/sandbox/maskedarray/mrecords.py	2007-10-03 01:46:24 UTC (rev 3390)
@@ -38,8 +38,7 @@
 reserved_fields = ['_data','_mask','_fieldmask', 'dtype']
 
 def _getformats(data):
-    """Returns the formats of each array of arraylist as a comma-separated 
-    string."""
+    "Returns the formats of each array of arraylist as a comma-separated string."
     if hasattr(data,'dtype'):
         return ",".join([desc[1] for desc in data.dtype.descr])
     
@@ -56,9 +55,9 @@
     return formats[:-1]    
 
 def _checknames(descr, names=None):
-    """Checks that the field names of the descriptor `descr` are not some 
-    reserved keywords. If this is the case, a default 'f%i' is substituted.
-    If the argument `names` is not None, updates the field names to valid names.    
+    """Checks that the field names of the descriptor ``descr`` are not some 
+reserved keywords. If this is the case, a default 'f%i' is substituted.
+If the argument `names` is not None, updates the field names to valid names.    
     """    
     ndescr = len(descr)
     default_names = ['f%i' % i for i in range(ndescr)]
@@ -90,12 +89,15 @@
 class MaskedRecords(MaskedArray, object):
     """
     
-:IVariables:
-    - `__localfdict` : Dictionary
-        Dictionary of local fields (`f0_data`, `f0_mask`...)
-    - `__globalfdict` : Dictionary
-        Dictionary of global fields, as the combination of a `_data` and a `_mask`.
-        (`f0`)
+*IVariables*:
+    _data : {recarray}
+        Underlying data, as a record array.
+    _mask : {boolean array}
+        Mask of the records. A record is masked when all its fields are masked.
+    _fieldmask : {boolean recarray}
+        Record array of booleans, setting the mask of each individual field of each record.
+    _fill_value : {record}
+        Filling values for each field.
     """
     _defaultfieldmask = nomask
     _defaulthardmask = False
@@ -183,6 +185,7 @@
     
     #......................................................
     def __getattribute__(self, attr):
+        "Returns the given attribute."
         try:
             # Returns a generic attribute
             return object.__getattribute__(self,attr)
@@ -205,6 +208,7 @@
         raise AttributeError,"No attribute '%s' !" % attr
             
     def __setattr__(self, attr, val):
+        "Sets the attribute attr to the value val."
         newattr = attr not in self.__dict__
         try:
             # Is attr a generic attribute ?
@@ -241,7 +245,7 @@
     #............................................
     def __getitem__(self, indx):
         """Returns all the fields sharing the same fieldname base.
-    The fieldname base is either `_data` or `_mask`."""
+The fieldname base is either `_data` or `_mask`."""
         _localdict = self.__dict__
         _data = self._data
         # We want a field ........
@@ -263,18 +267,12 @@
         return obj
     #............................................
     def __setitem__(self, indx, value):
-        """Sets the given record to value."""
+        "Sets the given record to value."
         MaskedArray.__setitem__(self, indx, value)
         
-#    def __getslice__(self, i, j):
-#        """Returns the slice described by [i,j]."""
-#        _localdict = self.__dict__
-#        return MaskedRecords(_localdict['_data'][i:j], 
-#                        mask=_localdict['_fieldmask'][i:j],
-#                       dtype=self.dtype)      
-#        
+
     def __setslice__(self, i, j, value):
-        """Sets the slice described by [i,j] to `value`."""
+        "Sets the slice described by [i,j] to `value`."
         _localdict = self.__dict__
         d = self._data
         m = _localdict['_fieldmask']
@@ -305,6 +303,7 @@
         
     #.....................................................           
     def __setmask__(self, mask):
+        "Sets the mask."
         names = self.dtype.names
         fmask = self.__dict__['_fieldmask']
         newmask = make_mask(mask, copy=False)
@@ -328,10 +327,7 @@
         
     #......................................................
     def __str__(self):
-        """x.__str__() <==> str(x)
-Calculates the string representation, using masked for fill if it is enabled. 
-Otherwise, fills with fill value.
-        """
+        "Calculates the string representation."
         if self.size > 1:
             mstr = ["(%s)" % ",".join([str(i) for i in s])  
                     for s in zip(*[getattr(self,f) for f in self.dtype.names])]
@@ -342,10 +338,7 @@
             return "(%s)" % ", ".join(mstr)
     
     def __repr__(self):
-        """x.__repr__() <==> repr(x)
-Calculates the repr representation, using masked for fill if it is enabled. 
-Otherwise fill with fill value.
-        """
+        "Calculates the repr representation."
         _names = self.dtype.names
         fmt = "%%%is : %%s" % (max([len(n) for n in _names])+4,)
         reprstr = [fmt % (f,getattr(self,f)) for f in self.dtype.names]
@@ -367,11 +360,12 @@
         return ndarray.view(self, obj)            
     #......................................................
     def filled(self, fill_value=None):
-        """Returns an array of the same class as `_data`,
- with masked values filled with `fill_value`.
+        """Returns an array of the same class as ``_data``, with masked values
+filled with ``fill_value``. If ``fill_value`` is None, ``self.fill_value`` is
+used instead.
+ 
 Subclassing is preserved.
         
-If `fill_value` is None, uses self.fill_value.
         """
         _localdict = self.__dict__
         d = self._data
@@ -419,28 +413,31 @@
                names=None, titles=None, aligned=False, byteorder=None):
     """Creates a mrecarray from a (flat) list of masked arrays.
 
-:Parameters:
-    - `arraylist` : Sequence
-      A list of (masked) arrays. Each element of the sequence is first converted
-      to a masked array if needed. If a 2D array is passed as argument, it is
-      processed line by line
-    - `dtype` : numeric.dtype
-      Data type descriptor.
-    - `shape` : Integer *[None]*
-      Number of records. If None, `shape` is defined from the shape of the first
-      array in the list.
-    - `formats` :
+*Parameters*:
+    arraylist : {sequence}
+        A list of (masked) arrays. Each element of the sequence is first converted
+        to a masked array if needed. If a 2D array is passed as argument, it is
+        processed line by line
+    dtype : {numeric.dtype}
+        Data type descriptor.
+    {shape} : {integer}
+        Number of records. If None, ``shape`` is defined from the shape of the 
+        first array in the list.
+    formats : {sequence}
+        Sequence of formats for each individual field. If None, the formats will
+        be autodetected by inspecting the fields and selecting the highest dtype
+        possible.
+    names : {sequence}
+        Sequence of the names of each field.
+    -titles : {sequence}
       (Description to write)
-    - `names` : 
-      (description to write)
-    - `titles`:
-      (Description to write)
-    - `aligned`: Boolen *[False]*
+    aligned : {boolean}
       (Description to write, not used anyway)   
-    - `byteorder`: Boolen *[None]*
+    byteorder: {boolean}
       (Description to write, not used anyway)
-       
-
+      
+*Notes*:
+    Lists of tuples should be preferred over lists of lists for faster processing.
     """
     arraylist = [masked_array(x) for x in arraylist]
     # Define/check the shape.....................
@@ -481,13 +478,31 @@
                 titles=None, aligned=False, byteorder=None):
     """Creates a MaskedRecords from a list of records.
 
-    The data in the same field can be heterogeneous, they will be promoted
-    to the highest data type.  This method is intended for creating
-    smaller record arrays.  If used to create large array without formats
-    defined, it can be slow.
+*Parameters*:
+    arraylist : {sequence}
+        A list of (masked) arrays. Each element of the sequence is first converted
+        to a masked array if needed. If a 2D array is passed as argument, it is
+        processed line by line
+    dtype : {numeric.dtype}
+        Data type descriptor.
+    {shape} : {integer}
+        Number of records. If None, ``shape`` is defined from the shape of the 
+        first array in the list.
+    formats : {sequence}
+        Sequence of formats for each individual field. If None, the formats will
+        be autodetected by inspecting the fields and selecting the highest dtype
+        possible.
+    names : {sequence}
+        Sequence of the names of each field.
+    -titles : {sequence}
+      (Description to write)
+    aligned : {boolean}
+      (Description to write, not used anyway)   
+    byteorder: {boolean}
+      (Description to write, not used anyway)
 
-    If formats is None, then this will auto-detect formats. Use a list of
-    tuples rather than a list of lists for faster processing.
+*Notes*:
+    Lists of tuples should be preferred over lists of lists for faster processing.
     """    
     # reclist is in fact a mrecarray .................
     if isinstance(reclist, MaskedRecords):
@@ -537,9 +552,9 @@
 
 def _guessvartypes(arr):        
     """Tries to guess the dtypes of the str_ ndarray `arr`, by testing element-wise
-    conversion. Returns a list of dtypes.
-    The array is first converted to ndarray. If the array is 2D, the test is 
-    performed on the first line. An exception is raised if the file is 3D or more.
+conversion. Returns a list of dtypes.
+The array is first converted to ndarray. If the array is 2D, the test is performed 
+on the first line. An exception is raised if the file is 3D or more.
     """
     vartypes = []
     arr = numeric.asarray(arr)
@@ -587,22 +602,22 @@
                  varnames=None, vartypes=None):
     """Creates a mrecarray from data stored in the file `filename`.
 
-:Parameters:
-    - `filename` : file name/handle
-      Handle of an opened file.  
-    - `delimitor` : Character *None*
-      Alphanumeric character used to separate columns in the file.
-      If None, any (group of) white spacestring(s) will be used.
-    - `commentchar` : String *['#']*
-      Alphanumeric character used to mark the start of a comment.
-    - `missingchar` : String *['']*
-      String indicating missing data, and used to create the masks.
-    - `varnames` : Sequence *[None]*
-      Sequence of the variable names. If None, a list will be created from
-      the first non empty line of the file.
-    - `vartypes` : Sequence *[None]*
-      Sequence of the variables dtypes. If None, the sequence will be estimated
-      from the first non-commented line.  
+*Parameters* :
+    filename : {file name/handle}
+        Handle of an opened file.  
+    delimitor : {string}
+        Alphanumeric character used to separate columns in the file.
+        If None, any (group of) white spacestring(s) will be used.
+    commentchar : {string}
+        Alphanumeric character used to mark the start of a comment.
+    missingchar` : {string}
+        String indicating missing data, and used to create the masks.
+    varnames : {sequence}
+        Sequence of the variable names. If None, a list will be created from
+        the first non empty line of the file.
+    vartypes : {sequence}
+        Sequence of the variables dtypes. If None, it will be estimated from 
+        the first non-commented line.  
     
     
     Ultra simple: the varnames are in the header, one line"""

Modified: trunk/scipy/sandbox/maskedarray/mstats.py
===================================================================
--- trunk/scipy/sandbox/maskedarray/mstats.py	2007-10-03 00:06:40 UTC (rev 3389)
+++ trunk/scipy/sandbox/maskedarray/mstats.py	2007-10-03 01:46:24 UTC (rev 3390)
@@ -32,10 +32,17 @@
 #####--------------------------------------------------------------------------
 
 def winsorize(data, alpha=0.2):
-    """Returns a Winsorized version of the input array: the (alpha/2.) lowest
-    values are set to the (alpha/2.)th percentile, and the (alpha/2.) highest
-    values are set to the (1-alpha/2.)th percentile 
-    Masked values are skipped. The input array is first flattened.
+    """Returns a Winsorized version of the input array.
+    
+The (alpha/2.) lowest values are set to the (alpha/2.)th percentile, and 
+the (alpha/2.) highest values are set to the (1-alpha/2.)th percentile 
+Masked values are skipped. 
+
+*Parameters*:
+    data : {ndarray}
+        Input data to Winsorize. The data is first flattened.
+    alpha : {float}, optional
+        Percentage of total Winsorization : alpha/2. on the left, alpha/2. on the right
     """
     data = masked_array(data, copy=False).ravel()
     idxsort = data.argsort()
@@ -47,16 +54,17 @@
 #..............................................................................  
 def trim_both(data, proportiontocut=0.2, axis=None):
     """Trims the data by masking the int(trim*n) smallest and int(trim*n) largest 
-    values of data along the given axis, where n is the number of unmasked values.
+values of data along the given axis, where n is the number of unmasked values.
     
-:Inputs: 
-    data : MaskedArray
+*Parameters*:
+    data : {ndarray}
         Data to trim.
-    trim : float *[0.2]*
+    proportiontocut : {float}
         Percentage of trimming. If n is the number of unmasked values before trimming, 
         the number of values after trimming is (1-2*trim)*n.
-    axis : integer *[None]*
-        Axis along which to perform the trimming.
+    axis : {integer}
+        Axis along which to perform the trimming. If None, the input array is first 
+        flattened.
     """
     #...................
     def _trim_1D(data, trim):
@@ -80,16 +88,21 @@
 #..............................................................................
 def trim_tail(data, proportiontocut=0.2, tail='left', axis=None):
     """Trims the data by masking int(trim*n) values from ONE tail of the data
-    along the given axis, where n is the number of unmasked values.
-    
-:Inputs: 
-    data : MaskedArray
+along the given axis, where n is the number of unmasked values.
+
+*Parameters*:
+    data : {ndarray}
         Data to trim.
-    trim : float *[0.2]*
+    proportiontocut : {float}
         Percentage of trimming. If n is the number of unmasked values before trimming, 
-        the number of values after trimming is (1-2*trim)*n.
-    axis : integer *[None]*
-        Axis along which to perform the trimming.
+        the number of values after trimming is (1-trim)*n.
+    tail : {string}
+        Trimming direction, in ('left', 'right'). If left, the proportiontocut 
+        lowest values are set to the corresponding percentile. If right, the
+        proportiontocut highest values are used instead.
+    axis : {integer}
+        Axis along which to perform the trimming. If None, the input array is first 
+        flattened.
     """
     #...................
     def _trim_1D(data, trim, left):
@@ -126,32 +139,34 @@
 #..............................................................................    
 def trimmed_mean(data, proportiontocut=0.2, axis=None):
     """Returns the trimmed mean of the data along the given axis. Trimming is
-    performed on both ends of the distribution.
+performed on both ends of the distribution.
     
-:Inputs: 
-    data : MaskedArray
+*Parameters*:
+    data : {ndarray}
         Data to trim.
-    proportiontocut : float *[0.2]*
+    proportiontocut : {float}
         Proportion of the data to cut from each side of the data . 
         As a result, (2*proportiontocut*n) values are actually trimmed.
-    axis : integer *[None]*
-        Axis along which to perform the trimming.    
+    axis : {integer}
+        Axis along which to perform the trimming. If None, the input array is first 
+        flattened.
     """
     return trim_both(data, proportiontocut=proportiontocut, axis=axis).mean(axis=axis)
 
 #..............................................................................   
 def trimmed_stde(data, proportiontocut=0.2, axis=None):
     """Returns the standard error of the trimmed mean for the input data, 
-    along the given axis. Trimming is performed on both ends of the distribution.
+along the given axis. Trimming is performed on both ends of the distribution.
     
-:Inputs: 
-    data : MaskedArray
+*Parameters*:
+    data : {ndarray}
         Data to trim.
-    proportiontocut : float *[0.2]*
+    proportiontocut : {float}
         Proportion of the data to cut from each side of the data . 
         As a result, (2*proportiontocut*n) values are actually trimmed.
-    axis : integer *[None]*
-        Axis along which to perform the trimming.  
+    axis : {integer}
+        Axis along which to perform the trimming. If None, the input array is first 
+        flattened.
     """
     #........................
     def _trimmed_stde_1D(data, trim=0.2):
@@ -172,7 +187,15 @@
 #.............................................................................
 def stde_median(data, axis=None):
     """Returns the McKean-Schrader estimate of the standard error of the sample
-    median along the given axis.
+median along the given axis.
+
+    
+*Parameters*:
+    data : {ndarray}
+        Data to trim.
+    axis : {integer}
+        Axis along which to perform the trimming. If None, the input array is first 
+        flattened.
     """
     def _stdemed_1D(data):
         sorted = numpy.sort(data.compressed())
@@ -217,18 +240,18 @@
     - (.4,.4)  : approximately quantile unbiased (Cunnane)
     - (.35,.35): APL, used with PWM
 
-:Parameters:
-    x : Sequence
+*Parameters*:
+    x : {sequence}
         Input data, as a sequence or array of dimension at most 2.
-    prob : Sequence *[(0.25, 0.5, 0.75)]*
+    prob : {sequence}
         List of quantiles to compute.
-    alpha : Float (*[0.4]*)
+    alpha : {float}
         Plotting positions parameter.
-    beta : Float (*[0.4]*)
+    beta : {float}
         Plotting positions parameter.
-    axis : Integer *[None]*
-        Axis along which to compute quantiles. If *None*, uses the whole 
-        (flattened/compressed) dataset.
+    axis : {integer}
+        Axis along which to perform the trimming. If None, the input array is first 
+        flattened.
     """
     def _quantiles1D(data,m,p):
         x = numpy.sort(data.compressed())
@@ -302,23 +325,29 @@
     
    
 def cov(x, y=None, rowvar=True, bias=False, strict=False):
-    """
-    Estimate the covariance matrix.
+    """Estimates the covariance matrix.
 
-    If x is a vector, return the variance.  For matrices, returns the covariance 
-    matrix.
 
-    If y is given, it is treated as an additional (set of) variable(s).
+Normalization is by (N-1) where N is the number of observations (unbiased 
+estimate).  If bias is True then normalization is by N.
 
-    Normalization is by (N-1) where N is the number of observations (unbiased 
-    estimate).  If bias is True then normalization is by N.
-
-    If rowvar is non-zero (default), then each row is a variable with observations 
-    in the columns, otherwise each column is a variable  and the observations  are 
-    in the rows.
-    
-    If strict is True, masked values are propagated: if a masked value appears in 
-    a row or column, the whole row or column is considered masked.
+*Parameters*:
+    x : {ndarray}
+        Input data. If x is a 1D array, returns the variance. If x is a 2D array,
+        returns the covariance matrix.
+    y : {ndarray}, optional
+        Optional set of variables.
+    rowvar : {boolean}
+        If rowvar is true, then each row is a variable with obersvations in columns.
+        If rowvar is False, each column is a variable and the observations are in
+        the rows.
+    bias : {boolean}
+        Whether to use a biased or unbiased estimate of the covariance.
+        If bias is True, then the normalization is by N, the number of observations.
+        Otherwise, the normalization is by (N-1)
+    strict : {boolean}
+        If strict is True, masked values are propagated: if a masked value appears in 
+        a row or column, the whole row or column is considered masked.
     """
     X = narray(x, ndmin=2, subok=True, dtype=float)
     if X.shape[0] == 1:
@@ -350,7 +379,7 @@
 
 def idealfourths(data, axis=None):
     """Returns an estimate of the interquartile range of the data along the given
-    axis, as computed with the ideal fourths.
+axis, as computed with the ideal fourths.
     """
     def _idf(data):
         x = numpy.sort(data.compressed())
@@ -368,13 +397,13 @@
     
     
 def rsh(data, points=None):
-    """Evalutates Rosenblatt's shifted histogram estimators for each
-    point of 'points' on the dataset 'data'.
+    """Evalutates Rosenblatt's shifted histogram estimators for each point 
+on the dataset 'data'.
     
-:Inputs:
-    data : sequence
-        Input data. Masked values are discarded.
-    points : 
+*Parameters* :
+    data : {sequence}
+        Input data. Masked values are ignored.
+    points : {sequence}
         Sequence of points where to evaluate Rosenblatt shifted histogram. 
         If None, use the data.        
     """

Modified: trunk/scipy/sandbox/maskedarray/testutils.py
===================================================================
--- trunk/scipy/sandbox/maskedarray/testutils.py	2007-10-03 00:06:40 UTC (rev 3389)
+++ trunk/scipy/sandbox/maskedarray/testutils.py	2007-10-03 01:46:24 UTC (rev 3390)
@@ -22,13 +22,14 @@
 from core import filled, equal, less
 
 #------------------------------------------------------------------------------
-def approx (a, b, fill_value=1, rtol=1.e-5, atol=1.e-8):
+def approx (a, b, fill_value=True, rtol=1.e-5, atol=1.e-8):
     """Returns true if all components of a and b are equal subject to given tolerances.
-    If fill_value is 1, masked values considered equal.
-    If fill_value is 0, masked values considered unequal.
-    The relative error rtol should be positive and << 1.0
-    The absolute error atol comes into play for those elements of b that are 
-    very small or zero; it says how small a must be also.
+    
+If fill_value is True, masked values considered equal. Otherwise, masked values
+are considered unequal.
+The relative error rtol should be positive and << 1.0
+The absolute error atol comes into play for those elements of b that are very 
+small or zero; it says how small a must be also.
     """
     m = mask_or(getmask(a), getmask(b))
     d1 = filled(a)
@@ -183,8 +184,7 @@
                          header='Arrays are not equal')
 ##............................
 def fail_if_array_equal(x, y, err_msg=''):
-    """Raises an assertion error if two masked arrays are not equal 
-    (elem by elem.)"""
+    "Raises an assertion error if two masked arrays are not equal (elementwise)."
     def compare(x,y):
         
         return (not N.alltrue(approx(x, y)))



More information about the Scipy-svn mailing list