Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/numpy/ma/core.py: 26%

6186 b'\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00?B\\x0f\\x00\\x00\\x00\\x00\\x00?B\\x0f\\x00\\x00\\x00\\x00\\x00\\x04\\x00\\x00\\x00\\x00\\x00\\x00\\x00'

6187

6188 """

6189 return self.filled(fill_value).tobytes(order=order)

6190

6191 def tofile(self, fid, sep="", format="%s"):

6192 """

6193 Save a masked array to a file in binary format.

6194

6195 .. warning::

6196 This function is not implemented yet.

6197

6198 Raises

6199 ------

6200 NotImplementedError

6201 When `tofile` is called.

6202

6203 """

6204 raise NotImplementedError("MaskedArray.tofile() not implemented yet.")

6205

6206 def toflex(self):

6207 """

6208 Transforms a masked array into a flexible-type array.

6209

6210 The flexible type array that is returned will have two fields:

6211

6212 * the ``_data`` field stores the ``_data`` part of the array.

6213 * the ``_mask`` field stores the ``_mask`` part of the array.

6214

6215 Parameters

6216 ----------

6217 None

6218

6219 Returns

6220 -------

6221 record : ndarray

6222 A new flexible-type `ndarray` with two fields: the first element

6223 containing a value, the second element containing the corresponding

6224 mask boolean. The returned record shape matches self.shape.

6225

6226 Notes

6227 -----

6228 A side-effect of transforming a masked array into a flexible `ndarray` is

6229 that meta information (``fill_value``, ...) will be lost.

6230

6231 Examples

6232 --------

6233 >>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)

6234 >>> x

6235 masked_array(

6236 data=[[1, --, 3],

6237 [--, 5, --],

6238 [7, --, 9]],

6239 mask=[[False, True, False],

6240 [ True, False, True],

6241 [False, True, False]],

6242 fill_value=999999)

6243 >>> x.toflex()

6244 array([[(1, False), (2, True), (3, False)],

6245 [(4, True), (5, False), (6, True)],

6246 [(7, False), (8, True), (9, False)]],

6247 dtype=[('_data', '<i8'), ('_mask', '?')])

6248

6249 """

6250 # Get the basic dtype.

6251 ddtype = self.dtype

6252 # Make sure we have a mask

6253 _mask = self._mask

6254 if _mask is None:

6255 _mask = make_mask_none(self.shape, ddtype)

6256 # And get its dtype

6257 mdtype = self._mask.dtype

6258

6259 record = np.ndarray(shape=self.shape,

6260 dtype=[('_data', ddtype), ('_mask', mdtype)])

6261 record['_data'] = self._data

6262 record['_mask'] = self._mask

6263 return record

6264 torecords = toflex

6265

6266 # Pickling

6267 def __getstate__(self):

6268 """Return the internal state of the masked array, for pickling

6269 purposes.

6270

6271 """

6272 cf = 'CF'[self.flags.fnc]

6273 data_state = super().__reduce__()[2]

6274 return data_state + (getmaskarray(self).tobytes(cf), self._fill_value)

6275

6276 def __setstate__(self, state):

6277 """Restore the internal state of the masked array, for

6278 pickling purposes. ``state`` is typically the output of the

6279 ``__getstate__`` output, and is a 5-tuple:

6280

6281 - class name

6282 - a tuple giving the shape of the data

6283 - a typecode for the data

6284 - a binary string for the data

6285 - a binary string for the mask.

6286

6287 """

6288 (_, shp, typ, isf, raw, msk, flv) = state

6289 super().__setstate__((shp, typ, isf, raw))

6290 self._mask.__setstate__((shp, make_mask_descr(typ), isf, msk))

6291 self.fill_value = flv

6292

6293 def __reduce__(self):

6294 """Return a 3-tuple for pickling a MaskedArray.

6295

6296 """

6297 return (_mareconstruct,

6298 (self.__class__, self._baseclass, (0,), 'b',),

6299 self.__getstate__())

6300

6301 def __deepcopy__(self, memo=None):

6302 from copy import deepcopy

6303 copied = MaskedArray.__new__(type(self), self, copy=True)

6304 if memo is None:

6305 memo = {}

6306 memo[id(self)] = copied

6307 for (k, v) in self.__dict__.items():

6308 copied.__dict__[k] = deepcopy(v, memo)

6309 return copied

6310

6311

6312def _mareconstruct(subtype, baseclass, baseshape, basetype,):

6313 """Internal function that builds a new MaskedArray from the

6314 information stored in a pickle.

6315

6316 """

6317 _data = ndarray.__new__(baseclass, baseshape, basetype)

6318 _mask = ndarray.__new__(ndarray, baseshape, make_mask_descr(basetype))

6319 return subtype.__new__(subtype, _data, mask=_mask, dtype=basetype,)

6320

6321

6322class mvoid(MaskedArray):

6323 """

6324 Fake a 'void' object to use for masked array with structured dtypes.

6325 """

6326

6327 def __new__(self, data, mask=nomask, dtype=None, fill_value=None,

6328 hardmask=False, copy=False, subok=True):

6329 _data = np.array(data, copy=copy, subok=subok, dtype=dtype)

6330 _data = _data.view(self)

6331 _data._hardmask = hardmask

6332 if mask is not nomask:

6333 if isinstance(mask, np.void):

6334 _data._mask = mask

6335 else:

6336 try:

6337 # Mask is already a 0D array

6338 _data._mask = np.void(mask)

6339 except TypeError:

6340 # Transform the mask to a void

6341 mdtype = make_mask_descr(dtype)

6342 _data._mask = np.array(mask, dtype=mdtype)[()]

6343 if fill_value is not None:

6344 _data.fill_value = fill_value

6345 return _data

6346

6347 @property

6348 def _data(self):

6349 # Make sure that the _data part is a np.void

6350 return super()._data[()]

6351

6352 def __getitem__(self, indx):

6353 """

6354 Get the index.

6355

6356 """

6357 m = self._mask

6358 if isinstance(m[indx], ndarray):

6359 # Can happen when indx is a multi-dimensional field:

6360 # A = ma.masked_array(data=[([0,1],)], mask=[([True,

6361 # False],)], dtype=[("A", ">i2", (2,))])

6362 # x = A[0]; y = x["A"]; then y.mask["A"].size==2

6363 # and we can not say masked/unmasked.

6364 # The result is no longer mvoid!

6365 # See also issue #6724.

6366 return masked_array(

6367 data=self._data[indx], mask=m[indx],

6368 fill_value=self._fill_value[indx],

6369 hard_mask=self._hardmask)

6370 if m is not nomask and m[indx]:

6371 return masked

6372 return self._data[indx]

6373

6374 def __setitem__(self, indx, value):

6375 self._data[indx] = value

6376 if self._hardmask:

6377 self._mask[indx] |= getattr(value, "_mask", False)

6378 else:

6379 self._mask[indx] = getattr(value, "_mask", False)

6380

6381 def __str__(self):

6382 m = self._mask

6383 if m is nomask:

6384 return str(self._data)

6385

6386 rdtype = _replace_dtype_fields(self._data.dtype, "O")

6387 data_arr = super()._data

6388 res = data_arr.astype(rdtype)

6389 _recursive_printoption(res, self._mask, masked_print_option)

6390 return str(res)

6391

6392 __repr__ = __str__

6393

6394 def __iter__(self):

6395 "Defines an iterator for mvoid"

6396 (_data, _mask) = (self._data, self._mask)

6397 if _mask is nomask:

6398 yield from _data

6399 else:

6400 for (d, m) in zip(_data, _mask):

6401 if m:

6402 yield masked

6403 else:

6404 yield d

6405

6406 def __len__(self):

6407 return self._data.__len__()

6408

6409 def filled(self, fill_value=None):

6410 """

6411 Return a copy with masked fields filled with a given value.

6412

6413 Parameters

6414 ----------

6415 fill_value : array_like, optional

6416 The value to use for invalid entries. Can be scalar or

6417 non-scalar. If latter is the case, the filled array should

6418 be broadcastable over input array. Default is None, in

6419 which case the `fill_value` attribute is used instead.

6420

6421 Returns

6422 -------

6423 filled_void

6424 A `np.void` object

6425

6426 See Also

6427 --------

6428 MaskedArray.filled

6429

6430 """

6431 return asarray(self).filled(fill_value)[()]

6432

6433 def tolist(self):

6434 """

6435 Transforms the mvoid object into a tuple.

6436

6437 Masked fields are replaced by None.

6438

6439 Returns

6440 -------

6441 returned_tuple

6442 Tuple of fields

6443 """

6444 _mask = self._mask

6445 if _mask is nomask:

6446 return self._data.tolist()

6447 result = []

6448 for (d, m) in zip(self._data, self._mask):

6449 if m:

6450 result.append(None)

6451 else:

6452 # .item() makes sure we return a standard Python object

6453 result.append(d.item())

6454 return tuple(result)

6455

6456

6457##############################################################################

6458# Shortcuts #

6459##############################################################################

6460

6461

6462def isMaskedArray(x):

6463 """

6464 Test whether input is an instance of MaskedArray.

6465

6466 This function returns True if `x` is an instance of MaskedArray

6467 and returns False otherwise. Any object is accepted as input.

6468

6469 Parameters

6470 ----------

6471 x : object

6472 Object to test.

6473

6474 Returns

6475 -------

6476 result : bool

6477 True if `x` is a MaskedArray.

6478

6479 See Also

6480 --------

6481 isMA : Alias to isMaskedArray.

6482 isarray : Alias to isMaskedArray.

6483

6484 Examples

6485 --------

6486 >>> import numpy.ma as ma

6487 >>> a = np.eye(3, 3)

6488 >>> a

6489 array([[ 1., 0., 0.],

6490 [ 0., 1., 0.],

6491 [ 0., 0., 1.]])

6492 >>> m = ma.masked_values(a, 0)

6493 >>> m

6494 masked_array(

6495 data=[[1.0, --, --],

6496 [--, 1.0, --],

6497 [--, --, 1.0]],

6498 mask=[[False, True, True],

6499 [ True, False, True],

6500 [ True, True, False]],

6501 fill_value=0.0)

6502 >>> ma.isMaskedArray(a)

6503 False

6504 >>> ma.isMaskedArray(m)

6505 True

6506 >>> ma.isMaskedArray([0, 1, 2])

6507 False

6508

6509 """

6510 return isinstance(x, MaskedArray)

6511

6512

6513isarray = isMaskedArray

6514isMA = isMaskedArray # backward compatibility

6515

6516

6517class MaskedConstant(MaskedArray):

6518 # the lone np.ma.masked instance

6519 __singleton = None

6520

6521 @classmethod

6522 def __has_singleton(cls):

6523 # second case ensures `cls.__singleton` is not just a view on the

6524 # superclass singleton

6525 return cls.__singleton is not None and type(cls.__singleton) is cls

6526

6527 def __new__(cls):

6528 if not cls.__has_singleton():

6529 # We define the masked singleton as a float for higher precedence.

6530 # Note that it can be tricky sometimes w/ type comparison

6531 data = np.array(0.)

6532 mask = np.array(True)

6533

6534 # prevent any modifications

6535 data.flags.writeable = False

6536 mask.flags.writeable = False

6537

6538 # don't fall back on MaskedArray.__new__(MaskedConstant), since

6539 # that might confuse it - this way, the construction is entirely

6540 # within our control

6541 cls.__singleton = MaskedArray(data, mask=mask).view(cls)

6542

6543 return cls.__singleton

6544

6545 def __array_finalize__(self, obj):

6546 if not self.__has_singleton():

6547 # this handles the `.view` in __new__, which we want to copy across

6548 # properties normally

6549 return super().__array_finalize__(obj)

6550 elif self is self.__singleton:

6551 # not clear how this can happen, play it safe

6552 pass

6553 else:

6554 # everywhere else, we want to downcast to MaskedArray, to prevent a

6555 # duplicate maskedconstant.

6556 self.__class__ = MaskedArray

6557 MaskedArray.__array_finalize__(self, obj)

6558

6559 def __array_prepare__(self, obj, context=None):

6560 return self.view(MaskedArray).__array_prepare__(obj, context)

6561

6562 def __array_wrap__(self, obj, context=None):

6563 return self.view(MaskedArray).__array_wrap__(obj, context)

6564

6565 def __str__(self):

6566 return str(masked_print_option._display)

6567

6568 def __repr__(self):

6569 if self is MaskedConstant.__singleton:

6570 return 'masked'

6571 else:

6572 # it's a subclass, or something is wrong, make it obvious

6573 return object.__repr__(self)

6574

6575 def __format__(self, format_spec):

6576 # Replace ndarray.__format__ with the default, which supports no format characters.

6577 # Supporting format characters is unwise here, because we do not know what type

6578 # the user was expecting - better to not guess.

6579 try:

6580 return object.__format__(self, format_spec)

6581 except TypeError:

6582 # 2020-03-23, NumPy 1.19.0

6583 warnings.warn(

6584 "Format strings passed to MaskedConstant are ignored, but in future may "

6585 "error or produce different behavior",

6586 FutureWarning, stacklevel=2

6587 )

6588 return object.__format__(self, "")

6589

6590 def __reduce__(self):

6591 """Override of MaskedArray's __reduce__.

6592 """

6593 return (self.__class__, ())

6594

6595 # inplace operations have no effect. We have to override them to avoid

6596 # trying to modify the readonly data and mask arrays

6597 def __iop__(self, other):

6598 return self

6599 __iadd__ = \

6600 __isub__ = \

6601 __imul__ = \

6602 __ifloordiv__ = \

6603 __itruediv__ = \

6604 __ipow__ = \

6605 __iop__

6606 del __iop__ # don't leave this around

6607

6608 def copy(self, *args, **kwargs):

6609 """ Copy is a no-op on the maskedconstant, as it is a scalar """

6610 # maskedconstant is a scalar, so copy doesn't need to copy. There's

6611 # precedent for this with `np.bool_` scalars.

6612 return self

6613

6614 def __copy__(self):

6615 return self

6616

6617 def __deepcopy__(self, memo):

6618 return self

6619

6620 def __setattr__(self, attr, value):

6621 if not self.__has_singleton():

6622 # allow the singleton to be initialized

6623 return super().__setattr__(attr, value)

6624 elif self is self.__singleton:

6625 raise AttributeError(

6626 f"attributes of {self!r} are not writeable")

6627 else:

6628 # duplicate instance - we can end up here from __array_finalize__,

6629 # where we set the __class__ attribute

6630 return super().__setattr__(attr, value)

6631

6632

6633masked = masked_singleton = MaskedConstant()

6634masked_array = MaskedArray

6635

6636

6637def array(data, dtype=None, copy=False, order=None,

6638 mask=nomask, fill_value=None, keep_mask=True,

6639 hard_mask=False, shrink=True, subok=True, ndmin=0):

6640 """

6641 Shortcut to MaskedArray.

6642

6643 The options are in a different order for convenience and backwards

6644 compatibility.

6645

6646 """

6647 return MaskedArray(data, mask=mask, dtype=dtype, copy=copy,

6648 subok=subok, keep_mask=keep_mask,

6649 hard_mask=hard_mask, fill_value=fill_value,

6650 ndmin=ndmin, shrink=shrink, order=order)

6651array.__doc__ = masked_array.__doc__

6652

6653

6654def is_masked(x):

6655 """

6656 Determine whether input has masked values.

6657

6658 Accepts any object as input, but always returns False unless the

6659 input is a MaskedArray containing masked values.

6660

6661 Parameters

6662 ----------

6663 x : array_like

6664 Array to check for masked values.

6665

6666 Returns

6667 -------

6668 result : bool

6669 True if `x` is a MaskedArray with masked values, False otherwise.

6670

6671 Examples

6672 --------

6673 >>> import numpy.ma as ma

6674 >>> x = ma.masked_equal([0, 1, 0, 2, 3], 0)

6675 >>> x

6676 masked_array(data=[--, 1, --, 2, 3],

6677 mask=[ True, False, True, False, False],

6678 fill_value=0)

6679 >>> ma.is_masked(x)

6680 True

6681 >>> x = ma.masked_equal([0, 1, 0, 2, 3], 42)

6682 >>> x

6683 masked_array(data=[0, 1, 0, 2, 3],

6684 mask=False,

6685 fill_value=42)

6686 >>> ma.is_masked(x)

6687 False

6688

6689 Always returns False if `x` isn't a MaskedArray.

6690

6691 >>> x = [False, True, False]

6692 >>> ma.is_masked(x)

6693 False

6694 >>> x = 'a string'

6695 >>> ma.is_masked(x)

6696 False

6697

6698 """

6699 m = getmask(x)

6700 if m is nomask:

6701 return False

6702 elif m.any():

6703 return True

6704 return False

6705

6706

6707##############################################################################

6708# Extrema functions #

6709##############################################################################

6710

6711

6712class _extrema_operation(_MaskedUFunc):

6713 """

6714 Generic class for maximum/minimum functions.

6715

6716 .. note::

6717 This is the base class for `_maximum_operation` and

6718 `_minimum_operation`.

6719

6720 """

6721 def __init__(self, ufunc, compare, fill_value):

6722 super().__init__(ufunc)

6723 self.compare = compare

6724 self.fill_value_func = fill_value

6725

6726 def __call__(self, a, b):

6727 "Executes the call behavior."

6728

6729 return where(self.compare(a, b), a, b)

6730

6731 def reduce(self, target, axis=np._NoValue):

6732 "Reduce target along the given axis."

6733 target = narray(target, copy=False, subok=True)

6734 m = getmask(target)

6735

6736 if axis is np._NoValue and target.ndim > 1:

6737 # 2017-05-06, Numpy 1.13.0: warn on axis default

6738 warnings.warn(

6739 f"In the future the default for ma.{self.__name__}.reduce will be axis=0, "

6740 f"not the current None, to match np.{self.__name__}.reduce. "

6741 "Explicitly pass 0 or None to silence this warning.",

6742 MaskedArrayFutureWarning, stacklevel=2)

6743 axis = None

6744

6745 if axis is not np._NoValue:

6746 kwargs = dict(axis=axis)

6747 else:

6748 kwargs = dict()

6749

6750 if m is nomask:

6751 t = self.f.reduce(target, **kwargs)

6752 else:

6753 target = target.filled(

6754 self.fill_value_func(target)).view(type(target))

6755 t = self.f.reduce(target, **kwargs)

6756 m = umath.logical_and.reduce(m, **kwargs)

6757 if hasattr(t, '_mask'):

6758 t._mask = m

6759 elif m:

6760 t = masked

6761 return t

6762

6763 def outer(self, a, b):

6764 "Return the function applied to the outer product of a and b."

6765 ma = getmask(a)

6766 mb = getmask(b)

6767 if ma is nomask and mb is nomask:

6768 m = nomask

6769 else:

6770 ma = getmaskarray(a)

6771 mb = getmaskarray(b)

6772 m = logical_or.outer(ma, mb)

6773 result = self.f.outer(filled(a), filled(b))

6774 if not isinstance(result, MaskedArray):

6775 result = result.view(MaskedArray)

6776 result._mask = m

6777 return result

6778

6779def min(obj, axis=None, out=None, fill_value=None, keepdims=np._NoValue):

6780 kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}

6781

6782 try:

6783 return obj.min(axis=axis, fill_value=fill_value, out=out, **kwargs)

6784 except (AttributeError, TypeError):

6785 # If obj doesn't have a min method, or if the method doesn't accept a

6786 # fill_value argument

6787 return asanyarray(obj).min(axis=axis, fill_value=fill_value,

6788 out=out, **kwargs)

6789min.__doc__ = MaskedArray.min.__doc__

6790

6791def max(obj, axis=None, out=None, fill_value=None, keepdims=np._NoValue):

6792 kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}

6793

6794 try:

6795 return obj.max(axis=axis, fill_value=fill_value, out=out, **kwargs)

6796 except (AttributeError, TypeError):

6797 # If obj doesn't have a max method, or if the method doesn't accept a

6798 # fill_value argument

6799 return asanyarray(obj).max(axis=axis, fill_value=fill_value,

6800 out=out, **kwargs)

6801max.__doc__ = MaskedArray.max.__doc__

6802

6803

6804def ptp(obj, axis=None, out=None, fill_value=None, keepdims=np._NoValue):

6805 kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}

6806 try:

6807 return obj.ptp(axis, out=out, fill_value=fill_value, **kwargs)

6808 except (AttributeError, TypeError):

6809 # If obj doesn't have a ptp method or if the method doesn't accept

6810 # a fill_value argument

6811 return asanyarray(obj).ptp(axis=axis, fill_value=fill_value,

6812 out=out, **kwargs)

6813ptp.__doc__ = MaskedArray.ptp.__doc__

6814

6815

6816##############################################################################

6817# Definition of functions from the corresponding methods #

6818##############################################################################

6819

6820

6821class _frommethod:

6822 """

6823 Define functions from existing MaskedArray methods.

6824

6825 Parameters

6826 ----------

6827 methodname : str

6828 Name of the method to transform.

6829

6830 """

6831

6832 def __init__(self, methodname, reversed=False):

6833 self.__name__ = methodname

6834 self.__doc__ = self.getdoc()

6835 self.reversed = reversed

6836

6837 def getdoc(self):

6838 "Return the doc of the function (from the doc of the method)."

6839 meth = getattr(MaskedArray, self.__name__, None) or\

6840 getattr(np, self.__name__, None)

6841 signature = self.__name__ + get_object_signature(meth)

6842 if meth is not None:

6843 doc = """ %s\n%s""" % (

6844 signature, getattr(meth, '__doc__', None))

6845 return doc

6846

6847 def __call__(self, a, *args, **params):

6848 if self.reversed:

6849 args = list(args)

6850 a, args[0] = args[0], a

6851

6852 marr = asanyarray(a)

6853 method_name = self.__name__

6854 method = getattr(type(marr), method_name, None)

6855 if method is None:

6856 # use the corresponding np function

6857 method = getattr(np, method_name)

6858

6859 return method(marr, *args, **params)

6860

6861

6862all = _frommethod('all')

6863anomalies = anom = _frommethod('anom')

6864any = _frommethod('any')

6865compress = _frommethod('compress', reversed=True)

6866cumprod = _frommethod('cumprod')

6867cumsum = _frommethod('cumsum')

6868copy = _frommethod('copy')

6869diagonal = _frommethod('diagonal')

6870harden_mask = _frommethod('harden_mask')

6871ids = _frommethod('ids')

6872maximum = _extrema_operation(umath.maximum, greater, maximum_fill_value)

6873mean = _frommethod('mean')

6874minimum = _extrema_operation(umath.minimum, less, minimum_fill_value)

6875nonzero = _frommethod('nonzero')

6876prod = _frommethod('prod')

6877product = _frommethod('prod')

6878ravel = _frommethod('ravel')

6879repeat = _frommethod('repeat')

6880shrink_mask = _frommethod('shrink_mask')

6881soften_mask = _frommethod('soften_mask')

6882std = _frommethod('std')

6883sum = _frommethod('sum')

6884swapaxes = _frommethod('swapaxes')

6885#take = _frommethod('take')

6886trace = _frommethod('trace')

6887var = _frommethod('var')

6888

6889count = _frommethod('count')

6890

6891def take(a, indices, axis=None, out=None, mode='raise'):

6892 """

6893 """

6894 a = masked_array(a)

6895 return a.take(indices, axis=axis, out=out, mode=mode)

6896

6897

6898def power(a, b, third=None):

6899 """

6900 Returns element-wise base array raised to power from second array.

6901

6902 This is the masked array version of `numpy.power`. For details see

6903 `numpy.power`.

6904

6905 See Also

6906 --------

6907 numpy.power

6908

6909 Notes

6910 -----

6911 The *out* argument to `numpy.power` is not supported, `third` has to be

6912 None.

6913

6914 Examples

6915 --------

6916 >>> import numpy.ma as ma

6917 >>> x = [11.2, -3.973, 0.801, -1.41]

6918 >>> mask = [0, 0, 0, 1]

6919 >>> masked_x = ma.masked_array(x, mask)

6920 >>> masked_x

6921 masked_array(data=[11.2, -3.973, 0.801, --],

6922 mask=[False, False, False, True],

6923 fill_value=1e+20)

6924 >>> ma.power(masked_x, 2)

6925 masked_array(data=[125.43999999999998, 15.784728999999999,

6926 0.6416010000000001, --],

6927 mask=[False, False, False, True],

6928 fill_value=1e+20)

6929 >>> y = [-0.5, 2, 0, 17]

6930 >>> masked_y = ma.masked_array(y, mask)

6931 >>> masked_y

6932 masked_array(data=[-0.5, 2.0, 0.0, --],

6933 mask=[False, False, False, True],

6934 fill_value=1e+20)

6935 >>> ma.power(masked_x, masked_y)

6936 masked_array(data=[0.29880715233359845, 15.784728999999999, 1.0, --],

6937 mask=[False, False, False, True],

6938 fill_value=1e+20)

6939

6940 """

6941 if third is not None:

6942 raise MaskError("3-argument power not supported.")

6943 # Get the masks

6944 ma = getmask(a)

6945 mb = getmask(b)

6946 m = mask_or(ma, mb)

6947 # Get the rawdata

6948 fa = getdata(a)

6949 fb = getdata(b)

6950 # Get the type of the result (so that we preserve subclasses)

6951 if isinstance(a, MaskedArray):

6952 basetype = type(a)

6953 else:

6954 basetype = MaskedArray

6955 # Get the result and view it as a (subclass of) MaskedArray

6956 with np.errstate(divide='ignore', invalid='ignore'):

6957 result = np.where(m, fa, umath.power(fa, fb)).view(basetype)

6958 result._update_from(a)

6959 # Find where we're in trouble w/ NaNs and Infs

6960 invalid = np.logical_not(np.isfinite(result.view(ndarray)))

6961 # Add the initial mask

6962 if m is not nomask:

6963 if not result.ndim:

6964 return masked

6965 result._mask = np.logical_or(m, invalid)

6966 # Fix the invalid parts

6967 if invalid.any():

6968 if not result.ndim:

6969 return masked

6970 elif result._mask is nomask:

6971 result._mask = invalid

6972 result._data[invalid] = result.fill_value

6973 return result

6974

6975argmin = _frommethod('argmin')

6976argmax = _frommethod('argmax')

6977

6978def argsort(a, axis=np._NoValue, kind=None, order=None, endwith=True, fill_value=None):

6979 "Function version of the eponymous method."

6980 a = np.asanyarray(a)

6981

6982 # 2017-04-11, Numpy 1.13.0, gh-8701: warn on axis default

6983 if axis is np._NoValue:

6984 axis = _deprecate_argsort_axis(a)

6985

6986 if isinstance(a, MaskedArray):

6987 return a.argsort(axis=axis, kind=kind, order=order,

6988 endwith=endwith, fill_value=fill_value)

6989 else:

6990 return a.argsort(axis=axis, kind=kind, order=order)

6991argsort.__doc__ = MaskedArray.argsort.__doc__

6992

6993def sort(a, axis=-1, kind=None, order=None, endwith=True, fill_value=None):

6994 """

6995 Return a sorted copy of the masked array.

6996

6997 Equivalent to creating a copy of the array

6998 and applying the MaskedArray ``sort()`` method.

6999

7000 Refer to ``MaskedArray.sort`` for the full documentation

7001

7002 See Also

7003 --------

7004 MaskedArray.sort : equivalent method

7005 """

7006 a = np.array(a, copy=True, subok=True)

7007 if axis is None:

7008 a = a.flatten()

7009 axis = 0

7010

7011 if isinstance(a, MaskedArray):

7012 a.sort(axis=axis, kind=kind, order=order,

7013 endwith=endwith, fill_value=fill_value)

7014 else:

7015 a.sort(axis=axis, kind=kind, order=order)

7016 return a

7017

7018

7019def compressed(x):

7020 """

7021 Return all the non-masked data as a 1-D array.

7022

7023 This function is equivalent to calling the "compressed" method of a

7024 `ma.MaskedArray`, see `ma.MaskedArray.compressed` for details.

7025

7026 See Also

7027 --------

7028 ma.MaskedArray.compressed : Equivalent method.

7029

7030 """

7031 return asanyarray(x).compressed()

7032

7033

7034def concatenate(arrays, axis=0):

7035 """

7036 Concatenate a sequence of arrays along the given axis.

7037

7038 Parameters

7039 ----------

7040 arrays : sequence of array_like

7041 The arrays must have the same shape, except in the dimension

7042 corresponding to `axis` (the first, by default).

7043 axis : int, optional

7044 The axis along which the arrays will be joined. Default is 0.

7045

7046 Returns

7047 -------

7048 result : MaskedArray

7049 The concatenated array with any masked entries preserved.

7050

7051 See Also

7052 --------

7053 numpy.concatenate : Equivalent function in the top-level NumPy module.

7054

7055 Examples

7056 --------

7057 >>> import numpy.ma as ma

7058 >>> a = ma.arange(3)

7059 >>> a[1] = ma.masked

7060 >>> b = ma.arange(2, 5)

7061 >>> a

7062 masked_array(data=[0, --, 2],

7063 mask=[False, True, False],

7064 fill_value=999999)

7065 >>> b

7066 masked_array(data=[2, 3, 4],

7067 mask=False,

7068 fill_value=999999)

7069 >>> ma.concatenate([a, b])

7070 masked_array(data=[0, --, 2, 2, 3, 4],

7071 mask=[False, True, False, False, False, False],

7072 fill_value=999999)

7073

7074 """

7075 d = np.concatenate([getdata(a) for a in arrays], axis)

7076 rcls = get_masked_subclass(*arrays)

7077 data = d.view(rcls)

7078 # Check whether one of the arrays has a non-empty mask.

7079 for x in arrays:

7080 if getmask(x) is not nomask:

7081 break

7082 else:

7083 return data

7084 # OK, so we have to concatenate the masks

7085 dm = np.concatenate([getmaskarray(a) for a in arrays], axis)

7086 dm = dm.reshape(d.shape)

7087

7088 # If we decide to keep a '_shrinkmask' option, we want to check that

7089 # all of them are True, and then check for dm.any()

7090 data._mask = _shrink_mask(dm)

7091 return data

7092

7093

7094def diag(v, k=0):

7095 """

7096 Extract a diagonal or construct a diagonal array.

7097

7098 This function is the equivalent of `numpy.diag` that takes masked

7099 values into account, see `numpy.diag` for details.

7100

7101 See Also

7102 --------

7103 numpy.diag : Equivalent function for ndarrays.

7104

7105 """

7106 output = np.diag(v, k).view(MaskedArray)

7107 if getmask(v) is not nomask:

7108 output._mask = np.diag(v._mask, k)

7109 return output

7110

7111

7112def left_shift(a, n):

7113 """

7114 Shift the bits of an integer to the left.

7115

7116 This is the masked array version of `numpy.left_shift`, for details

7117 see that function.

7118

7119 See Also

7120 --------

7121 numpy.left_shift

7122

7123 """

7124 m = getmask(a)

7125 if m is nomask:

7126 d = umath.left_shift(filled(a), n)

7127 return masked_array(d)

7128 else:

7129 d = umath.left_shift(filled(a, 0), n)

7130 return masked_array(d, mask=m)

7131

7132

7133def right_shift(a, n):

7134 """

7135 Shift the bits of an integer to the right.

7136

7137 This is the masked array version of `numpy.right_shift`, for details

7138 see that function.

7139

7140 See Also

7141 --------

7142 numpy.right_shift

7143

7144 """

7145 m = getmask(a)

7146 if m is nomask:

7147 d = umath.right_shift(filled(a), n)

7148 return masked_array(d)

7149 else:

7150 d = umath.right_shift(filled(a, 0), n)

7151 return masked_array(d, mask=m)

7152

7153

7154def put(a, indices, values, mode='raise'):

7155 """

7156 Set storage-indexed locations to corresponding values.

7157

7158 This function is equivalent to `MaskedArray.put`, see that method

7159 for details.

7160

7161 See Also

7162 --------

7163 MaskedArray.put

7164

7165 """

7166 # We can't use 'frommethod', the order of arguments is different

7167 try:

7168 return a.put(indices, values, mode=mode)

7169 except AttributeError:

7170 return narray(a, copy=False).put(indices, values, mode=mode)

7171

7172

7173def putmask(a, mask, values): # , mode='raise'):

7174 """

7175 Changes elements of an array based on conditional and input values.

7176

7177 This is the masked array version of `numpy.putmask`, for details see

7178 `numpy.putmask`.

7179

7180 See Also

7181 --------

7182 numpy.putmask

7183

7184 Notes

7185 -----

7186 Using a masked array as `values` will **not** transform a `ndarray` into

7187 a `MaskedArray`.

7188

7189 """

7190 # We can't use 'frommethod', the order of arguments is different

7191 if not isinstance(a, MaskedArray):

7192 a = a.view(MaskedArray)

7193 (valdata, valmask) = (getdata(values), getmask(values))

7194 if getmask(a) is nomask:

7195 if valmask is not nomask:

7196 a._sharedmask = True

7197 a._mask = make_mask_none(a.shape, a.dtype)

7198 np.copyto(a._mask, valmask, where=mask)

7199 elif a._hardmask:

7200 if valmask is not nomask:

7201 m = a._mask.copy()

7202 np.copyto(m, valmask, where=mask)

7203 a.mask |= m

7204 else:

7205 if valmask is nomask:

7206 valmask = getmaskarray(values)

7207 np.copyto(a._mask, valmask, where=mask)

7208 np.copyto(a._data, valdata, where=mask)

7209 return

7210

7211

7212def transpose(a, axes=None):

7213 """

7214 Permute the dimensions of an array.

7215

7216 This function is exactly equivalent to `numpy.transpose`.

7217

7218 See Also

7219 --------

7220 numpy.transpose : Equivalent function in top-level NumPy module.

7221

7222 Examples

7223 --------

7224 >>> import numpy.ma as ma

7225 >>> x = ma.arange(4).reshape((2,2))

7226 >>> x[1, 1] = ma.masked

7227 >>> x

7228 masked_array(

7229 data=[[0, 1],

7230 [2, --]],

7231 mask=[[False, False],

7232 [False, True]],

7233 fill_value=999999)

7234

7235 >>> ma.transpose(x)

7236 masked_array(

7237 data=[[0, 2],

7238 [1, --]],

7239 mask=[[False, False],

7240 [False, True]],

7241 fill_value=999999)

7242 """

7243 # We can't use 'frommethod', as 'transpose' doesn't take keywords

7244 try:

7245 return a.transpose(axes)

7246 except AttributeError:

7247 return narray(a, copy=False).transpose(axes).view(MaskedArray)

7248

7249

7250def reshape(a, new_shape, order='C'):

7251 """

7252 Returns an array containing the same data with a new shape.

7253

7254 Refer to `MaskedArray.reshape` for full documentation.

7255

7256 See Also

7257 --------

7258 MaskedArray.reshape : equivalent function

7259

7260 """

7261 # We can't use 'frommethod', it whine about some parameters. Dmmit.

7262 try:

7263 return a.reshape(new_shape, order=order)

7264 except AttributeError:

7265 _tmp = narray(a, copy=False).reshape(new_shape, order=order)

7266 return _tmp.view(MaskedArray)

7267

7268

7269def resize(x, new_shape):

7270 """

7271 Return a new masked array with the specified size and shape.

7272

7273 This is the masked equivalent of the `numpy.resize` function. The new

7274 array is filled with repeated copies of `x` (in the order that the

7275 data are stored in memory). If `x` is masked, the new array will be

7276 masked, and the new mask will be a repetition of the old one.

7277

7278 See Also

7279 --------

7280 numpy.resize : Equivalent function in the top level NumPy module.

7281

7282 Examples

7283 --------

7284 >>> import numpy.ma as ma

7285 >>> a = ma.array([[1, 2] ,[3, 4]])

7286 >>> a[0, 1] = ma.masked

7287 >>> a

7288 masked_array(

7289 data=[[1, --],

7290 [3, 4]],

7291 mask=[[False, True],

7292 [False, False]],

7293 fill_value=999999)

7294 >>> np.resize(a, (3, 3))

7295 masked_array(

7296 data=[[1, 2, 3],

7297 [4, 1, 2],

7298 [3, 4, 1]],

7299 mask=False,

7300 fill_value=999999)

7301 >>> ma.resize(a, (3, 3))

7302 masked_array(

7303 data=[[1, --, 3],

7304 [4, 1, --],

7305 [3, 4, 1]],

7306 mask=[[False, True, False],

7307 [False, False, True],

7308 [False, False, False]],

7309 fill_value=999999)

7310

7311 A MaskedArray is always returned, regardless of the input type.

7312

7313 >>> a = np.array([[1, 2] ,[3, 4]])

7314 >>> ma.resize(a, (3, 3))

7315 masked_array(

7316 data=[[1, 2, 3],

7317 [4, 1, 2],

7318 [3, 4, 1]],

7319 mask=False,

7320 fill_value=999999)

7321

7322 """

7323 # We can't use _frommethods here, as N.resize is notoriously whiny.

7324 m = getmask(x)

7325 if m is not nomask:

7326 m = np.resize(m, new_shape)

7327 result = np.resize(x, new_shape).view(get_masked_subclass(x))

7328 if result.ndim:

7329 result._mask = m

7330 return result

7331

7332

7333def ndim(obj):

7334 """

7335 maskedarray version of the numpy function.

7336

7337 """

7338 return np.ndim(getdata(obj))

7339

7340ndim.__doc__ = np.ndim.__doc__

7341

7342

7343def shape(obj):

7344 "maskedarray version of the numpy function."

7345 return np.shape(getdata(obj))

7346shape.__doc__ = np.shape.__doc__

7347

7348

7349def size(obj, axis=None):

7350 "maskedarray version of the numpy function."

7351 return np.size(getdata(obj), axis)

7352size.__doc__ = np.size.__doc__

7353

7354

7355##############################################################################

7356# Extra functions #

7357##############################################################################

7358

7359

7360def where(condition, x=_NoValue, y=_NoValue):

7361 """

7362 Return a masked array with elements from `x` or `y`, depending on condition.

7363

7364 .. note::

7365 When only `condition` is provided, this function is identical to

7366 `nonzero`. The rest of this documentation covers only the case where

7367 all three arguments are provided.

7368

7369 Parameters

7370 ----------

7371 condition : array_like, bool

7372 Where True, yield `x`, otherwise yield `y`.

7373 x, y : array_like, optional

7374 Values from which to choose. `x`, `y` and `condition` need to be

7375 broadcastable to some shape.

7376

7377 Returns

7378 -------

7379 out : MaskedArray

7380 An masked array with `masked` elements where the condition is masked,

7381 elements from `x` where `condition` is True, and elements from `y`

7382 elsewhere.

7383

7384 See Also

7385 --------

7386 numpy.where : Equivalent function in the top-level NumPy module.

7387 nonzero : The function that is called when x and y are omitted

7388

7389 Examples

7390 --------

7391 >>> x = np.ma.array(np.arange(9.).reshape(3, 3), mask=[[0, 1, 0],

7392 ... [1, 0, 1],

7393 ... [0, 1, 0]])

7394 >>> x

7395 masked_array(

7396 data=[[0.0, --, 2.0],

7397 [--, 4.0, --],

7398 [6.0, --, 8.0]],

7399 mask=[[False, True, False],

7400 [ True, False, True],

7401 [False, True, False]],

7402 fill_value=1e+20)

7403 >>> np.ma.where(x > 5, x, -3.1416)

7404 masked_array(

7405 data=[[-3.1416, --, -3.1416],

7406 [--, -3.1416, --],

7407 [6.0, --, 8.0]],

7408 mask=[[False, True, False],

7409 [ True, False, True],

7410 [False, True, False]],

7411 fill_value=1e+20)

7412

7413 """

7414

7415 # handle the single-argument case

7416 missing = (x is _NoValue, y is _NoValue).count(True)

7417 if missing == 1:

7418 raise ValueError("Must provide both 'x' and 'y' or neither.")

7419 if missing == 2:

7420 return nonzero(condition)

7421

7422 # we only care if the condition is true - false or masked pick y

7423 cf = filled(condition, False)

7424 xd = getdata(x)

7425 yd = getdata(y)

7426

7427 # we need the full arrays here for correct final dimensions

7428 cm = getmaskarray(condition)

7429 xm = getmaskarray(x)

7430 ym = getmaskarray(y)

7431

7432 # deal with the fact that masked.dtype == float64, but we don't actually

7433 # want to treat it as that.

7434 if x is masked and y is not masked:

7435 xd = np.zeros((), dtype=yd.dtype)

7436 xm = np.ones((), dtype=ym.dtype)

7437 elif y is masked and x is not masked:

7438 yd = np.zeros((), dtype=xd.dtype)

7439 ym = np.ones((), dtype=xm.dtype)

7440

7441 data = np.where(cf, xd, yd)

7442 mask = np.where(cf, xm, ym)

7443 mask = np.where(cm, np.ones((), dtype=mask.dtype), mask)

7444

7445 # collapse the mask, for backwards compatibility

7446 mask = _shrink_mask(mask)

7447

7448 return masked_array(data, mask=mask)

7449

7450

7451def choose(indices, choices, out=None, mode='raise'):

7452 """

7453 Use an index array to construct a new array from a list of choices.

7454

7455 Given an array of integers and a list of n choice arrays, this method

7456 will create a new array that merges each of the choice arrays. Where a

7457 value in `index` is i, the new array will have the value that choices[i]

7458 contains in the same place.

7459

7460 Parameters

7461 ----------

7462 indices : ndarray of ints

7463 This array must contain integers in ``[0, n-1]``, where n is the

7464 number of choices.

7465 choices : sequence of arrays

7466 Choice arrays. The index array and all of the choices should be

7467 broadcastable to the same shape.

7468 out : array, optional

7469 If provided, the result will be inserted into this array. It should

7470 be of the appropriate shape and `dtype`.

7471 mode : {'raise', 'wrap', 'clip'}, optional

7472 Specifies how out-of-bounds indices will behave.

7473

7474 * 'raise' : raise an error

7475 * 'wrap' : wrap around

7476 * 'clip' : clip to the range

7477

7478 Returns

7479 -------

7480 merged_array : array

7481

7482 See Also

7483 --------

7484 choose : equivalent function

7485

7486 Examples

7487 --------

7488 >>> choice = np.array([[1,1,1], [2,2,2], [3,3,3]])

7489 >>> a = np.array([2, 1, 0])

7490 >>> np.ma.choose(a, choice)

7491 masked_array(data=[3, 2, 1],

7492 mask=False,

7493 fill_value=999999)

7494

7495 """

7496 def fmask(x):

7497 "Returns the filled array, or True if masked."

7498 if x is masked:

7499 return True

7500 return filled(x)

7501

7502 def nmask(x):

7503 "Returns the mask, True if ``masked``, False if ``nomask``."

7504 if x is masked:

7505 return True

7506 return getmask(x)

7507 # Get the indices.

7508 c = filled(indices, 0)

7509 # Get the masks.

7510 masks = [nmask(x) for x in choices]

7511 data = [fmask(x) for x in choices]

7512 # Construct the mask

7513 outputmask = np.choose(c, masks, mode=mode)

7514 outputmask = make_mask(mask_or(outputmask, getmask(indices)),

7515 copy=False, shrink=True)

7516 # Get the choices.

7517 d = np.choose(c, data, mode=mode, out=out).view(MaskedArray)

7518 if out is not None:

7519 if isinstance(out, MaskedArray):

7520 out.__setmask__(outputmask)

7521 return out

7522 d.__setmask__(outputmask)

7523 return d

7524

7525

7526def round_(a, decimals=0, out=None):

7527 """

7528 Return a copy of a, rounded to 'decimals' places.

7529

7530 When 'decimals' is negative, it specifies the number of positions

7531 to the left of the decimal point. The real and imaginary parts of

7532 complex numbers are rounded separately. Nothing is done if the

7533 array is not of float type and 'decimals' is greater than or equal

7534 to 0.

7535

7536 Parameters

7537 ----------

7538 decimals : int

7539 Number of decimals to round to. May be negative.

7540 out : array_like

7541 Existing array to use for output.

7542 If not given, returns a default copy of a.

7543

7544 Notes

7545 -----

7546 If out is given and does not have a mask attribute, the mask of a

7547 is lost!

7548

7549 Examples

7550 --------

7551 >>> import numpy.ma as ma

7552 >>> x = [11.2, -3.973, 0.801, -1.41]

7553 >>> mask = [0, 0, 0, 1]

7554 >>> masked_x = ma.masked_array(x, mask)

7555 >>> masked_x

7556 masked_array(data=[11.2, -3.973, 0.801, --],

7557 mask=[False, False, False, True],

7558 fill_value=1e+20)

7559 >>> ma.round_(masked_x)

7560 masked_array(data=[11.0, -4.0, 1.0, --],

7561 mask=[False, False, False, True],

7562 fill_value=1e+20)

7563 >>> ma.round(masked_x, decimals=1)

7564 masked_array(data=[11.2, -4.0, 0.8, --],

7565 mask=[False, False, False, True],

7566 fill_value=1e+20)

7567 >>> ma.round_(masked_x, decimals=-1)

7568 masked_array(data=[10.0, -0.0, 0.0, --],

7569 mask=[False, False, False, True],

7570 fill_value=1e+20)

7571 """

7572 if out is None:

7573 return np.round_(a, decimals, out)

7574 else:

7575 np.round_(getdata(a), decimals, out)

7576 if hasattr(out, '_mask'):

7577 out._mask = getmask(a)

7578 return out

7579round = round_

7580

7581

7582# Needed by dot, so move here from extras.py. It will still be exported

7583# from extras.py for compatibility.

7584def mask_rowcols(a, axis=None):

7585 """

7586 Mask rows and/or columns of a 2D array that contain masked values.

7587

7588 Mask whole rows and/or columns of a 2D array that contain

7589 masked values. The masking behavior is selected using the

7590 `axis` parameter.

7591

7592 - If `axis` is None, rows *and* columns are masked.

7593 - If `axis` is 0, only rows are masked.

7594 - If `axis` is 1 or -1, only columns are masked.

7595

7596 Parameters

7597 ----------

7598 a : array_like, MaskedArray

7599 The array to mask. If not a MaskedArray instance (or if no array

7600 elements are masked). The result is a MaskedArray with `mask` set

7601 to `nomask` (False). Must be a 2D array.

7602 axis : int, optional

7603 Axis along which to perform the operation. If None, applies to a

7604 flattened version of the array.

7605

7606 Returns

7607 -------

7608 a : MaskedArray

7609 A modified version of the input array, masked depending on the value

7610 of the `axis` parameter.

7611

7612 Raises

7613 ------

7614 NotImplementedError

7615 If input array `a` is not 2D.

7616

7617 See Also

7618 --------

7619 mask_rows : Mask rows of a 2D array that contain masked values.

7620 mask_cols : Mask cols of a 2D array that contain masked values.

7621 masked_where : Mask where a condition is met.

7622

7623 Notes

7624 -----

7625 The input array's mask is modified by this function.

7626

7627 Examples

7628 --------

7629 >>> import numpy.ma as ma

7630 >>> a = np.zeros((3, 3), dtype=int)

7631 >>> a[1, 1] = 1

7632 >>> a

7633 array([[0, 0, 0],

7634 [0, 1, 0],

7635 [0, 0, 0]])

7636 >>> a = ma.masked_equal(a, 1)

7637 >>> a

7638 masked_array(

7639 data=[[0, 0, 0],

7640 [0, --, 0],

7641 [0, 0, 0]],

7642 mask=[[False, False, False],

7643 [False, True, False],

7644 [False, False, False]],

7645 fill_value=1)

7646 >>> ma.mask_rowcols(a)

7647 masked_array(

7648 data=[[0, --, 0],

7649 [--, --, --],

7650 [0, --, 0]],

7651 mask=[[False, True, False],

7652 [ True, True, True],

7653 [False, True, False]],

7654 fill_value=1)

7655

7656 """

7657 a = array(a, subok=False)

7658 if a.ndim != 2:

7659 raise NotImplementedError("mask_rowcols works for 2D arrays only.")

7660 m = getmask(a)

7661 # Nothing is masked: return a

7662 if m is nomask or not m.any():

7663 return a

7664 maskedval = m.nonzero()

7665 a._mask = a._mask.copy()

7666 if not axis:

7667 a[np.unique(maskedval[0])] = masked

7668 if axis in [None, 1, -1]:

7669 a[:, np.unique(maskedval[1])] = masked

7670 return a

7671

7672

7673# Include masked dot here to avoid import problems in getting it from

7674# extras.py. Note that it is not included in __all__, but rather exported

7675# from extras in order to avoid backward compatibility problems.

7676def dot(a, b, strict=False, out=None):

7677 """

7678 Return the dot product of two arrays.

7679

7680 This function is the equivalent of `numpy.dot` that takes masked values

7681 into account. Note that `strict` and `out` are in different position

7682 than in the method version. In order to maintain compatibility with the

7683 corresponding method, it is recommended that the optional arguments be

7684 treated as keyword only. At some point that may be mandatory.

7685

7686 .. note::

7687 Works only with 2-D arrays at the moment.

7688

7689

7690 Parameters

7691 ----------

7692 a, b : masked_array_like

7693 Inputs arrays.

7694 strict : bool, optional

7695 Whether masked data are propagated (True) or set to 0 (False) for

7696 the computation. Default is False. Propagating the mask means that

7697 if a masked value appears in a row or column, the whole row or

7698 column is considered masked.

7699 out : masked_array, optional

7700 Output argument. This must have the exact kind that would be returned

7701 if it was not used. In particular, it must have the right type, must be

7702 C-contiguous, and its dtype must be the dtype that would be returned

7703 for `dot(a,b)`. This is a performance feature. Therefore, if these

7704 conditions are not met, an exception is raised, instead of attempting

7705 to be flexible.

7706

7707 .. versionadded:: 1.10.2

7708

7709 See Also

7710 --------

7711 numpy.dot : Equivalent function for ndarrays.

7712

7713 Examples

7714 --------

7715 >>> a = np.ma.array([[1, 2, 3], [4, 5, 6]], mask=[[1, 0, 0], [0, 0, 0]])

7716 >>> b = np.ma.array([[1, 2], [3, 4], [5, 6]], mask=[[1, 0], [0, 0], [0, 0]])

7717 >>> np.ma.dot(a, b)

7718 masked_array(

7719 data=[[21, 26],

7720 [45, 64]],

7721 mask=[[False, False],

7722 [False, False]],

7723 fill_value=999999)

7724 >>> np.ma.dot(a, b, strict=True)

7725 masked_array(

7726 data=[[--, --],

7727 [--, 64]],

7728 mask=[[ True, True],

7729 [ True, False]],

7730 fill_value=999999)

7731

7732 """

7733 # !!!: Works only with 2D arrays. There should be a way to get it to run

7734 # with higher dimension

7735 if strict and (a.ndim == 2) and (b.ndim == 2):

7736 a = mask_rowcols(a, 0)

7737 b = mask_rowcols(b, 1)

7738 am = ~getmaskarray(a)

7739 bm = ~getmaskarray(b)

7740

7741 if out is None:

7742 d = np.dot(filled(a, 0), filled(b, 0))

7743 m = ~np.dot(am, bm)

7744 if d.ndim == 0:

7745 d = np.asarray(d)

7746 r = d.view(get_masked_subclass(a, b))

7747 r.__setmask__(m)

7748 return r

7749 else:

7750 d = np.dot(filled(a, 0), filled(b, 0), out._data)

7751 if out.mask.shape != d.shape:

7752 out._mask = np.empty(d.shape, MaskType)

7753 np.dot(am, bm, out._mask)

7754 np.logical_not(out._mask, out._mask)

7755 return out

7756

7757

7758def inner(a, b):

7759 """

7760 Returns the inner product of a and b for arrays of floating point types.

7761

7762 Like the generic NumPy equivalent the product sum is over the last dimension

7763 of a and b. The first argument is not conjugated.

7764

7765 """

7766 fa = filled(a, 0)

7767 fb = filled(b, 0)

7768 if fa.ndim == 0:

7769 fa.shape = (1,)

7770 if fb.ndim == 0:

7771 fb.shape = (1,)

7772 return np.inner(fa, fb).view(MaskedArray)

7773inner.__doc__ = doc_note(np.inner.__doc__,

7774 "Masked values are replaced by 0.")

7775innerproduct = inner

7776

7777

7778def outer(a, b):

7779 "maskedarray version of the numpy function."

7780 fa = filled(a, 0).ravel()

7781 fb = filled(b, 0).ravel()

7782 d = np.outer(fa, fb)

7783 ma = getmask(a)

7784 mb = getmask(b)

7785 if ma is nomask and mb is nomask:

7786 return masked_array(d)

7787 ma = getmaskarray(a)

7788 mb = getmaskarray(b)

7789 m = make_mask(1 - np.outer(1 - ma, 1 - mb), copy=False)

7790 return masked_array(d, mask=m)

7791outer.__doc__ = doc_note(np.outer.__doc__,

7792 "Masked values are replaced by 0.")

7793outerproduct = outer

7794

7795

7796def _convolve_or_correlate(f, a, v, mode, propagate_mask):

7797 """

7798 Helper function for ma.correlate and ma.convolve

7799 """

7800 if propagate_mask:

7801 # results which are contributed to by either item in any pair being invalid

7802 mask = (

7803 f(getmaskarray(a), np.ones(np.shape(v), dtype=bool), mode=mode)

7804 | f(np.ones(np.shape(a), dtype=bool), getmaskarray(v), mode=mode)

7805 )

7806 data = f(getdata(a), getdata(v), mode=mode)

7807 else:

7808 # results which are not contributed to by any pair of valid elements

7809 mask = ~f(~getmaskarray(a), ~getmaskarray(v))

7810 data = f(filled(a, 0), filled(v, 0), mode=mode)

7811

7812 return masked_array(data, mask=mask)

7813

7814

7815def correlate(a, v, mode='valid', propagate_mask=True):

7816 """

7817 Cross-correlation of two 1-dimensional sequences.

7818

7819 Parameters

7820 ----------

7821 a, v : array_like

7822 Input sequences.

7823 mode : {'valid', 'same', 'full'}, optional

7824 Refer to the `np.convolve` docstring. Note that the default

7825 is 'valid', unlike `convolve`, which uses 'full'.

7826 propagate_mask : bool

7827 If True, then a result element is masked if any masked element contributes towards it.

7828 If False, then a result element is only masked if no non-masked element

7829 contribute towards it

7830

7831 Returns

7832 -------

7833 out : MaskedArray

7834 Discrete cross-correlation of `a` and `v`.

7835

7836 See Also

7837 --------

7838 numpy.correlate : Equivalent function in the top-level NumPy module.

7839 """

7840 return _convolve_or_correlate(np.correlate, a, v, mode, propagate_mask)

7841

7842

7843def convolve(a, v, mode='full', propagate_mask=True):

7844 """

7845 Returns the discrete, linear convolution of two one-dimensional sequences.

7846

7847 Parameters

7848 ----------

7849 a, v : array_like

7850 Input sequences.

7851 mode : {'valid', 'same', 'full'}, optional

7852 Refer to the `np.convolve` docstring.

7853 propagate_mask : bool

7854 If True, then if any masked element is included in the sum for a result

7855 element, then the result is masked.

7856 If False, then the result element is only masked if no non-masked cells

7857 contribute towards it

7858

7859 Returns

7860 -------

7861 out : MaskedArray

7862 Discrete, linear convolution of `a` and `v`.

7863

7864 See Also

7865 --------

7866 numpy.convolve : Equivalent function in the top-level NumPy module.

7867 """

7868 return _convolve_or_correlate(np.convolve, a, v, mode, propagate_mask)

7869

7870

7871def allequal(a, b, fill_value=True):

7872 """

7873 Return True if all entries of a and b are equal, using

7874 fill_value as a truth value where either or both are masked.

7875

7876 Parameters

7877 ----------

7878 a, b : array_like

7879 Input arrays to compare.

7880 fill_value : bool, optional

7881 Whether masked values in a or b are considered equal (True) or not

7882 (False).

7883

7884 Returns

7885 -------

7886 y : bool

7887 Returns True if the two arrays are equal within the given

7888 tolerance, False otherwise. If either array contains NaN,

7889 then False is returned.

7890

7891 See Also

7892 --------

7893 all, any

7894 numpy.ma.allclose

7895

7896 Examples

7897 --------

7898 >>> a = np.ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1])

7899 >>> a

7900 masked_array(data=[10000000000.0, 1e-07, --],

7901 mask=[False, False, True],

7902 fill_value=1e+20)

7903

7904 >>> b = np.array([1e10, 1e-7, -42.0])

7905 >>> b

7906 array([ 1.00000000e+10, 1.00000000e-07, -4.20000000e+01])

7907 >>> np.ma.allequal(a, b, fill_value=False)

7908 False

7909 >>> np.ma.allequal(a, b)

7910 True

7911

7912 """

7913 m = mask_or(getmask(a), getmask(b))

7914 if m is nomask:

7915 x = getdata(a)

7916 y = getdata(b)

7917 d = umath.equal(x, y)

7918 return d.all()

7919 elif fill_value:

7920 x = getdata(a)

7921 y = getdata(b)

7922 d = umath.equal(x, y)

7923 dm = array(d, mask=m, copy=False)

7924 return dm.filled(True).all(None)

7925 else:

7926 return False

7927

7928

7929def allclose(a, b, masked_equal=True, rtol=1e-5, atol=1e-8):

7930 """

7931 Returns True if two arrays are element-wise equal within a tolerance.

7932

7933 This function is equivalent to `allclose` except that masked values

7934 are treated as equal (default) or unequal, depending on the `masked_equal`

7935 argument.

7936

7937 Parameters

7938 ----------

7939 a, b : array_like

7940 Input arrays to compare.

7941 masked_equal : bool, optional

7942 Whether masked values in `a` and `b` are considered equal (True) or not

7943 (False). They are considered equal by default.

7944 rtol : float, optional

7945 Relative tolerance. The relative difference is equal to ``rtol * b``.

7946 Default is 1e-5.

7947 atol : float, optional

7948 Absolute tolerance. The absolute difference is equal to `atol`.

7949 Default is 1e-8.

7950

7951 Returns

7952 -------

7953 y : bool

7954 Returns True if the two arrays are equal within the given

7955 tolerance, False otherwise. If either array contains NaN, then

7956 False is returned.

7957

7958 See Also

7959 --------

7960 all, any

7961 numpy.allclose : the non-masked `allclose`.

7962

7963 Notes

7964 -----

7965 If the following equation is element-wise True, then `allclose` returns

7966 True::

7967

7968 absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`))

7969

7970 Return True if all elements of `a` and `b` are equal subject to

7971 given tolerances.

7972

7973 Examples

7974 --------

7975 >>> a = np.ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1])

7976 >>> a

7977 masked_array(data=[10000000000.0, 1e-07, --],

7978 mask=[False, False, True],

7979 fill_value=1e+20)

7980 >>> b = np.ma.array([1e10, 1e-8, -42.0], mask=[0, 0, 1])

7981 >>> np.ma.allclose(a, b)

7982 False

7983

7984 >>> a = np.ma.array([1e10, 1e-8, 42.0], mask=[0, 0, 1])

7985 >>> b = np.ma.array([1.00001e10, 1e-9, -42.0], mask=[0, 0, 1])

7986 >>> np.ma.allclose(a, b)

7987 True

7988 >>> np.ma.allclose(a, b, masked_equal=False)

7989 False

7990

7991 Masked values are not compared directly.

7992

7993 >>> a = np.ma.array([1e10, 1e-8, 42.0], mask=[0, 0, 1])

7994 >>> b = np.ma.array([1.00001e10, 1e-9, 42.0], mask=[0, 0, 1])

7995 >>> np.ma.allclose(a, b)

7996 True

7997 >>> np.ma.allclose(a, b, masked_equal=False)

7998 False

7999

8000 """

8001 x = masked_array(a, copy=False)

8002 y = masked_array(b, copy=False)

8003

8004 # make sure y is an inexact type to avoid abs(MIN_INT); will cause

8005 # casting of x later.

8006 # NOTE: We explicitly allow timedelta, which used to work. This could

8007 # possibly be deprecated. See also gh-18286.

8008 # timedelta works if `atol` is an integer or also a timedelta.

8009 # Although, the default tolerances are unlikely to be useful

8010 if y.dtype.kind != "m":

8011 dtype = np.result_type(y, 1.)

8012 if y.dtype != dtype:

8013 y = masked_array(y, dtype=dtype, copy=False)

8014

8015 m = mask_or(getmask(x), getmask(y))

8016 xinf = np.isinf(masked_array(x, copy=False, mask=m)).filled(False)

8017 # If we have some infs, they should fall at the same place.

8018 if not np.all(xinf == filled(np.isinf(y), False)):

8019 return False

8020 # No infs at all

8021 if not np.any(xinf):

8022 d = filled(less_equal(absolute(x - y), atol + rtol * absolute(y)),

8023 masked_equal)

8024 return np.all(d)

8025

8026 if not np.all(filled(x[xinf] == y[xinf], masked_equal)):

8027 return False

8028 x = x[~xinf]

8029 y = y[~xinf]

8030

8031 d = filled(less_equal(absolute(x - y), atol + rtol * absolute(y)),

8032 masked_equal)

8033

8034 return np.all(d)

8035

8036

8037def asarray(a, dtype=None, order=None):

8038 """

8039 Convert the input to a masked array of the given data-type.

8040

8041 No copy is performed if the input is already an `ndarray`. If `a` is

8042 a subclass of `MaskedArray`, a base class `MaskedArray` is returned.

8043

8044 Parameters

8045 ----------

8046 a : array_like

8047 Input data, in any form that can be converted to a masked array. This

8048 includes lists, lists of tuples, tuples, tuples of tuples, tuples

8049 of lists, ndarrays and masked arrays.

8050 dtype : dtype, optional

8051 By default, the data-type is inferred from the input data.

8052 order : {'C', 'F'}, optional

8053 Whether to use row-major ('C') or column-major ('FORTRAN') memory

8054 representation. Default is 'C'.

8055

8056 Returns

8057 -------

8058 out : MaskedArray

8059 Masked array interpretation of `a`.

8060

8061 See Also

8062 --------

8063 asanyarray : Similar to `asarray`, but conserves subclasses.

8064

8065 Examples

8066 --------

8067 >>> x = np.arange(10.).reshape(2, 5)

8068 >>> x

8069 array([[0., 1., 2., 3., 4.],

8070 [5., 6., 7., 8., 9.]])

8071 >>> np.ma.asarray(x)

8072 masked_array(

8073 data=[[0., 1., 2., 3., 4.],

8074 [5., 6., 7., 8., 9.]],

8075 mask=False,

8076 fill_value=1e+20)

8077 >>> type(np.ma.asarray(x))

8078 <class 'numpy.ma.core.MaskedArray'>

8079

8080 """

8081 order = order or 'C'

8082 return masked_array(a, dtype=dtype, copy=False, keep_mask=True,

8083 subok=False, order=order)

8084

8085

8086def asanyarray(a, dtype=None):

8087 """

8088 Convert the input to a masked array, conserving subclasses.

8089

8090 If `a` is a subclass of `MaskedArray`, its class is conserved.

8091 No copy is performed if the input is already an `ndarray`.

8092

8093 Parameters

8094 ----------

8095 a : array_like

8096 Input data, in any form that can be converted to an array.

8097 dtype : dtype, optional

8098 By default, the data-type is inferred from the input data.

8099 order : {'C', 'F'}, optional

8100 Whether to use row-major ('C') or column-major ('FORTRAN') memory

8101 representation. Default is 'C'.

8102

8103 Returns

8104 -------

8105 out : MaskedArray

8106 MaskedArray interpretation of `a`.

8107

8108 See Also

8109 --------

8110 asarray : Similar to `asanyarray`, but does not conserve subclass.

8111

8112 Examples

8113 --------

8114 >>> x = np.arange(10.).reshape(2, 5)

8115 >>> x

8116 array([[0., 1., 2., 3., 4.],

8117 [5., 6., 7., 8., 9.]])

8118 >>> np.ma.asanyarray(x)

8119 masked_array(

8120 data=[[0., 1., 2., 3., 4.],

8121 [5., 6., 7., 8., 9.]],

8122 mask=False,

8123 fill_value=1e+20)

8124 >>> type(np.ma.asanyarray(x))

8125 <class 'numpy.ma.core.MaskedArray'>

8126

8127 """

8128 # workaround for #8666, to preserve identity. Ideally the bottom line

8129 # would handle this for us.

8130 if isinstance(a, MaskedArray) and (dtype is None or dtype == a.dtype):

8131 return a

8132 return masked_array(a, dtype=dtype, copy=False, keep_mask=True, subok=True)

8133

8134

8135##############################################################################

8136# Pickling #

8137##############################################################################

8138

8139

8140def fromfile(file, dtype=float, count=-1, sep=''):

8141 raise NotImplementedError(

8142 "fromfile() not yet implemented for a MaskedArray.")

8143

8144

8145def fromflex(fxarray):

8146 """

8147 Build a masked array from a suitable flexible-type array.

8148

8149 The input array has to have a data-type with ``_data`` and ``_mask``

8150 fields. This type of array is output by `MaskedArray.toflex`.

8151

8152 Parameters

8153 ----------

8154 fxarray : ndarray

8155 The structured input array, containing ``_data`` and ``_mask``

8156 fields. If present, other fields are discarded.

8157

8158 Returns

8159 -------

8160 result : MaskedArray

8161 The constructed masked array.

8162

8163 See Also

8164 --------

8165 MaskedArray.toflex : Build a flexible-type array from a masked array.

8166

8167 Examples

8168 --------

8169 >>> x = np.ma.array(np.arange(9).reshape(3, 3), mask=[0] + [1, 0] * 4)

8170 >>> rec = x.toflex()

8171 >>> rec

8172 array([[(0, False), (1, True), (2, False)],

8173 [(3, True), (4, False), (5, True)],

8174 [(6, False), (7, True), (8, False)]],

8175 dtype=[('_data', '<i8'), ('_mask', '?')])

8176 >>> x2 = np.ma.fromflex(rec)

8177 >>> x2

8178 masked_array(

8179 data=[[0, --, 2],

8180 [--, 4, --],

8181 [6, --, 8]],

8182 mask=[[False, True, False],

8183 [ True, False, True],

8184 [False, True, False]],

8185 fill_value=999999)

8186

8187 Extra fields can be present in the structured array but are discarded:

8188

8189 >>> dt = [('_data', '<i4'), ('_mask', '|b1'), ('field3', '<f4')]

8190 >>> rec2 = np.zeros((2, 2), dtype=dt)

8191 >>> rec2

8192 array([[(0, False, 0.), (0, False, 0.)],

8193 [(0, False, 0.), (0, False, 0.)]],

8194 dtype=[('_data', '<i4'), ('_mask', '?'), ('field3', '<f4')])

8195 >>> y = np.ma.fromflex(rec2)

8196 >>> y

8197 masked_array(

8198 data=[[0, 0],

8199 [0, 0]],

8200 mask=[[False, False],

8201 [False, False]],

8202 fill_value=999999,

8203 dtype=int32)

8204

8205 """

8206 return masked_array(fxarray['_data'], mask=fxarray['_mask'])

8207

8208

8209class _convert2ma:

8210

8211 """

8212 Convert functions from numpy to numpy.ma.

8213

8214 Parameters

8215 ----------

8216 _methodname : string

8217 Name of the method to transform.

8218

8219 """

8220 __doc__ = None

8221

8222 def __init__(self, funcname, np_ret, np_ma_ret, params=None):

8223 self._func = getattr(np, funcname)

8224 self.__doc__ = self.getdoc(np_ret, np_ma_ret)

8225 self._extras = params or {}

8226

8227 def getdoc(self, np_ret, np_ma_ret):

8228 "Return the doc of the function (from the doc of the method)."

8229 doc = getattr(self._func, '__doc__', None)

8230 sig = get_object_signature(self._func)

8231 if doc:

8232 doc = self._replace_return_type(doc, np_ret, np_ma_ret)

8233 # Add the signature of the function at the beginning of the doc

8234 if sig:

8235 sig = "%s%s\n" % (self._func.__name__, sig)

8236 doc = sig + doc

8237 return doc

8238

8239 def _replace_return_type(self, doc, np_ret, np_ma_ret):

8240 """

8241 Replace documentation of ``np`` function's return type.

8242

8243 Replaces it with the proper type for the ``np.ma`` function.

8244

8245 Parameters

8246 ----------

8247 doc : str

8248 The documentation of the ``np`` method.

8249 np_ret : str

8250 The return type string of the ``np`` method that we want to

8251 replace. (e.g. "out : ndarray")

8252 np_ma_ret : str

8253 The return type string of the ``np.ma`` method.

8254 (e.g. "out : MaskedArray")

8255 """

8256 if np_ret not in doc:

8257 raise RuntimeError(

8258 f"Failed to replace `{np_ret}` with `{np_ma_ret}`. "

8259 f"The documentation string for return type, {np_ret}, is not "

8260 f"found in the docstring for `np.{self._func.__name__}`. "

8261 f"Fix the docstring for `np.{self._func.__name__}` or "

8262 "update the expected string for return type."

8263 )

8264

8265 return doc.replace(np_ret, np_ma_ret)

8266

8267 def __call__(self, *args, **params):

8268 # Find the common parameters to the call and the definition

8269 _extras = self._extras

8270 common_params = set(params).intersection(_extras)

8271 # Drop the common parameters from the call

8272 for p in common_params:

8273 _extras[p] = params.pop(p)

8274 # Get the result

8275 result = self._func.__call__(*args, **params).view(MaskedArray)

8276 if "fill_value" in common_params:

8277 result.fill_value = _extras.get("fill_value", None)

8278 if "hardmask" in common_params:

8279 result._hardmask = bool(_extras.get("hard_mask", False))

8280 return result

8281

8282

8283arange = _convert2ma(

8284 'arange',

8285 params=dict(fill_value=None, hardmask=False),

8286 np_ret='arange : ndarray',

8287 np_ma_ret='arange : MaskedArray',

8288)

8289clip = _convert2ma(

8290 'clip',

8291 params=dict(fill_value=None, hardmask=False),

8292 np_ret='clipped_array : ndarray',

8293 np_ma_ret='clipped_array : MaskedArray',

8294)

8295diff = _convert2ma(

8296 'diff',

8297 params=dict(fill_value=None, hardmask=False),

8298 np_ret='diff : ndarray',

8299 np_ma_ret='diff : MaskedArray',

8300)

8301empty = _convert2ma(

8302 'empty',

8303 params=dict(fill_value=None, hardmask=False),

8304 np_ret='out : ndarray',

8305 np_ma_ret='out : MaskedArray',

8306)

8307empty_like = _convert2ma(

8308 'empty_like',

8309 np_ret='out : ndarray',

8310 np_ma_ret='out : MaskedArray',

8311)

8312frombuffer = _convert2ma(

8313 'frombuffer',

8314 np_ret='out : ndarray',

8315 np_ma_ret='out: MaskedArray',

8316)

8317fromfunction = _convert2ma(

8318 'fromfunction',

8319 np_ret='fromfunction : any',

8320 np_ma_ret='fromfunction: MaskedArray',

8321)

8322identity = _convert2ma(

8323 'identity',

8324 params=dict(fill_value=None, hardmask=False),

8325 np_ret='out : ndarray',

8326 np_ma_ret='out : MaskedArray',

8327)

8328indices = _convert2ma(

8329 'indices',

8330 params=dict(fill_value=None, hardmask=False),

8331 np_ret='grid : one ndarray or tuple of ndarrays',

8332 np_ma_ret='grid : one MaskedArray or tuple of MaskedArrays',

8333)

8334ones = _convert2ma(

8335 'ones',

8336 params=dict(fill_value=None, hardmask=False),

8337 np_ret='out : ndarray',

8338 np_ma_ret='out : MaskedArray',

8339)

8340ones_like = _convert2ma(

8341 'ones_like',

8342 np_ret='out : ndarray',

8343 np_ma_ret='out : MaskedArray',

8344)

8345squeeze = _convert2ma(

8346 'squeeze',

8347 params=dict(fill_value=None, hardmask=False),

8348 np_ret='squeezed : ndarray',

8349 np_ma_ret='squeezed : MaskedArray',

8350)

8351zeros = _convert2ma(

8352 'zeros',

8353 params=dict(fill_value=None, hardmask=False),

8354 np_ret='out : ndarray',

8355 np_ma_ret='out : MaskedArray',

8356)

8357zeros_like = _convert2ma(

8358 'zeros_like',

8359 np_ret='out : ndarray',

8360 np_ma_ret='out : MaskedArray',

8361)

8362

8363

8364def append(a, b, axis=None):

8365 """Append values to the end of an array.

8366

8367 .. versionadded:: 1.9.0

8368

8369 Parameters

8370 ----------

8371 a : array_like

8372 Values are appended to a copy of this array.

8373 b : array_like

8374 These values are appended to a copy of `a`. It must be of the

8375 correct shape (the same shape as `a`, excluding `axis`). If `axis`

8376 is not specified, `b` can be any shape and will be flattened

8377 before use.

8378 axis : int, optional

8379 The axis along which `v` are appended. If `axis` is not given,

8380 both `a` and `b` are flattened before use.

8381

8382 Returns

8383 -------

8384 append : MaskedArray

8385 A copy of `a` with `b` appended to `axis`. Note that `append`

8386 does not occur in-place: a new array is allocated and filled. If

8387 `axis` is None, the result is a flattened array.

8388

8389 See Also

8390 --------

8391 numpy.append : Equivalent function in the top-level NumPy module.

8392

8393 Examples

8394 --------

8395 >>> import numpy.ma as ma

8396 >>> a = ma.masked_values([1, 2, 3], 2)

8397 >>> b = ma.masked_values([[4, 5, 6], [7, 8, 9]], 7)

8398 >>> ma.append(a, b)

8399 masked_array(data=[1, --, 3, 4, 5, 6, --, 8, 9],

8400 mask=[False, True, False, False, False, False, True, False,

8401 False],

8402 fill_value=999999)

8403 """

8404 return concatenate([a, b], axis)