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

6385 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'

6386

6387 """

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

6389

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

6391 """

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

6393

6394 .. warning::

6395 This function is not implemented yet.

6396

6397 Raises

6398 ------

6399 NotImplementedError

6400 When `tofile` is called.

6401

6402 """

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

6404

6405 def toflex(self):

6406 """

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

6408

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

6410

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

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

6413

6414 Parameters

6415 ----------

6416 None

6417

6418 Returns

6419 -------

6420 record : ndarray

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

6422 containing a value, the second element containing the corresponding

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

6424

6425 Notes

6426 -----

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

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

6429

6430 Examples

6431 --------

6432 >>> import numpy as np

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

6434 >>> x

6435 masked_array(

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

6437 [--, 5, --],

6438 [7, --, 9]],

6439 mask=[[False, True, False],

6440 [ True, False, True],

6441 [False, True, False]],

6442 fill_value=999999)

6443 >>> x.toflex()

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

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

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

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

6448

6449 """

6450 # Get the basic dtype.

6451 ddtype = self.dtype

6452 # Make sure we have a mask

6453 _mask = self._mask

6454 if _mask is None:

6455 _mask = make_mask_none(self.shape, ddtype)

6456 # And get its dtype

6457 mdtype = self._mask.dtype

6458

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

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

6461 record['_data'] = self._data

6462 record['_mask'] = self._mask

6463 return record

6464 torecords = toflex

6465

6466 # Pickling

6467 def __getstate__(self):

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

6469 purposes.

6470

6471 """

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

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

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

6475

6476 def __setstate__(self, state):

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

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

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

6480

6481 - class name

6482 - a tuple giving the shape of the data

6483 - a typecode for the data

6484 - a binary string for the data

6485 - a binary string for the mask.

6486

6487 """

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

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

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

6491 self.fill_value = flv

6492

6493 def __reduce__(self):

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

6495

6496 """

6497 return (_mareconstruct,

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

6499 self.__getstate__())

6500

6501 def __deepcopy__(self, memo=None):

6502 from copy import deepcopy

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

6504 if memo is None:

6505 memo = {}

6506 memo[id(self)] = copied

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

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

6509 # as clearly documented for np.copy(), you need to use

6510 # deepcopy() directly for arrays of object type that may

6511 # contain compound types--you cannot depend on normal

6512 # copy semantics to do the right thing here

6513 if self.dtype.hasobject:

6514 copied._data[...] = deepcopy(copied._data)

6515 return copied

6516

6517

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

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

6520 information stored in a pickle.

6521

6522 """

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

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

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

6526

6527

6528class mvoid(MaskedArray):

6529 """

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

6531 """

6532

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

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

6535 copy = None if not copy else True

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

6537 _data = _data.view(self)

6538 _data._hardmask = hardmask

6539 if mask is not nomask:

6540 if isinstance(mask, np.void):

6541 _data._mask = mask

6542 else:

6543 try:

6544 # Mask is already a 0D array

6545 _data._mask = np.void(mask)

6546 except TypeError:

6547 # Transform the mask to a void

6548 mdtype = make_mask_descr(dtype)

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

6550 if fill_value is not None:

6551 _data.fill_value = fill_value

6552 return _data

6553

6554 @property

6555 def _data(self):

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

6557 return super()._data[()]

6558

6559 def __getitem__(self, indx):

6560 """

6561 Get the index.

6562

6563 """

6564 m = self._mask

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

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

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

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

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

6570 # and we can not say masked/unmasked.

6571 # The result is no longer mvoid!

6572 # See also issue #6724.

6573 return masked_array(

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

6575 fill_value=self._fill_value[indx],

6576 hard_mask=self._hardmask)

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

6578 return masked

6579 return self._data[indx]

6580

6581 def __setitem__(self, indx, value):

6582 self._data[indx] = value

6583 if self._hardmask:

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

6585 else:

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

6587

6588 def __str__(self):

6589 m = self._mask

6590 if m is nomask:

6591 return str(self._data)

6592

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

6594 data_arr = super()._data

6595 res = data_arr.astype(rdtype)

6596 _recursive_printoption(res, self._mask, masked_print_option)

6597 return str(res)

6598

6599 __repr__ = __str__

6600

6601 def __iter__(self):

6602 "Defines an iterator for mvoid"

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

6604 if _mask is nomask:

6605 yield from _data

6606 else:

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

6608 if m:

6609 yield masked

6610 else:

6611 yield d

6612

6613 def __len__(self):

6614 return self._data.__len__()

6615

6616 def filled(self, fill_value=None):

6617 """

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

6619

6620 Parameters

6621 ----------

6622 fill_value : array_like, optional

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

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

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

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

6627

6628 Returns

6629 -------

6630 filled_void

6631 A `np.void` object

6632

6633 See Also

6634 --------

6635 MaskedArray.filled

6636

6637 """

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

6639

6640 def tolist(self):

6641 """

6642 Transforms the mvoid object into a tuple.

6643

6644 Masked fields are replaced by None.

6645

6646 Returns

6647 -------

6648 returned_tuple

6649 Tuple of fields

6650 """

6651 _mask = self._mask

6652 if _mask is nomask:

6653 return self._data.tolist()

6654 result = []

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

6656 if m:

6657 result.append(None)

6658 else:

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

6660 result.append(d.item())

6661 return tuple(result)

6662

6663

6664##############################################################################

6665# Shortcuts #

6666##############################################################################

6667

6668

6669def isMaskedArray(x):

6670 """

6671 Test whether input is an instance of MaskedArray.

6672

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

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

6675

6676 Parameters

6677 ----------

6678 x : object

6679 Object to test.

6680

6681 Returns

6682 -------

6683 result : bool

6684 True if `x` is a MaskedArray.

6685

6686 See Also

6687 --------

6688 isMA : Alias to isMaskedArray.

6689 isarray : Alias to isMaskedArray.

6690

6691 Examples

6692 --------

6693 >>> import numpy as np

6694 >>> import numpy.ma as ma

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

6696 >>> a

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

6698 [ 0., 1., 0.],

6699 [ 0., 0., 1.]])

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

6701 >>> m

6702 masked_array(

6703 data=[[1.0, --, --],

6704 [--, 1.0, --],

6705 [--, --, 1.0]],

6706 mask=[[False, True, True],

6707 [ True, False, True],

6708 [ True, True, False]],

6709 fill_value=0.0)

6710 >>> ma.isMaskedArray(a)

6711 False

6712 >>> ma.isMaskedArray(m)

6713 True

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

6715 False

6716

6717 """

6718 return isinstance(x, MaskedArray)

6719

6720

6721isarray = isMaskedArray

6722isMA = isMaskedArray # backward compatibility

6723

6724

6725class MaskedConstant(MaskedArray):

6726 # the lone np.ma.masked instance

6727 __singleton = None

6728

6729 @classmethod

6730 def __has_singleton(cls):

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

6732 # superclass singleton

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

6734

6735 def __new__(cls):

6736 if not cls.__has_singleton():

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

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

6739 data = np.array(0.)

6740 mask = np.array(True)

6741

6742 # prevent any modifications

6743 data.flags.writeable = False

6744 mask.flags.writeable = False

6745

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

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

6748 # within our control

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

6750

6751 return cls.__singleton

6752

6753 def __array_finalize__(self, obj):

6754 if not self.__has_singleton():

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

6756 # properties normally

6757 return super().__array_finalize__(obj)

6758 elif self is self.__singleton:

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

6760 pass

6761 else:

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

6763 # duplicate maskedconstant.

6764 self.__class__ = MaskedArray

6765 MaskedArray.__array_finalize__(self, obj)

6766

6767 def __array_wrap__(self, obj, context=None, return_scalar=False):

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

6769

6770 def __str__(self):

6771 return str(masked_print_option._display)

6772

6773 def __repr__(self):

6774 if self is MaskedConstant.__singleton:

6775 return 'masked'

6776 else:

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

6778 return object.__repr__(self)

6779

6780 def __format__(self, format_spec):

6781 # Replace ndarray.__format__ with the default, which supports no

6782 # format characters.

6783 # Supporting format characters is unwise here, because we do not know

6784 # what type the user was expecting - better to not guess.

6785 try:

6786 return object.__format__(self, format_spec)

6787 except TypeError:

6788 # 2020-03-23, NumPy 1.19.0

6789 warnings.warn(

6790 "Format strings passed to MaskedConstant are ignored,"

6791 " but in future may error or produce different behavior",

6792 FutureWarning, stacklevel=2

6793 )

6794 return object.__format__(self, "")

6795

6796 def __reduce__(self):

6797 """Override of MaskedArray's __reduce__.

6798 """

6799 return (self.__class__, ())

6800

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

6802 # trying to modify the readonly data and mask arrays

6803 def __iop__(self, other):

6804 return self

6805 __iadd__ = \

6806 __isub__ = \

6807 __imul__ = \

6808 __ifloordiv__ = \

6809 __itruediv__ = \

6810 __ipow__ = \

6811 __iop__

6812 del __iop__ # don't leave this around

6813

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

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

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

6817 # precedent for this with `np.bool` scalars.

6818 return self

6819

6820 def __copy__(self):

6821 return self

6822

6823 def __deepcopy__(self, memo):

6824 return self

6825

6826 def __setattr__(self, attr, value):

6827 if not self.__has_singleton():

6828 # allow the singleton to be initialized

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

6830 elif self is self.__singleton:

6831 raise AttributeError(

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

6833 else:

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

6835 # where we set the __class__ attribute

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

6837

6838

6839masked = masked_singleton = MaskedConstant()

6840masked_array = MaskedArray

6841

6842

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

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

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

6846 """

6847 Shortcut to MaskedArray.

6848

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

6850 compatibility.

6851

6852 """

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

6854 subok=subok, keep_mask=keep_mask,

6855 hard_mask=hard_mask, fill_value=fill_value,

6856 ndmin=ndmin, shrink=shrink, order=order)

6857

6858

6859array.__doc__ = masked_array.__doc__

6860

6861

6862def is_masked(x):

6863 """

6864 Determine whether input has masked values.

6865

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

6867 input is a MaskedArray containing masked values.

6868

6869 Parameters

6870 ----------

6871 x : array_like

6872 Array to check for masked values.

6873

6874 Returns

6875 -------

6876 result : bool

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

6878

6879 Examples

6880 --------

6881 >>> import numpy as np

6882 >>> import numpy.ma as ma

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

6884 >>> x

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

6886 mask=[ True, False, True, False, False],

6887 fill_value=0)

6888 >>> ma.is_masked(x)

6889 True

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

6891 >>> x

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

6893 mask=False,

6894 fill_value=42)

6895 >>> ma.is_masked(x)

6896 False

6897

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

6899

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

6901 >>> ma.is_masked(x)

6902 False

6903 >>> x = 'a string'

6904 >>> ma.is_masked(x)

6905 False

6906

6907 """

6908 m = getmask(x)

6909 if m is nomask:

6910 return False

6911 elif m.any():

6912 return True

6913 return False

6914

6915

6916##############################################################################

6917# Extrema functions #

6918##############################################################################

6919

6920

6921class _extrema_operation(_MaskedUFunc):

6922 """

6923 Generic class for maximum/minimum functions.

6924

6925 .. note::

6926 This is the base class for `_maximum_operation` and

6927 `_minimum_operation`.

6928

6929 """

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

6931 super().__init__(ufunc)

6932 self.compare = compare

6933 self.fill_value_func = fill_value

6934

6935 def __call__(self, a, b):

6936 "Executes the call behavior."

6937

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

6939

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

6941 "Reduce target along the given axis."

6942 target = narray(target, copy=None, subok=True)

6943 m = getmask(target)

6944

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

6946 name = self.__name__

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

6948 warnings.warn(

6949 f"In the future the default for ma.{name}.reduce will be axis=0, "

6950 f"not the current None, to match np.{name}.reduce. "

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

6952 MaskedArrayFutureWarning, stacklevel=2)

6953 axis = None

6954

6955 if axis is not np._NoValue:

6956 kwargs = {'axis': axis}

6957 else:

6958 kwargs = {}

6959

6960 if m is nomask:

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

6962 else:

6963 target = target.filled(

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

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

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

6967 if hasattr(t, '_mask'):

6968 t._mask = m

6969 elif m:

6970 t = masked

6971 return t

6972

6973 def outer(self, a, b):

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

6975 ma = getmask(a)

6976 mb = getmask(b)

6977 if ma is nomask and mb is nomask:

6978 m = nomask

6979 else:

6980 ma = getmaskarray(a)

6981 mb = getmaskarray(b)

6982 m = logical_or.outer(ma, mb)

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

6984 if not isinstance(result, MaskedArray):

6985 result = result.view(MaskedArray)

6986 result._mask = m

6987 return result

6988

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

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

6991

6992 try:

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

6994 except (AttributeError, TypeError):

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

6996 # fill_value argument

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

6998 out=out, **kwargs)

6999

7000

7001min.__doc__ = MaskedArray.min.__doc__

7002

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

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

7005

7006 try:

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

7008 except (AttributeError, TypeError):

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

7010 # fill_value argument

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

7012 out=out, **kwargs)

7013

7014

7015max.__doc__ = MaskedArray.max.__doc__

7016

7017

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

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

7020 try:

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

7022 except (AttributeError, TypeError):

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

7024 # a fill_value argument

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

7026 out=out, **kwargs)

7027

7028

7029ptp.__doc__ = MaskedArray.ptp.__doc__

7030

7031

7032##############################################################################

7033# Definition of functions from the corresponding methods #

7034##############################################################################

7035

7036

7037def _frommethod(methodname: str, reversed: bool = False):

7038 """

7039 Define functions from existing MaskedArray methods.

7040

7041 Parameters

7042 ----------

7043 methodname : str

7044 Name of the method to transform.

7045 reversed : bool, optional

7046 Whether to reverse the first two arguments of the method. Default is False.

7047 """

7048 method = getattr(MaskedArray, methodname)

7049 assert callable(method)

7050

7051 signature = inspect.signature(method)

7052 params = list(signature.parameters.values())

7053 params[0] = params[0].replace(name="a") # rename 'self' to 'a'

7054

7055 if reversed:

7056 assert len(params) >= 2

7057 params[0], params[1] = params[1], params[0]

7058

7059 def wrapper(a, b, *args, **params):

7060 return getattr(asanyarray(b), methodname)(a, *args, **params)

7061

7062 else:

7063 def wrapper(a, *args, **params):

7064 return getattr(asanyarray(a), methodname)(*args, **params)

7065

7066 wrapper.__signature__ = signature.replace(parameters=params)

7067 wrapper.__name__ = wrapper.__qualname__ = methodname

7068

7069 # __doc__ is None when using `python -OO ...`

7070 if method.__doc__ is not None:

7071 str_signature = f"{methodname}{signature}"

7072 # TODO: For methods with a docstring "Parameters" section, that do not already

7073 # mention `a` (see e.g. `MaskedArray.var.__doc__`), it should be inserted there.

7074 wrapper.__doc__ = f" {str_signature}\n{method.__doc__}"

7075

7076 return wrapper

7077

7078

7079all = _frommethod('all')

7080anomalies = anom = _frommethod('anom')

7081any = _frommethod('any')

7082argmax = _frommethod('argmax')

7083argmin = _frommethod('argmin')

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

7085count = _frommethod('count')

7086cumprod = _frommethod('cumprod')

7087cumsum = _frommethod('cumsum')

7088copy = _frommethod('copy')

7089diagonal = _frommethod('diagonal')

7090harden_mask = _frommethod('harden_mask')

7091ids = _frommethod('ids')

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

7093mean = _frommethod('mean')

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

7095nonzero = _frommethod('nonzero')

7096prod = _frommethod('prod')

7097product = _frommethod('product')

7098ravel = _frommethod('ravel')

7099repeat = _frommethod('repeat')

7100shrink_mask = _frommethod('shrink_mask')

7101soften_mask = _frommethod('soften_mask')

7102std = _frommethod('std')

7103sum = _frommethod('sum')

7104swapaxes = _frommethod('swapaxes')

7105#take = _frommethod('take')

7106trace = _frommethod('trace')

7107var = _frommethod('var')

7108

7109

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

7111 """

7112

7113 """

7114 a = masked_array(a)

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

7116

7117

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

7119 """

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

7121

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

7123 `numpy.power`.

7124

7125 See Also

7126 --------

7127 numpy.power

7128

7129 Notes

7130 -----

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

7132 None.

7133

7134 Examples

7135 --------

7136 >>> import numpy as np

7137 >>> import numpy.ma as ma

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

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

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

7141 >>> masked_x

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

7143 mask=[False, False, False, True],

7144 fill_value=1e+20)

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

7146 masked_array(data=[125.43999999999998, 15.784728999999999,

7147 0.6416010000000001, --],

7148 mask=[False, False, False, True],

7149 fill_value=1e+20)

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

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

7152 >>> masked_y

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

7154 mask=[False, False, False, True],

7155 fill_value=1e+20)

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

7157 masked_array(data=[0.2988071523335984, 15.784728999999999, 1.0, --],

7158 mask=[False, False, False, True],

7159 fill_value=1e+20)

7160

7161 """

7162 if third is not None:

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

7164 # Get the masks

7165 ma = getmask(a)

7166 mb = getmask(b)

7167 m = mask_or(ma, mb)

7168 # Get the rawdata

7169 fa = getdata(a)

7170 fb = getdata(b)

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

7172 if isinstance(a, MaskedArray):

7173 basetype = type(a)

7174 else:

7175 basetype = MaskedArray

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

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

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

7179 result._update_from(a)

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

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

7182 # Add the initial mask

7183 if m is not nomask:

7184 if not result.ndim:

7185 return masked

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

7187 # Fix the invalid parts

7188 if invalid.any():

7189 if not result.ndim:

7190 return masked

7191 elif result._mask is nomask:

7192 result._mask = invalid

7193 result._data[invalid] = result.fill_value

7194 return result

7195

7196

7197def argsort(a, axis=np._NoValue, kind=None, order=None, endwith=True,

7198 fill_value=None, *, stable=None):

7199 "Function version of the eponymous method."

7200 a = np.asanyarray(a)

7201

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

7203 if axis is np._NoValue:

7204 axis = _deprecate_argsort_axis(a)

7205

7206 if isinstance(a, MaskedArray):

7207 return a.argsort(axis=axis, kind=kind, order=order, endwith=endwith,

7208 fill_value=fill_value, stable=None)

7209 else:

7210 return a.argsort(axis=axis, kind=kind, order=order, stable=None)

7211

7212

7213argsort.__doc__ = MaskedArray.argsort.__doc__

7214

7215def sort(a, axis=-1, kind=None, order=None, endwith=True, fill_value=None, *,

7216 stable=None):

7217 """

7218 Return a sorted copy of the masked array.

7219

7220 Equivalent to creating a copy of the array

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

7222

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

7224

7225 See Also

7226 --------

7227 MaskedArray.sort : equivalent method

7228

7229 Examples

7230 --------

7231 >>> import numpy as np

7232 >>> import numpy.ma as ma

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

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

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

7236 >>> masked_x

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

7238 mask=[False, False, False, True],

7239 fill_value=1e+20)

7240 >>> ma.sort(masked_x)

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

7242 mask=[False, False, False, True],

7243 fill_value=1e+20)

7244 """

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

7246 if axis is None:

7247 a = a.flatten()

7248 axis = 0

7249

7250 if isinstance(a, MaskedArray):

7251 a.sort(axis=axis, kind=kind, order=order, endwith=endwith,

7252 fill_value=fill_value, stable=stable)

7253 else:

7254 a.sort(axis=axis, kind=kind, order=order, stable=stable)

7255 return a

7256

7257

7258def compressed(x):

7259 """

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

7261

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

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

7264

7265 See Also

7266 --------

7267 ma.MaskedArray.compressed : Equivalent method.

7268

7269 Examples

7270 --------

7271 >>> import numpy as np

7272

7273 Create an array with negative values masked:

7274

7275 >>> import numpy as np

7276 >>> x = np.array([[1, -1, 0], [2, -1, 3], [7, 4, -1]])

7277 >>> masked_x = np.ma.masked_array(x, mask=x < 0)

7278 >>> masked_x

7279 masked_array(

7280 data=[[1, --, 0],

7281 [2, --, 3],

7282 [7, 4, --]],

7283 mask=[[False, True, False],

7284 [False, True, False],

7285 [False, False, True]],

7286 fill_value=999999)

7287

7288 Compress the masked array into a 1-D array of non-masked values:

7289

7290 >>> np.ma.compressed(masked_x)

7291 array([1, 0, 2, 3, 7, 4])

7292

7293 """

7294 return asanyarray(x).compressed()

7295

7296

7297def concatenate(arrays, axis=0):

7298 """

7299 Concatenate a sequence of arrays along the given axis.

7300

7301 Parameters

7302 ----------

7303 arrays : sequence of array_like

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

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

7306 axis : int, optional

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

7308

7309 Returns

7310 -------

7311 result : MaskedArray

7312 The concatenated array with any masked entries preserved.

7313

7314 See Also

7315 --------

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

7317

7318 Examples

7319 --------

7320 >>> import numpy as np

7321 >>> import numpy.ma as ma

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

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

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

7325 >>> a

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

7327 mask=[False, True, False],

7328 fill_value=999999)

7329 >>> b

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

7331 mask=False,

7332 fill_value=999999)

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

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

7335 mask=[False, True, False, False, False, False],

7336 fill_value=999999)

7337

7338 """

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

7340 rcls = get_masked_subclass(*arrays)

7341 data = d.view(rcls)

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

7343 for x in arrays:

7344 if getmask(x) is not nomask:

7345 break

7346 else:

7347 return data

7348 # OK, so we have to concatenate the masks

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

7350 dm = dm.reshape(d.shape)

7351

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

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

7354 data._mask = _shrink_mask(dm)

7355 return data

7356

7357

7358def diag(v, k=0):

7359 """

7360 Extract a diagonal or construct a diagonal array.

7361

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

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

7364

7365 See Also

7366 --------

7367 numpy.diag : Equivalent function for ndarrays.

7368

7369 Examples

7370 --------

7371 >>> import numpy as np

7372

7373 Create an array with negative values masked:

7374

7375 >>> import numpy as np

7376 >>> x = np.array([[11.2, -3.973, 18], [0.801, -1.41, 12], [7, 33, -12]])

7377 >>> masked_x = np.ma.masked_array(x, mask=x < 0)

7378 >>> masked_x

7379 masked_array(

7380 data=[[11.2, --, 18.0],

7381 [0.801, --, 12.0],

7382 [7.0, 33.0, --]],

7383 mask=[[False, True, False],

7384 [False, True, False],

7385 [False, False, True]],

7386 fill_value=1e+20)

7387

7388 Isolate the main diagonal from the masked array:

7389

7390 >>> np.ma.diag(masked_x)

7391 masked_array(data=[11.2, --, --],

7392 mask=[False, True, True],

7393 fill_value=1e+20)

7394

7395 Isolate the first diagonal below the main diagonal:

7396

7397 >>> np.ma.diag(masked_x, -1)

7398 masked_array(data=[0.801, 33.0],

7399 mask=[False, False],

7400 fill_value=1e+20)

7401

7402 """

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

7404 if getmask(v) is not nomask:

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

7406 return output

7407

7408

7409def left_shift(a, n):

7410 """

7411 Shift the bits of an integer to the left.

7412

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

7414 see that function.

7415

7416 See Also

7417 --------

7418 numpy.left_shift

7419

7420 Examples

7421 --------

7422 Shift with a masked array:

7423

7424 >>> arr = np.ma.array([10, 20, 30], mask=[False, True, False])

7425 >>> np.ma.left_shift(arr, 1)

7426 masked_array(data=[20, --, 60],

7427 mask=[False, True, False],

7428 fill_value=999999)

7429

7430 Large shift:

7431

7432 >>> np.ma.left_shift(10, 10)

7433 masked_array(data=10240,

7434 mask=False,

7435 fill_value=999999)

7436

7437 Shift with a scalar and an array:

7438

7439 >>> scalar = 10

7440 >>> arr = np.ma.array([1, 2, 3], mask=[False, True, False])

7441 >>> np.ma.left_shift(scalar, arr)

7442 masked_array(data=[20, --, 80],

7443 mask=[False, True, False],

7444 fill_value=999999)

7445

7446

7447 """

7448 m = getmask(a)

7449 if m is nomask:

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

7451 return masked_array(d)

7452 else:

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

7454 return masked_array(d, mask=m)

7455

7456

7457def right_shift(a, n):

7458 """

7459 Shift the bits of an integer to the right.

7460

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

7462 see that function.

7463

7464 See Also

7465 --------

7466 numpy.right_shift

7467

7468 Examples

7469 --------

7470 >>> import numpy as np

7471 >>> import numpy.ma as ma

7472 >>> x = [11, 3, 8, 1]

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

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

7475 >>> masked_x

7476 masked_array(data=[11, 3, 8, --],

7477 mask=[False, False, False, True],

7478 fill_value=999999)

7479 >>> ma.right_shift(masked_x,1)

7480 masked_array(data=[5, 1, 4, --],

7481 mask=[False, False, False, True],

7482 fill_value=999999)

7483

7484 """

7485 m = getmask(a)

7486 if m is nomask:

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

7488 return masked_array(d)

7489 else:

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

7491 return masked_array(d, mask=m)

7492

7493

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

7495 """

7496 Set storage-indexed locations to corresponding values.

7497

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

7499 for details.

7500

7501 See Also

7502 --------

7503 MaskedArray.put

7504

7505 Examples

7506 --------

7507 Putting values in a masked array:

7508

7509 >>> a = np.ma.array([1, 2, 3, 4], mask=[False, True, False, False])

7510 >>> np.ma.put(a, [1, 3], [10, 30])

7511 >>> a

7512 masked_array(data=[ 1, 10, 3, 30],

7513 mask=False,

7514 fill_value=999999)

7515

7516 Using put with a 2D array:

7517

7518 >>> b = np.ma.array([[1, 2], [3, 4]], mask=[[False, True], [False, False]])

7519 >>> np.ma.put(b, [[0, 1], [1, 0]], [[10, 20], [30, 40]])

7520 >>> b

7521 masked_array(

7522 data=[[40, 30],

7523 [ 3, 4]],

7524 mask=False,

7525 fill_value=999999)

7526

7527 """

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

7529 try:

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

7531 except AttributeError:

7532 return np.asarray(a).put(indices, values, mode=mode)

7533

7534

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

7536 """

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

7538

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

7540 `numpy.putmask`.

7541

7542 See Also

7543 --------

7544 numpy.putmask

7545

7546 Notes

7547 -----

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

7549 a `MaskedArray`.

7550

7551 Examples

7552 --------

7553 >>> import numpy as np

7554 >>> arr = [[1, 2], [3, 4]]

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

7556 >>> x = np.ma.array(arr, mask=mask)

7557 >>> np.ma.putmask(x, x < 4, 10*x)

7558 >>> x

7559 masked_array(

7560 data=[[--, 20],

7561 [30, 4]],

7562 mask=[[ True, False],

7563 [False, False]],

7564 fill_value=999999)

7565 >>> x.data

7566 array([[10, 20],

7567 [30, 4]])

7568

7569 """

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

7571 if not isinstance(a, MaskedArray):

7572 a = a.view(MaskedArray)

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

7574 if getmask(a) is nomask:

7575 if valmask is not nomask:

7576 a._sharedmask = True

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

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

7579 elif a._hardmask:

7580 if valmask is not nomask:

7581 m = a._mask.copy()

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

7583 a.mask |= m

7584 else:

7585 if valmask is nomask:

7586 valmask = getmaskarray(values)

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

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

7589

7590

7591def transpose(a, axes=None):

7592 """

7593 Permute the dimensions of an array.

7594

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

7596

7597 See Also

7598 --------

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

7600

7601 Examples

7602 --------

7603 >>> import numpy as np

7604 >>> import numpy.ma as ma

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

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

7607 >>> x

7608 masked_array(

7609 data=[[0, 1],

7610 [2, --]],

7611 mask=[[False, False],

7612 [False, True]],

7613 fill_value=999999)

7614

7615 >>> ma.transpose(x)

7616 masked_array(

7617 data=[[0, 2],

7618 [1, --]],

7619 mask=[[False, False],

7620 [False, True]],

7621 fill_value=999999)

7622 """

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

7624 try:

7625 return a.transpose(axes)

7626 except AttributeError:

7627 return np.asarray(a).transpose(axes).view(MaskedArray)

7628

7629

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

7631 """

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

7633

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

7635

7636 See Also

7637 --------

7638 MaskedArray.reshape : equivalent function

7639

7640 Examples

7641 --------

7642 Reshaping a 1-D array:

7643

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

7645 >>> np.ma.reshape(a, (2, 2))

7646 masked_array(

7647 data=[[1, 2],

7648 [3, 4]],

7649 mask=False,

7650 fill_value=999999)

7651

7652 Reshaping a 2-D array:

7653

7654 >>> b = np.ma.array([[1, 2], [3, 4]])

7655 >>> np.ma.reshape(b, (1, 4))

7656 masked_array(data=[[1, 2, 3, 4]],

7657 mask=False,

7658 fill_value=999999)

7659

7660 Reshaping a 1-D array with a mask:

7661

7662 >>> c = np.ma.array([1, 2, 3, 4], mask=[False, True, False, False])

7663 >>> np.ma.reshape(c, (2, 2))

7664 masked_array(

7665 data=[[1, --],

7666 [3, 4]],

7667 mask=[[False, True],

7668 [False, False]],

7669 fill_value=999999)

7670

7671 """

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

7673 try:

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

7675 except AttributeError:

7676 _tmp = np.asarray(a).reshape(new_shape, order=order)

7677 return _tmp.view(MaskedArray)

7678

7679

7680def resize(x, new_shape):

7681 """

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

7683

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

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

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

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

7688

7689 See Also

7690 --------

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

7692

7693 Examples

7694 --------

7695 >>> import numpy as np

7696 >>> import numpy.ma as ma

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

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

7699 >>> a

7700 masked_array(

7701 data=[[1, --],

7702 [3, 4]],

7703 mask=[[False, True],

7704 [False, False]],

7705 fill_value=999999)

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

7707 masked_array(

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

7709 [4, 1, 2],

7710 [3, 4, 1]],

7711 mask=False,

7712 fill_value=999999)

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

7714 masked_array(

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

7716 [4, 1, --],

7717 [3, 4, 1]],

7718 mask=[[False, True, False],

7719 [False, False, True],

7720 [False, False, False]],

7721 fill_value=999999)

7722

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

7724

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

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

7727 masked_array(

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

7729 [4, 1, 2],

7730 [3, 4, 1]],

7731 mask=False,

7732 fill_value=999999)

7733

7734 """

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

7736 m = getmask(x)

7737 if m is not nomask:

7738 m = np.resize(m, new_shape)

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

7740 if result.ndim:

7741 result._mask = m

7742 return result

7743

7744

7745def ndim(obj):

7746 """

7747 maskedarray version of the numpy function.

7748

7749 """

7750 return np.ndim(getdata(obj))

7751

7752

7753ndim.__doc__ = np.ndim.__doc__

7754

7755

7756def shape(obj):

7757 "maskedarray version of the numpy function."

7758 return np.shape(getdata(obj))

7759

7760

7761shape.__doc__ = np.shape.__doc__

7762

7763

7764def size(obj, axis=None):

7765 "maskedarray version of the numpy function."

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

7767

7768

7769size.__doc__ = np.size.__doc__

7770

7771

7772def diff(a, /, n=1, axis=-1, prepend=np._NoValue, append=np._NoValue):

7773 """

7774 Calculate the n-th discrete difference along the given axis.

7775 The first difference is given by ``out[i] = a[i+1] - a[i]`` along

7776 the given axis, higher differences are calculated by using `diff`

7777 recursively.

7778 Preserves the input mask.

7779

7780 Parameters

7781 ----------

7782 a : array_like

7783 Input array

7784 n : int, optional

7785 The number of times values are differenced. If zero, the input

7786 is returned as-is.

7787 axis : int, optional

7788 The axis along which the difference is taken, default is the

7789 last axis.

7790 prepend, append : array_like, optional

7791 Values to prepend or append to `a` along axis prior to

7792 performing the difference. Scalar values are expanded to

7793 arrays with length 1 in the direction of axis and the shape

7794 of the input array in along all other axes. Otherwise the

7795 dimension and shape must match `a` except along axis.

7796

7797 Returns

7798 -------

7799 diff : MaskedArray

7800 The n-th differences. The shape of the output is the same as `a`

7801 except along `axis` where the dimension is smaller by `n`. The

7802 type of the output is the same as the type of the difference

7803 between any two elements of `a`. This is the same as the type of

7804 `a` in most cases. A notable exception is `datetime64`, which

7805 results in a `timedelta64` output array.

7806

7807 See Also

7808 --------

7809 numpy.diff : Equivalent function in the top-level NumPy module.

7810

7811 Notes

7812 -----

7813 Type is preserved for boolean arrays, so the result will contain

7814 `False` when consecutive elements are the same and `True` when they

7815 differ.

7816

7817 For unsigned integer arrays, the results will also be unsigned. This

7818 should not be surprising, as the result is consistent with

7819 calculating the difference directly:

7820

7821 >>> u8_arr = np.array([1, 0], dtype=np.uint8)

7822 >>> np.ma.diff(u8_arr)

7823 masked_array(data=[255],

7824 mask=False,

7825 fill_value=np.uint64(999999),

7826 dtype=uint8)

7827 >>> u8_arr[1,...] - u8_arr[0,...]

7828 np.uint8(255)

7829

7830 If this is not desirable, then the array should be cast to a larger

7831 integer type first:

7832

7833 >>> i16_arr = u8_arr.astype(np.int16)

7834 >>> np.ma.diff(i16_arr)

7835 masked_array(data=[-1],

7836 mask=False,

7837 fill_value=np.int64(999999),

7838 dtype=int16)

7839

7840 Examples

7841 --------

7842 >>> import numpy as np

7843 >>> a = np.array([1, 2, 3, 4, 7, 0, 2, 3])

7844 >>> x = np.ma.masked_where(a < 2, a)

7845 >>> np.ma.diff(x)

7846 masked_array(data=[--, 1, 1, 3, --, --, 1],

7847 mask=[ True, False, False, False, True, True, False],

7848 fill_value=999999)

7849

7850 >>> np.ma.diff(x, n=2)

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

7852 mask=[ True, False, False, True, True, True],

7853 fill_value=999999)

7854

7855 >>> a = np.array([[1, 3, 1, 5, 10], [0, 1, 5, 6, 8]])

7856 >>> x = np.ma.masked_equal(a, value=1)

7857 >>> np.ma.diff(x)

7858 masked_array(

7859 data=[[--, --, --, 5],

7860 [--, --, 1, 2]],

7861 mask=[[ True, True, True, False],

7862 [ True, True, False, False]],

7863 fill_value=1)

7864

7865 >>> np.ma.diff(x, axis=0)

7866 masked_array(data=[[--, --, --, 1, -2]],

7867 mask=[[ True, True, True, False, False]],

7868 fill_value=1)

7869

7870 """

7871 if n == 0:

7872 return a

7873 if n < 0:

7874 raise ValueError("order must be non-negative but got " + repr(n))

7875

7876 a = np.ma.asanyarray(a)

7877 if a.ndim == 0:

7878 raise ValueError(

7879 "diff requires input that is at least one dimensional"

7880 )

7881

7882 combined = []

7883 if prepend is not np._NoValue:

7884 prepend = np.ma.asanyarray(prepend)

7885 if prepend.ndim == 0:

7886 shape = list(a.shape)

7887 shape[axis] = 1

7888 prepend = np.broadcast_to(prepend, tuple(shape))

7889 combined.append(prepend)

7890

7891 combined.append(a)

7892

7893 if append is not np._NoValue:

7894 append = np.ma.asanyarray(append)

7895 if append.ndim == 0:

7896 shape = list(a.shape)

7897 shape[axis] = 1

7898 append = np.broadcast_to(append, tuple(shape))

7899 combined.append(append)

7900

7901 if len(combined) > 1:

7902 a = np.ma.concatenate(combined, axis)

7903

7904 # GH 22465 np.diff without prepend/append preserves the mask

7905 return np.diff(a, n, axis)

7906

7907

7908##############################################################################

7909# Extra functions #

7910##############################################################################

7911

7912

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

7914 """

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

7916

7917 .. note::

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

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

7920 all three arguments are provided.

7921

7922 Parameters

7923 ----------

7924 condition : array_like, bool

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

7926 x, y : array_like, optional

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

7928 broadcastable to some shape.

7929

7930 Returns

7931 -------

7932 out : MaskedArray

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

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

7935 elsewhere.

7936

7937 See Also

7938 --------

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

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

7941

7942 Examples

7943 --------

7944 >>> import numpy as np

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

7946 ... [1, 0, 1],

7947 ... [0, 1, 0]])

7948 >>> x

7949 masked_array(

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

7951 [--, 4.0, --],

7952 [6.0, --, 8.0]],

7953 mask=[[False, True, False],

7954 [ True, False, True],

7955 [False, True, False]],

7956 fill_value=1e+20)

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

7958 masked_array(

7959 data=[[-3.1416, --, -3.1416],

7960 [--, -3.1416, --],

7961 [6.0, --, 8.0]],

7962 mask=[[False, True, False],

7963 [ True, False, True],

7964 [False, True, False]],

7965 fill_value=1e+20)

7966

7967 """

7968

7969 # handle the single-argument case

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

7971 if missing == 1:

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

7973 if missing == 2:

7974 return nonzero(condition)

7975

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

7977 cf = filled(condition, False)

7978 xd = getdata(x)

7979 yd = getdata(y)

7980

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

7982 cm = getmaskarray(condition)

7983 xm = getmaskarray(x)

7984 ym = getmaskarray(y)

7985

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

7987 # want to treat it as that.

7988 if x is masked and y is not masked:

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

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

7991 elif y is masked and x is not masked:

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

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

7994

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

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

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

7998

7999 # collapse the mask, for backwards compatibility

8000 mask = _shrink_mask(mask)

8001

8002 return masked_array(data, mask=mask)

8003

8004

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

8006 """

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

8008

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

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

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

8012 contains in the same place.

8013

8014 Parameters

8015 ----------

8016 indices : ndarray of ints

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

8018 number of choices.

8019 choices : sequence of arrays

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

8021 broadcastable to the same shape.

8022 out : array, optional

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

8024 be of the appropriate shape and `dtype`.

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

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

8027

8028 * 'raise' : raise an error

8029 * 'wrap' : wrap around

8030 * 'clip' : clip to the range

8031

8032 Returns

8033 -------

8034 merged_array : array

8035

8036 See Also

8037 --------

8038 choose : equivalent function

8039

8040 Examples

8041 --------

8042 >>> import numpy as np

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

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

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

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

8047 mask=False,

8048 fill_value=999999)

8049

8050 """

8051 def fmask(x):

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

8053 if x is masked:

8054 return True

8055 return filled(x)

8056

8057 def nmask(x):

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

8059 if x is masked:

8060 return True

8061 return getmask(x)

8062 # Get the indices.

8063 c = filled(indices, 0)

8064 # Get the masks.

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

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

8067 # Construct the mask

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

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

8070 copy=False, shrink=True)

8071 # Get the choices.

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

8073 if out is not None:

8074 if isinstance(out, MaskedArray):

8075 out.__setmask__(outputmask)

8076 return out

8077 d.__setmask__(outputmask)

8078 return d

8079

8080

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

8082 """

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

8084

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

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

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

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

8089 to 0.

8090

8091 Parameters

8092 ----------

8093 decimals : int

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

8095 out : array_like

8096 Existing array to use for output.

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

8098

8099 Notes

8100 -----

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

8102 is lost!

8103

8104 Examples

8105 --------

8106 >>> import numpy as np

8107 >>> import numpy.ma as ma

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

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

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

8111 >>> masked_x

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

8113 mask=[False, False, False, True],

8114 fill_value=1e+20)

8115 >>> ma.round_(masked_x)

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

8117 mask=[False, False, False, True],

8118 fill_value=1e+20)

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

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

8121 mask=[False, False, False, True],

8122 fill_value=1e+20)

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

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

8125 mask=[False, False, False, True],

8126 fill_value=1e+20)

8127 """

8128 if out is None:

8129 return np.round(a, decimals, out)

8130 else:

8131 np.round(getdata(a), decimals, out)

8132 if hasattr(out, '_mask'):

8133 out._mask = getmask(a)

8134 return out

8137round = round_

8140def _mask_propagate(a, axis):

8141 """

8142 Mask whole 1-d vectors of an array that contain masked values.

8143 """

8144 a = array(a, subok=False)

8145 m = getmask(a)

8146 if m is nomask or not m.any() or axis is None:

8147 return a

8148 a._mask = a._mask.copy()

8149 axes = normalize_axis_tuple(axis, a.ndim)

8150 for ax in axes:

8151 a._mask |= m.any(axis=ax, keepdims=True)

8152 return a

8153

8154

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

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

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

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

8159 """

8160 Return the dot product of two arrays.

8161

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

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

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

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

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

8167

8168 Parameters

8169 ----------

8170 a, b : masked_array_like

8171 Inputs arrays.

8172 strict : bool, optional

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

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

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

8176 column is considered masked.

8177 out : masked_array, optional

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

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

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

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

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

8183 to be flexible.

8184

8185 See Also

8186 --------

8187 numpy.dot : Equivalent function for ndarrays.

8188

8189 Examples

8190 --------

8191 >>> import numpy as np

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

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

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

8195 masked_array(

8196 data=[[21, 26],

8197 [45, 64]],

8198 mask=[[False, False],

8199 [False, False]],

8200 fill_value=999999)

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

8202 masked_array(

8203 data=[[--, --],

8204 [--, 64]],

8205 mask=[[ True, True],

8206 [ True, False]],

8207 fill_value=999999)

8208

8209 """

8210 if strict is True:

8211 if np.ndim(a) == 0 or np.ndim(b) == 0:

8212 pass

8213 elif b.ndim == 1:

8214 a = _mask_propagate(a, a.ndim - 1)

8215 b = _mask_propagate(b, b.ndim - 1)

8216 else:

8217 a = _mask_propagate(a, a.ndim - 1)

8218 b = _mask_propagate(b, b.ndim - 2)

8219 am = ~getmaskarray(a)

8220 bm = ~getmaskarray(b)

8221

8222 if out is None:

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

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

8225 if np.ndim(d) == 0:

8226 d = np.asarray(d)

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

8228 r.__setmask__(m)

8229 return r

8230 else:

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

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

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

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

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

8236 return out

8237

8238

8239def inner(a, b):

8240 """

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

8242

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

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

8245

8246 """

8247 fa = filled(a, 0)

8248 fb = filled(b, 0)

8249 if fa.ndim == 0:

8250 fa.shape = (1,)

8251 if fb.ndim == 0:

8252 fb.shape = (1,)

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

8254

8255

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

8257 "Masked values are replaced by 0.")

8258innerproduct = inner

8259

8260

8261def outer(a, b):

8262 "maskedarray version of the numpy function."

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

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

8265 d = np.outer(fa, fb)

8266 ma = getmask(a)

8267 mb = getmask(b)

8268 if ma is nomask and mb is nomask:

8269 return masked_array(d)

8270 ma = getmaskarray(a)

8271 mb = getmaskarray(b)

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

8273 return masked_array(d, mask=m)

8274

8275

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

8277 "Masked values are replaced by 0.")

8278outerproduct = outer

8279

8280

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

8282 """

8283 Helper function for ma.correlate and ma.convolve

8284 """

8285 if propagate_mask:

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

8287 mask = (

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

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

8290 )

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

8292 else:

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

8294 mask = ~f(~getmaskarray(a), ~getmaskarray(v), mode=mode)

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

8296

8297 return masked_array(data, mask=mask)

8298

8299

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

8301 """

8302 Cross-correlation of two 1-dimensional sequences.

8303

8304 Parameters

8305 ----------

8306 a, v : array_like

8307 Input sequences.

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

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

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

8311 propagate_mask : bool

8312 If True, then a result element is masked if any masked element contributes

8313 towards it. If False, then a result element is only masked if no non-masked

8314 element contribute towards it

8315

8316 Returns

8317 -------

8318 out : MaskedArray

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

8320

8321 See Also

8322 --------

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

8324

8325 Examples

8326 --------

8327 Basic correlation:

8328

8329 >>> a = np.ma.array([1, 2, 3])

8330 >>> v = np.ma.array([0, 1, 0])

8331 >>> np.ma.correlate(a, v, mode='valid')

8332 masked_array(data=[2],

8333 mask=[False],

8334 fill_value=999999)

8335

8336 Correlation with masked elements:

8337

8338 >>> a = np.ma.array([1, 2, 3], mask=[False, True, False])

8339 >>> v = np.ma.array([0, 1, 0])

8340 >>> np.ma.correlate(a, v, mode='valid', propagate_mask=True)

8341 masked_array(data=[--],

8342 mask=[ True],

8343 fill_value=999999,

8344 dtype=int64)

8345

8346 Correlation with different modes and mixed array types:

8347

8348 >>> a = np.ma.array([1, 2, 3])

8349 >>> v = np.ma.array([0, 1, 0])

8350 >>> np.ma.correlate(a, v, mode='full')

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

8352 mask=[False, False, False, False, False],

8353 fill_value=999999)

8354

8355 """

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

8357

8358

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

8360 """

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

8362

8363 Parameters

8364 ----------

8365 a, v : array_like

8366 Input sequences.

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

8368 Refer to the `np.convolve` docstring.

8369 propagate_mask : bool

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

8371 element, then the result is masked.

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

8373 contribute towards it

8374

8375 Returns

8376 -------

8377 out : MaskedArray

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

8379

8380 See Also

8381 --------

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

8383 """

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

8385

8386

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

8388 """

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

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

8391

8392 Parameters

8393 ----------

8394 a, b : array_like

8395 Input arrays to compare.

8396 fill_value : bool, optional

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

8398 (False).

8399

8400 Returns

8401 -------

8402 y : bool

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

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

8405 then False is returned.

8406

8407 See Also

8408 --------

8409 all, any

8410 numpy.ma.allclose

8411

8412 Examples

8413 --------

8414 >>> import numpy as np

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

8416 >>> a

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

8418 mask=[False, False, True],

8419 fill_value=1e+20)

8420

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

8422 >>> b

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

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

8425 False

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

8427 True

8428

8429 """

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

8431 if m is nomask:

8432 x = getdata(a)

8433 y = getdata(b)

8434 d = umath.equal(x, y)

8435 return d.all()

8436 elif fill_value:

8437 x = getdata(a)

8438 y = getdata(b)

8439 d = umath.equal(x, y)

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

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

8442 else:

8443 return False

8444

8445

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

8447 """

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

8449

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

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

8452 argument.

8453

8454 Parameters

8455 ----------

8456 a, b : array_like

8457 Input arrays to compare.

8458 masked_equal : bool, optional

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

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

8461 rtol : float, optional

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

8463 Default is 1e-5.

8464 atol : float, optional

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

8466 Default is 1e-8.

8467

8468 Returns

8469 -------

8470 y : bool

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

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

8473 False is returned.

8474

8475 See Also

8476 --------

8477 all, any

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

8479

8480 Notes

8481 -----

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

8483 True::

8484

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

8486

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

8488 given tolerances.

8489

8490 Examples

8491 --------

8492 >>> import numpy as np

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

8494 >>> a

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

8496 mask=[False, False, True],

8497 fill_value=1e+20)

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

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

8500 False

8501

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

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

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

8505 True

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

8507 False

8508

8509 Masked values are not compared directly.

8510

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

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

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

8514 True

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

8516 False

8517

8518 """

8519 x = masked_array(a, copy=False)

8520 y = masked_array(b, copy=False)

8521

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

8523 # casting of x later.

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

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

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

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

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

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

8530 if y.dtype != dtype:

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

8532

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

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

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

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

8537 return False

8538 # No infs at all

8539 if not np.any(xinf):

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

8541 masked_equal)

8542 return np.all(d)

8543

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

8545 return False

8546 x = x[~xinf]

8547 y = y[~xinf]

8548

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

8550 masked_equal)

8551

8552 return np.all(d)

8553

8554

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

8556 """

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

8558

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

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

8561

8562 Parameters

8563 ----------

8564 a : array_like

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

8566 includes lists, lists of tuples, tuples, tuples of tuples, tuples

8567 of lists, ndarrays and masked arrays.

8568 dtype : dtype, optional

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

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

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

8572 representation. Default is 'C'.

8573

8574 Returns

8575 -------

8576 out : MaskedArray

8577 Masked array interpretation of `a`.

8578

8579 See Also

8580 --------

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

8582

8583 Examples

8584 --------

8585 >>> import numpy as np

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

8587 >>> x

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

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

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

8591 masked_array(

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

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

8594 mask=False,

8595 fill_value=1e+20)

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

8597 <class 'numpy.ma.MaskedArray'>

8598

8599 """

8600 order = order or 'C'

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

8602 subok=False, order=order)

8603

8604

8605def asanyarray(a, dtype=None, order=None):

8606 """

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

8608

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

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

8611

8612 Parameters

8613 ----------

8614 a : array_like

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

8616 dtype : dtype, optional

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

8618 order : {'C', 'F', 'A', 'K'}, optional

8619 Memory layout. 'A' and 'K' depend on the order of input array ``a``.

8620 'C' row-major (C-style),

8621 'F' column-major (Fortran-style) memory representation.

8622 'A' (any) means 'F' if ``a`` is Fortran contiguous, 'C' otherwise

8623 'K' (keep) preserve input order

8624 Defaults to 'K'.

8625

8626 Returns

8627 -------

8628 out : MaskedArray

8629 MaskedArray interpretation of `a`.

8630

8631 See Also

8632 --------

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

8634

8635 Examples

8636 --------

8637 >>> import numpy as np

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

8639 >>> x

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

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

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

8643 masked_array(

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

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

8646 mask=False,

8647 fill_value=1e+20)

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

8649 <class 'numpy.ma.MaskedArray'>

8650

8651 """

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

8653 # would handle this for us.

8654 if (

8655 isinstance(a, MaskedArray)

8656 and (dtype is None or dtype == a.dtype)

8657 and (

8658 order in {None, 'A', 'K'}

8659 or order == 'C' and a.flags.carray

8660 or order == 'F' and a.flags.f_contiguous

8661 )

8662 ):

8663 return a

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

8665 order=order)

8666

8667

8668##############################################################################

8669# Pickling #

8670##############################################################################

8671

8672

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

8674 raise NotImplementedError(

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

8676

8677

8678def fromflex(fxarray):

8679 """

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

8681

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

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

8684

8685 Parameters

8686 ----------

8687 fxarray : ndarray

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

8689 fields. If present, other fields are discarded.

8690

8691 Returns

8692 -------

8693 result : MaskedArray

8694 The constructed masked array.

8695

8696 See Also

8697 --------

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

8699

8700 Examples

8701 --------

8702 >>> import numpy as np

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

8704 >>> rec = x.toflex()

8705 >>> rec

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

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

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

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

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

8711 >>> x2

8712 masked_array(

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

8714 [--, 4, --],

8715 [6, --, 8]],

8716 mask=[[False, True, False],

8717 [ True, False, True],

8718 [False, True, False]],

8719 fill_value=999999)

8720

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

8722

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

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

8725 >>> rec2

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

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

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

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

8730 >>> y

8731 masked_array(

8732 data=[[0, 0],

8733 [0, 0]],

8734 mask=[[False, False],

8735 [False, False]],

8736 fill_value=np.int64(999999),

8737 dtype=int32)

8738

8739 """

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

8741

8742

8743def _convert2ma(funcname: str, np_ret: str, np_ma_ret: str,

8744 params: dict[str, str] | None = None):

8745 """Convert function from numpy to numpy.ma."""

8746 func = getattr(np, funcname)

8747 params = params or {}

8748

8749 @functools.wraps(func, assigned=set(functools.WRAPPER_ASSIGNMENTS) - {"__module__"})

8750 def wrapper(*args, **kwargs):

8751 common_params = kwargs.keys() & params.keys()

8752 extras = params | {p: kwargs.pop(p) for p in common_params}

8753

8754 result = func.__call__(*args, **kwargs).view(MaskedArray)

8755

8756 if "fill_value" in common_params:

8757 result.fill_value = extras["fill_value"]

8758 if "hardmask" in common_params:

8759 result._hardmask = bool(extras["hardmask"])

8760

8761 return result

8762

8763 # workaround for a doctest bug in Python 3.11 that incorrectly assumes `__code__`

8764 # exists on wrapped functions

8765 del wrapper.__wrapped__

8766

8767 # `arange`, `empty`, `empty_like`, `frombuffer`, and `zeros` have no signature

8768 try:

8769 signature = inspect.signature(func)

8770 except ValueError:

8771 signature = inspect.Signature([

8772 inspect.Parameter('args', inspect.Parameter.VAR_POSITIONAL),

8773 inspect.Parameter('kwargs', inspect.Parameter.VAR_KEYWORD),

8774 ])

8775

8776 if params:

8777 sig_params = list(signature.parameters.values())

8778

8779 # pop `**kwargs` if present

8780 sig_kwargs = None

8781 if sig_params[-1].kind is inspect.Parameter.VAR_KEYWORD:

8782 sig_kwargs = sig_params.pop()

8783

8784 # add new keyword-only parameters

8785 for param_name, default in params.items():

8786 new_param = inspect.Parameter(

8787 param_name,

8788 inspect.Parameter.KEYWORD_ONLY,

8789 default=default,

8790 )

8791 sig_params.append(new_param)

8792

8793 # re-append `**kwargs` if it was present

8794 if sig_kwargs:

8795 sig_params.append(sig_kwargs)

8796

8797 signature = signature.replace(parameters=sig_params)

8798

8799 wrapper.__signature__ = signature

8800

8801 # __doc__ is None when using `python -OO ...`

8802 if func.__doc__ is not None:

8803 assert np_ret in func.__doc__, (

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

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

8806 f"found in the docstring for `np.{func.__name__}`. "

8807 f"Fix the docstring for `np.{func.__name__}` or "

8808 "update the expected string for return type."

8809 )

8810 wrapper.__doc__ = inspect.cleandoc(func.__doc__).replace(np_ret, np_ma_ret)

8811

8812 return wrapper

8813

8814

8815arange = _convert2ma(

8816 'arange',

8817 params={'fill_value': None, 'hardmask': False},

8818 np_ret='arange : ndarray',

8819 np_ma_ret='arange : MaskedArray',

8820)

8821clip = _convert2ma(

8822 'clip',

8823 params={'fill_value': None, 'hardmask': False},

8824 np_ret='clipped_array : ndarray',

8825 np_ma_ret='clipped_array : MaskedArray',

8826)

8827empty = _convert2ma(

8828 'empty',

8829 params={'fill_value': None, 'hardmask': False},

8830 np_ret='out : ndarray',

8831 np_ma_ret='out : MaskedArray',

8832)

8833empty_like = _convert2ma(

8834 'empty_like',

8835 np_ret='out : ndarray',

8836 np_ma_ret='out : MaskedArray',

8837)

8838frombuffer = _convert2ma(

8839 'frombuffer',

8840 np_ret='out : ndarray',

8841 np_ma_ret='out: MaskedArray',

8842)

8843fromfunction = _convert2ma(

8844 'fromfunction',

8845 np_ret='fromfunction : any',

8846 np_ma_ret='fromfunction: MaskedArray',

8847)

8848identity = _convert2ma(

8849 'identity',

8850 params={'fill_value': None, 'hardmask': False},

8851 np_ret='out : ndarray',

8852 np_ma_ret='out : MaskedArray',

8853)

8854indices = _convert2ma(

8855 'indices',

8856 params={'fill_value': None, 'hardmask': False},

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

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

8859)

8860ones = _convert2ma(

8861 'ones',

8862 params={'fill_value': None, 'hardmask': False},

8863 np_ret='out : ndarray',

8864 np_ma_ret='out : MaskedArray',

8865)

8866ones_like = _convert2ma(

8867 'ones_like',

8868 np_ret='out : ndarray',

8869 np_ma_ret='out : MaskedArray',

8870)

8871squeeze = _convert2ma(

8872 'squeeze',

8873 params={'fill_value': None, 'hardmask': False},

8874 np_ret='squeezed : ndarray',

8875 np_ma_ret='squeezed : MaskedArray',

8876)

8877zeros = _convert2ma(

8878 'zeros',

8879 params={'fill_value': None, 'hardmask': False},

8880 np_ret='out : ndarray',

8881 np_ma_ret='out : MaskedArray',

8882)

8883zeros_like = _convert2ma(

8884 'zeros_like',

8885 np_ret='out : ndarray',

8886 np_ma_ret='out : MaskedArray',

8887)

8888

8889

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

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

8892

8893 Parameters

8894 ----------

8895 a : array_like

8896 Values are appended to a copy of this array.

8897 b : array_like

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

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

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

8901 before use.

8902 axis : int, optional

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

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

8905

8906 Returns

8907 -------

8908 append : MaskedArray

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

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

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

8912

8913 See Also

8914 --------

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

8916

8917 Examples

8918 --------

8919 >>> import numpy as np

8920 >>> import numpy.ma as ma

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

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

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

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

8925 mask=[False, True, False, False, False, False, True, False,

8926 False],

8927 fill_value=999999)

8928 """

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