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.

See also

nlcpy.ma.MaskedArray.hardmask

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.

See also

nlcpy.ma.MaskedArray.hardmask

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