2
numpy.ma : a package to handle missing or invalid values.
4
This package was initially written for numarray by Paul F. Dubois
5
at Lawrence Livermore National Laboratory.
6
In 2006, the package was completely rewritten by Pierre Gerard-Marchant
7
(University of Georgia) to make the MaskedArray class a subclass of ndarray,
8
and to improve support of structured arrays.
11
Copyright 1999, 2000, 2001 Regents of the University of California.
12
Released for unlimited redistribution.
14
* Adapted for numpy_core 2005 by Travis Oliphant and (mainly) Paul Dubois.
15
* Subclassing of the base `ndarray` 2006 by Pierre Gerard-Marchant
16
(pgmdevlist_AT_gmail_DOT_com)
17
* Improvements suggested by Reggie Dugard (reggie_AT_merfinllc_DOT_com)
19
.. moduleauthor:: Pierre Gerard-Marchant
1
22
# pylint: disable-msg=E1002
3
24
numpy.ma : a package to handle missing or invalid values.
5
26
This package was initially written for numarray by Paul F. Dubois
6
at Lawrence Livermore National Laboratory.
27
at Lawrence Livermore National Laboratory.
7
28
In 2006, the package was completely rewritten by Pierre Gerard-Marchant
8
29
(University of Georgia) to make the MaskedArray class a subclass of ndarray,
9
30
and to improve support of structured arrays.
29
50
'amax', 'amin', 'anom', 'anomalies', 'any', 'arange',
30
51
'arccos', 'arccosh', 'arcsin', 'arcsinh', 'arctan', 'arctan2',
31
52
'arctanh', 'argmax', 'argmin', 'argsort', 'around',
32
'array', 'asarray','asanyarray',
53
'array', 'asarray', 'asanyarray',
33
54
'bitwise_and', 'bitwise_or', 'bitwise_xor',
34
55
'ceil', 'choose', 'clip', 'common_fill_value', 'compress',
35
56
'compressed', 'concatenate', 'conjugate', 'copy', 'cos', 'cosh',
36
57
'count', 'cumprod', 'cumsum',
37
'default_fill_value', 'diag', 'diagonal', 'divide', 'dump', 'dumps',
58
'default_fill_value', 'diag', 'diagonal', 'diff', 'divide', 'dump',
38
60
'empty', 'empty_like', 'equal', 'exp', 'expand_dims',
39
61
'fabs', 'flatten_mask', 'fmod', 'filled', 'floor', 'floor_divide',
40
62
'fix_invalid', 'flatten_structured_array', 'frombuffer', 'fromflex',
42
'getdata','getmask', 'getmaskarray', 'greater', 'greater_equal',
64
'getdata', 'getmask', 'getmaskarray', 'greater', 'greater_equal',
43
65
'harden_mask', 'hypot',
44
66
'identity', 'ids', 'indices', 'inner', 'innerproduct',
45
67
'isMA', 'isMaskedArray', 'is_mask', 'is_masked', 'isarray',
48
70
'make_mask', 'make_mask_descr', 'make_mask_none', 'mask_or',
49
71
'masked', 'masked_array', 'masked_equal', 'masked_greater',
50
72
'masked_greater_equal', 'masked_inside', 'masked_invalid',
51
'masked_less','masked_less_equal', 'masked_not_equal',
52
'masked_object','masked_outside', 'masked_print_option',
53
'masked_singleton','masked_values', 'masked_where', 'max', 'maximum',
73
'masked_less', 'masked_less_equal', 'masked_not_equal',
74
'masked_object', 'masked_outside', 'masked_print_option',
75
'masked_singleton', 'masked_values', 'masked_where', 'max', 'maximum',
54
76
'maximum_fill_value', 'mean', 'min', 'minimum', 'minimum_fill_value',
56
78
'negative', 'nomask', 'nonzero', 'not_equal',
154
177
def default_fill_value(obj):
156
Calculate the default fill value for the argument object.
179
Return the default fill value for the argument object.
181
The default filling value depends on the datatype of the input
182
array or the type of the input scalar:
198
obj : ndarray, dtype or scalar
199
The array data-type or scalar for which the default fill value
205
The default fill value.
209
>>> np.ma.default_fill_value(1)
211
>>> np.ma.default_fill_value(np.array([1.1, 2., np.pi]))
213
>>> np.ma.default_fill_value(np.dtype(complex))
159
if hasattr(obj,'dtype'):
217
if hasattr(obj, 'dtype'):
160
218
defval = _check_fill_value(None, obj.dtype)
161
219
elif isinstance(obj, np.dtype):
163
defval = default_filler[obj.subdtype[0].kind]
221
defval = default_filler.get(obj.subdtype[0].kind, '?')
165
defval = default_filler[obj.kind]
223
defval = default_filler.get(obj.kind, '?')
166
224
elif isinstance(obj, float):
167
225
defval = default_filler['f']
168
226
elif isinstance(obj, int) or isinstance(obj, long):
169
227
defval = default_filler['i']
170
228
elif isinstance(obj, str):
171
229
defval = default_filler['S']
230
elif isinstance(obj, unicode):
231
defval = default_filler['U']
172
232
elif isinstance(obj, complex):
173
233
defval = default_filler['c']
190
250
def minimum_fill_value(obj):
192
Calculate the default fill value suitable for taking the minimum of ``obj``.
252
Return the maximum value that can be represented by the dtype of an object.
254
This function is useful for calculating a fill value suitable for
255
taking the minimum of an array with a given dtype.
259
obj : ndarray or dtype
260
An object that can be queried for it's numeric type.
265
The maximum representable value.
270
If `obj` isn't a suitable numeric type.
274
maximum_fill_value : The inverse function.
275
set_fill_value : Set the filling value of a masked array.
276
MaskedArray.fill_value : Return current fill value.
280
>>> import numpy.ma as ma
282
>>> ma.minimum_fill_value(a)
285
>>> ma.minimum_fill_value(a)
288
An array of numeric data can also be passed.
290
>>> a = np.array([1, 2, 3], dtype=np.int8)
291
>>> ma.minimum_fill_value(a)
293
>>> a = np.array([1, 2, 3], dtype=np.float32)
294
>>> ma.minimum_fill_value(a)
195
298
errmsg = "Unsuitable type for calculating minimum."
210
313
def maximum_fill_value(obj):
212
Calculate the default fill value suitable for taking the maximum of ``obj``.
315
Return the minimum value that can be represented by the dtype of an object.
317
This function is useful for calculating a fill value suitable for
318
taking the maximum of an array with a given dtype.
322
obj : {ndarray, dtype}
323
An object that can be queried for it's numeric type.
328
The minimum representable value.
333
If `obj` isn't a suitable numeric type.
337
minimum_fill_value : The inverse function.
338
set_fill_value : Set the filling value of a masked array.
339
MaskedArray.fill_value : Return current fill value.
343
>>> import numpy.ma as ma
345
>>> ma.maximum_fill_value(a)
348
>>> ma.maximum_fill_value(a)
351
An array of numeric data can also be passed.
353
>>> a = np.array([1, 2, 3], dtype=np.int8)
354
>>> ma.maximum_fill_value(a)
356
>>> a = np.array([1, 2, 3], dtype=np.float32)
357
>>> ma.maximum_fill_value(a)
215
361
errmsg = "Unsuitable type for calculating maximum."
372
519
def common_fill_value(a, b):
374
Return the common filling value of a and b, if any.
375
If a and b have different filling values, returns None.
521
Return the common filling value of two masked arrays, if any.
523
If ``a.fill_value == b.fill_value``, return the fill value,
524
otherwise return None.
529
The masked arrays for which to compare fill values.
533
fill_value : scalar or None
534
The common fill value, or None.
538
>>> x = np.ma.array([0, 1.], fill_value=3)
539
>>> y = np.ma.array([0, 1.], fill_value=3)
540
>>> np.ma.common_fill_value(x, y)
378
544
t1 = get_fill_value(a)
385
551
#####--------------------------------------------------------------------------
386
def filled(a, fill_value = None):
552
def filled(a, fill_value=None):
388
Return `a` as an array where masked data have been replaced by `value`.
554
Return input as an array with masked data replaced by a fill value.
390
If `a` is not a MaskedArray, `a` itself is returned.
391
If `a` is a MaskedArray and `fill_value` is None, `fill_value` is set to
556
If `a` is not a `MaskedArray`, `a` itself is returned.
557
If `a` is a `MaskedArray` and `fill_value` is None, `fill_value` is set to
396
a : maskedarray or array_like
562
a : MaskedArray or array_like
398
fill_value : {var}, optional
399
Filling value. If None, the output of :func:`get_fill_value(a)` is used
564
fill_value : scalar, optional
565
Filling value. Default is None.
574
>>> x = np.ma.array(np.arange(9).reshape(3, 3), mask=[[1, 0, 0],
578
array([[999999, 1, 2],
407
583
if hasattr(a, 'filled'):
492
671
def fix_invalid(a, mask=nomask, copy=True, fill_value=None):
494
Return (a copy of) `a` where invalid data (nan/inf) are masked
495
and replaced by `fill_value`.
673
Return input with invalid data masked and replaced by a fill value.
497
Note that a copy is performed by default (just in case...).
675
Invalid data means values of `nan`, `inf`, etc.
502
A (subclass of) ndarray.
680
Input array, a (subclass of) ndarray.
681
copy : bool, optional
504
682
Whether to use a copy of `a` (True) or to fix `a` in place (False).
505
fill_value : {var}, optional
506
Value used for fixing invalid data. If not given, the output
507
of get_fill_value(a) is used instead.
684
fill_value : scalar, optional
685
Value used for fixing invalid data. Default is None, in which case
686
the ``a.fill_value`` is used.
691
The input array with invalid entries fixed.
695
A copy is performed by default.
699
>>> x = np.ma.array([1., -1, np.nan, np.inf], mask=[1] + [0]*3)
701
masked_array(data = [-- -1.0 nan inf],
702
mask = [ True False False False],
704
>>> np.ma.fix_invalid(x)
705
masked_array(data = [-- -1.0 -- --],
706
mask = [ True False True True],
709
>>> fixed = np.ma.fix_invalid(x)
711
array([ 1.00000000e+00, -1.00000000e+00, 1.00000000e+20,
714
array([ 1., -1., NaN, Inf])
514
717
a = masked_array(a, copy=copy, mask=mask, subok=True)
558
764
def __init__(self, eps):
559
765
"domain_tan(eps) = true where abs(cos(x)) < eps)"
561
768
def __call__ (self, x):
562
769
"Executes the call behavior."
563
770
return umath.less(umath.absolute(umath.cos(x)), self.eps)
564
#............................
565
774
class _DomainSafeDivide:
566
775
"""Define a domain for safe division."""
567
776
def __init__ (self, tolerance=None):
568
777
self.tolerance = tolerance
569
779
def __call__ (self, a, b):
570
780
# Delay the selection of the tolerance to here in order to reduce numpy
571
781
# import times. The calculation of these parameters is a substantial
597
811
#..............................................................................
598
812
class _MaskedUnaryOperation:
599
"""Defines masked version of unary operations, where invalid
600
values are pre-masked.
814
Defines masked version of unary operations, where invalid values are
606
Default filling value (0).
608
Default domain (None).
820
The function for which to define a masked version. Made available
821
as ``_MaskedUnaryOperation.f``.
822
fill : scalar, optional
823
Filling value, default is 0.
824
domain : class instance
825
Domain for the function. Should be one of the ``_Domain*``
826
classes. Default is None.
611
829
def __init__ (self, mufunc, fill=0, domain=None):
625
843
def __call__ (self, a, *args, **kwargs):
626
844
"Execute the call behavior."
846
# Case 1.1. : Domained function
631
847
if self.domain is not None:
632
dm = np.array(self.domain(d1), copy=False)
633
m = np.logical_or(m, dm)
634
# The following two lines control the domain filling methods.
636
# We could use smart indexing : d1[dm] = self.fill ...
637
# ... but np.putmask looks more efficient, despite the copy.
638
np.putmask(d1, dm, self.fill)
639
# Take care of the masked singletong first ...
640
if (not m.ndim) and m:
643
result = self.f(d1, *args, **kwargs)
645
result = np.where(m, d1, self.f(d1, *args, **kwargs))
646
# If result is not a scalar
648
# Get the result subclass:
649
if isinstance(a, MaskedArray):
652
subtype = MaskedArray
653
result = result.view(subtype)
655
result._update_from(a)
848
# Save the error status
849
err_status_ini = np.geterr()
850
np.seterr(divide='ignore', invalid='ignore')
852
result = self.f(d, *args, **kwargs)
853
# Reset the error status
854
np.seterr(**err_status_ini)
856
m = ~umath.isfinite(result)
859
# Case 1.2. : Function without a domain
861
# Get the result and the mask
862
result = self.f(d, *args, **kwargs)
864
# Case 2.1. : The result is scalarscalar
869
# Case 2.2. The result is an array
870
# We need to fill the invalid data back w/ the input
871
# Now, that's plain silly: in C, we would just skip the element and keep
872
# the original, but we do have to do it that way in Python
874
# In case result has a lower dtype than the inputs (as in equal)
876
np.putmask(result, m, d)
880
if isinstance(a, MaskedArray):
883
subtype = MaskedArray
884
result = result.view(subtype)
886
result._update_from(a)
658
889
def __str__ (self):
659
890
return "Masked version of %s. [Invalid values are masked]" % str(self.f)
661
#..............................................................................
662
894
class _MaskedBinaryOperation:
663
"""Define masked version of binary operations, where invalid
896
Define masked version of binary operations, where invalid
664
897
values are pre-masked.
670
Default filling value for the first argument (0).
672
Default filling value for the second argument (0).
674
Default domain (None).
902
The function for which to define a masked version. Made available
903
as ``_MaskedBinaryOperation.f``.
904
domain : class instance
905
Default domain for the function. Should be one of the ``_Domain*``
906
classes. Default is None.
907
fillx : scalar, optional
908
Filling value for the first argument, default is 0.
909
filly : scalar, optional
910
Filling value for the second argument, default is 0.
677
913
def __init__ (self, mbfunc, fillx=0, filly=0):
689
925
def __call__ (self, a, b, *args, **kwargs):
690
926
"Execute the call behavior."
691
m = mask_or(getmask(a), getmask(b), shrink=False)
692
(da, db) = (getdata(a), getdata(b))
693
# Easy case: there's no mask...
695
result = self.f(da, db, *args, **kwargs)
696
# There are some masked elements: run only on the unmasked
927
# Get the data, as ndarray
928
(da, db) = (getdata(a, subok=False), getdata(b, subok=False))
930
(ma, mb) = (getmask(a), getmask(b))
935
m = umath.logical_or(getmaskarray(a), mb)
937
m = umath.logical_or(ma, getmaskarray(b))
698
result = np.where(m, da, self.f(da, db, *args, **kwargs))
699
# Transforms to a (subclass of) MaskedArray if we don't have a scalar
701
result = result.view(get_masked_subclass(a, b))
702
# If we have a mask, make sure it's broadcasted properly
704
result._mask = mask_or(getmaskarray(a), getmaskarray(b))
705
# If some initial masks where not shrunk, don't shrink the result
707
result._mask = make_mask_none(result.shape, result.dtype)
939
m = umath.logical_or(ma, mb)
941
result = self.f(da, db, *args, **kwargs)
948
# Revert result to da where masked
950
np.putmask(result, m, 0)
952
# Transforms to a (subclass of) MaskedArray
953
result = result.view(get_masked_subclass(a, b))
955
# Update the optional info from the inputs
956
if isinstance(b, MaskedArray):
708
957
if isinstance(a, MaskedArray):
709
958
result._update_from(a)
710
if isinstance(b, MaskedArray):
711
960
result._update_from(b)
712
# ... or return masked if we have a scalar and the common mask is True
961
elif isinstance(a, MaskedArray):
962
result._update_from(a)
717
# result = self.f(d1, d2, *args, **kwargs).view(get_masked_subclass(a, b))
718
# if len(result.shape):
719
# if m is not nomask:
720
# result._mask = make_mask_none(result.shape)
721
# result._mask.flat = m
723
# # Force m to be at least 1D
724
# m.shape = m.shape or (1,)
725
# print "Resetting data"
726
# result.data[m].flat = d1.flat
728
# if isinstance(a, MaskedArray):
729
# result._update_from(a)
730
# if isinstance(b, MaskedArray):
731
# result._update_from(b)
736
966
def reduce(self, target, axis=0, dtype=None):
737
967
"""Reduce `target` along the given `axis`."""
830
1066
def __call__(self, a, b, *args, **kwargs):
831
1067
"Execute the call behavior."
836
t = narray(self.domain(da, db), copy=False)
838
mb = mask_or(mb, t, shrink=False)
839
# The following line controls the domain filling
840
if t.size == db.size:
841
db = np.where(t, self.filly, db)
1068
# Get the data and the mask
1069
(da, db) = (getdata(a, subok=False), getdata(b, subok=False))
1070
(ma, mb) = (getmask(a), getmask(b))
1071
# Save the current error status
1072
err_status_ini = np.geterr()
1073
np.seterr(divide='ignore', invalid='ignore')
1075
result = self.f(da, db, *args, **kwargs)
1076
# Reset the error status
1077
np.seterr(**err_status_ini)
1078
# Get the mask as a combination of ma, mb and invalid
1079
m = ~umath.isfinite(result)
1082
# Take care of the scalar case first
843
db = np.where(np.resize(t, db.shape), self.filly, db)
844
# Shrink m if a.mask was nomask, otherwise don't.
845
m = mask_or(ma, mb, shrink=(getattr(a, '_mask', nomask) is nomask))
846
if (not m.ndim) and m:
849
result = self.f(da, db, *args, **kwargs)
851
result = np.where(m, da, self.f(da, db, *args, **kwargs))
853
result = result.view(get_masked_subclass(a, b))
854
# If we have a mask, make sure it's broadcasted properly
856
result._mask = mask_or(getmaskarray(a), mb)
857
# If some initial masks where not shrunk, don't shrink the result
859
result._mask = make_mask_none(result.shape, result.dtype)
1088
# When the mask is True, put back da
1089
np.putmask(result, m, 0)
1091
result = result.view(get_masked_subclass(a, b))
1093
if isinstance(b, MaskedArray):
860
1094
if isinstance(a, MaskedArray):
861
1095
result._update_from(a)
862
if isinstance(b, MaskedArray):
863
1097
result._update_from(b)
1098
elif isinstance(a, MaskedArray):
1099
result._update_from(a)
866
1102
def __str__ (self):
1335
1571
def mask_or (m1, m2, copy=False, shrink=True):
1337
Return the combination of two masks m1 and m2.
1573
Combine two masks with the ``logical_or`` operator.
1339
The masks are combined with the *logical_or* operator, treating
1340
nomask as False. The result may equal m1 or m2 if the other is
1575
The result may be a view on `m1` or `m2` if the other is `nomask`
1349
copy : {False, True}, optional
1350
Whether to return a copy.
1351
shrink : {True, False}, optional
1352
Whether to shrink m to nomask if all its values are False.
1582
copy : bool, optional
1583
If copy is False and one of the inputs is `nomask`, return a view
1584
of the other input mask. Defaults to False.
1585
shrink : bool, optional
1586
Whether to shrink the output to `nomask` if all its values are
1587
False. Defaults to True.
1592
The result masks values that are masked in either `m1` or `m2`.
1357
If m1 and m2 have different flexible dtypes.
1597
If `m1` and `m2` have different flexible dtypes.
1601
>>> m1 = np.ma.make_mask([0, 1, 1, 0])
1602
>>> m2 = np.ma.make_mask([1, 0, 0, 0])
1603
>>> np.ma.mask_or(m1, m2)
1604
array([ True, True, True, False], dtype=bool)
1360
1607
def _recursive_mask_or(m1, m2, newmask):
1395
1642
mask : array_like
1643
Input array, which will be interpreted as booleans.
1400
flattened_mask : ndarray
1647
flattened_mask : ndarray of bools
1648
The flattened input.
1405
1652
>>> mask = np.array([0, 0, 1], dtype=np.bool)
1406
1653
>>> flatten_mask(mask)
1407
1654
array([False, False, True], dtype=bool)
1408
1656
>>> mask = np.array([(0, 0), (0, 1)], dtype=[('a', bool), ('b', bool)])
1409
1657
>>> flatten_mask(mask)
1410
1658
array([False, False, False, True], dtype=bool)
1411
1660
>>> mdtype = [('a', bool), ('b', [('ba', bool), ('bb', bool)])]
1412
1661
>>> mask = np.array([(0, (0, 0)), (0, (0, 1))], dtype=mdtype)
1413
1662
>>> flatten_mask(mask)
1720
1976
# c = umath.equal(d, value)
1721
1977
# m = mask_or(c, getmask(x))
1722
1978
# return array(d, mask=m, copy=copy)
1723
return masked_where(equal(x, value), x, copy=copy)
1979
output = masked_where(equal(x, value), x, copy=copy)
1980
output.fill_value = value
1726
1984
def masked_inside(x, v1, v2, copy=True):
2087
2348
Define a wrapper for basic array methods.
2089
Upon call, returns a masked array, where the new _data array is
2350
Upon call, returns a masked array, where the new ``_data`` array is
2090
2351
the output of the corresponding method called on the original
2093
If onmask is True, the new mask is the output of the method called
2354
If `onmask` is True, the new mask is the output of the method called
2094
2355
on the initial mask. Otherwise, the new mask is just a reference
2095
2356
to the initial mask.
2361
Holds the `onmask` parameter.
2363
The object calling `_arraymethod`.
2100
2368
Name of the function to apply on data.
2102
2370
Whether the mask must be processed also (True) or left
2103
alone (False). Default: True.
2105
The object calling the arraymethod.
2371
alone (False). Default is True. Make available as `_onmask`
2108
2375
def __init__(self, funcname, onmask=True):
2141
2413
#..........................................................
2143
2415
class MaskedIterator(object):
2144
"Define an interator."
2417
Flat iterator object to iterate over masked arrays.
2419
A `MaskedIterator` iterator is returned by ``x.flat`` for any masked array
2420
`x`. It allows iterating over the array as if it were a 1-D array,
2421
either in a for-loop or by calling its `next` method.
2423
Iteration is done in C-contiguous style, with the last index varying the
2424
fastest. The iterator can also be indexed using basic slicing or
2429
MaskedArray.flat : Return a flat iterator over an array.
2430
MaskedArray.flatten : Returns a flattened copy of an array.
2434
`MaskedIterator` is not exported by the `ma` module. Instead of
2435
instantiating a `MaskedIterator` directly, use `MaskedArray.flat`.
2439
>>> x = np.ma.array(arange(6).reshape(2, 3))
2442
<class 'numpy.ma.core.MaskedIterator'>
2453
Extracting more than a single element b indexing the `MaskedIterator`
2454
returns a masked array:
2457
masked_array(data = [2 3],
2459
fill_value = 999999)
2145
2462
def __init__(self, ma):
2147
2464
self.dataiter = ma._data.flat
2230
2572
class MaskedArray(ndarray):
2232
Arrays with possibly masked values. Masked values of True
2233
exclude the corresponding element from any computation.
2236
x = MaskedArray(data, mask=nomask, dtype=None, copy=True,
2237
fill_value=None, keep_mask=True, hard_mask=False, shrink=True)
2574
An array class with possibly masked values.
2576
Masked values of True exclude the corresponding element from any
2581
x = MaskedArray(data, mask=nomask, dtype=None, copy=True,
2582
fill_value=None, keep_mask=True, hard_mask=False,
2243
mask : {nomask, sequence}, optional
2244
Mask. Must be convertible to an array of booleans with
2245
the same shape as data: True indicates a masked (eg.,
2247
dtype : {dtype}, optional
2589
mask : sequence, optional
2590
Mask. Must be convertible to an array of booleans with the same
2591
shape as `data`. True indicates a masked (i.e. invalid) data.
2592
dtype : dtype, optional
2248
2593
Data type of the output.
2249
If dtype is None, the type of the data argument (`data.dtype`) is used.
2250
If dtype is not None and different from `data.dtype`, a copy is performed.
2251
copy : {False, True}, optional
2594
If `dtype` is None, the type of the data argument (``data.dtype``)
2595
is used. If `dtype` is not None and different from ``data.dtype``,
2596
a copy is performed.
2597
copy : bool, optional
2252
2598
Whether to copy the input data (True), or to use a reference instead.
2253
Note: data are NOT copied by default.
2254
subok : {True, False}, optional
2255
Whether to return a subclass of MaskedArray (if possible)
2256
or a plain MaskedArray.
2257
ndmin : {0, int}, optional
2258
Minimum number of dimensions
2259
fill_value : {var}, optional
2600
subok : bool, optional
2601
Whether to return a subclass of `MaskedArray` if possible (True) or a
2602
plain `MaskedArray`. Default is True.
2603
ndmin : int, optional
2604
Minimum number of dimensions. Default is 0.
2605
fill_value : scalar, optional
2260
2606
Value used to fill in the masked values when necessary.
2261
If None, a default based on the datatype is used.
2262
keep_mask : {True, boolean}, optional
2263
Whether to combine mask with the mask of the input data,
2264
if any (True), or to use only mask for the output (False).
2265
hard_mask : {False, boolean}, optional
2266
Whether to use a hard mask or not.
2267
With a hard mask, masked values cannot be unmasked.
2268
shrink : {True, boolean}, optional
2269
Whether to force compression of an empty mask.
2607
If None, a default based on the data-type is used.
2608
keep_mask : bool, optional
2609
Whether to combine `mask` with the mask of the input data, if any
2610
(True), or to use only `mask` for the output (False). Default is True.
2611
hard_mask : bool, optional
2612
Whether to use a hard mask or not. With a hard mask, masked values
2613
cannot be unmasked. Default is False.
2614
shrink : bool, optional
2615
Whether to force compression of an empty mask. Default is True.
2421
2767
_hardmask=getattr(obj, '_hardmask', False),
2422
2768
_sharedmask=getattr(obj, '_sharedmask', False),
2423
2769
_isfield=getattr(obj, '_isfield', False),
2424
_baseclass=getattr(obj,'_baseclass', _baseclass),
2770
_baseclass=getattr(obj, '_baseclass', _baseclass),
2425
2771
_optinfo=_optinfo,
2426
2772
_basedict=_optinfo)
2427
2773
self.__dict__.update(_dict)
2664
3013
# Unshare the mask if necessary to avoid propagation
2665
3014
if not self._isfield:
2666
3015
self.unshare_mask()
2667
_mask = ndarray.__getattribute__(self,'_mask')
3016
_mask = ndarray.__getattribute__(self, '_mask')
2668
3017
# Set the data, then the mask
2669
3018
ndarray.__setitem__(_data, indx, dval)
2670
3019
ndarray.__setitem__(_mask, indx, mval)
2671
elif hasattr(indx, 'dtype') and (indx.dtype==MaskType):
3020
elif hasattr(indx, 'dtype') and (indx.dtype == MaskType):
2672
3021
indx = indx * umath.logical_not(_mask)
2673
3022
ndarray.__setitem__(_data, indx, dval)
2796
3145
#............................................
2797
3146
def harden_mask(self):
2798
"""Force the mask to hard.
3148
Force the mask to hard.
3150
Whether the mask of a masked array is hard or soft is determined by
3151
its `hardmask` property. `harden_mask` sets `hardmask` to True.
2801
3158
self._hardmask = True
2803
3161
def soften_mask(self):
2804
"""Force the mask to soft.
3163
Force the mask to soft.
3165
Whether the mask of a masked array is hard or soft is determined by
3166
its `hardmask` property. `soften_mask` sets `hardmask` to False.
2807
3173
self._hardmask = False
2809
3176
hardmask = property(fget=lambda self: self._hardmask,
2810
3177
doc="Hardness of the mask")
2813
3180
def unshare_mask(self):
2814
"""Copy the mask and set the sharedmask flag to False.
3182
Copy the mask and set the sharedmask flag to False.
3184
Whether the mask is shared between masked arrays can be seen from
3185
the `sharedmask` property. `unshare_mask` ensures the mask is not shared.
3186
A copy of the mask is only made if it was shared.
2817
3193
if self._sharedmask:
2818
3194
self._mask = self._mask.copy()
2819
3195
self._sharedmask = False
2821
3198
sharedmask = property(fget=lambda self: self._sharedmask,
2822
3199
doc="Share status of the mask (read-only).")
2824
3201
def shrink_mask(self):
2825
"""Reduce a mask to nomask when possible.
3203
Reduce a mask to nomask when possible.
3215
>>> x = np.ma.array([[1,2 ], [3, 4]], mask=[0]*4)
3217
array([[False, False],
3218
[False, False]], dtype=bool)
2829
3225
if m.ndim and not m.any():
2830
3226
self._mask = nomask
2832
3229
#............................................
2834
baseclass = property(fget= lambda self:self._baseclass,
3231
baseclass = property(fget=lambda self:self._baseclass,
2835
3232
doc="Class of the underlying data (read-only).")
2837
3234
def _get_data(self):
2838
3235
"""Return the current data, as a view of the original
2839
3236
underlying data.
2844
3241
data = property(fget=_get_data)
2846
3243
def raw_data(self):
2847
"""Return the _data part of the MaskedArray.
2849
DEPRECATED: You should really use ``.data`` instead...
3245
Return the data part of the masked array.
3247
DEPRECATED: You should really use ``.data`` instead.
3251
>>> x = np.ma.array([1, 2, 3], mask=[False, True, False])
3253
masked_array(data = [1 -- 3],
3254
mask = [False True False],
3255
fill_value = 999999)
2852
3260
warnings.warn('Use .data instead.', DeprecationWarning)
2869
3277
doc="Flat version of the array.")
2870
3278
#............................................
2871
3279
def get_fill_value(self):
2872
"""Return the filling value.
3281
Return the filling value of the masked array.
3290
>>> for dt in [np.int32, np.int64, np.float64, np.complex128]:
3291
... np.ma.array([0, 1], dtype=dt).get_fill_value()
3298
>>> x = np.ma.array([0, 1.], fill_value=-np.inf)
3299
>>> x.get_fill_value()
2875
3303
if self._fill_value is None:
2877
3305
return self._fill_value
2879
3307
def set_fill_value(self, value=None):
2880
"""Set the filling value to value.
2882
If value is None, use a default based on the data type.
3309
Set the filling value of the masked array.
3313
value : scalar, optional
3314
The new filling value. Default is None, in which case a default
3315
based on the data type is used.
3319
ma.set_fill_value : Equivalent function.
3323
>>> x = np.ma.array([0, 1.], fill_value=-np.inf)
3326
>>> x.set_fill_value(np.pi)
3332
>>> x.set_fill_value()
2885
3337
self._fill_value = _check_fill_value(value, self.dtype)
2891
3343
def filled(self, fill_value=None):
2893
Return a copy of self, where masked values are filled with `fill_value`.
2895
If `fill_value` is None, `self.fill_value` is used instead.
2899
+ Subclassing is preserved
2900
+ The result is NOT a MaskedArray !
2904
>>> x = np.ma.array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
2906
array([1,2,-999,4,-999])
2907
>>> type(x.filled())
2908
<type 'numpy.ndarray'>
3345
Return a copy of self, where masked values are filled with a fill value.
3347
If `fill_value` is None, `MaskedArray.fill_value` is used instead.
3351
fill_value : scalar, optional
3352
The value to use for invalid entries. Default is None.
3356
The result is **not** a MaskedArray!
3360
>>> x = np.ma.array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
3362
array([1, 2, -999, 4, -999])
3363
>>> type(x.filled())
3364
<type 'numpy.ndarray'>
3366
Subclassing is preserved. This means that if the data part of the masked
3367
array is a matrix, `filled` returns a matrix:
3369
>>> x = np.ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
3371
matrix([[ 1, 999999],
3273
3741
return int(self.item())
3274
3742
#............................................
3275
3743
def get_imag(self):
3276
"Returns the imaginary part."
3745
Return the imaginary part of the masked array.
3747
The returned array is a view on the imaginary part of the `MaskedArray`
3748
whose `get_imag` method is called.
3756
result : MaskedArray
3757
The imaginary part of the masked array.
3761
get_real, real, imag
3765
>>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
3767
masked_array(data = [1.0 -- 1.6],
3768
mask = [False True False],
3277
3772
result = self._data.imag.view(type(self))
3278
3773
result.__setmask__(self._mask)
3280
3775
imag = property(fget=get_imag, doc="Imaginary part.")
3282
3777
def get_real(self):
3283
"Returns the real part."
3779
Return the real part of the masked array.
3781
The returned array is a view on the real part of the `MaskedArray`
3782
whose `get_real` method is called.
3790
result : MaskedArray
3791
The real part of the masked array.
3795
get_imag, real, imag
3799
>>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
3801
masked_array(data = [1.0 -- 3.45],
3802
mask = [False True False],
3284
3806
result = self._data.real.view(type(self))
3285
3807
result.__setmask__(self._mask)
3297
3819
axis : int, optional
3298
Axis along which to count the non-masked elements. If axis is None,
3299
all the non masked elements are counted.
3820
Axis along which to count the non-masked elements. If `axis` is
3821
`None`, all non-masked elements are counted.
3303
result : MaskedArray
3304
A masked array where the mask is True where all data are
3305
masked. If axis is None, returns either a scalar ot the
3306
masked singleton if all values are masked.
3825
result : int or ndarray
3826
If `axis` is `None`, an integer count is returned. When `axis` is
3827
not `None`, an array with shape determined by the lengths of the
3828
remaining axes, is returned.
3832
count_masked : Count masked elements in array or along a given axis.
3836
>>> import numpy.ma as ma
3837
>>> a = ma.arange(6).reshape((2, 3))
3838
>>> a[1, :] = ma.masked
3844
[[False False False]
3846
fill_value = 999999)
3850
When the `axis` keyword is specified an array of appropriate size is
3364
3914
def reshape (self, *s, **kwargs):
3366
Returns a masked array containing the data of a, but with a new shape.
3367
The result is a view to the original array; if this is not possible,
3368
a ValueError is raised.
3916
Give a new shape to the array without changing its data.
3918
Returns a masked array containing the same data, but with a new shape.
3919
The result is a view on the original array; if this is not possible, a
3920
ValueError is raised.
3372
shape : shape tuple or int
3373
The new shape should be compatible with the original shape. If an
3374
integer, then the result will be a 1D array of that length.
3924
shape : int or tuple of ints
3925
The new shape should be compatible with the original shape. If an
3926
integer is supplied, then the result will be a 1-D array of that
3375
3928
order : {'C', 'F'}, optional
3376
3929
Determines whether the array data should be viewed as in C
3377
(row-major) order or FORTRAN (column-major) order.
3930
(row-major) or FORTRAN (column-major) order.
3381
3934
reshaped_array : array
3382
A new view to the array.
3935
A new view on the array.
3939
reshape : Equivalent function in the masked array module.
3940
numpy.ndarray.reshape : Equivalent method on ndarray object.
3941
numpy.reshape : Equivalent function in the NumPy module.
3386
If you want to modify the shape in place, please use ``a.shape = s``
3945
The reshaping operation cannot guarantee that a copy will not be made,
3946
to modify the shape in place, use ``a.shape = s``
3497
4064
#............................................
3498
4065
def ids (self):
3499
"""Return the addresses of the data and mask areas."""
4067
Return the addresses of the data and mask areas.
4075
>>> x = np.ma.array([1, 2, 3], mask=[0, 1, 1])
4077
(166670640, 166659832)
4079
If the array has no mask, the address of `nomask` is returned. This address
4080
is typically not close to the data in memory:
4082
>>> x = np.ma.array([1, 2, 3])
4084
(166691080, 3083169284L)
3500
4087
if self._mask is nomask:
3501
4088
return (self.ctypes.data, id(nomask))
3502
4089
return (self.ctypes.data, self._mask.ctypes.data)
3504
4091
def iscontiguous(self):
3505
"Is the data contiguous?"
4093
Return a boolean indicating whether the data is contiguous.
4101
>>> x = np.ma.array([1, 2, 3])
4102
>>> x.iscontiguous()
4105
`iscontiguous` returns one of the flags of the masked array:
4113
UPDATEIFCOPY : False
3506
4116
return self.flags['CONTIGUOUS']
3508
4118
#............................................
3592
4202
def nonzero(self):
3594
Return the indices of the elements of a that are not zero
3595
nor masked, as a tuple of arrays.
3597
There are as many tuples as dimensions of a, each tuple
3598
contains the indices of the non-zero elements in that
3599
dimension. The corresponding non-zero values can be obtained
3600
with ``a[a.nonzero()]``.
3602
To group the indices by element, rather than dimension, use
3603
instead: ``transpose(a.nonzero())``.
3605
The result of this is always a 2d array, with a row for each
4204
Return the indices of unmasked elements that are not zero.
4206
Returns a tuple of arrays, one for each dimension, containing the
4207
indices of the non-zero elements in that dimension. The corresponding
4208
non-zero values can be obtained with::
4212
To group the indices by element, rather than dimension, use
4215
np.transpose(a.nonzero())
4217
The result of this is always a 2d array, with a row for each non-zero
4226
tuple_of_arrays : tuple
4227
Indices of elements that are non-zero.
4232
Function operating on ndarrays.
4234
Return indices that are non-zero in the flattened version of the input
4237
Equivalent ndarray method.
4241
>>> import numpy.ma as ma
4242
>>> x = ma.array(np.eye(3))
4252
(array([0, 1, 2]), array([0, 1, 2]))
4254
Masked elements are ignored.
4256
>>> x[1, 1] = ma.masked
4263
[[False False False]
4265
[False False False]],
4268
(array([0, 2]), array([0, 2]))
4270
Indices can also be grouped by element.
4272
>>> np.transpose(x.nonzero())
4276
A common use for ``nonzero`` is to find the indices of an array, where
4277
a condition is True. Given an array `a`, the condition `a` > 3 is a
4278
boolean array and since False is interpreted as 0, ma.nonzero(a > 3)
4279
yields the indices of the `a` where the condition is true.
4281
>>> a = ma.array([[1,2,3],[4,5,6],[7,8,9]])
4284
[[False False False]
4290
>>> ma.nonzero(a > 3)
4291
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))
4293
The ``nonzero`` method of the condition array can also be called.
4295
>>> (a > 3).nonzero()
4296
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))
3609
4299
return narray(self.filled(0), copy=False).nonzero()
3693
4385
def cumsum(self, axis=None, dtype=None, out=None):
3695
Return the cumulative sum of the elements along the given axis.
3696
The cumulative sum is calculated over the flattened array by
3697
default, otherwise over the specified axis.
3699
Masked values are set to 0 internally during the computation.
3700
However, their position is saved, and the result will be masked at
3705
axis : {None, -1, int}, optional
3706
Axis along which the sum is computed. The default (`axis` = None) is to
3707
compute over the flattened array. `axis` may be negative, in which case
3708
it counts from the last to the first axis.
3709
dtype : {None, dtype}, optional
3710
Type of the returned array and of the accumulator in which the
3711
elements are summed. If `dtype` is not specified, it defaults
3712
to the dtype of `a`, unless `a` has an integer dtype with a
3713
precision less than that of the default platform integer. In
3714
that case, the default platform integer is used.
3715
out : ndarray, optional
3716
Alternative output array in which to place the result. It must
3717
have the same shape and buffer length as the expected output
3718
but the type will be cast if necessary.
3722
The mask is lost if out is not a valid :class:`MaskedArray` !
3727
A new array holding the result is returned unless ``out`` is
3728
specified, in which case a reference to ``out`` is returned.
3732
>>> marr = np.ma.array(np.arange(10), mask=[0,0,0,1,1,1,0,0,0,0])
3733
>>> print marr.cumsum()
3734
[0 1 3 -- -- -- 9 16 24 33]
3739
Arithmetic is modular when using integer types, and no error is
4387
Return the cumulative sum of the elements along the given axis.
4388
The cumulative sum is calculated over the flattened array by
4389
default, otherwise over the specified axis.
4391
Masked values are set to 0 internally during the computation.
4392
However, their position is saved, and the result will be masked at
4397
axis : {None, -1, int}, optional
4398
Axis along which the sum is computed. The default (`axis` = None) is to
4399
compute over the flattened array. `axis` may be negative, in which case
4400
it counts from the last to the first axis.
4401
dtype : {None, dtype}, optional
4402
Type of the returned array and of the accumulator in which the
4403
elements are summed. If `dtype` is not specified, it defaults
4404
to the dtype of `a`, unless `a` has an integer dtype with a
4405
precision less than that of the default platform integer. In
4406
that case, the default platform integer is used.
4407
out : ndarray, optional
4408
Alternative output array in which to place the result. It must
4409
have the same shape and buffer length as the expected output
4410
but the type will be cast if necessary.
4415
A new array holding the result is returned unless ``out`` is
4416
specified, in which case a reference to ``out`` is returned.
4420
The mask is lost if `out` is not a valid :class:`MaskedArray` !
4422
Arithmetic is modular when using integer types, and no error is
4427
>>> marr = np.ma.array(np.arange(10), mask=[0,0,0,1,1,1,0,0,0,0])
4428
>>> print marr.cumsum()
4429
[0 1 3 -- -- -- 9 16 24 33]
3743
4432
result = self.filled(0).cumsum(axis=axis, dtype=dtype, out=out)
3823
4514
def cumprod(self, axis=None, dtype=None, out=None):
3825
Return the cumulative product of the elements along the given axis.
3826
The cumulative product is taken over the flattened array by
3827
default, otherwise over the specified axis.
3829
Masked values are set to 1 internally during the computation.
3830
However, their position is saved, and the result will be masked at
3835
axis : {None, -1, int}, optional
3836
Axis along which the product is computed. The default
3837
(`axis` = None) is to compute over the flattened array.
3838
dtype : {None, dtype}, optional
3839
Determines the type of the returned array and of the accumulator
3840
where the elements are multiplied. If ``dtype`` has the value ``None`` and
3841
the type of ``a`` is an integer type of precision less than the default
3842
platform integer, then the default platform integer precision is
3843
used. Otherwise, the dtype is the same as that of ``a``.
3844
out : ndarray, optional
3845
Alternative output array in which to place the result. It must
3846
have the same shape and buffer length as the expected output
3847
but the type will be cast if necessary.
3851
The mask is lost if out is not a valid MaskedArray !
3856
A new array holding the result is returned unless out is specified,
3857
in which case a reference to out is returned.
3861
Arithmetic is modular when using integer types, and no error is
4516
Return the cumulative product of the elements along the given axis.
4517
The cumulative product is taken over the flattened array by
4518
default, otherwise over the specified axis.
4520
Masked values are set to 1 internally during the computation.
4521
However, their position is saved, and the result will be masked at
4526
axis : {None, -1, int}, optional
4527
Axis along which the product is computed. The default
4528
(`axis` = None) is to compute over the flattened array.
4529
dtype : {None, dtype}, optional
4530
Determines the type of the returned array and of the accumulator
4531
where the elements are multiplied. If ``dtype`` has the value ``None``
4532
and the type of ``a`` is an integer type of precision less than the
4533
default platform integer, then the default platform integer precision
4534
is used. Otherwise, the dtype is the same as that of ``a``.
4535
out : ndarray, optional
4536
Alternative output array in which to place the result. It must
4537
have the same shape and buffer length as the expected output
4538
but the type will be cast if necessary.
4543
A new array holding the result is returned unless out is specified,
4544
in which case a reference to out is returned.
4548
The mask is lost if `out` is not a valid MaskedArray !
4550
Arithmetic is modular when using integer types, and no error is
3865
4554
result = self.filled(1).cumprod(axis=axis, dtype=dtype, out=out)
3866
4555
if out is not None:
3867
4556
if isinstance(out, MaskedArray):
3875
4564
def mean(self, axis=None, dtype=None, out=None):
3877
Returns the average of the array elements along given axis.
3878
Refer to `numpy.mean` for full documentation.
3882
numpy.mean : equivalent function'
4566
Returns the average of the array elements.
4568
Masked entries are ignored.
4569
The average is taken over the flattened array by default, otherwise over
4570
the specified axis. Refer to `numpy.mean` for the full documentation.
4575
Array containing numbers whose mean is desired. If `a` is not an
4576
array, a conversion is attempted.
4577
axis : int, optional
4578
Axis along which the means are computed. The default is to compute
4579
the mean of the flattened array.
4580
dtype : dtype, optional
4581
Type to use in computing the mean. For integer inputs, the default
4582
is float64; for floating point, inputs it is the same as the input
4584
out : ndarray, optional
4585
Alternative output array in which to place the result. It must have
4586
the same shape as the expected output but the type will be cast if
4591
mean : ndarray, see dtype parameter above
4592
If `out=None`, returns a new array containing the mean values,
4593
otherwise a reference to the output array is returned.
4597
numpy.ma.mean : Equivalent function.
4598
numpy.mean : Equivalent function on non-masked arrays.
4599
numpy.ma.average: Weighted average.
4603
>>> a = np.ma.array([1,2,3], mask=[False, False, True])
4605
masked_array(data = [1 2 --],
4606
mask = [False False True],
4607
fill_value = 999999)
3884
4612
if self._mask is nomask:
3885
4613
result = super(MaskedArray, self).mean(axis=axis, dtype=dtype)
3887
4615
dsum = self.sum(axis=axis, dtype=dtype)
3888
4616
cnt = self.count(axis=axis)
3889
result = dsum*1./cnt
4617
result = dsum * 1. / cnt
3890
4618
if out is not None:
3891
4619
out.flat = result
3892
4620
if isinstance(out, MaskedArray):
3900
4628
def anom(self, axis=None, dtype=None):
3902
Return the anomalies (deviations from the average) along the given axis.
3906
axis : int, optional
3907
Axis along which to perform the operation.
3908
If None, applies to a flattened version of the array.
3909
dtype : {dtype}, optional
3910
Datatype for the intermediary computation.
3911
If not given, the current dtype is used instead.
4630
Compute the anomalies (deviations from the arithmetic mean)
4631
along the given axis.
4633
Returns an array of anomalies, with the same shape as the input and
4634
where the arithmetic mean is computed along the given axis.
4638
axis : int, optional
4639
Axis over which the anomalies are taken.
4640
The default is to use the mean of the flattened array as reference.
4641
dtype : dtype, optional
4642
Type to use in computing the variance. For arrays of integer type
4643
the default is float32; for arrays of float types it is the same as
4648
mean : Compute the mean of the array.
4652
>>> a = np.ma.array([1,2,3])
4654
masked_array(data = [-1. 0. 1.],
3914
4659
m = self.mean(axis, dtype)
3916
4661
return (self - m)
3923
4668
if self._mask is nomask:
3924
4669
return self._data.var(axis=axis, dtype=dtype, out=out, ddof=ddof)
3925
4670
# Some data are masked, yay!
3926
cnt = self.count(axis=axis)-ddof
4671
cnt = self.count(axis=axis) - ddof
3927
4672
danom = self.anom(axis=axis, dtype=dtype)
3928
4673
if iscomplexobj(self):
3929
danom = umath.absolute(danom)**2
4674
danom = umath.absolute(danom) ** 2
3932
4677
dvar = divide(danom.sum(axis), cnt).view(type(self))
3933
4678
# Apply the mask if it's not a scalar
3935
dvar._mask = mask_or(self._mask.all(axis), (cnt<=ddof))
4680
dvar._mask = mask_or(self._mask.all(axis), (cnt <= ddof))
3936
4681
dvar._update_from(self)
3937
elif getattr(dvar,'_mask', False):
4682
elif getattr(dvar, '_mask', False):
3938
4683
# Make sure that masked is returned when the scalar is masked.
3940
4685
if out is not None:
3997
4742
def argsort(self, axis=None, fill_value=None, kind='quicksort',
4000
Return an ndarray of indices that sort the array along the
4001
specified axis. Masked values are filled beforehand to
4006
axis : int, optional
4007
Axis along which to sort. If not given, the flattened array is used.
4008
kind : {'quicksort', 'mergesort', 'heapsort'}, optional
4010
order : list, optional
4011
When `a` is an array with fields defined, this argument specifies
4012
which fields to compare first, second, etc. Not all fields need be
4016
index_array : ndarray, int
4017
Array of indices that sort `a` along the specified axis.
4018
In other words, ``a[index_array]`` yields a sorted `a`.
4022
sort : Describes sorting algorithms used.
4023
lexsort : Indirect stable sort with multiple keys.
4024
ndarray.sort : Inplace sort.
4028
See `sort` for notes on the different sorting algorithms.
4745
Return an ndarray of indices that sort the array along the
4746
specified axis. Masked values are filled beforehand to
4751
axis : int, optional
4752
Axis along which to sort. The default is -1 (last axis).
4753
If None, the flattened array is used.
4754
fill_value : var, optional
4755
Value used to fill the array before sorting.
4756
The default is the `fill_value` attribute of the input array.
4757
kind : {'quicksort', 'mergesort', 'heapsort'}, optional
4759
order : list, optional
4760
When `a` is an array with fields defined, this argument specifies
4761
which fields to compare first, second, etc. Not all fields need be
4766
index_array : ndarray, int
4767
Array of indices that sort `a` along the specified axis.
4768
In other words, ``a[index_array]`` yields a sorted `a`.
4772
sort : Describes sorting algorithms used.
4773
lexsort : Indirect stable sort with multiple keys.
4774
ndarray.sort : Inplace sort.
4778
See `sort` for notes on the different sorting algorithms.
4782
>>> a = np.ma.array([3,2,1], mask=[False, False, True])
4784
masked_array(data = [3 2 --],
4785
mask = [False False True],
4786
fill_value = 999999)
4031
4791
if fill_value is None:
4287
5047
def mini(self, axis=None):
5049
Return the array minimum along the specified axis.
5053
axis : int, optional
5054
The axis along which to find the minima. Default is None, in which case
5055
the minimum value in the whole array is returned.
5059
min : scalar or MaskedArray
5060
If `axis` is None, the result is a scalar. Otherwise, if `axis` is
5061
given and the array is at least 2-D, the result is a masked array with
5062
dimension one smaller than the array on which `mini` is called.
5066
>>> x = np.ma.array(np.arange(6), mask=[0 ,1, 0, 0, 0 ,1]).reshape(3, 2)
5074
masked_array(data = [0 3],
5075
mask = [False False],
5076
fill_value = 999999)
5077
>>> print x.mini(axis=1)
4288
5081
if axis is None:
4289
5082
return minimum(self)
4397
5190
#--------------------------------------------
4398
5191
def tolist(self, fill_value=None):
4400
Copy the data portion of the array to a hierarchical python
4401
list and returns that list.
4403
Data items are converted to the nearest compatible Python
4404
type. Masked values are converted to fill_value. If
4405
fill_value is None, the corresponding entries in the output
4406
list will be ``None``.
5193
Return the data portion of the masked array as a hierarchical Python list.
5195
Data items are converted to the nearest compatible Python type.
5196
Masked values are converted to `fill_value`. If `fill_value` is None,
5197
the corresponding entries in the output list will be ``None``.
5201
fill_value : scalar, optional
5202
The value to use for invalid entries. Default is None.
5207
The Python list representation of the masked array.
5211
>>> x = np.ma.array([[1,2,3], [4,5,6], [7,8,9]], mask=[0] + [1,0]*4)
5213
[[1, None, 3], [None, 5, None], [7, None, 9]]
5215
[[1, -999, 3], [-999, 5, -999], [7, -999, 9]]
4409
5218
if fill_value is not None:
4434
5243
#........................
4435
5244
def tostring(self, fill_value=None, order='C'):
4437
Return a copy of array data as a Python string containing the raw bytes
4438
in the array. The array is filled beforehand.
5246
Return the array data as a string containing the raw bytes in the array.
5248
The array is filled with a fill value before the string conversion.
4442
fill_value : {var}, optional
4443
Value used to fill in the masked values.
4444
If None, uses self.fill_value instead.
4446
Order of the data item in the copy {'C','F','A'}.
4447
'C' -- C order (row major)
4448
'Fortran' -- Fortran order (column major)
4449
'Any' -- Current order of array.
4450
None -- Same as "Any"
5252
fill_value : scalar, optional
5253
Value used to fill in the masked values. Deafult is None, in which
5254
case `MaskedArray.fill_value` is used.
5255
order : {'C','F','A'}, optional
5256
Order of the data item in the copy. Default is 'C'.
5258
- 'C' -- C order (row major).
5259
- 'F' -- Fortran order (column major).
5260
- 'A' -- Any, current order of array.
5261
- None -- Same as 'A'.
4454
As for method:`ndarray.tostring`, information about the shape, dtype...,
4455
but also fill_value will be lost.
5270
As for `ndarray.tostring`, information about the shape, dtype, etc.,
5271
but also about `fill_value`, will be lost.
5275
>>> x = np.ma.array(np.array([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
5277
'\\x01\\x00\\x00\\x00?B\\x0f\\x00?B\\x0f\\x00\\x04\\x00\\x00\\x00'
4458
5280
return self.filled(fill_value).tostring(order=order)
4459
5281
#........................
4460
5282
def tofile(self, fid, sep="", format="%s"):
5284
Save a masked array to a file in binary format.
5287
This function is not implemented yet.
5292
When `tofile` is called.
4461
5295
raise NotImplementedError("Not implemented yet, sorry...")
4463
5297
def toflex(self):
4465
Transforms a MaskedArray into a flexible-type array with two fields:
4467
* the ``_data`` field stores the ``_data`` part of the array;
4468
* the ``_mask`` field stores the ``_mask`` part of the array;
5299
Transforms a masked array into a flexible-type array.
5301
The flexible type array that is returned will have two fields:
5303
* the ``_data`` field stores the ``_data`` part of the array.
5304
* the ``_mask`` field stores the ``_mask`` part of the array.
4472
5312
record : ndarray
4473
A new flexible-type ndarray with two fields: the first element
5313
A new flexible-type `ndarray` with two fields: the first element
4474
5314
containing a value, the second element containing the corresponding
4475
mask boolean. The returned record shape matches self.shape.
5315
mask boolean. The returned record shape matches self.shape.
4479
A side-effect of transforming a masked array into a flexible ndarray is
5319
A side-effect of transforming a masked array into a flexible `ndarray` is
4480
5320
that meta information (``fill_value``, ...) will be lost.
4835
5684
def __call__(self, a, *args, **params):
4836
if isinstance(a, MaskedArray):
4837
return getattr(a, self.__name__).__call__(*args, **params)
4839
#As x is not a MaskedArray, we transform it to a ndarray with asarray
4840
#... and call the corresponding method.
4841
#Except that sometimes it doesn't work (try reshape([1,2,3,4],(2,2)))
4842
#we end up with a "SystemError: NULL result without error in PyObject_Call"
4843
#A dirty trick is then to call the initial numpy function...
4844
method = getattr(narray(a, copy=False), self.__name__)
5685
# Get the method from the array (if possible)
5686
method_name = self.__name__
5687
method = getattr(a, method_name, None)
5688
if method is not None:
4846
5689
return method(*args, **params)
4848
return getattr(np,self.__name__).__call__(a, *args, **params)
5690
# Still here ? Then a is not a MaskedArray
5691
method = getattr(MaskedArray, method_name, None)
5692
if method is not None:
5693
return method(MaskedArray(a), *args, **params)
5694
# Still here ? OK, let's call the corresponding np function
5695
method = getattr(np, method_name)
5696
return method(a, *args, **params)
4850
5698
all = _frommethod('all')
4851
5699
anomalies = anom = _frommethod('anom')
4950
5811
if fill_value is None:
4951
5812
fill_value = default_fill_value(a)
4953
fill_value = - fill_value
5814
fill_value = -fill_value
4956
5817
d = filled(a, fill_value)
4957
5818
return d.argmax(axis=axis)
4958
5819
argmin.__doc__ = MaskedArray.argmax.__doc__
4960
def sort(a, axis=-1, kind='quicksort', order=None, endwith=True, fill_value=None):
5821
def sort(a, axis= -1, kind='quicksort', order=None, endwith=True, fill_value=None):
4961
5822
"Function version of the eponymous method."
4962
5823
a = narray(a, copy=True, subok=True)
4963
5824
if axis is None:
4993
5857
return x.compressed()
4995
5859
def concatenate(arrays, axis=0):
4996
"Concatenate the arrays along the given axis."
5861
Concatenate a sequence of arrays along the given axis.
5865
arrays : sequence of array_like
5866
The arrays must have the same shape, except in the dimension
5867
corresponding to `axis` (the first, by default).
5868
axis : int, optional
5869
The axis along which the arrays will be joined. Default is 0.
5873
result : MaskedArray
5874
The concatenated array with any masked entries preserved.
5878
numpy.concatenate : Equivalent function in the top-level NumPy module.
5882
>>> import numpy.ma as ma
5883
>>> a = ma.arange(3)
5884
>>> a[1] = ma.masked
5885
>>> b = ma.arange(2, 5)
5887
masked_array(data = [0 -- 2],
5888
mask = [False True False],
5889
fill_value = 999999)
5891
masked_array(data = [2 3 4],
5893
fill_value = 999999)
5894
>>> ma.concatenate([a, b])
5895
masked_array(data = [0 -- 2 2 3 4],
5896
mask = [False True False False False False],
5897
fill_value = 999999)
4997
5900
d = np.concatenate([getdata(a) for a in arrays], axis)
4998
5901
rcls = get_masked_subclass(*arrays)
4999
5902
data = d.view(rcls)
5027
5930
Extract a diagonal or construct a diagonal array.
5032
If `v` is a 2-dimensional array, return a copy of
5033
its `k`-th diagonal. If `v` is a 1-dimensional array,
5034
return a 2-dimensional array with `v` on the `k`-th diagonal.
5036
Diagonal in question. The defaults is 0.
5932
This function is the equivalent of `numpy.diag` that takes masked
5933
values into account, see `numpy.diag` for details.
5040
>>> x = np.arange(9).reshape((3,3))
5047
>>> np.diag(np.diag(x))
5937
numpy.diag : Equivalent function for ndarrays.
5053
5940
output = np.diag(v, k).view(MaskedArray)
5059
5946
def expand_dims(x, axis):
5061
Expand the shape of the array by including a new axis before
5948
Expand the shape of an array.
5950
Expands the shape of the array by including a new axis before the one
5951
specified by the `axis` parameter. This function behaves the same as
5952
`numpy.expand_dims` but preserves masked elements.
5956
numpy.expand_dims : Equivalent function in top-level NumPy module.
5960
>>> import numpy.ma as ma
5961
>>> x = ma.array([1, 2, 4])
5962
>>> x[1] = ma.masked
5964
masked_array(data = [1 -- 4],
5965
mask = [False True False],
5966
fill_value = 999999)
5967
>>> np.expand_dims(x, axis=0)
5969
>>> ma.expand_dims(x, axis=0)
5973
[[False True False]],
5974
fill_value = 999999)
5976
The same result can be achieved using slicing syntax with `np.newaxis`.
5978
>>> x[np.newaxis, :]
5982
[[False True False]],
5983
fill_value = 999999)
5065
5986
result = n_expand_dims(x, axis)
5106
6053
return narray(a, copy=False).put(indices, values, mode=mode)
5108
6055
def putmask(a, mask, values): #, mode='raise'):
5109
"""Set a.flat[n] = values[n] for each n where mask.flat[n] is true.
5111
If values is not the same size of a and mask then it will repeat
5112
as necessary. This gives different behavior than
5115
Note: Using a masked array as values will NOT transform a ndarray in
6057
Changes elements of an array based on conditional and input values.
6059
This is the masked array version of `numpy.putmask`, for details see
6068
Using a masked array as `values` will **not** transform a `ndarray` into
5119
6072
# We can't use 'frommethod', the order of arguments is different
5140
6093
def transpose(a, axes=None):
5142
Return a view of the array with dimensions permuted according to axes,
5145
If ``axes`` is None (default), the output view has reversed
5146
dimensions compared to the original.
6095
Permute the dimensions of an array.
6097
This function is exactly equivalent to `numpy.transpose`.
6101
numpy.transpose : Equivalent function in top-level NumPy module.
6105
>>> import numpy.ma as ma
6106
>>> x = ma.arange(4).reshape((2,2))
6107
>>> x[1, 1] = ma.masked
6115
fill_value = 999999)
6123
fill_value = 999999)
5149
6126
#We can't use 'frommethod', as 'transpose' doesn't take keywords
5162
6148
return _tmp.view(MaskedArray)
5164
6150
def resize(x, new_shape):
5165
"""Return a new array with the specified shape.
5167
The total size of the original array can be any size. The new
5168
array is filled with repeated copies of a. If a was masked, the
5169
new array will be masked, and the new mask will be a repetition of
6152
Return a new masked array with the specified size and shape.
6154
This is the masked equivalent of the `numpy.resize` function. The new
6155
array is filled with repeated copies of `x` (in the order that the
6156
data are stored in memory). If `x` is masked, the new array will be
6157
masked, and the new mask will be a repetition of the old one.
6161
numpy.resize : Equivalent function in the top level NumPy module.
6165
>>> import numpy.ma as ma
6166
>>> a = ma.array([[1, 2] ,[3, 4]])
6167
>>> a[0, 1] = ma.masked
6175
fill_value = 999999)
6176
>>> np.resize(a, (3, 3))
6180
>>> ma.resize(a, (3, 3))
6188
[False False False]],
6189
fill_value = 999999)
6191
A MaskedArray is always returned, regardless of the input type.
6193
>>> a = np.array([[1, 2] ,[3, 4]])
6194
>>> ma.resize(a, (3, 3))
6201
fill_value = 999999)
5173
6204
# We can't use _frommethods here, as N.resize is notoriously whiny.
5201
6232
#---- --- Extra functions ---
5202
6233
#####--------------------------------------------------------------------------
5203
6234
def where (condition, x=None, y=None):
5204
"""where(condition | x, y)
6236
Return a masked array with elements from x or y, depending on condition.
5206
Returns a (subclass of) masked array, shaped like condition, where
5207
the elements are x when condition is True, and y otherwise. If
5208
neither x nor y are given, returns a tuple of indices where
5209
condition is True (a la condition.nonzero()).
6238
Returns a masked array, shaped like condition, where the elements
6239
are from `x` when `condition` is True, and from `y` otherwise.
6240
If neither `x` nor `y` are given, the function returns a tuple of
6241
indices where `condition` is True (the result of
6242
``condition.nonzero()``).
5214
The condition to meet. Must be convertible to an integer
5217
Values of the output when the condition is met
5219
Values of the output when the condition is not met.
6246
condition : array_like, bool
6247
The condition to meet. For each True element, yield the corresponding
6248
element from `x`, otherwise from `y`.
6249
x, y : array_like, optional
6250
Values from which to choose. `x` and `y` need to have the same shape
6251
as condition, or be broadcast-able to that shape.
6255
out : MaskedArray or tuple of ndarrays
6256
The resulting masked array if `x` and `y` were given, otherwise
6257
the result of ``condition.nonzero()``.
6261
numpy.where : Equivalent function in the top-level NumPy module.
6265
>>> x = np.ma.array(np.arange(9.).reshape(3, 3), mask=[[0, 1, 0],
6272
>>> np.ma.where(x > 5) # return the indices where x > 5
6273
(array([2, 2]), array([0, 2]))
6275
>>> print np.ma.where(x > 5, x, -3.1416)
6276
[[-3.1416 -- -3.1416]
5222
6281
if x is None and y is None:
5266
This array must contain integers in [0, n-1], where n is the number
6323
This array must contain integers in ``[0, n-1]``, where n is the
5268
6325
choices : sequence of arrays
5269
6326
Choice arrays. The index array and all of the choices should be
5270
6327
broadcastable to the same shape.
5271
6328
out : array, optional
5272
6329
If provided, the result will be inserted into this array. It should
5273
be of the appropriate shape and dtype
6330
be of the appropriate shape and `dtype`.
5274
6331
mode : {'raise', 'wrap', 'clip'}, optional
5275
6332
Specifies how out-of-bounds indices will behave.
5276
'raise' : raise an error
5277
'wrap' : wrap around
5278
'clip' : clip to the range
6334
* 'raise' : raise an error
6335
* 'wrap' : wrap around
6336
* 'clip' : clip to the range
5393
6460
Return True if all entries of a and b are equal, using
5394
6461
fill_value as a truth value where either or both are masked.
6466
Input arrays to compare.
6467
fill_value : bool, optional
6468
Whether masked values in a or b are considered equal (True) or not
6474
Returns True if the two arrays are equal within the given
6475
tolerance, False otherwise. If either array contains NaN,
6476
then False is returned.
6485
>>> a = ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1])
6487
masked_array(data = [10000000000.0 1e-07 --],
6488
mask = [False False True],
6491
>>> b = array([1e10, 1e-7, -42.0])
6493
array([ 1.00000000e+10, 1.00000000e-07, -4.20000000e+01])
6494
>>> ma.allequal(a, b, fill_value=False)
6496
>>> ma.allequal(a, b)
5397
6500
m = mask_or(getmask(a), getmask(b))
5398
6501
if m is nomask:
5422
6525
a, b : array_like
5423
6526
Input arrays to compare.
5424
masked_equal : boolean, optional
6527
masked_equal : bool, optional
5425
6528
Whether masked values in `a` and `b` are considered equal (True) or not
5426
6529
(False). They are considered equal by default.
5427
rtol : Relative tolerance
5428
The relative difference is equal to `rtol` * `b`.
5429
atol : Absolute tolerance
5430
The absolute difference is equal to `atol`.
5431
fill_value : boolean, optional
5432
*Deprecated* - Whether masked values in a or b are considered equal
6530
rtol : float, optional
6531
Relative tolerance. The relative difference is equal to ``rtol * b``.
6533
atol : float, optional
6534
Absolute tolerance. The absolute difference is equal to `atol`.
6536
fill_value : bool, optional
6537
*Deprecated* - Whether masked values in `a` or `b` are considered equal
5433
6538
(True) or not (False).
5438
6543
Returns True if the two arrays are equal within the given
5439
tolerance; False otherwise. If either array contains NaN, then
6544
tolerance, False otherwise. If either array contains NaN, then
5440
6545
False is returned.
5445
numpy.allclose : the non-masked allclose
6550
numpy.allclose : the non-masked `allclose`.
5449
If the following equation is element-wise True, then allclose returns
5452
absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`))
5454
Return True if all elements of a and b are equal subject to
6554
If the following equation is element-wise True, then `allclose` returns
6557
absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`))
6559
Return True if all elements of `a` and `b` are equal subject to
5455
6560
given tolerances.
5511
6617
#..............................................................................
5512
6618
def asarray(a, dtype=None, order=None):
5514
Convert the input `a` to a masked array of the given datatype.
6620
Convert the input to a masked array of the given data-type.
6622
No copy is performed if the input is already an `ndarray`. If `a` is
6623
a subclass of `MaskedArray`, a base class `MaskedArray` is returned.
5519
Input data, in any form that can be converted to an array. This
6628
Input data, in any form that can be converted to a masked array. This
5520
6629
includes lists, lists of tuples, tuples, tuples of tuples, tuples
5521
of lists and ndarrays.
5522
dtype : data-type, optional
6630
of lists, ndarrays and masked arrays.
6631
dtype : dtype, optional
5523
6632
By default, the data-type is inferred from the input data.
5524
6633
order : {'C', 'F'}, optional
5525
6634
Whether to use row-major ('C') or column-major ('FORTRAN') memory
5526
representation. Defaults to 'C'.
6635
representation. Default is 'C'.
5531
MaskedArray interpretation of `a`. No copy is performed if the input
5532
is already an ndarray. If `a` is a subclass of MaskedArray, a base
5533
class MaskedArray is returned.
6640
Masked array interpretation of `a`.
6644
asanyarray : Similar to `asarray`, but conserves subclasses.
6648
>>> x = np.arange(10.).reshape(2, 5)
6650
array([[ 0., 1., 2., 3., 4.],
6651
[ 5., 6., 7., 8., 9.]])
6652
>>> np.ma.asarray(x)
6659
>>> type(np.ma.asarray(x))
6660
<class 'numpy.ma.core.MaskedArray'>
5536
6663
return masked_array(a, dtype=dtype, copy=False, keep_mask=True, subok=False)
5538
6665
def asanyarray(a, dtype=None):
5540
Convert the input `a` to a masked array of the given datatype.
5541
If `a` is a subclass of MaskedArray, its class is conserved.
6667
Convert the input to a masked array, conserving subclasses.
6669
If `a` is a subclass of `MaskedArray`, its class is conserved.
6670
No copy is performed if the input is already an `ndarray`.
5546
Input data, in any form that can be converted to an array. This
5547
includes lists, lists of tuples, tuples, tuples of tuples, tuples
5548
of lists and ndarrays.
5549
dtype : data-type, optional
6675
Input data, in any form that can be converted to an array.
6676
dtype : dtype, optional
5550
6677
By default, the data-type is inferred from the input data.
5551
6678
order : {'C', 'F'}, optional
5552
6679
Whether to use row-major ('C') or column-major ('FORTRAN') memory
5553
representation. Defaults to 'C'.
6680
representation. Default is 'C'.
5558
MaskedArray interpretation of `a`. No copy is performed if the input
5559
is already an ndarray.
6685
MaskedArray interpretation of `a`.
6689
asarray : Similar to `asanyarray`, but does not conserve subclass.
6693
>>> x = np.arange(10.).reshape(2, 5)
6695
array([[ 0., 1., 2., 3., 4.],
6696
[ 5., 6., 7., 8., 9.]])
6697
>>> np.ma.asanyarray(x)
6704
>>> type(np.ma.asanyarray(x))
6705
<class 'numpy.ma.core.MaskedArray'>
5562
6708
return masked_array(a, dtype=dtype, copy=False, keep_mask=True, subok=True)
5567
6713
#####--------------------------------------------------------------------------
5568
6714
def dump(a, F):
5570
Pickle the MaskedArray `a` to the file `F`. `F` can either be
5571
the handle of an exiting file, or a string representing a file
6716
Pickle a masked array to a file.
6718
This is a wrapper around ``cPickle.dump``.
6723
The array to be pickled.
6724
F : str or file-like object
6725
The file to pickle `a` to. If a string, the full path to the file.
5575
if not hasattr(F,'readline'):
6728
if not hasattr(F, 'readline'):
5576
6729
F = open(F, 'w')
5577
6730
return cPickle.dump(a, F)
5581
Return a string corresponding to the pickling of the MaskedArray.
6734
Return a string corresponding to the pickling of a masked array.
6736
This is a wrapper around ``cPickle.dumps``.
6741
The array for which the string representation of the pickle is
5584
6745
return cPickle.dumps(a)
5588
6749
Wrapper around ``cPickle.load`` which accepts either a file-like object
6755
The file or file name to load.
6759
dump : Pickle an array
6763
This is different from `numpy.load`, which does not use cPickle but loads
6764
the NumPy binary .npy format.
5592
6767
if not hasattr(F, 'readline'):
5594
6769
return cPickle.load(F)
5596
6771
def loads(strg):
5597
"Load a pickle from the current string."""
6773
Load a pickle from the current string.
6775
The result of ``cPickle.loads(strg)`` is returned.
6784
dumps : Return a string corresponding to the pickling of a masked array.
5598
6787
return cPickle.loads(strg)
5600
6789
################################################################################
5601
def fromfile(file, dtype=float, count=-1, sep=''):
6790
def fromfile(file, dtype=float, count= -1, sep=''):
5602
6791
raise NotImplementedError("Not yet implemented. Sorry")
5605
6794
def fromflex(fxarray):
5607
Rebuilds a masked_array from a flexible-type array output by the '.torecord'
6796
Build a masked array from a suitable flexible-type array.
6798
The input array has to have a data-type with ``_data`` and ``_mask``
6799
fields. This type of array is output by `MaskedArray.toflex`.
6804
The structured input array, containing ``_data`` and ``_mask``
6805
fields. If present, other fields are discarded.
6809
result : MaskedArray
6810
The constructed masked array.
6814
MaskedArray.toflex : Build a flexible-type array from a masked array.
6818
>>> x = np.ma.array(np.arange(9).reshape(3, 3), mask=[0] + [1, 0] * 4)
6819
>>> rec = x.toflex()
6821
array([[(0, False), (1, True), (2, False)],
6822
[(3, True), (4, False), (5, True)],
6823
[(6, False), (7, True), (8, False)]],
6824
dtype=[('_data', '<i4'), ('_mask', '|b1')])
6825
>>> x2 = np.ma.fromflex(rec)
6834
[False True False]],
6835
fill_value = 999999)
6837
Extra fields can be present in the structured array but are discarded:
6839
>>> dt = [('_data', '<i4'), ('_mask', '|b1'), ('field3', '<f4')]
6840
>>> rec2 = np.zeros((2, 2), dtype=dt)
6842
array([[(0, False, 0.0), (0, False, 0.0)],
6843
[(0, False, 0.0), (0, False, 0.0)]],
6844
dtype=[('_data', '<i4'), ('_mask', '|b1'), ('field3', '<f4')])
6845
>>> y = np.ma.fromflex(rec2)
6853
fill_value = 999999)
5610
6856
return masked_array(fxarray['_data'], mask=fxarray['_mask'])
added
removed
numpy/ma/core.py
