nlcpy.ma.MaskedArray

class nlcpy.ma.MaskedArray(data=None, mask=False, dtype=None, copy=False, subok=None, ndmin=0, fill_value=None, keep_mask=True, hard_mask=None, shrink=True, order=None)[source]

An array class with possibly masked values.

Masked values of True exclude the corresponding element from any computation.

Parameters
dataarray_like

Input data.

masksequence, optional

Mask. Must be convertible to an array of booleans with the same shape as data. True indicates a masked (i.e. invalid) data.

dtypedtype, optional

Data type of the output. If dtype is None, the type of the data argument (data.dtype) is used. If dtype is not None and different from data.dtype, a copy is performed.

copybool, optional

Whether to copy the input data (True), or to use a reference instead. Default is False.

subokbool, optional

Whether to return a subclass of MaskedArray if possible (True) or a plain MaskedArray. subok=True is Not Implemented.

ndminint, optional

Minimum number of dimensions. Default is 0.

fill_valuescalar, optional

Value used to fill in the masked values when necessary. If None, a default based on the data-type is used.

keep_maskbool, optional

Whether to combine mask with the mask of the input data, if any (True), or to use only mask for the output (False). Default is True.

hard_maskbool, optional

Whether to use a hard mask or not. With a hard mask, masked values cannot be unmasked. Default is False.

shrinkbool, optional

Whether to force compression of an empty mask. Default is True.

order{‘C’, ‘F’, ‘A’}, optional

Specify the order of the array. If order is ‘C’, then the array will be in C-contiguous order (last-index varies the fastest). If order is ‘F’, then the returned array will be in Fortran-contiguous order (first-index varies the fastest). If order is ‘A’ (default), then the returned array may be in any order (either C-, Fortran-contiguous, or even discontiguous), unless a copy is required, in which case it will be C-contiguous.

Examples

The mask can be initialized with an array of boolean values with the same shape as data.

>>> import nlcpy as vp
>>> import numpy as np
>>> data = vp.arange(6).reshape((2, 3))
>>> vp.ma.MaskedArray(data, mask=[[False, True, False],
...                               [False, False, True]])
masked_array(
  data=[[0, --, 2],
        [3, 4, --]],
  mask=[[False,  True, False],
        [False, False,  True]],
  fill_value=999999)

Alternatively, the mask can be initialized to homogeneous boolean array with the same shape as data by passing in a scalar boolean value:

>>> vp.ma.MaskedArray(data, mask=False)
masked_array(
  data=[[0, 1, 2],
        [3, 4, 5]],
  mask=[[False, False, False],
        [False, False, False]],
  fill_value=999999)
>>> vp.ma.MaskedArray(data, mask=True)
masked_array(
  data=[[--, --, --],
        [--, --, --]],
  mask=[[ True,  True,  True],
        [ True,  True,  True]],
  fill_value=999999,
  dtype=int64)

Note

The recommended practice for initializing mask with a scalar boolean value is to use True/False rather than np.True_/np.False_. The reason is nomask is represented internally as np.False_.

>>> np.False_ is vp.ma.nomask
True

Methods

__getitem__(indx)[source]

Return self[key].

__setitem__(indx, value)[source]

x.__setitem__(i, y) is equivalent to x[i] = y.

Set item described by index. If value is masked, masks those locations.

__len__(/)

Return len(self).

__iter__(/)

Implement iter(self).

all(axis=None, out=None, keepdims=<no value>)[source]

Masked version of all is not implemented yet.

any(axis=None, out=None, keepdims=False)[source]

Masked version of any is not implemented yet.

argmax(axis=None, out=None)[source]

Masked version of argmax is not implemented yet.

argmin(axis=None, out=None)[source]

Masked version of argmin is not implemented yet.

argsort(axis=- 1, kind=None, order=None)[source]

Masked version of argsort is not implemented yet.

astype(self, dtype, order='K', casting=None, subok=None, copy=True) ndarray[source]

Returns a copy of the array, casts to a specified type.

Parameters
dtypestr or dtype

Typecode or data-type to which the array is cast.

order{‘C’,’F’,’A’,’K’}, optional

Controls the memory layout order of the result. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. Default is ‘K’.

castingstr, optional

This argument is not supported. The default is None.

subokbool, optional

This argument is not supported. The default is None.

copybool, optional

By default, astype always returns a newly allocated array. If this is set to false, and the dtype, order requirements are satisfied, the input array is returned instead of a copy.

Returns
arr_tndarray

Unless copy is False and the other conditions for returning the input array are satisfied (see description for copy input parameter), arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.

Examples

>>> import nlcpy as vp
>>> x = vp.array([1, 2, 2.5])
>>> x
array([1. , 2. , 2.5])
>>> x.astype(int)
array([1, 2, 2])
clip(a_min, a_max, out=None, **kwargs)[source]

Masked version of clip is not implemented yet.

conj(out=None, where=True, casting='same_kind', order='K', dtype=None, subok=False)[source]

Masked version of conj is not implemented yet.

conjugate(out=None, where=True, casting='same_kind', order='K', dtype=None, subok=False)[source]

Masked version of conjugate is not implemented yet.

copy(self, order='C') ndarray

Returns a copy of the array.

Parameters
order{‘C’,’F’,’A’,’K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and nlcpy.copy are very similar, but have different default values for their order= arguments.)

See also

nlcpy.copy

Equivalent function.

cumsum(axis=None, dtype=None, out=None)[source]

Masked version of cumsum is not implemented yet.

diagonal(self, offset=0, axis1=0, axis2=1) ndarray

Returns specified diagonals.

Refer to nlcpy.diagonal for full documentation.

See also

nlcpy.diagonal

Equivalent function.

dot(b, out=None)[source]

Masked version of dot is not implemented yet.

fill(self, value)

Fills the array with a scalar value.

Parameters
valuescalar

All elements of the ndarray will be assigned this value.

Examples

>>> import nlcpy as vp
>>> a = vp.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = vp.empty(2)
>>> a.fill(1)
>>> a
array([1., 1.])
filled(fill_value=None)[source]

Returns a copy of self, with masked values filled with a given value.

However, if there are no masked values to fill, self will be returned instead as an ndarray.

Parameters
fill_valuearray_like, optional

The value to use for invalid entries. Can be scalar or non-scalar. If non-scalar, the resulting ndarray must be broadcastable over input array. Default is None, in which case, the fill_value attribute of the array is used instead.

Returns
filled_arrayndarray

A copy of self with invalid entries replaced by fill_value (be it the function argument or the attribute of self), or self itself as an ndarray if there are no invalid entries to be replaced.

Note

The result is not a MaskedArray!

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
>>> x.filled()
array([   1,    2, -999,    4, -999])
>>> x.filled(fill_value=1000)
array([   1,    2, 1000,    4, 1000])
>>> type(x.filled())
<class 'nlcpy.core.core.ndarray'>
flatten(self, order='C')

Returns a copy of the array collapsed into one dimension.

Parameters
order{‘C’,’F’,’A’,’K’}, optional

‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran-style) order. ‘A’ means to flatten in column-major order if a is Fortran contiguous in memory, row-major order otherwise. ‘K’ means to flatten a in the order the elements occur in memory. The default is ‘C’.

Returns
outndarray

A copy of the input array, flattened to one dimension.

See also

nlcpy.ravel

Returns a flattened array.

Restriction

  • If order = ‘F’ : NotImplementedError occurs.

  • If order = ‘A’ or ‘K’ : NotImplementedError occurs when a is using
    Fortran-style order

Examples

>>> import nlcpy as vp
>>> a = vp.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
get(self, order='C', out=None)[source]

Returns a NumPy array on VH that copied from VE.

Parameters
order{‘C’,’F’,’A’}, optional

Controls the memory layout order of the result. The default is ‘C’. The order will be ignored if out is specified.

get_fill_value()

The filling value of the masked array is a scalar.

When setting, None will set to a default based on the data type.

Examples

>>> import nlcpy as vp
>>> for dt in [vp.int32, vp.int64, vp.float64, vp.complex128]:
...     vp.ma.array([0, 1], dtype=dt).get_fill_value()
...
999999
999999
1e+20
(1e+20+0j)
>>> x = vp.ma.array([0, 1.], fill_value=-vp.inf)
>>> x.fill_value
-inf
>>> x.fill_value = vp.pi
>>> x.fill_value
3.141592653589793

Reset to default:

>>> x.fill_value = None
>>> x.fill_value
1e+20
get_imag()

The imaginary part of the masked array.

This property is a view on the imaginary part of this MaskedArray.

See also

real

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
>>> x.imag
masked_array(data=[1.0, --, 1.6],
             mask=[False,  True, False],
       fill_value=1e+20)
get_real()

The real part of the masked array.

This property is a view on the real part of this MaskedArray.

See also

imag

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
>>> x.real
masked_array(data=[1.0, --, 3.45],
             mask=[False,  True, False],
       fill_value=1e+20)
harden_mask()[source]

Forces the mask to hard.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. harden_mask sets hardmask to True.

max(axis=None, out=None, keepdims=False, initial=<no value>, where=True)[source]

Masked version of max is not implemented yet.

mean(axis=None, dtype=None, out=False, keepdims=<no value>)[source]

Masked version of mean is not implemented yet.

min(axis=None, out=None, keepdims=False, initial=<no value>, where=True)[source]

Masked version of min is not implemented yet.

nonzero()[source]

Masked version of nonzero is not implemented yet.

prod(axis=None, dtype=None, out=None, keepdims=False, initial=<no value>, where=True)[source]

Masked version of prod is not implemented yet.

ptp(axis=None, out=None, keepdims=<no value>)[source]

Masked version of ptp is not implemented yet.

ravel(order='C')[source]

Returns a 1D version of self, as a view.

Parameters
order{‘C’, ‘F’, ‘A’, ‘K’}, optional

The elements of a are read using this index order. ‘C’ means to index the elements in C-like order, with the last axis index changing fastest, back to the first axis index changing slowest. ‘F’ means to index the elements in Fortran-like index order, with the first index changing fastest, and the last index changing slowest. Note that the ‘C’ and ‘F’ options take no account of the memory layout of the underlying array, and only refer to the order of axis indexing. ‘A’ means to read the elements in Fortran-like index order if m is Fortran contiguous in memory, C-like order otherwise. ‘K’ means to read the elements in the order they occur in memory, except for reversing the data when strides are negative. By default, ‘C’ index order is used.

Returns
MaskedArray

Output view is of shape (self.size,) (or (nlcpy.ma.product(self.shape),)).

Restriction

  • If order == ‘K’: NotImplementedError occurs.

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> x
masked_array(
  data=[[1, --, 3],
        [--, 5, --],
        [7, --, 9]],
  mask=[[False,  True, False],
        [ True, False,  True],
        [False,  True, False]],
  fill_value=999999)
>>> x.ravel()
masked_array(data=[1, --, 3, --, 5, --, 7, --, 9],
             mask=[False,  True, False,  True, False,  True, False,  True,
                   False],
       fill_value=999999)
repeat(self, repeats, axis=None)

Repeats elements of an array.

Refer to nlcpy.repeat() for full documentation.

See also

nlcpy.repeat

Equivalent function.

reshape(*shape, order='C')[source]

Gives a new shape to the array without changing its data.

Returns a masked array containing the same data, but with a new shape. The result is a view on the original array; if this is not possible, a ValueError is raised.

Parameters
shapeint or tuple of ints

The new shape should be compatible with the original shape. If an integer is supplied, then the result will be a 1-D array of that length.

order{‘C’, ‘F’}, optional

Determines whether the array data should be viewed as in C (row-major) or FORTRAN (column-major) order.

Returns
reshaped_arrayarray

A new view on the array.

See also

reshape

Equivalent function in the masked array module.

nlcpy.ndarray.reshape

Equivalent method on ndarray object.

nlcpy.reshape

Equivalent function in the NLCPy module.

Note

The reshaping operation cannot guarantee that a copy will not be made, to modify the shape in place, use a.shape = s

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([[1,2],[3,4]], mask=[1,0,0,1])
>>> x
masked_array(
  data=[[--, 2],
        [3, --]],
  mask=[[ True, False],
        [False,  True]],
  fill_value=999999)
>>> x = x.reshape((4,1))
>>> x
masked_array(
  data=[[--],
        [2],
        [3],
        [--]],
  mask=[[ True],
        [False],
        [False],
        [ True]],
  fill_value=999999)
resize(newshape, refcheck=True, order=False)[source]

Warning

This method does nothing, except raise a ValueError exception. A masked array does not own its data and therefore cannot safely be resized in place. Use the nlcpy.ma.resize() function instead.

This method is difficult to implement safely and may be deprecated in future releases of NLCPy.

set(self, a_cpu)

Copies an array on the host memory to nlcpy.ndarray.

Parameters
a_cpunumpy.ndarray

The source array on the host memory.

set_fill_value(value)
shrink_mask()[source]

Reduces a mask to nomask when possible.

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([[1, 2], [3, 4]], mask=[0]*4)
>>> x.mask
array([[False, False],
       [False, False]])
>>> x.shrink_mask()
masked_array(
  data=[[1, 2],
        [3, 4]],
  mask=False,
  fill_value=999999)
>>> x.mask
False
soften_mask()[source]

Forces the mask to soft.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. soften_mask sets hardmask to False.

sort(axis=- 1, kind=None, order=None)[source]

Masked version of sort is not implemented yet.

squeeze(self, axis=None)

Removes single-dimensional entries from the shape of an array.

Refer to nlcpy.squeeze() for full documentation.

See also

nlcpy.squeeze

Equivalent function.

std(axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>)[source]

Masked version of std is not implemented yet.

sum(axis=None, dtype=None, out=None, keepdims=False, initial=0, where=True)[source]

Masked version of sum is not implemented yet.

swapaxes(self, axis1, axis2)

Returns a view of the array with axis1 and axis2 interchanged.

Refer to nlcpy.swapaxes() for full documentation.

See also

nlcpy.swapaxes

Equivalent function.

take(self, indices, axis=None, out=None, mode='wrap') ndarray[source]

Takes elements from an array along an axis.

Refer to nlcpy.take() for full documentation.

See also

nlcpy.take

Equivalent function.

tobytes(fill_value=None, order='C')[source]

Returns the array data as a string containing the raw bytes in the array.

The array is filled with a fill value before the string conversion.

Parameters
fill_valuescalar, optional

Value used to fill in the masked values. Default is None, in which case MaskedArray.fill_value is used.

order{‘C’,’F’,’A’}, optional

Order of the data item in the copy. Default is ‘C’. - ‘C’ – C order (row major). - ‘F’ – Fortran order (column major). - ‘A’ – Any, current order of array. - None – Same as ‘A’.

See also

nlcpy.ndarray.tobytes

Constructs Python bytes containing the raw data bytes in the array.

tolist

Returns the data portion of the masked array as a hierarchical Python list.

Note

As for nlcpy.ndarray.tobytes(), information about the shape, dtype, etc., but also about fill_value, will be lost.

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array(vp.array([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
>>> x.tobytes()
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'
tolist(fill_value=None)[source]

Returns the data portion of the masked array as a hierarchical Python list.

Data items are converted to the nearest compatible Python type. Masked values are converted to fill_value. If fill_value is None, the corresponding entries in the output list will be None.

Parameters
fill_valuescalar, optional

The value to use for invalid entries. Default is None.

Returns
resultlist

The Python list representation of the masked array.

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([[1,2,3], [4,5,6], [7,8,9]], mask=[0] + [1,0]*4)
>>> x.tolist()
[[1, None, 3], [None, 5, None], [7, None, 9]]
>>> x.tolist(-999)
[[1, -999, 3], [-999, 5, -999], [7, -999, 9]]
transpose(self, *axes)

Returns a view of the array with axes transposed.

For a 1-D array this has no effect, as a transposed vector is simply the same vector. To convert a 1-D array into a 2D column vector, an additional dimension must be added. a[:, nlcpy.newaxis] achieves this. For a 2-D array, this is a standard matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters
axesNone, tuple of ints, or n ints
  • None or no argument: reverses the order of the axes.

  • tuple of ints: i in the j-th place in the tuple means a’s i-th axis becomes a.transpose()’s j-th axis.

  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)

Returns
outndarray

View of a, with axes suitably permuted.

See also

nlcpy.ndarray.reshape

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

Examples

>>> import nlcpy as vp
>>> a = vp.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])
unshare_mask()[source]

Copies the mask and set the sharedmask flag to False.

Whether the mask is shared between masked arrays can be seen from the sharedmask property. unshare_mask ensures the mask is not shared. A copy of the mask is only made if it was shared.

See also

sharedmask
var(axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>)[source]

Masked version of var is not implemented yet.

view(dtype=None, type=None, fill_value=None)[source]

Returns a view of the MaskedArray data.

Parameters
dtypedata-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int32. The default, None, results in the view having the same data-type as a. As with nlcpy.ndarray.view(), dtype can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type.

typePython type, optional

Type of the returned view, either ndarray or a subclass. The default None results in type preservation.

fill_valuescalar, optional

The value to use for invalid entries (None by default). If None, then this argument is inferred from the passed dtype, or in its absence the original array, as discussed in the notes below.

See also

nlcpy.ndarray.view

Equivalent method on ndarray object.

Note

a.view() is used two different ways: a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory. a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory. If fill_value is not specified, but dtype is specified (and is not an ndarray sub-class), the fill_value of the MaskedArray will be reset. If neither fill_value nor dtype are specified (or if dtype is an ndarray sub-class), then the fill value is preserved. Finally, if fill_value is specified, but dtype is not, the fill value is set to the specified value. For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

__eq__(value, /)

Return self==value.

__ne__(value, /)

Return self!=value.

__lt__(value, /)

Return self<value.

__le__(value, /)

Return self<=value.

__gt__(value, /)

Return self>value.

__ge__(value, /)

Return self>=value.

__bool__(/)

self != 0

Attributes

T
base
baseclass

Class of the underlying data (read-only).

data

Returns the underlying data, as a view of the masked array.

The type of the data can be accessed through the baseclass attribute.

dtype
fill_value

The filling value of the masked array is a scalar.

When setting, None will set to a default based on the data type.

Examples

>>> import nlcpy as vp
>>> for dt in [vp.int32, vp.int64, vp.float64, vp.complex128]:
...     vp.ma.array([0, 1], dtype=dt).get_fill_value()
...
999999
999999
1e+20
(1e+20+0j)
>>> x = vp.ma.array([0, 1.], fill_value=-vp.inf)
>>> x.fill_value
-inf
>>> x.fill_value = vp.pi
>>> x.fill_value
3.141592653589793

Reset to default:

>>> x.fill_value = None
>>> x.fill_value
1e+20
flags

Information about the memory layout of the array.

hardmask

Hardness of the mask.

If True, masked values cannot be unmasked.

imag

The imaginary part of the masked array.

This property is a view on the imaginary part of this MaskedArray.

See also

real

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
>>> x.imag
masked_array(data=[1.0, --, 1.6],
             mask=[False,  True, False],
       fill_value=1e+20)
itemsize
mask
nbytes

Total number of bytes for all elements.

ndim

Number of dimensions.

node_id
real

The real part of the masked array.

This property is a view on the real part of this MaskedArray.

See also

imag

Examples

>>> import nlcpy as vp
>>> x = vp.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
>>> x.real
masked_array(data=[1.0, --, 3.45],
             mask=[False,  True, False],
       fill_value=1e+20)
shape
sharedmask

Share status of the mask (read-only).

size
strides

Strides of each axis in bytes.

ve_adr
venode

VENode object that ndarray exists on.

veo_hmem