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

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

6204

6205 """

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

6207

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

6209 """

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

6211

6212 .. warning::

6213 This function is not implemented yet.

6214

6215 Raises

6216 ------

6217 NotImplementedError

6218 When `tofile` is called.

6219

6220 """

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

6222

6223 def toflex(self):

6224 """

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

6226

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

6228

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

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

6231

6232 Parameters

6233 ----------

6234 None

6235

6236 Returns

6237 -------

6238 record : ndarray

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

6240 containing a value, the second element containing the corresponding

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

6242

6243 Notes

6244 -----

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

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

6247

6248 Examples

6249 --------

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

6251 >>> x

6252 masked_array(

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

6254 [--, 5, --],

6255 [7, --, 9]],

6256 mask=[[False, True, False],

6257 [ True, False, True],

6258 [False, True, False]],

6259 fill_value=999999)

6260 >>> x.toflex()

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

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

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

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

6265

6266 """

6267 # Get the basic dtype.

6268 ddtype = self.dtype

6269 # Make sure we have a mask

6270 _mask = self._mask

6271 if _mask is None:

6272 _mask = make_mask_none(self.shape, ddtype)

6273 # And get its dtype

6274 mdtype = self._mask.dtype

6275

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

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

6278 record['_data'] = self._data

6279 record['_mask'] = self._mask

6280 return record

6281 torecords = toflex

6282

6283 # Pickling

6284 def __getstate__(self):

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

6286 purposes.

6287

6288 """

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

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

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

6292

6293 def __setstate__(self, state):

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

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

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

6297

6298 - class name

6299 - a tuple giving the shape of the data

6300 - a typecode for the data

6301 - a binary string for the data

6302 - a binary string for the mask.

6303

6304 """

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

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

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

6308 self.fill_value = flv

6309

6310 def __reduce__(self):

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

6312

6313 """

6314 return (_mareconstruct,

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

6316 self.__getstate__())

6317

6318 def __deepcopy__(self, memo=None):

6319 from copy import deepcopy

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

6321 if memo is None:

6322 memo = {}

6323 memo[id(self)] = copied

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

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

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

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

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

6329 # copy semantics to do the right thing here

6330 if self.dtype.hasobject:

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

6332 return copied

6333

6334

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

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

6337 information stored in a pickle.

6338

6339 """

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

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

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

6343

6344

6345class mvoid(MaskedArray):

6346 """

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

6348 """

6349

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

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

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

6353 _data = _data.view(self)

6354 _data._hardmask = hardmask

6355 if mask is not nomask:

6356 if isinstance(mask, np.void):

6357 _data._mask = mask

6358 else:

6359 try:

6360 # Mask is already a 0D array

6361 _data._mask = np.void(mask)

6362 except TypeError:

6363 # Transform the mask to a void

6364 mdtype = make_mask_descr(dtype)

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

6366 if fill_value is not None:

6367 _data.fill_value = fill_value

6368 return _data

6369

6370 @property

6371 def _data(self):

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

6373 return super()._data[()]

6374

6375 def __getitem__(self, indx):

6376 """

6377 Get the index.

6378

6379 """

6380 m = self._mask

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

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

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

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

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

6386 # and we can not say masked/unmasked.

6387 # The result is no longer mvoid!

6388 # See also issue #6724.

6389 return masked_array(

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

6391 fill_value=self._fill_value[indx],

6392 hard_mask=self._hardmask)

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

6394 return masked

6395 return self._data[indx]

6396

6397 def __setitem__(self, indx, value):

6398 self._data[indx] = value

6399 if self._hardmask:

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

6401 else:

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

6403

6404 def __str__(self):

6405 m = self._mask

6406 if m is nomask:

6407 return str(self._data)

6408

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

6410 data_arr = super()._data

6411 res = data_arr.astype(rdtype)

6412 _recursive_printoption(res, self._mask, masked_print_option)

6413 return str(res)

6414

6415 __repr__ = __str__

6416

6417 def __iter__(self):

6418 "Defines an iterator for mvoid"

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

6420 if _mask is nomask:

6421 yield from _data

6422 else:

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

6424 if m:

6425 yield masked

6426 else:

6427 yield d

6428

6429 def __len__(self):

6430 return self._data.__len__()

6431

6432 def filled(self, fill_value=None):

6433 """

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

6435

6436 Parameters

6437 ----------

6438 fill_value : array_like, optional

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

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

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

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

6443

6444 Returns

6445 -------

6446 filled_void

6447 A `np.void` object

6448

6449 See Also

6450 --------

6451 MaskedArray.filled

6452

6453 """

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

6455

6456 def tolist(self):

6457 """

6458 Transforms the mvoid object into a tuple.

6459

6460 Masked fields are replaced by None.

6461

6462 Returns

6463 -------

6464 returned_tuple

6465 Tuple of fields

6466 """

6467 _mask = self._mask

6468 if _mask is nomask:

6469 return self._data.tolist()

6470 result = []

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

6472 if m:

6473 result.append(None)

6474 else:

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

6476 result.append(d.item())

6477 return tuple(result)

6478

6479

6480##############################################################################

6481# Shortcuts #

6482##############################################################################

6483

6484

6485def isMaskedArray(x):

6486 """

6487 Test whether input is an instance of MaskedArray.

6488

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

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

6491

6492 Parameters

6493 ----------

6494 x : object

6495 Object to test.

6496

6497 Returns

6498 -------

6499 result : bool

6500 True if `x` is a MaskedArray.

6501

6502 See Also

6503 --------

6504 isMA : Alias to isMaskedArray.

6505 isarray : Alias to isMaskedArray.

6506

6507 Examples

6508 --------

6509 >>> import numpy.ma as ma

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

6511 >>> a

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

6513 [ 0., 1., 0.],

6514 [ 0., 0., 1.]])

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

6516 >>> m

6517 masked_array(

6518 data=[[1.0, --, --],

6519 [--, 1.0, --],

6520 [--, --, 1.0]],

6521 mask=[[False, True, True],

6522 [ True, False, True],

6523 [ True, True, False]],

6524 fill_value=0.0)

6525 >>> ma.isMaskedArray(a)

6526 False

6527 >>> ma.isMaskedArray(m)

6528 True

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

6530 False

6531

6532 """

6533 return isinstance(x, MaskedArray)

6534

6535

6536isarray = isMaskedArray

6537isMA = isMaskedArray # backward compatibility

6538

6539

6540class MaskedConstant(MaskedArray):

6541 # the lone np.ma.masked instance

6542 __singleton = None

6543

6544 @classmethod

6545 def __has_singleton(cls):

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

6547 # superclass singleton

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

6549

6550 def __new__(cls):

6551 if not cls.__has_singleton():

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

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

6554 data = np.array(0.)

6555 mask = np.array(True)

6556

6557 # prevent any modifications

6558 data.flags.writeable = False

6559 mask.flags.writeable = False

6560

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

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

6563 # within our control

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

6565

6566 return cls.__singleton

6567

6568 def __array_finalize__(self, obj):

6569 if not self.__has_singleton():

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

6571 # properties normally

6572 return super().__array_finalize__(obj)

6573 elif self is self.__singleton:

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

6575 pass

6576 else:

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

6578 # duplicate maskedconstant.

6579 self.__class__ = MaskedArray

6580 MaskedArray.__array_finalize__(self, obj)

6581

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

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

6584

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

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

6587

6588 def __str__(self):

6589 return str(masked_print_option._display)

6590

6591 def __repr__(self):

6592 if self is MaskedConstant.__singleton:

6593 return 'masked'

6594 else:

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

6596 return object.__repr__(self)

6597

6598 def __format__(self, format_spec):

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

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

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

6602 try:

6603 return object.__format__(self, format_spec)

6604 except TypeError:

6605 # 2020-03-23, NumPy 1.19.0

6606 warnings.warn(

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

6608 "error or produce different behavior",

6609 FutureWarning, stacklevel=2

6610 )

6611 return object.__format__(self, "")

6612

6613 def __reduce__(self):

6614 """Override of MaskedArray's __reduce__.

6615 """

6616 return (self.__class__, ())

6617

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

6619 # trying to modify the readonly data and mask arrays

6620 def __iop__(self, other):

6621 return self

6622 __iadd__ = \

6623 __isub__ = \

6624 __imul__ = \

6625 __ifloordiv__ = \

6626 __itruediv__ = \

6627 __ipow__ = \

6628 __iop__

6629 del __iop__ # don't leave this around

6630

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

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

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

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

6635 return self

6636

6637 def __copy__(self):

6638 return self

6639

6640 def __deepcopy__(self, memo):

6641 return self

6642

6643 def __setattr__(self, attr, value):

6644 if not self.__has_singleton():

6645 # allow the singleton to be initialized

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

6647 elif self is self.__singleton:

6648 raise AttributeError(

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

6650 else:

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

6652 # where we set the __class__ attribute

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

6654

6655

6656masked = masked_singleton = MaskedConstant()

6657masked_array = MaskedArray

6658

6659

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

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

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

6663 """

6664 Shortcut to MaskedArray.

6665

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

6667 compatibility.

6668

6669 """

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

6671 subok=subok, keep_mask=keep_mask,

6672 hard_mask=hard_mask, fill_value=fill_value,

6673 ndmin=ndmin, shrink=shrink, order=order)

6674array.__doc__ = masked_array.__doc__

6675

6676

6677def is_masked(x):

6678 """

6679 Determine whether input has masked values.

6680

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

6682 input is a MaskedArray containing masked values.

6683

6684 Parameters

6685 ----------

6686 x : array_like

6687 Array to check for masked values.

6688

6689 Returns

6690 -------

6691 result : bool

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

6693

6694 Examples

6695 --------

6696 >>> import numpy.ma as ma

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

6698 >>> x

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

6700 mask=[ True, False, True, False, False],

6701 fill_value=0)

6702 >>> ma.is_masked(x)

6703 True

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

6705 >>> x

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

6707 mask=False,

6708 fill_value=42)

6709 >>> ma.is_masked(x)

6710 False

6711

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

6713

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

6715 >>> ma.is_masked(x)

6716 False

6717 >>> x = 'a string'

6718 >>> ma.is_masked(x)

6719 False

6720

6721 """

6722 m = getmask(x)

6723 if m is nomask:

6724 return False

6725 elif m.any():

6726 return True

6727 return False

6728

6729

6730##############################################################################

6731# Extrema functions #

6732##############################################################################

6733

6734

6735class _extrema_operation(_MaskedUFunc):

6736 """

6737 Generic class for maximum/minimum functions.

6738

6739 .. note::

6740 This is the base class for `_maximum_operation` and

6741 `_minimum_operation`.

6742

6743 """

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

6745 super().__init__(ufunc)

6746 self.compare = compare

6747 self.fill_value_func = fill_value

6748

6749 def __call__(self, a, b):

6750 "Executes the call behavior."

6751

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

6753

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

6755 "Reduce target along the given axis."

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

6757 m = getmask(target)

6758

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

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

6761 warnings.warn(

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

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

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

6765 MaskedArrayFutureWarning, stacklevel=2)

6766 axis = None

6767

6768 if axis is not np._NoValue:

6769 kwargs = dict(axis=axis)

6770 else:

6771 kwargs = dict()

6772

6773 if m is nomask:

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

6775 else:

6776 target = target.filled(

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

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

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

6780 if hasattr(t, '_mask'):

6781 t._mask = m

6782 elif m:

6783 t = masked

6784 return t

6785

6786 def outer(self, a, b):

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

6788 ma = getmask(a)

6789 mb = getmask(b)

6790 if ma is nomask and mb is nomask:

6791 m = nomask

6792 else:

6793 ma = getmaskarray(a)

6794 mb = getmaskarray(b)

6795 m = logical_or.outer(ma, mb)

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

6797 if not isinstance(result, MaskedArray):

6798 result = result.view(MaskedArray)

6799 result._mask = m

6800 return result

6801

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

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

6804

6805 try:

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

6807 except (AttributeError, TypeError):

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

6809 # fill_value argument

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

6811 out=out, **kwargs)

6812min.__doc__ = MaskedArray.min.__doc__

6813

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

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

6816

6817 try:

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

6819 except (AttributeError, TypeError):

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

6821 # fill_value argument

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

6823 out=out, **kwargs)

6824max.__doc__ = MaskedArray.max.__doc__

6825

6826

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

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

6829 try:

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

6831 except (AttributeError, TypeError):

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

6833 # a fill_value argument

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

6835 out=out, **kwargs)

6836ptp.__doc__ = MaskedArray.ptp.__doc__

6837

6838

6839##############################################################################

6840# Definition of functions from the corresponding methods #

6841##############################################################################

6842

6843

6844class _frommethod:

6845 """

6846 Define functions from existing MaskedArray methods.

6847

6848 Parameters

6849 ----------

6850 methodname : str

6851 Name of the method to transform.

6852

6853 """

6854

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

6856 self.__name__ = methodname

6857 self.__doc__ = self.getdoc()

6858 self.reversed = reversed

6859

6860 def getdoc(self):

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

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

6863 getattr(np, self.__name__, None)

6864 signature = self.__name__ + get_object_signature(meth)

6865 if meth is not None:

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

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

6868 return doc

6869

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

6871 if self.reversed:

6872 args = list(args)

6873 a, args[0] = args[0], a

6874

6875 marr = asanyarray(a)

6876 method_name = self.__name__

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

6878 if method is None:

6879 # use the corresponding np function

6880 method = getattr(np, method_name)

6881

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

6883

6884

6885all = _frommethod('all')

6886anomalies = anom = _frommethod('anom')

6887any = _frommethod('any')

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

6889cumprod = _frommethod('cumprod')

6890cumsum = _frommethod('cumsum')

6891copy = _frommethod('copy')

6892diagonal = _frommethod('diagonal')

6893harden_mask = _frommethod('harden_mask')

6894ids = _frommethod('ids')

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

6896mean = _frommethod('mean')

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

6898nonzero = _frommethod('nonzero')

6899prod = _frommethod('prod')

6900product = _frommethod('prod')

6901ravel = _frommethod('ravel')

6902repeat = _frommethod('repeat')

6903shrink_mask = _frommethod('shrink_mask')

6904soften_mask = _frommethod('soften_mask')

6905std = _frommethod('std')

6906sum = _frommethod('sum')

6907swapaxes = _frommethod('swapaxes')

6908#take = _frommethod('take')

6909trace = _frommethod('trace')

6910var = _frommethod('var')

6911

6912count = _frommethod('count')

6913

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

6915 """

6916 """

6917 a = masked_array(a)

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

6919

6920

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

6922 """

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

6924

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

6926 `numpy.power`.

6927

6928 See Also

6929 --------

6930 numpy.power

6931

6932 Notes

6933 -----

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

6935 None.

6936

6937 Examples

6938 --------

6939 >>> import numpy.ma as ma

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

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

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

6943 >>> masked_x

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

6945 mask=[False, False, False, True],

6946 fill_value=1e+20)

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

6948 masked_array(data=[125.43999999999998, 15.784728999999999,

6949 0.6416010000000001, --],

6950 mask=[False, False, False, True],

6951 fill_value=1e+20)

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

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

6954 >>> masked_y

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

6956 mask=[False, False, False, True],

6957 fill_value=1e+20)

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

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

6960 mask=[False, False, False, True],

6961 fill_value=1e+20)

6962

6963 """

6964 if third is not None:

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

6966 # Get the masks

6967 ma = getmask(a)

6968 mb = getmask(b)

6969 m = mask_or(ma, mb)

6970 # Get the rawdata

6971 fa = getdata(a)

6972 fb = getdata(b)

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

6974 if isinstance(a, MaskedArray):

6975 basetype = type(a)

6976 else:

6977 basetype = MaskedArray

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

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

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

6981 result._update_from(a)

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

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

6984 # Add the initial mask

6985 if m is not nomask:

6986 if not result.ndim:

6987 return masked

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

6989 # Fix the invalid parts

6990 if invalid.any():

6991 if not result.ndim:

6992 return masked

6993 elif result._mask is nomask:

6994 result._mask = invalid

6995 result._data[invalid] = result.fill_value

6996 return result

6997

6998argmin = _frommethod('argmin')

6999argmax = _frommethod('argmax')

7000

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

7002 "Function version of the eponymous method."

7003 a = np.asanyarray(a)

7004

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

7006 if axis is np._NoValue:

7007 axis = _deprecate_argsort_axis(a)

7008

7009 if isinstance(a, MaskedArray):

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

7011 endwith=endwith, fill_value=fill_value)

7012 else:

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

7014argsort.__doc__ = MaskedArray.argsort.__doc__

7015

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

7017 """

7018 Return a sorted copy of the masked array.

7019

7020 Equivalent to creating a copy of the array

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

7022

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

7024

7025 See Also

7026 --------

7027 MaskedArray.sort : equivalent method

7028

7029 Examples

7030 --------

7031 >>> import numpy.ma as ma

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

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

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

7035 >>> masked_x

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

7037 mask=[False, False, False, True],

7038 fill_value=1e+20)

7039 >>> ma.sort(masked_x)

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

7041 mask=[False, False, False, True],

7042 fill_value=1e+20)

7043 """

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

7045 if axis is None:

7046 a = a.flatten()

7047 axis = 0

7048

7049 if isinstance(a, MaskedArray):

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

7051 endwith=endwith, fill_value=fill_value)

7052 else:

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

7054 return a

7055

7056

7057def compressed(x):

7058 """

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

7060

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

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

7063

7064 See Also

7065 --------

7066 ma.MaskedArray.compressed : Equivalent method.

7067

7068 Examples

7069 --------

7070

7071 Create an array with negative values masked:

7072

7073 >>> import numpy as np

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

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

7076 >>> masked_x

7077 masked_array(

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

7079 [2, --, 3],

7080 [7, 4, --]],

7081 mask=[[False, True, False],

7082 [False, True, False],

7083 [False, False, True]],

7084 fill_value=999999)

7085

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

7087

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

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

7090

7091 """

7092 return asanyarray(x).compressed()

7093

7094

7095def concatenate(arrays, axis=0):

7096 """

7097 Concatenate a sequence of arrays along the given axis.

7098

7099 Parameters

7100 ----------

7101 arrays : sequence of array_like

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

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

7104 axis : int, optional

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

7106

7107 Returns

7108 -------

7109 result : MaskedArray

7110 The concatenated array with any masked entries preserved.

7111

7112 See Also

7113 --------

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

7115

7116 Examples

7117 --------

7118 >>> import numpy.ma as ma

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

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

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

7122 >>> a

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

7124 mask=[False, True, False],

7125 fill_value=999999)

7126 >>> b

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

7128 mask=False,

7129 fill_value=999999)

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

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

7132 mask=[False, True, False, False, False, False],

7133 fill_value=999999)

7134

7135 """

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

7137 rcls = get_masked_subclass(*arrays)

7138 data = d.view(rcls)

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

7140 for x in arrays:

7141 if getmask(x) is not nomask:

7142 break

7143 else:

7144 return data

7145 # OK, so we have to concatenate the masks

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

7147 dm = dm.reshape(d.shape)

7148

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

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

7151 data._mask = _shrink_mask(dm)

7152 return data

7153

7154

7155def diag(v, k=0):

7156 """

7157 Extract a diagonal or construct a diagonal array.

7158

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

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

7161

7162 See Also

7163 --------

7164 numpy.diag : Equivalent function for ndarrays.

7165

7166 Examples

7167 --------

7168

7169 Create an array with negative values masked:

7170

7171 >>> import numpy as np

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

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

7174 >>> masked_x

7175 masked_array(

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

7177 [0.801, --, 12.0],

7178 [7.0, 33.0, --]],

7179 mask=[[False, True, False],

7180 [False, True, False],

7181 [False, False, True]],

7182 fill_value=1e+20)

7183

7184 Isolate the main diagonal from the masked array:

7185

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

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

7188 mask=[False, True, True],

7189 fill_value=1e+20)

7190

7191 Isolate the first diagonal below the main diagonal:

7192

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

7194 masked_array(data=[0.801, 33.0],

7195 mask=[False, False],

7196 fill_value=1e+20)

7197

7198 """

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

7200 if getmask(v) is not nomask:

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

7202 return output

7203

7204

7205def left_shift(a, n):

7206 """

7207 Shift the bits of an integer to the left.

7208

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

7210 see that function.

7211

7212 See Also

7213 --------

7214 numpy.left_shift

7215

7216 """

7217 m = getmask(a)

7218 if m is nomask:

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

7220 return masked_array(d)

7221 else:

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

7223 return masked_array(d, mask=m)

7224

7225

7226def right_shift(a, n):

7227 """

7228 Shift the bits of an integer to the right.

7229

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

7231 see that function.

7232

7233 See Also

7234 --------

7235 numpy.right_shift

7236

7237 Examples

7238 --------

7239 >>> import numpy.ma as ma

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

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

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

7243 >>> masked_x

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

7245 mask=[False, False, False, True],

7246 fill_value=999999)

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

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

7249 mask=[False, False, False, True],

7250 fill_value=999999)

7251

7252 """

7253 m = getmask(a)

7254 if m is nomask:

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

7256 return masked_array(d)

7257 else:

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

7259 return masked_array(d, mask=m)

7260

7261

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

7263 """

7264 Set storage-indexed locations to corresponding values.

7265

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

7267 for details.

7268

7269 See Also

7270 --------

7271 MaskedArray.put

7272

7273 """

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

7275 try:

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

7277 except AttributeError:

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

7279

7280

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

7282 """

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

7284

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

7286 `numpy.putmask`.

7287

7288 See Also

7289 --------

7290 numpy.putmask

7291

7292 Notes

7293 -----

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

7295 a `MaskedArray`.

7296

7297 """

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

7299 if not isinstance(a, MaskedArray):

7300 a = a.view(MaskedArray)

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

7302 if getmask(a) is nomask:

7303 if valmask is not nomask:

7304 a._sharedmask = True

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

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

7307 elif a._hardmask:

7308 if valmask is not nomask:

7309 m = a._mask.copy()

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

7311 a.mask |= m

7312 else:

7313 if valmask is nomask:

7314 valmask = getmaskarray(values)

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

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

7317 return

7318

7319

7320def transpose(a, axes=None):

7321 """

7322 Permute the dimensions of an array.

7323

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

7325

7326 See Also

7327 --------

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

7329

7330 Examples

7331 --------

7332 >>> import numpy.ma as ma

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

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

7335 >>> x

7336 masked_array(

7337 data=[[0, 1],

7338 [2, --]],

7339 mask=[[False, False],

7340 [False, True]],

7341 fill_value=999999)

7342

7343 >>> ma.transpose(x)

7344 masked_array(

7345 data=[[0, 2],

7346 [1, --]],

7347 mask=[[False, False],

7348 [False, True]],

7349 fill_value=999999)

7350 """

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

7352 try:

7353 return a.transpose(axes)

7354 except AttributeError:

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

7356

7357

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

7359 """

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

7361

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

7363

7364 See Also

7365 --------

7366 MaskedArray.reshape : equivalent function

7367

7368 """

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

7370 try:

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

7372 except AttributeError:

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

7374 return _tmp.view(MaskedArray)

7375

7376

7377def resize(x, new_shape):

7378 """

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

7380

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

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

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

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

7385

7386 See Also

7387 --------

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

7389

7390 Examples

7391 --------

7392 >>> import numpy.ma as ma

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

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

7395 >>> a

7396 masked_array(

7397 data=[[1, --],

7398 [3, 4]],

7399 mask=[[False, True],

7400 [False, False]],

7401 fill_value=999999)

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

7403 masked_array(

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

7405 [4, 1, 2],

7406 [3, 4, 1]],

7407 mask=False,

7408 fill_value=999999)

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

7410 masked_array(

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

7412 [4, 1, --],

7413 [3, 4, 1]],

7414 mask=[[False, True, False],

7415 [False, False, True],

7416 [False, False, False]],

7417 fill_value=999999)

7418

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

7420

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

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

7423 masked_array(

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

7425 [4, 1, 2],

7426 [3, 4, 1]],

7427 mask=False,

7428 fill_value=999999)

7429

7430 """

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

7432 m = getmask(x)

7433 if m is not nomask:

7434 m = np.resize(m, new_shape)

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

7436 if result.ndim:

7437 result._mask = m

7438 return result

7439

7440

7441def ndim(obj):

7442 """

7443 maskedarray version of the numpy function.

7444

7445 """

7446 return np.ndim(getdata(obj))

7447

7448ndim.__doc__ = np.ndim.__doc__

7449

7450

7451def shape(obj):

7452 "maskedarray version of the numpy function."

7453 return np.shape(getdata(obj))

7454shape.__doc__ = np.shape.__doc__

7455

7456

7457def size(obj, axis=None):

7458 "maskedarray version of the numpy function."

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

7460size.__doc__ = np.size.__doc__

7461

7462

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

7464 """

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

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

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

7468 recursively.

7469 Preserves the input mask.

7470

7471 Parameters

7472 ----------

7473 a : array_like

7474 Input array

7475 n : int, optional

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

7477 is returned as-is.

7478 axis : int, optional

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

7480 last axis.

7481 prepend, append : array_like, optional

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

7483 performing the difference. Scalar values are expanded to

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

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

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

7487

7488 Returns

7489 -------

7490 diff : MaskedArray

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

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

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

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

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

7496 results in a `timedelta64` output array.

7497

7498 See Also

7499 --------

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

7501

7502 Notes

7503 -----

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

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

7506 differ.

7507

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

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

7510 calculating the difference directly:

7511

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

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

7514 masked_array(data=[255],

7515 mask=False,

7516 fill_value=999999,

7517 dtype=uint8)

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

7519 255

7520

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

7522 integer type first:

7523

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

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

7526 masked_array(data=[-1],

7527 mask=False,

7528 fill_value=999999,

7529 dtype=int16)

7530

7531 Examples

7532 --------

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

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

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

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

7537 mask=[ True, False, False, False, True, True, False],

7538 fill_value=999999)

7539

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

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

7542 mask=[ True, False, False, True, True, True],

7543 fill_value=999999)

7544

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

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

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

7548 masked_array(

7549 data=[[--, --, --, 5],

7550 [--, --, 1, 2]],

7551 mask=[[ True, True, True, False],

7552 [ True, True, False, False]],

7553 fill_value=1)

7554

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

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

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

7558 fill_value=1)

7559

7560 """

7561 if n == 0:

7562 return a

7563 if n < 0:

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

7565

7566 a = np.ma.asanyarray(a)

7567 if a.ndim == 0:

7568 raise ValueError(

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

7570 )

7571

7572 combined = []

7573 if prepend is not np._NoValue:

7574 prepend = np.ma.asanyarray(prepend)

7575 if prepend.ndim == 0:

7576 shape = list(a.shape)

7577 shape[axis] = 1

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

7579 combined.append(prepend)

7580

7581 combined.append(a)

7582

7583 if append is not np._NoValue:

7584 append = np.ma.asanyarray(append)

7585 if append.ndim == 0:

7586 shape = list(a.shape)

7587 shape[axis] = 1

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

7589 combined.append(append)

7590

7591 if len(combined) > 1:

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

7593

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

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

7596

7597

7598##############################################################################

7599# Extra functions #

7600##############################################################################

7601

7602

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

7604 """

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

7606

7607 .. note::

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

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

7610 all three arguments are provided.

7611

7612 Parameters

7613 ----------

7614 condition : array_like, bool

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

7616 x, y : array_like, optional

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

7618 broadcastable to some shape.

7619

7620 Returns

7621 -------

7622 out : MaskedArray

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

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

7625 elsewhere.

7626

7627 See Also

7628 --------

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

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

7631

7632 Examples

7633 --------

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

7635 ... [1, 0, 1],

7636 ... [0, 1, 0]])

7637 >>> x

7638 masked_array(

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

7640 [--, 4.0, --],

7641 [6.0, --, 8.0]],

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

7643 [ True, False, True],

7644 [False, True, False]],

7645 fill_value=1e+20)

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

7647 masked_array(

7648 data=[[-3.1416, --, -3.1416],

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

7650 [6.0, --, 8.0]],

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

7652 [ True, False, True],

7653 [False, True, False]],

7654 fill_value=1e+20)

7655

7656 """

7657

7658 # handle the single-argument case

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

7660 if missing == 1:

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

7662 if missing == 2:

7663 return nonzero(condition)

7664

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

7666 cf = filled(condition, False)

7667 xd = getdata(x)

7668 yd = getdata(y)

7669

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

7671 cm = getmaskarray(condition)

7672 xm = getmaskarray(x)

7673 ym = getmaskarray(y)

7674

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

7676 # want to treat it as that.

7677 if x is masked and y is not masked:

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

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

7680 elif y is masked and x is not masked:

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

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

7683

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

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

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

7687

7688 # collapse the mask, for backwards compatibility

7689 mask = _shrink_mask(mask)

7690

7691 return masked_array(data, mask=mask)

7692

7693

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

7695 """

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

7697

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

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

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

7701 contains in the same place.

7702

7703 Parameters

7704 ----------

7705 indices : ndarray of ints

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

7707 number of choices.

7708 choices : sequence of arrays

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

7710 broadcastable to the same shape.

7711 out : array, optional

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

7713 be of the appropriate shape and `dtype`.

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

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

7716

7717 * 'raise' : raise an error

7718 * 'wrap' : wrap around

7719 * 'clip' : clip to the range

7720

7721 Returns

7722 -------

7723 merged_array : array

7724

7725 See Also

7726 --------

7727 choose : equivalent function

7728

7729 Examples

7730 --------

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

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

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

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

7735 mask=False,

7736 fill_value=999999)

7737

7738 """

7739 def fmask(x):

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

7741 if x is masked:

7742 return True

7743 return filled(x)

7744

7745 def nmask(x):

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

7747 if x is masked:

7748 return True

7749 return getmask(x)

7750 # Get the indices.

7751 c = filled(indices, 0)

7752 # Get the masks.

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

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

7755 # Construct the mask

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

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

7758 copy=False, shrink=True)

7759 # Get the choices.

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

7761 if out is not None:

7762 if isinstance(out, MaskedArray):

7763 out.__setmask__(outputmask)

7764 return out

7765 d.__setmask__(outputmask)

7766 return d

7767

7768

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

7770 """

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

7772

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

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

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

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

7777 to 0.

7778

7779 Parameters

7780 ----------

7781 decimals : int

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

7783 out : array_like

7784 Existing array to use for output.

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

7786

7787 Notes

7788 -----

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

7790 is lost!

7791

7792 Examples

7793 --------

7794 >>> import numpy.ma as ma

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

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

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

7798 >>> masked_x

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

7800 mask=[False, False, False, True],

7801 fill_value=1e+20)

7802 >>> ma.round_(masked_x)

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

7804 mask=[False, False, False, True],

7805 fill_value=1e+20)

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

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

7808 mask=[False, False, False, True],

7809 fill_value=1e+20)

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

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

7812 mask=[False, False, False, True],

7813 fill_value=1e+20)

7814 """

7815 if out is None:

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

7817 else:

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

7819 if hasattr(out, '_mask'):

7820 out._mask = getmask(a)

7821 return out

7822round = round_

7823

7824

7825def _mask_propagate(a, axis):

7826 """

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

7828 """

7829 a = array(a, subok=False)

7830 m = getmask(a)

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

7832 return a

7833 a._mask = a._mask.copy()

7834 axes = normalize_axis_tuple(axis, a.ndim)

7835 for ax in axes:

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

7837 return a

7838

7839

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

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

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

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

7844 """

7845 Return the dot product of two arrays.

7846

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

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

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

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

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

7852

7853 Parameters

7854 ----------

7855 a, b : masked_array_like

7856 Inputs arrays.

7857 strict : bool, optional

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

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

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

7861 column is considered masked.

7862 out : masked_array, optional

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

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

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

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

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

7868 to be flexible.

7869

7870 .. versionadded:: 1.10.2

7871

7872 See Also

7873 --------

7874 numpy.dot : Equivalent function for ndarrays.

7875

7876 Examples

7877 --------

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

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

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

7881 masked_array(

7882 data=[[21, 26],

7883 [45, 64]],

7884 mask=[[False, False],

7885 [False, False]],

7886 fill_value=999999)

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

7888 masked_array(

7889 data=[[--, --],

7890 [--, 64]],

7891 mask=[[ True, True],

7892 [ True, False]],

7893 fill_value=999999)

7894

7895 """

7896 if strict is True:

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

7898 pass

7899 elif b.ndim == 1:

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

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

7902 else:

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

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

7905 am = ~getmaskarray(a)

7906 bm = ~getmaskarray(b)

7907

7908 if out is None:

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

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

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

7912 d = np.asarray(d)

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

7914 r.__setmask__(m)

7915 return r

7916 else:

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

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

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

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

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

7922 return out

7923

7924

7925def inner(a, b):

7926 """

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

7928

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

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

7931

7932 """

7933 fa = filled(a, 0)

7934 fb = filled(b, 0)

7935 if fa.ndim == 0:

7936 fa.shape = (1,)

7937 if fb.ndim == 0:

7938 fb.shape = (1,)

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

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

7941 "Masked values are replaced by 0.")

7942innerproduct = inner

7943

7944

7945def outer(a, b):

7946 "maskedarray version of the numpy function."

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

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

7949 d = np.outer(fa, fb)

7950 ma = getmask(a)

7951 mb = getmask(b)

7952 if ma is nomask and mb is nomask:

7953 return masked_array(d)

7954 ma = getmaskarray(a)

7955 mb = getmaskarray(b)

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

7957 return masked_array(d, mask=m)

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

7959 "Masked values are replaced by 0.")

7960outerproduct = outer

7961

7962

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

7964 """

7965 Helper function for ma.correlate and ma.convolve

7966 """

7967 if propagate_mask:

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

7969 mask = (

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

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

7972 )

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

7974 else:

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

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

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

7978

7979 return masked_array(data, mask=mask)

7980

7981

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

7983 """

7984 Cross-correlation of two 1-dimensional sequences.

7985

7986 Parameters

7987 ----------

7988 a, v : array_like

7989 Input sequences.

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

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

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

7993 propagate_mask : bool

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

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

7996 contribute towards it

7997

7998 Returns

7999 -------

8000 out : MaskedArray

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

8002

8003 See Also

8004 --------

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

8006 """

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

8008

8009

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

8011 """

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

8013

8014 Parameters

8015 ----------

8016 a, v : array_like

8017 Input sequences.

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

8019 Refer to the `np.convolve` docstring.

8020 propagate_mask : bool

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

8022 element, then the result is masked.

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

8024 contribute towards it

8025

8026 Returns

8027 -------

8028 out : MaskedArray

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

8030

8031 See Also

8032 --------

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

8034 """

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

8036

8037

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

8039 """

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

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

8042

8043 Parameters

8044 ----------

8045 a, b : array_like

8046 Input arrays to compare.

8047 fill_value : bool, optional

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

8049 (False).

8050

8051 Returns

8052 -------

8053 y : bool

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

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

8056 then False is returned.

8057

8058 See Also

8059 --------

8060 all, any

8061 numpy.ma.allclose

8062

8063 Examples

8064 --------

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

8066 >>> a

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

8068 mask=[False, False, True],

8069 fill_value=1e+20)

8070

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

8072 >>> b

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

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

8075 False

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

8077 True

8078

8079 """

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

8081 if m is nomask:

8082 x = getdata(a)

8083 y = getdata(b)

8084 d = umath.equal(x, y)

8085 return d.all()

8086 elif fill_value:

8087 x = getdata(a)

8088 y = getdata(b)

8089 d = umath.equal(x, y)

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

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

8092 else:

8093 return False

8094

8095

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

8097 """

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

8099

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

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

8102 argument.

8103

8104 Parameters

8105 ----------

8106 a, b : array_like

8107 Input arrays to compare.

8108 masked_equal : bool, optional

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

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

8111 rtol : float, optional

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

8113 Default is 1e-5.

8114 atol : float, optional

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

8116 Default is 1e-8.

8117

8118 Returns

8119 -------

8120 y : bool

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

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

8123 False is returned.

8124

8125 See Also

8126 --------

8127 all, any

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

8129

8130 Notes

8131 -----

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

8133 True::

8134

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

8136

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

8138 given tolerances.

8139

8140 Examples

8141 --------

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

8143 >>> a

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

8145 mask=[False, False, True],

8146 fill_value=1e+20)

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

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

8149 False

8150

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

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

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

8154 True

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

8156 False

8157

8158 Masked values are not compared directly.

8159

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

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

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

8163 True

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

8165 False

8166

8167 """

8168 x = masked_array(a, copy=False)

8169 y = masked_array(b, copy=False)

8170

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

8172 # casting of x later.

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

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

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

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

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

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

8179 if y.dtype != dtype:

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

8181

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

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

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

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

8186 return False

8187 # No infs at all

8188 if not np.any(xinf):

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

8190 masked_equal)

8191 return np.all(d)

8192

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

8194 return False

8195 x = x[~xinf]

8196 y = y[~xinf]

8197

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

8199 masked_equal)

8200

8201 return np.all(d)

8202

8203

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

8205 """

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

8207

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

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

8210

8211 Parameters

8212 ----------

8213 a : array_like

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

8215 includes lists, lists of tuples, tuples, tuples of tuples, tuples

8216 of lists, ndarrays and masked arrays.

8217 dtype : dtype, optional

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

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

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

8221 representation. Default is 'C'.

8222

8223 Returns

8224 -------

8225 out : MaskedArray

8226 Masked array interpretation of `a`.

8227

8228 See Also

8229 --------

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

8231

8232 Examples

8233 --------

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

8235 >>> x

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

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

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

8239 masked_array(

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

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

8242 mask=False,

8243 fill_value=1e+20)

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

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

8246

8247 """

8248 order = order or 'C'

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

8250 subok=False, order=order)

8251

8252

8253def asanyarray(a, dtype=None):

8254 """

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

8256

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

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

8259

8260 Parameters

8261 ----------

8262 a : array_like

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

8264 dtype : dtype, optional

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

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

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

8268 representation. Default is 'C'.

8269

8270 Returns

8271 -------

8272 out : MaskedArray

8273 MaskedArray interpretation of `a`.

8274

8275 See Also

8276 --------

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

8278

8279 Examples

8280 --------

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

8282 >>> x

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

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

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

8286 masked_array(

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

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

8289 mask=False,

8290 fill_value=1e+20)

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

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

8293

8294 """

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

8296 # would handle this for us.

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

8298 return a

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

8300

8301

8302##############################################################################

8303# Pickling #

8304##############################################################################

8305

8306

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

8308 raise NotImplementedError(

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

8310

8311

8312def fromflex(fxarray):

8313 """

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

8315

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

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

8318

8319 Parameters

8320 ----------

8321 fxarray : ndarray

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

8323 fields. If present, other fields are discarded.

8324

8325 Returns

8326 -------

8327 result : MaskedArray

8328 The constructed masked array.

8329

8330 See Also

8331 --------

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

8333

8334 Examples

8335 --------

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

8337 >>> rec = x.toflex()

8338 >>> rec

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

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

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

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

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

8344 >>> x2

8345 masked_array(

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

8347 [--, 4, --],

8348 [6, --, 8]],

8349 mask=[[False, True, False],

8350 [ True, False, True],

8351 [False, True, False]],

8352 fill_value=999999)

8353

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

8355

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

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

8358 >>> rec2

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

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

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

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

8363 >>> y

8364 masked_array(

8365 data=[[0, 0],

8366 [0, 0]],

8367 mask=[[False, False],

8368 [False, False]],

8369 fill_value=999999,

8370 dtype=int32)

8371

8372 """

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

8374

8375

8376class _convert2ma:

8377

8378 """

8379 Convert functions from numpy to numpy.ma.

8380

8381 Parameters

8382 ----------

8383 _methodname : string

8384 Name of the method to transform.

8385

8386 """

8387 __doc__ = None

8388

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

8390 self._func = getattr(np, funcname)

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

8392 self._extras = params or {}

8393

8394 def getdoc(self, np_ret, np_ma_ret):

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

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

8397 sig = get_object_signature(self._func)

8398 if doc:

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

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

8401 if sig:

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

8403 doc = sig + doc

8404 return doc

8405

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

8407 """

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

8409

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

8411

8412 Parameters

8413 ----------

8414 doc : str

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

8416 np_ret : str

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

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

8419 np_ma_ret : str

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

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

8422 """

8423 if np_ret not in doc:

8424 raise RuntimeError(

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

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

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

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

8429 "update the expected string for return type."

8430 )

8431

8432 return doc.replace(np_ret, np_ma_ret)

8433

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

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

8436 _extras = self._extras

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

8438 # Drop the common parameters from the call

8439 for p in common_params:

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

8441 # Get the result

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

8443 if "fill_value" in common_params:

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

8445 if "hardmask" in common_params:

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

8447 return result

8448

8449

8450arange = _convert2ma(

8451 'arange',

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

8453 np_ret='arange : ndarray',

8454 np_ma_ret='arange : MaskedArray',

8455)

8456clip = _convert2ma(

8457 'clip',

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

8459 np_ret='clipped_array : ndarray',

8460 np_ma_ret='clipped_array : MaskedArray',

8461)

8462empty = _convert2ma(

8463 'empty',

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

8465 np_ret='out : ndarray',

8466 np_ma_ret='out : MaskedArray',

8467)

8468empty_like = _convert2ma(

8469 'empty_like',

8470 np_ret='out : ndarray',

8471 np_ma_ret='out : MaskedArray',

8472)

8473frombuffer = _convert2ma(

8474 'frombuffer',

8475 np_ret='out : ndarray',

8476 np_ma_ret='out: MaskedArray',

8477)

8478fromfunction = _convert2ma(

8479 'fromfunction',

8480 np_ret='fromfunction : any',

8481 np_ma_ret='fromfunction: MaskedArray',

8482)

8483identity = _convert2ma(

8484 'identity',

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

8486 np_ret='out : ndarray',

8487 np_ma_ret='out : MaskedArray',

8488)

8489indices = _convert2ma(

8490 'indices',

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

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

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

8494)

8495ones = _convert2ma(

8496 'ones',

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

8498 np_ret='out : ndarray',

8499 np_ma_ret='out : MaskedArray',

8500)

8501ones_like = _convert2ma(

8502 'ones_like',

8503 np_ret='out : ndarray',

8504 np_ma_ret='out : MaskedArray',

8505)

8506squeeze = _convert2ma(

8507 'squeeze',

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

8509 np_ret='squeezed : ndarray',

8510 np_ma_ret='squeezed : MaskedArray',

8511)

8512zeros = _convert2ma(

8513 'zeros',

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

8515 np_ret='out : ndarray',

8516 np_ma_ret='out : MaskedArray',

8517)

8518zeros_like = _convert2ma(

8519 'zeros_like',

8520 np_ret='out : ndarray',

8521 np_ma_ret='out : MaskedArray',

8522)

8523

8524

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

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

8527

8528 .. versionadded:: 1.9.0

8529

8530 Parameters

8531 ----------

8532 a : array_like

8533 Values are appended to a copy of this array.

8534 b : array_like

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

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

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

8538 before use.

8539 axis : int, optional

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

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

8542

8543 Returns

8544 -------

8545 append : MaskedArray

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

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

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

8549

8550 See Also

8551 --------

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

8553

8554 Examples

8555 --------

8556 >>> import numpy.ma as ma

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

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

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

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

8561 mask=[False, True, False, False, False, False, True, False,

8562 False],

8563 fill_value=999999)

8564 """

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