diff options
Diffstat (limited to 'numpy')
| -rw-r--r-- | numpy/ma/core.py | 131 | ||||
| -rw-r--r-- | numpy/ma/extras.py | 122 |
2 files changed, 152 insertions, 101 deletions
diff --git a/numpy/ma/core.py b/numpy/ma/core.py index 1f87675d3..2d990447b 100644 --- a/numpy/ma/core.py +++ b/numpy/ma/core.py @@ -1,19 +1,22 @@ # pylint: disable-msg=E1002 """ -MA: a facility for dealing with missing observations -MA is generally used as a numpy.array look-alike. -by Paul F. Dubois. +numpy.ma : a package to handle missing or invalid values. + +This package was initially written for numarray by Paul F. Dubois +at Lawrence Livermore National Laboratory. +In 2006, the package was completely rewritten by Pierre Gerard-Marchant +(University of Georgia) to make the MaskedArray class a subclass of ndarray, +and to improve support of structured arrays. + Copyright 1999, 2000, 2001 Regents of the University of California. Released for unlimited redistribution. -Adapted for numpy_core 2005 by Travis Oliphant and -(mainly) Paul Dubois. - +* Adapted for numpy_core 2005 by Travis Oliphant and (mainly) Paul Dubois. * Subclassing of the base ndarray 2006 by Pierre Gerard-Marchant (pgmdevlist_AT_gmail_DOT_com) * Improvements suggested by Reggie Dugard (reggie_AT_merfinllc_DOT_com) -:author: Pierre Gerard-Marchant +.. moduleauthor:: Pierre Gerard-Marchant """ @@ -1106,7 +1109,7 @@ def flatten_mask(mask): def masked_where(condition, a, copy=True): """ - Return ``a`` as an array masked where ``condition`` is True. + Return ``a`` as an array masked where ``condition`` is ``True``. Masked values of ``a`` or ``condition`` are kept. Parameters @@ -1139,7 +1142,7 @@ def masked_where(condition, a, copy=True): def masked_greater(x, value, copy=True): """ - Return the array `x` masked where (x > value). + Return the array `x` masked where ``(x > value)``. Any value of mask already masked is kept masked. """ @@ -1147,29 +1150,33 @@ def masked_greater(x, value, copy=True): def masked_greater_equal(x, value, copy=True): - "Shortcut to masked_where, with condition = (x >= value)." + "Shortcut to masked_where, with condition ``(x >= value)``." return masked_where(greater_equal(x, value), x, copy=copy) def masked_less(x, value, copy=True): - "Shortcut to masked_where, with condition = (x < value)." + "Shortcut to masked_where, with condition ``(x < value)``." return masked_where(less(x, value), x, copy=copy) def masked_less_equal(x, value, copy=True): - "Shortcut to masked_where, with condition = (x <= value)." + "Shortcut to masked_where, with condition ``(x <= value)``." return masked_where(less_equal(x, value), x, copy=copy) def masked_not_equal(x, value, copy=True): - "Shortcut to masked_where, with condition = (x != value)." + "Shortcut to masked_where, with condition ``(x != value)``." return masked_where(not_equal(x, value), x, copy=copy) def masked_equal(x, value, copy=True): """ - Shortcut to masked_where, with condition = (x == value). For - floating point, consider ``masked_values(x, value)`` instead. + Shortcut to masked_where, with condition ``(x == value)``. + + See Also + -------- + masked_where : base function + masked_values : equivalent function for floats. """ # An alternative implementation relies on filling first: probably not needed. @@ -1755,7 +1762,8 @@ class MaskedArray(ndarray): return #.................................. def __array_wrap__(self, obj, context=None): - """Special hook for ufuncs. + """ + Special hook for ufuncs. Wraps the numpy array and sets the mask according to context. """ result = obj.view(type(self)) @@ -1988,7 +1996,8 @@ class MaskedArray(ndarray): ndarray.__setitem__(_data, indx, dindx) _mask[indx] = mindx return - #............................................ + + def __getslice__(self, i, j): """x.__getslice__(i, j) <==> x[i:j] @@ -1997,7 +2006,8 @@ class MaskedArray(ndarray): """ return self.__getitem__(slice(i, j)) - #........................ + + def __setslice__(self, i, j, value): """x.__setslice__(i, j, value) <==> x[i:j]=value @@ -2006,7 +2016,8 @@ class MaskedArray(ndarray): """ self.__setitem__(slice(i, j), value) - #............................................ + + def __setmask__(self, mask, copy=False): """Set the mask. @@ -2107,6 +2118,10 @@ class MaskedArray(ndarray): """ self._hardmask = False + hardmask = property(fget=lambda self: self._hardmask, + doc="Hardness of the mask") + + def unshare_mask(self): """Copy the mask and set the sharedmask flag to False. @@ -2115,6 +2130,9 @@ class MaskedArray(ndarray): self._mask = self._mask.copy() self._sharedmask = False + sharedmask = property(fget=lambda self: self._sharedmask, + doc="Share status of the mask (read-only).") + def shrink_mask(self): """Reduce a mask to nomask when possible. @@ -2124,6 +2142,10 @@ class MaskedArray(ndarray): self._mask = nomask #............................................ + + baseclass = property(fget= lambda self:self._baseclass, + doc="Class of the underlying data (read-only).") + def _get_data(self): """Return the current data, as a view of the original underlying data. @@ -2179,23 +2201,23 @@ class MaskedArray(ndarray): def filled(self, fill_value=None): - """Return a copy of self._data, where masked values are filled - with fill_value. + """ + Return a copy of self, where masked values are filled with `fill_value`. - If fill_value is None, self.fill_value is used instead. + If `fill_value` is None, `self.fill_value` is used instead. - Notes - ----- - + Subclassing is preserved - + The result is NOT a MaskedArray ! + Notes + ----- + + Subclassing is preserved + + The result is NOT a MaskedArray ! - Examples - -------- - >>> x = np.ma.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'> + Examples + -------- + >>> x = np.ma.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 @@ -2502,7 +2524,7 @@ class MaskedArray(ndarray): return self #... def __ipow__(self, other): - "Raise self to the power other, in place" + "Raise self to the power other, in place." other_data = getdata(other) other_mask = getmask(other) ndarray.__ipow__(self._data, np.where(self._mask, 1, other_data)) @@ -3728,6 +3750,7 @@ class MaskedArray(ndarray): def toflex(self): """ Transforms a MaskedArray into a flexible-type array with two fields: + * the ``_data`` field stores the ``_data`` part of the array; * the ``_mask`` field stores the ``_mask`` part of the array; @@ -4563,7 +4586,8 @@ outer.__doc__ = doc_note(np.outer.__doc__, outerproduct = outer def allequal (a, b, fill_value=True): - """Return True if all entries of a and b are equal, using + """ + Return True if all entries of a and b are equal, using fill_value as a truth value where either or both are masked. """ @@ -4654,9 +4678,9 @@ def allclose (a, b, masked_equal=True, rtol=1.e-5, atol=1.e-8, fill_value=None): return np.all(d) #.............................................................................. -def asarray(a, dtype=None): +def asarray(a, dtype=None, order=None): """ - Convert the input to a masked array. + Convert the input `a` to a masked array of the given datatype. Parameters ---------- @@ -4674,23 +4698,34 @@ def asarray(a, dtype=None): ------- out : ndarray MaskedArray interpretation of `a`. No copy is performed if the input - is already an ndarray. If `a` is a subclass of ndarray, a base - class ndarray is returned. - Return 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. + is already an ndarray. If `a` is a subclass of MaskedArray, a base + class MaskedArray is returned. """ return masked_array(a, dtype=dtype, copy=False, keep_mask=True, subok=False) def asanyarray(a, dtype=None): - """asanyarray(data, dtype) = array(data, dtype, copy=0, subok=1) + """ + Convert the input `a` to a masked array of the given datatype. + If `a` is a subclass of MaskedArray, its class is conserved. - Return 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. + Parameters + ---------- + a : array_like + Input data, in any form that can be converted to an array. This + includes lists, lists of tuples, tuples, tuples of tuples, tuples + of lists and ndarrays. + dtype : data-type, optional + By default, the data-type is inferred from the input data. + order : {'C', 'F'}, optional + Whether to use row-major ('C') or column-major ('FORTRAN') memory + representation. Defaults to 'C'. + + Returns + ------- + out : ndarray + MaskedArray interpretation of `a`. No copy is performed if the input + is already an ndarray. """ return masked_array(a, dtype=dtype, copy=False, keep_mask=True, subok=True) diff --git a/numpy/ma/extras.py b/numpy/ma/extras.py index cf80180e4..006292cd5 100644 --- a/numpy/ma/extras.py +++ b/numpy/ma/extras.py @@ -45,22 +45,19 @@ from numpy.linalg import lstsq #............................................................................... def issequence(seq): """Is seq a sequence (ndarray, list or tuple)?""" - if isinstance(seq, ndarray): - return True - elif isinstance(seq, tuple): - return True - elif isinstance(seq, list): + if isinstance(seq, (ndarray, tuple, list)): return True return False def count_masked(arr, axis=None): - """Count the number of masked elements along the given axis. + """ + Count the number of masked elements along the given axis. Parameters ---------- - axis : int, optional - Axis along which to count. - If None (default), a flattened version of the array is used. + axis : int, optional + Axis along which to count. + If None (default), a flattened version of the array is used. """ m = getmaskarray(arr) @@ -252,7 +249,8 @@ apply_along_axis.__doc__ = np.apply_along_axis.__doc__ def average(a, axis=None, weights=None, returned=False): - """Average the array over the given axis. + """ + Average the array over the given axis. Parameters ---------- @@ -440,10 +438,10 @@ def median(a, axis=None, out=None, overwrite_input=False): #.............................................................................. def compress_rowcols(x, axis=None): """ - Suppress the rows and/or columns of a 2D array that contains + Suppress the rows and/or columns of a 2D array that contain masked values. - The suppression behavior is selected with the `axis`parameter. + 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. @@ -482,13 +480,15 @@ def compress_rowcols(x, axis=None): return x._data[idxr][:,idxc] def compress_rows(a): - """Suppress whole rows of a 2D array that contain masked values. + """ + Suppress whole rows of a 2D array that contain masked values. """ return compress_rowcols(a, 0) def compress_cols(a): - """Suppress whole columnss of a 2D array that contain masked values. + """ + Suppress whole columns of a 2D array that contain masked values. """ return compress_rowcols(a, 1) @@ -530,30 +530,35 @@ def mask_rowcols(a, axis=None): return a def mask_rows(a, axis=None): - """Mask whole rows of a 2D array that contain masked values. + """ + Mask whole rows of a 2D array that contain masked values. Parameters ---------- - axis : int, optional - Axis along which to perform the operation. - If None, applies to a flattened version of the array. + axis : int, optional + Axis along which to perform the operation. + If None, applies to a flattened version of the array. + """ return mask_rowcols(a, 0) def mask_cols(a, axis=None): - """Mask whole columns of a 2D array that contain masked values. + """ + Mask whole columns of a 2D array that contain masked values. Parameters ---------- - axis : int, optional - Axis along which to perform the operation. - If None, applies to a flattened version of the array. + axis : int, optional + Axis along which to perform the operation. + If None, applies to a flattened version of the array. + """ return mask_rowcols(a, 1) def dot(a,b, strict=False): - """Return the dot product of two 2D masked arrays a and b. + """ + Return 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. If strict is True, @@ -584,24 +589,25 @@ def dot(a,b, strict=False): #............................................................................... def ediff1d(array, to_end=None, to_begin=None): - """Return the differences between consecutive elements of an + """ + Return 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. + 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]). + ed : {array} + The differences. Loosely, this will be (ary[1:] - ary[:-1]). """ a = masked_array(array, copy=True) @@ -747,7 +753,8 @@ def cov(x, y=None, rowvar=True, bias=False, allow_masked=True): def corrcoef(x, y=None, rowvar=True, bias=False, allow_masked=True): - """The correlation coefficients formed from the array x, where the + """ + The correlation coefficients formed from the array x, where the rows are the observations, and the columns are variables. corrcoef(x,y) where x and y are 1d arrays is the same as @@ -818,7 +825,8 @@ def corrcoef(x, y=None, rowvar=True, bias=False, allow_masked=True): #####-------------------------------------------------------------------------- class MAxisConcatenator(AxisConcatenator): - """Translate slice objects to concatenation along an axis. + """ + Translate slice objects to concatenation along an axis. """ @@ -877,11 +885,13 @@ class MAxisConcatenator(AxisConcatenator): return self._retval(res) class mr_class(MAxisConcatenator): - """Translate slice objects to concatenation along the first axis. + """ + Translate slice objects to concatenation along the first axis. - For example: - >>> np.ma.mr_[np.ma.array([1,2,3]), 0, 0, np.ma.array([4,5,6])] - array([1, 2, 3, 0, 0, 4, 5, 6]) + Examples + -------- + >>> np.ma.mr_[np.ma.array([1,2,3]), 0, 0, np.ma.array([4,5,6])] + array([1, 2, 3, 0, 0, 4, 5, 6]) """ def __init__(self): @@ -894,7 +904,8 @@ mr_ = mr_class() #####-------------------------------------------------------------------------- def flatnotmasked_edges(a): - """Find the indices of the first and last not masked values in a + """ + Find the indices of the first and last not masked values in a 1D masked array. If all values are masked, returns None. """ @@ -907,8 +918,10 @@ def flatnotmasked_edges(a): else: return None + def notmasked_edges(a, axis=None): - """Find the indices of the first and last not masked values along + """ + Find the indices of the first and last not masked values along the given axis in a masked array. If all values are masked, return None. Otherwise, return a list @@ -917,9 +930,10 @@ def notmasked_edges(a, axis=None): Parameters ---------- - axis : int, optional - Axis along which to perform the operation. - If None, applies to a flattened version of the array. + axis : int, optional + Axis along which to perform the operation. + If None, applies to a flattened version of the array. + """ a = asarray(a) if axis is None or a.ndim == 1: @@ -929,8 +943,10 @@ def notmasked_edges(a, axis=None): return [tuple([idx[i].min(axis).compressed() for i in range(a.ndim)]), tuple([idx[i].max(axis).compressed() for i in range(a.ndim)]),] + def flatnotmasked_contiguous(a): - """Find contiguous unmasked data in a flattened masked array. + """ + Find contiguous unmasked data in a flattened masked array. Return a sorted sequence of slices (start index, end index). @@ -950,22 +966,22 @@ def flatnotmasked_contiguous(a): return result def notmasked_contiguous(a, axis=None): - """Find contiguous unmasked data in a masked array along the given - axis. + """ + Find contiguous unmasked data in a masked array along the given axis. Parameters ---------- - axis : int, optional - Axis along which to perform the operation. - If None, applies to a flattened version of the array. + axis : int, optional + Axis along which to perform the operation. + If None, applies to a flattened version of the array. Returns ------- - A sorted sequence of slices (start index, end index). + A sorted sequence of slices (start index, end index). Notes ----- - Only accepts 2D arrays at most. + Only accepts 2D arrays at most. """ a = asarray(a) |