[Scipy-svn] r3390 - trunk/scipy/sandbox/maskedarray
scipy-svn at scipy.org
scipy-svn at scipy.org
Tue Oct 2 21:46:32 EDT 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