Table of Contents

Class MaskedArrayModule

Namespace
NumSharp
Assembly
NumSharp.dll

The numpy.ma module surface, reachable as ma. Holds the masked-array substrate (getdata(object)/getmask(object)/getmaskarray(object)/filled(object, object)/ NDMasked/nomask) and the masked ufunc family — every unary/binary arithmetic, comparison, logical and bitwise op NumPy exposes on numpy.ma via its _MaskedUnaryOperation/_MaskedBinaryOperation/_DomainedBinaryOperation wrappers.

Each ufunc is a thin wrapper that (1) pulls the raw data out of its operand(s), (2) calls the already-optimized np.* kernel on that data, and (3) propagates the mask — pass-through for a domain-free unary, logical-OR of the input masks for a binary, and OR'd with the domain's invalid-input predicate for a domained op (sqrt/log/divide/…). No new compute loop is emitted; the work is mask bookkeeping over existing IL/NDIter-backed ops.

Reductions (sum/mean/…), creation (zeros/arange/…) and the extras functions are separate mechanisms and are NOT part of this ufunc-family module yet.

[ModuleName("np.ma")]
public class MaskedArrayModule
Inheritance
MaskedArrayModule
Inherited Members

Remarks

Properties

MaskType

NumPy's MaskType: the dtype of a mask, i.e. boolean.

public DType MaskType { get; }

Property Value

DType

NDMasked

The masked constant in NumSharp's ND* spelling: the ONE NDMaskedConstant instance standing for a single masked value (a 0-D float64 0.0 datum under a 0-D True mask). Ufuncs and reductions whose result is a single fully-masked 0-D element return THIS object, so test for it by reference (ReferenceEquals(r, np.ma.NDMasked)) or with is_masked(object); assigning it through the indexer (x[i] = np.ma.NDMasked) masks the slot and leaves the data untouched.

public NDMaskedConstant NDMasked { get; }

Property Value

NDMaskedConstant

Remarks

NumPy spells this value np.ma.masked (and np.ma.masked_singleton). Both NumPy names are exposed as aliases — masked and masked_singleton — that return this very instance, so ported NumPy code compiles unchanged while NumSharp code may use the ND* name. Every spelling is the same object; comparing any two of them by reference is always true.

NDMaskedSingleton

Alias of NDMasked mirroring NumPy's masked_singleton in the ND* spelling — the SAME object, not a copy.

public NDMaskedConstant NDMaskedSingleton { get; }

Property Value

NDMaskedConstant

bool_

NumPy's bool_: the boolean dtype (same as MaskType), exported by numpy.ma for building masks explicitly.

public DType bool_ { get; }

Property Value

DType

masked

NumPy's np.ma.masked: the SAME NDMaskedConstant instance as NDMasked (NumSharp's ND* spelling of it), exposed under NumPy's name so NumPy code ports verbatim — x[i] = np.ma.masked masks a slot, and a fully-masked reduction such as np.ma.sum(allMasked) returns an object reference-equal to this one.

public NDMaskedConstant masked { get; }

Property Value

NDMaskedConstant

Remarks

An expression-bodied alias rather than a second stored instance on purpose: a separate new NDMaskedConstant() would break the reference-identity contract the ufuncs rely on (they return NDMasked, which must be is-equal to np.ma.masked).

masked_print_option

NumPy's masked_print_option: the shared, mutable object controlling the masked-slot display token (default --) and whether masked slots are shown as that token or as the fill value. Mutating it changes every subsequent ToString() — a process-global side effect. See MaskedPrintOption.

public MaskedPrintOption masked_print_option { get; }

Property Value

MaskedPrintOption

masked_singleton

NumPy's np.ma.masked_singleton — in NumPy just another name for masked (np.ma.masked is np.ma.masked_singleton is True); here likewise the SAME instance as NDMasked and masked.

public NDMaskedConstant masked_singleton { get; }

Property Value

NDMaskedConstant

mr_

NumPy's mr_: the masked concatenation index-expression object (the masked counterpart of r_). Use as np.ma.mr_[a, b] / np.ma.mr_["1", A, B]. See MrClass.

public MrClass mr_ { get; }

Property Value

MrClass

nomask

NumPy's nomask: the shared 0-D False that mask returns when nothing is masked. Internally "no mask" is stored as a null mask; this is only the public face of that state.

public NDArray nomask { get; }

Property Value

NDArray

Remarks

Detached from every scope at construction (Own(NDArray)): this module is built by np's static constructor, which runs wherever np is FIRST touched — possibly inside a caller's open NDScope, which would otherwise track this process-wide singleton and dispose it when that scope closed (probed: every later read was a use-after-dispose).

Methods

MaskedArray(object, object, DType, bool, int, object, bool, bool?, bool, char?)

NumPy's np.ma.MaskedArray(data, mask, ...): the masked-array CLASS called as NumPy code calls it - np.ma.masked_array IS that class (ma.MaskedArray is ma.masked_array is True), so this is masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?), parameter for parameter.

public NDMaskedArray MaskedArray(object data, object mask = null, DType dtype = null, bool copy = false, int ndmin = 0, object fill_value = null, bool keep_mask = true, bool? hard_mask = null, bool shrink = true, char? order = null)

Parameters

data object

Data array-like (required, as masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?)'s).

mask object

Optional mask array-like (see masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?)).

dtype DType

Optional dtype the data is cast or converted to.

copy bool

When true, copies the data and the masks.

ndmin int

The minimum rank of the result.

fill_value object

Optional default fill value.

keep_mask bool

With a given mask, true ORs it with the data's own mask.

hard_mask bool?

Hard / soft mask, or null to inherit the data's hardness.

shrink bool

With no mask and keep_mask false, true leaves no mask.

order char?

The data's memory layout (NumPy's np.array(..., order=)).

Returns

NDMaskedArray

A new NDMaskedArray, masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?)'s answer.

Remarks

The C# class is NDMaskedArray (the ND* type naming); this member is NumPy's spelling of its construction. API-parity batch 13.

Exceptions

MaskError

The mask does not fit the data (see masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?)).

TypeError

A fill value numpy.ma cannot convert to the data's dtype.

ValueError

An unknown order letter, ndmin past 64, or a data / dtype pair NumPy refuses (see masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?)).

abs(object, NDMaskedArray, NDArray, DType)

Element-wise absolute value over the data; the mask is unchanged. Alias of absolute(object, NDMaskedArray, NDArray, DType).

public NDMaskedArray abs(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of |data|.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

absolute(object, NDMaskedArray, NDArray, DType)

Element-wise absolute value over the data; the mask is unchanged (same op as abs(object, NDMaskedArray, NDArray, DType)).

public NDMaskedArray absolute(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of |data|.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

add(object, object, NDMaskedArray, NDArray, DType)

Element-wise sum; result is masked wherever EITHER operand was masked.

public NDMaskedArray add(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a+b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

all(object, int, NDMaskedArray, bool)

The owner's kept int form of all(object, NDAxis?, NDMaskedArray, bool).

public NDMaskedArray all(object a, int axis, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked logical-AND, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

all(object, int[], NDMaskedArray, bool)

The owner's kept int[] form of all(object, NDAxis?, NDMaskedArray, bool).

public NDMaskedArray all(object a, int[] axis, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked logical-AND, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

all(object, NDAxis?, NDMaskedArray, bool)

Logical-AND reduction — NumPy's np.ma.all(a, axis=None, out=None, keepdims): masked slots are treated as True (excluded); a cell whose whole slice was masked is itself masked.

public NDMaskedArray all(object a, NDAxis? axis = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked logical-AND, or out.

Remarks

A masked out takes NumPy's if out.ndim or mask: out.setmask(mask). The plain-scalar shortcut serves only the default call (no axis, no keepdims, no out): keepdims with no axis keeps the reduced axes as NumPy does. Tuple axis and out since API-parity batch 8.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

allclose(object, object, bool, double, double)

True iff all corresponding elements are within tolerance, with masked positions treated as equal when masked_equal is true (NumPy's ma.allclose, statement for statement): |x - y| <= atol + rtol * |y| over the masked arithmetic, and infinities must sit at the same places with the same signs.

public bool allclose(object a, object b, bool masked_equal = true, double rtol = 1E-05, double atol = 1E-08)

Parameters

a object

First operand.

b object

Second operand.

masked_equal bool

Treat masked positions as equal.

rtol double

Relative tolerance.

atol double

Absolute tolerance.

Returns

bool

A single bool.

Remarks

NumPy's statements: x = masked_array(a); y = masked_array(b); y is cast to np.result_type(y, 1.) (a bool or integer y becomes float64, so abs(MIN_INT) cannot wrap); m = mask_or(getmask(x), getmask(y)); xinf = np.isinf(masked_array(x, mask=m)).filled(False); unequal infinity positions are False; with no infinity the closeness is filled(less_equal(absolute(x - y), atol + rtol * absolute(y)), masked_equal); otherwise the infinities must be equal (x[xinf] == y[xinf]) and the rest close. A NaN is never close unless masked.

Scoped ([NDScoped]): every intermediate is reclaimed; only the verdict leaves.

Exceptions

DTypePromotionError

b is text: np.result_type(y, 1.) finds no common DType with a Python float — raised before any element is read.

TypeError

a is text: np.isinf has no string loop.

MaskError

The combined mask does not fit a (a 0-d a against a masked array).

IncorrectShapeException

The operands do not broadcast (NumPy's ValueError text).

allequal(object, object, bool)

True iff every corresponding pair of elements is equal, with masked positions treated as equal when fill_value is true (NumPy's allequal).

public bool allequal(object a, object b, bool fill_value = true)

Parameters

a object

First operand.

b object

Second operand.

fill_value bool

Treat masked positions as equal (true) or unequal (false).

Returns

bool

A single bool.

Remarks

Scoped ([NDScoped]): the element-wise equality and mask combinations are reclaimed.

alltrue(object, int?, DType)

Logical-AND reduction along an axis (NumPy's ma.alltrue — _MaskedBinaryOperation(logical_and, 1, 1).reduce, NOT an alias of all(object, NDAxis?, NDMaskedArray, bool)): the masked slots are filled with 1 (True), the result is masked where its whole slice was masked, and the default axis is 0.

public NDMaskedArray alltrue(object target, int? axis = 0, DType dtype = null)

Parameters

target object

Operand.

axis int?

The reduced axis (default 0, as NumPy's), or null for the flattened array.

dtype DType

NumPy's dtype= of the reduction (used only when target has a mask; only bool has a logical_and loop).

Returns

NDMaskedArray

The NDMasked singleton for a masked 0-d result, an unmasked 0-d array for a scalar, otherwise a boolean masked array whose mask is an ARRAY when the operand had one (NumPy does not shrink it).

Exceptions

AxisError

axis is outside the operand.

TypeError

A masked operand with a non-bool dtype (No loop matching the specified signature and casting was found for ufunc logical_and).

amax(object, int, NDMaskedArray, bool, object, NDArray)

amax(object, NDAxis?, NDMaskedArray, bool, object, NDArray) with the axis as one int: the overload a C# integer binds, forwarding to the NDAxis form.

public NDMaskedArray amax(object a, int axis, NDMaskedArray @out = null, bool keepdims = false, object initial = null, NDArray where = null)

Parameters

a object

Operand: a masked array, or a plain array / array-like.

axis int

The axis (a negative value counts from the end).

out NDMaskedArray

NumPy's out (see the NDAxis form).

keepdims bool

Keep the reduced axis as size 1.

initial object

NumPy's initial (a plain operand only, see the NDAxis form).

where NDArray

NumPy's where (a plain operand only, see the NDAxis form).

Returns

NDMaskedArray

The masked maximum, or out.

Exceptions

TypeError

A masked operand with initial or where.

AxisError

axis is outside the operand.

MaskError

A plain integer or bool out would receive a masked slot.

ValueError

out has another shape than the result.

amax(object, int[], NDMaskedArray, bool, object, NDArray)

amax(object, NDAxis?, NDMaskedArray, bool, object, NDArray) with the axes as an int[]: a null array is NumPy's None, any other array NumPy's tuple.

public NDMaskedArray amax(object a, int[] axis, NDMaskedArray @out = null, bool keepdims = false, object initial = null, NDArray where = null)

Parameters

a object

Operand: a masked array, or a plain array / array-like.

axis int[]

The axes as NumPy's tuple, or null for None.

out NDMaskedArray

NumPy's out (see the NDAxis form).

keepdims bool

Keep the reduced axes as size 1.

initial object

NumPy's initial (a plain operand only, see the NDAxis form).

where NDArray

NumPy's where (a plain operand only, see the NDAxis form).

Returns

NDMaskedArray

The masked maximum, or out.

Exceptions

TypeError

A masked operand with initial or where.

AxisError

An axis is outside the operand.

MaskError

A plain integer or bool out would receive a masked slot.

ValueError

A repeated axis, or out has another shape than the result.

amax(object, NDAxis?, NDMaskedArray, bool, object, NDArray)

The maximum along an axis — NumPy's ma.amax, which IS np.amax(a, axis=None, out=None, keepdims=<no value>, initial=<no value>, where=<no value>): a masked operand runs its own MaskedArray.max(axis, out, keepdims) (max(object, NDAxis?, NDMaskedArray, object, bool), masked slots never win), a plain one np.amax.

public NDMaskedArray amax(object a, NDAxis? axis = null, NDMaskedArray @out = null, bool keepdims = false, object initial = null, NDArray where = null)

Parameters

a object

Operand: a masked array, or a plain array / array-like.

axis NDAxis?

The axis, a tuple of axes ((0, 1)), or null for every axis.

out NDMaskedArray

NumPy's out: the maximum is written into it and it is returned. A masked out takes the result's mask (an array); a plain one (an NDArray converts) receives NaN at the masked slots and refuses an integer or bool dtype (see max(object, NDAxis?, NDMaskedArray, object, bool)). NumPy's third positional parameter, where C# had fill_value until API-parity batch 9.

keepdims bool

Keep the reduced axes as size 1.

initial object

NumPy's initial: a plain operand's starting value (np.amax's); a masked operand refuses it, as its MaskedArray.max has no such parameter.

where NDArray

NumPy's where: a plain operand's element filter (np.amax's, which needs initial for an empty selection); a masked operand refuses it.

Returns

NDMaskedArray

The masked maximum (NDMasked for a fully masked full reduction), or out. A plain operand's answer is NumPy's plain array, wrapped mask-less (C#'s static return type).

Remarks

NumPy's _wrapreduction(a, np.maximum, 'max', axis, None, out, keepdims=, initial=, where=): for an object that is not a plain ndarray it calls a.max(axis=axis, out=out, **passkwargs) with only the keywords given, so a masked operand meets Python's own unexpected-keyword TypeError for initial / where. Until API-parity batch 9 this was (a, int? axis, fill_value, keepdims): fill_value answered a call NumPy refuses (amax() got an unexpected keyword argument 'fill_value'), and a fill beyond the data won over it.

Exceptions

TypeError

A masked operand with initial or where: MaskedArray.max() got an unexpected keyword argument 'initial' (or 'where'; initial is reported first, in NumPy's keyword order).

AxisError

An axis is outside the operand.

MaskError

A plain integer or bool out would receive a masked slot.

ValueError

out has another shape than the result, or a plain operand's empty selection without initial.

amin(object, int, NDMaskedArray, bool, object, NDArray)

amin(object, NDAxis?, NDMaskedArray, bool, object, NDArray) with the axis as one int: the overload a C# integer binds, forwarding to the NDAxis form.

public NDMaskedArray amin(object a, int axis, NDMaskedArray @out = null, bool keepdims = false, object initial = null, NDArray where = null)

Parameters

a object

Operand: a masked array, or a plain array / array-like.

axis int

The axis (a negative value counts from the end).

out NDMaskedArray

NumPy's out (see the NDAxis form).

keepdims bool

Keep the reduced axis as size 1.

initial object

NumPy's initial (a plain operand only, see the NDAxis form).

where NDArray

NumPy's where (a plain operand only, see the NDAxis form).

Returns

NDMaskedArray

The masked minimum, or out.

Exceptions

TypeError

A masked operand with initial or where.

AxisError

axis is outside the operand.

MaskError

A plain integer or bool out would receive a masked slot.

ValueError

out has another shape than the result.

amin(object, int[], NDMaskedArray, bool, object, NDArray)

amin(object, NDAxis?, NDMaskedArray, bool, object, NDArray) with the axes as an int[]: a null array is NumPy's None, any other array NumPy's tuple.

public NDMaskedArray amin(object a, int[] axis, NDMaskedArray @out = null, bool keepdims = false, object initial = null, NDArray where = null)

Parameters

a object

Operand: a masked array, or a plain array / array-like.

axis int[]

The axes as NumPy's tuple, or null for None.

out NDMaskedArray

NumPy's out (see the NDAxis form).

keepdims bool

Keep the reduced axes as size 1.

initial object

NumPy's initial (a plain operand only, see the NDAxis form).

where NDArray

NumPy's where (a plain operand only, see the NDAxis form).

Returns

NDMaskedArray

The masked minimum, or out.

Exceptions

TypeError

A masked operand with initial or where.

AxisError

An axis is outside the operand.

MaskError

A plain integer or bool out would receive a masked slot.

ValueError

A repeated axis, or out has another shape than the result.

amin(object, NDAxis?, NDMaskedArray, bool, object, NDArray)

The minimum along an axis — NumPy's ma.amin, which IS np.amin(a, axis=None, out=None, keepdims=<no value>, initial=<no value>, where=<no value>): a masked operand runs its own MaskedArray.min(axis, out, keepdims) (min(object, NDAxis?, NDMaskedArray, object, bool), masked slots never win), a plain one np.amin.

public NDMaskedArray amin(object a, NDAxis? axis = null, NDMaskedArray @out = null, bool keepdims = false, object initial = null, NDArray where = null)

Parameters

a object

Operand: a masked array, or a plain array / array-like.

axis NDAxis?

The axis, a tuple of axes ((0, 1)), or null for every axis.

out NDMaskedArray

NumPy's out: the minimum is written into it and it is returned. A masked out takes the result's mask (an array); a plain one (an NDArray converts) receives NaN at the masked slots and refuses an integer or bool dtype (see min(object, NDAxis?, NDMaskedArray, object, bool)). NumPy's third positional parameter, where C# had fill_value until API-parity batch 9.

keepdims bool

Keep the reduced axes as size 1.

initial object

NumPy's initial: a plain operand's starting value (np.amin's); a masked operand refuses it, as its MaskedArray.min has no such parameter.

where NDArray

NumPy's where: a plain operand's element filter (np.amin's, which needs initial for an empty selection); a masked operand refuses it.

Returns

NDMaskedArray

The masked minimum (NDMasked for a fully masked full reduction), or out. A plain operand's answer is NumPy's plain array, wrapped mask-less (C#'s static return type).

Remarks

NumPy's _wrapreduction(a, np.minimum, 'min', axis, None, out, keepdims=, initial=, where=): for an object that is not a plain ndarray it calls a.min(axis=axis, out=out, **passkwargs) with only the keywords given, so a masked operand meets Python's own unexpected-keyword TypeError for initial / where. Until API-parity batch 9 this was (a, int? axis, fill_value, keepdims): fill_value answered a call NumPy refuses (amin() got an unexpected keyword argument 'fill_value'), and a fill beyond the data won over it.

Exceptions

TypeError

A masked operand with initial or where: MaskedArray.min() got an unexpected keyword argument 'initial' (or 'where'; initial is reported first, in NumPy's keyword order).

AxisError

An axis is outside the operand.

MaskError

A plain integer or bool out would receive a masked slot.

ValueError

out has another shape than the result, or a plain operand's empty selection without initial.

angle(object, bool)

Angle (argument) of the elements — NumPy's np.ma.angle(a, deg=False), which passes its arguments on to angle(NDArray, bool); mask unchanged.

public NDMaskedArray angle(object a, bool deg = false)

Parameters

a object

Operand.

deg bool

Return the angles in degrees (true) instead of radians (false, the default) — NumPy's deg. Masked entries stay masked; their data is converted too, as NumPy's is (the function runs over the whole data).

Returns

NDMaskedArray

A masked array of angle(data), float64 (an integer or real operand's angle is 0 or pi, 180 in degrees).

Remarks

The deg parameter arrived in API-parity batch 7.

anom(object, int?, DType)

Anomalies (deviations from the mean along the axis): NumPy's MaskedArray.anom, m = self.mean(axis, dtype), then self - m when not axis (no axis, AND axis 0) and self - expand_dims(m, axis) otherwise, through numpy.ma's subtract. The mean is the plain one (no keepdims), which is observable: a flat or 1-D mean is a numpy scalar (an inf one unmasked, a float32 one turned float64 by dsum * 1.) or masked, which then masks every anomaly.

public NDMaskedArray anom(object a, int? axis = null, DType dtype = null)

Parameters

a object

Operand: a NDMaskedArray, an NDArray, a C# array or scalar.

axis int?

The axis of the mean, or null for the flattened array.

dtype DType

The mean's dtype= (see mean(object, NDAxis?, DType, NDMaskedArray, bool)).

Returns

NDMaskedArray

The masked anomalies, the input's shape, in result_type(a, mean).

Remarks

Scoped by hand: the mean (and its expanded view) is only the subtraction's operand and is reclaimed.

Exceptions

AxisError

axis is outside the operand.

anomalies(object, int?, DType)

Alias of anom(object, int?, DType) (NumPy's anomalies).

public NDMaskedArray anomalies(object a, int? axis = null, DType dtype = null)

Parameters

a object

Operand.

axis int?

Axis or null.

dtype DType

Mean accumulator dtype.

Returns

NDMaskedArray

The masked anomalies.

any(object, int, NDMaskedArray, bool)

The owner's kept int form of any(object, NDAxis?, NDMaskedArray, bool).

public NDMaskedArray any(object a, int axis, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked logical-OR, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

any(object, int[], NDMaskedArray, bool)

The owner's kept int[] form of any(object, NDAxis?, NDMaskedArray, bool).

public NDMaskedArray any(object a, int[] axis, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked logical-OR, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

any(object, NDAxis?, NDMaskedArray, bool)

Logical-OR reduction — NumPy's np.ma.any(a, axis=None, out=None, keepdims): masked slots are treated as False (excluded).

public NDMaskedArray any(object a, NDAxis? axis = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked logical-OR, or out.

Remarks

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

append(object, object, int?)

Appends b to a (NumPy's ma.append) = masked concatenate(object[], int?); with axis null BOTH operands are flattened first.

public NDMaskedArray append(object a, object b, int? axis = null)

Parameters

a object

First operand.

b object

Value(s) appended.

axis int?

Join axis, or null to flatten both operands and append 1-D.

Returns

NDMaskedArray

The appended masked array (a fresh allocation, never in place).

apply_along_axis(Func<NDMaskedArray, NDMaskedArray>, int, object)

Applies func1d to each 1-D MASKED slice of arr taken along axis, assembling the results (NumPy's ma.apply_along_axis). The slice is handed over as a NDMaskedArray (via the indexer), so the mask rides through the function; the output shape is arr's shape with the axis entry replaced by func1d's result shape (dropped entirely for a scalar result).

public NDMaskedArray apply_along_axis(Func<NDMaskedArray, NDMaskedArray> func1d, int axis, object arr)

Parameters

func1d Func<NDMaskedArray, NDMaskedArray>

The per-slice function; may return a scalar (0-d) or a 1-D masked array.

axis int

The axis along which the 1-D slices are taken.

arr object

Operand.

Returns

NDMaskedArray

The assembled masked array, storing the default fill value at its own dtype (NumPy's result.fill_value = ma.default_fill_value(result), see ResultDefaultFill(NDArray)): an int32 result reads np.int32(999999), a float16 one np.float16(inf).

Remarks

Ownership — the same contract as apply_along_axis(Func<NDArray, NDArray>, int, NDArray): every masked array func1d returns stays the CALLER's and is never disposed here (a callback may return an array it keeps using), which is why the callbacks run OUTSIDE any scope this method opens. The per-slice views handed to func1d (and a scalar operand this method had to materialize) are this method's own and are released once the result is assembled — on a throw too; a callback must therefore not retain its ARGUMENT past the call. The assembly (stacking, reshaping, the stand-in all-False masks) runs inside a scope, so only the result's data and mask leave.

Exceptions

AxisError

axis is out of range.

NotSupportedException

func1d returns a result of rank ≥ 2 (NumSharp supports the scalar- and 1-D-result cases; a higher-rank per-slice result needs the object-array assembly NumSharp lacks).

TypeError

The result's dtype cannot hold the default fill (int8, uint8, int16, uint16: Cannot convert fill_value 999999 to dtype uint8), raised after every func1d call, as NumPy raises it.

apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray>, object, NDAxis)

Applies func repeatedly over the given axes (NumPy's ma.apply_over_axes): each pass calls func(val, axis) and — when the result dropped the reduced axis — re-expands it, so a keepdims-less reduction still composes. func receives (and returns) a whole NDMaskedArray, so the mask is handled by the reduction itself (this is why it composes cleanly, unlike per-1-D-slice apply_along_axis).

public NDMaskedArray apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray> func, object a, NDAxis axes)

Parameters

func Func<NDMaskedArray, int, NDMaskedArray>

The reduction, e.g. (m, ax) => np.ma.sum(m, ax).

a object

Operand.

axes NDAxis

NumPy's axes: one axis or a tuple of axes, applied in order (an int is NumPy's (axes,); () applies nothing; a repeat applies func again). Negative axes count from the end of the OPERAND's rank, as NumPy's N + axis does.

Returns

NDMaskedArray

The successively-reduced masked array.

Remarks

Ownership — the same contract as apply_over_axes(Func<NDArray, int, NDArray>, NDArray, NDAxis): every masked array func returns stays the CALLER's (this method never disposes one — a callback may return an array it keeps using), so an allocating reduction's per-axis intermediates are released only by a GC unless the caller runs the call inside an NDScope. That is also why this method opens NO scope of its own: one would capture — and dispose — whatever the callback allocates. The re-expanded views this method creates (and a scalar operand it had to materialize) are its own and are released as soon as they are superseded.

Exceptions

ValueError

func returns an array of the wrong rank.

AxisError

An axis out of range — raised by func (a reduction's own check), as in NumPy, which validates nothing itself.

apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray>, object, int)

apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray>, object, NDAxis) with the axes as one int: the overload a C# integer binds (the owner's kept integer form beside every NumPy-axis member), forwarding to the NDAxis form, so every answer and error is that overload's.

public NDMaskedArray apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray> func, object a, int axes)

Parameters

func Func<NDMaskedArray, int, NDMaskedArray>

The reduction.

a object

Operand.

axes int

The axis (NumPy's keyword name; this form called it axis before API-parity batch 7, a name NumPy does not have).

Returns

NDMaskedArray

The reduced masked array.

Exceptions

ValueError

func returns an array of the wrong rank.

apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray>, object, int[])

apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray>, object, NDAxis) with the axes as an int[]: the overload a C# array binds (the owner's kept integer form), forwarding to the NDAxis form.

public NDMaskedArray apply_over_axes(Func<NDMaskedArray, int, NDMaskedArray> func, object a, int[] axes)

Parameters

func Func<NDMaskedArray, int, NDMaskedArray>

The reduction.

a object

Operand.

axes int[]

The axes, applied in order.

Returns

NDMaskedArray

The successively-reduced masked array.

Exceptions

ValueError

func returns an array of the wrong rank.

arange(double, double, double, DType, string, object, bool)

Masked evenly-spaced floating values in [start, stop) stepping by step — NumPy's ma.arange(start, stop, step, *, dtype=None, device=None, fill_value=None, hardmask=False).

public NDMaskedArray arange(double start, double stop, double step = 1, DType dtype = null, string device = null, object fill_value = null, bool hardmask = false)

Parameters

start double

Inclusive start.

stop double

Exclusive stop.

step double

Step.

dtype DType

The result's dtype, or null for np.arange's own choice (float64 for these bounds).

device string

NumPy's Array-API device: only "cpu" or null.

fill_value object

The masked array's fill value (see arange(int, DType, string, object, bool)); null keeps the dtype's default.

hardmask bool

True gives the result a hard mask.

Returns

NDMaskedArray

A new masked array without a mask.

Remarks

NumPy 2.4.2's ma.arange is _convert2ma('arange', params={'fill_value': None, 'hardmask': False}): np.arange(*args, **kwargs).view(MaskedArray) (the device check and the dtype are np.arange's), then result.fill_value = fill_value and result._hardmask = bool(hardmask) when given. A null fill_value is NumPy's default, which setting None also restores, so "not given" and null agree. The three C# forms stay (they are not collapsed into np.arange's eleven); like= is excluded, as everywhere. The keywords arrived in API-parity batch 9.

Exceptions

ValueError

device is not "cpu", or step is 0.

TypeError

fill_value does not fit the dtype, or dtype is a text dtype.

arange(int, DType, string, object, bool)

Masked evenly-spaced values in [0, stop) (no element masked) — NumPy's ma.arange(stop, *, dtype=None, device=None, fill_value=None, hardmask=False).

public NDMaskedArray arange(int stop, DType dtype = null, string device = null, object fill_value = null, bool hardmask = false)

Parameters

stop int

Exclusive upper bound (a Python int: the default dtype is int64).

dtype DType

The result's dtype, or null for np.arange's own choice (int64 for these integer bounds).

device string

NumPy's Array-API device: only "cpu" or null.

fill_value object

The masked array's fill value, set through fill_value (so a value the dtype cannot hold is NumPy's TypeError); null keeps the dtype's default.

hardmask bool

True gives the result a hard mask (NumPy's result._hardmask = bool(hardmask)).

Returns

NDMaskedArray

A new masked array without a mask.

Remarks

See arange(double, double, double, DType, string, object, bool) for NumPy's statements. The keywords arrived in API-parity batch 9.

Exceptions

ValueError

device is not "cpu" (Device not understood. Only "cpu" is allowed, but received: gpu).

TypeError

fill_value does not fit the dtype (Cannot set fill value of string with array of dtype int64), or dtype is a text dtype.

arange(int, int, int, DType, string, object, bool)

Masked evenly-spaced values in [start, stop) stepping by step — NumPy's ma.arange(start, stop, step, *, dtype=None, device=None, fill_value=None, hardmask=False).

public NDMaskedArray arange(int start, int stop, int step = 1, DType dtype = null, string device = null, object fill_value = null, bool hardmask = false)

Parameters

start int

Inclusive start.

stop int

Exclusive stop.

step int

Step.

dtype DType

The result's dtype, or null for np.arange's own choice (int64 for these integer bounds).

device string

NumPy's Array-API device: only "cpu" or null.

fill_value object

The masked array's fill value (see arange(int, DType, string, object, bool)); null keeps the dtype's default.

hardmask bool

True gives the result a hard mask.

Returns

NDMaskedArray

A new masked array without a mask.

Remarks

See arange(double, double, double, DType, string, object, bool) for NumPy's statements. np.ma.arange(0, 5) binds here (an int does not convert to DType), not to the stop form.

Exceptions

ValueError

device is not "cpu", or step is 0.

TypeError

fill_value does not fit the dtype, or dtype is a text dtype.

arccos(object, NDMaskedArray, NDArray, DType)

Arccosine; additionally masks inputs outside [-1, 1].

public NDMaskedArray arccos(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 0.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of arccos(data) with out-of-domain inputs masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

arccosh(object, NDMaskedArray, NDArray, DType)

Inverse hyperbolic cosine; additionally masks inputs < 1.

public NDMaskedArray arccosh(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 1.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of arccosh(data) with sub-1 inputs masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

arcsin(object, NDMaskedArray, NDArray, DType)

Arcsine; additionally masks inputs outside [-1, 1].

public NDMaskedArray arcsin(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 0.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of arcsin(data) with out-of-domain inputs masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

arcsinh(object, NDMaskedArray, NDArray, DType)

Inverse hyperbolic sine; mask unchanged.

public NDMaskedArray arcsinh(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of arcsinh(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

arctan(object, NDMaskedArray, NDArray, DType)

Arctangent; mask unchanged.

public NDMaskedArray arctan(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of arctan(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

arctan2(object, object, NDMaskedArray, NDArray, DType)

Two-argument arctangent; masked where either operand was.

public NDMaskedArray arctan2(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

y operand.

b object

x operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of arctan2(a, b).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

arctanh(object, NDMaskedArray, NDArray, DType)

Inverse hyperbolic tangent; additionally masks inputs outside (-1, 1).

public NDMaskedArray arctanh(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 0.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of arctanh(data) with out-of-domain inputs masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

argmax(object, int?, object, NDArray, bool)

Indices of the maximum along the axis, treating masked slots as the dtype's smallest value.

public NDArray argmax(object a, int? axis = null, object fill_value = null, NDArray @out = null, bool keepdims = false)

Parameters

a object

Operand.

axis int?

Axis or null (flattened index).

fill_value object

Override the masked fill; null uses maximum_fill_value(object).

out NDArray

NumPy's out: the indices are written into it and it is returned (an int64-compatible array of the result's shape; np.argmax's checks).

keepdims bool

NumPy's keepdims: keep the reduced axis (axes, for null) with length 1.

Returns

NDArray

An int64 NDArray of indices, or out.

Remarks

Scoped ([NDScoped]): the fill-substituted copy the index is computed over is reclaimed; a given out is the caller's and is returned, never released. NumPy's MaskedArray.argmax is self.filled(fill_value).view(ndarray).argmax(axis, out=out, keepdims=keepdims); out and keepdims arrived in API-parity batch 7.

Exceptions

TypeError

out's dtype cannot hold the indices under the 'safe' rule.

ValueError

out has the wrong shape (output array does not match result of np.argmax.).

AxisError

axis is out of range.

argmin(object, int?, object, NDArray, bool)

Indices of the minimum along the axis, treating masked slots as the dtype's largest value (NumPy's argmin) — a plain int64 array, never masked.

public NDArray argmin(object a, int? axis = null, object fill_value = null, NDArray @out = null, bool keepdims = false)

Parameters

a object

Operand.

axis int?

Axis or null (flattened index).

fill_value object

Override the masked fill; null uses minimum_fill_value(object).

out NDArray

NumPy's out: the indices are written into it and it is returned (an int64-compatible array of the result's shape; np.argmin's checks).

keepdims bool

NumPy's keepdims: keep the reduced axis (axes, for null) with length 1.

Returns

NDArray

An int64 NDArray of indices, or out.

Remarks

Scoped ([NDScoped]): the fill-substituted copy the index is computed over is reclaimed; a given out is the caller's and is returned, never released. NumPy's MaskedArray.argmin is self.filled(fill_value).view(ndarray).argmin(axis, out=out, keepdims=keepdims); out and keepdims arrived in API-parity batch 7.

Exceptions

TypeError

out's dtype cannot hold the indices under the 'safe' rule (Cannot cast array data from dtype('float64') to dtype('int64') according to the rule 'safe').

ValueError

out has the wrong shape (output array does not match result of np.argmin.).

AxisError

axis is out of range.

argsort(object, bool, object, string, object, bool?, bool?)

argsort(object, int?, string, object, bool, object, bool?, bool?) with NumPy's DEFAULT axis (ma.argsort(a, axis=np._NoValue)): _deprecate_argsort_axis picks the last axis for a 0-d or 1-D operand and None (the FLATTENED array, with NumPy's FutureWarning) from two dimensions on.

public NDArray argsort(object a, bool endwith = true, object fill_value = null, string kind = null, object order = null, bool? stable = null, bool? descending = null)

Parameters

a object

Operand.

endwith bool

True (default) sends masked entries to the END; false to the FRONT.

fill_value object

Override the masked sort key; null uses the endwith default.

kind string

NumPy's sort kind, or null for the default (see the axis form).

order object

NumPy's structured-array field order (refused for numeric data, see the axis form).

stable bool?

See the axis form: a masked operand refuses true.

descending bool?

See the axis form: a masked operand refuses true.

Returns

NDArray

An int64 NDArray of sort indices (1-D for an operand of two or more dimensions).

Remarks

C#'s spelling of NumPy's axis=<no value>: endwith and fill_value stay first and the API-parity batch 9 keywords follow them, so a positional null second argument still binds the axis form (axis=None) instead of being ambiguous with a kind. Name the keywords: np.ma.argsort(a, kind: "stable"). Scoped ([NDScoped]): an array-like operand materialized to read its rank is reclaimed.

Exceptions

ValueError

A masked operand with stable or descending true, an unknown kind, or an order.

argsort(object, int?, string, object, bool, object, bool?, bool?)

Indices that would sort the array with masked entries treated as the dtype's largest (or, with endwith false, smallest) value — NumPy's ma.argsort. A PLAIN int64 index array (masked entries land at the end/front).

public NDArray argsort(object a, int? axis, string kind = null, object order = null, bool endwith = true, object fill_value = null, bool? stable = null, bool? descending = null)

Parameters

a object

Operand.

axis int?

Sort axis (negative counts from the end), or null for the flattened array (NumPy's axis=None). Omitting it is NumPy's default (see argsort(object, bool, object, string, object, bool?, bool?)).

kind string

NumPy's sort kind, or null for the default; validated by argsort(NDArray, int?, string, object, bool?, bool?) with NumPy's text. Added in API-parity batch 9, in NumPy's third slot, where C# had endwith.

order object

NumPy's structured-array field order; numeric data has no fields, so any value is NumPy's ValueError: Cannot specify order when the array has no fields.

endwith bool

True (default) sends masked entries to the END; false to the FRONT.

fill_value object

Override the masked sort key; null uses the endwith default.

stable bool?

NumPy's keyword-only stable: a masked operand refuses true (NumPy 2.5's ma.argsort passes it on to the method, where 2.4 passed None); a plain operand's ndarray.argsort takes it.

descending bool?

NumPy 2.5's keyword-only descending: a masked operand refuses true; a plain operand's ndarray.argsort orders descending.

Returns

NDArray

An int64 NDArray of sort indices.

Remarks

NumPy's statements: a = np.asanyarray(a); a masked operand runs a.argsort(axis=axis, kind=kind, order=order, endwith=endwith, fill_value=fill_value, stable=stable, descending=descending) (the keywords refused when true, the sort keys filled, then filled.argsort(axis, kind, order)), a plain one a.argsort(axis, kind, order, stable=stable, descending=descending). Scoped ([NDScoped]): the filled sort keys (and an array-like operand this method had to materialize) are reclaimed; only the index array leaves.

Exceptions

AxisError

axis is outside the operand.

ValueError

A masked operand with stable or descending true (stable first), an unknown kind, or an order.

around(object, int, NDMaskedArray)

Evenly rounds to decimals places — NumPy's np.ma.around(a, decimals=0, out=None), which is _MaskedUnaryOperation(np.around), NOT round(object, int, NDMaskedArray): the masked positions get the operand's ORIGINAL data back (np.copyto(result, d, where=m)), and the result takes the operand's mask object, fill value and hard-mask flag.

public NDMaskedArray around(object a, int decimals = 0, NDMaskedArray @out = null)

Parameters

a object

Data (a masked array, an array, a scalar or an array-like).

decimals int

Decimal places (negative rounds to the left of the decimal point).

out NDMaskedArray

NumPy's out: np.around(getdata(a), decimals, out=out) writes the rounded data, the masked positions are written back with the operand's data, and the result is a NEW masked array over out's data carrying the operand's mask — the out itself keeps the mask NumPy's in-place ufunc wraps leave there (an all-False mask for decimals 0, the infinite results otherwise, whose data is written as 1.0 or 10**-decimals; see RoundInto(NDArray, int, NDMaskedArray, bool)). A 0-d out is returned itself, or NDMasked when the operand is masked. Added in API-parity batch 8.

Returns

NDMaskedArray

The masked, rounded array (a 0-d result is NDMasked when masked, else an unmasked 0-d array).

Remarks

Until API-parity batch 8 NumSharp had two forms: around(a) (this one, decimals 0) and around(a, decimals) = round(object, int, NDMaskedArray), which rounded the masked positions' data too. Scoped by hand with out: a materialized operand and the ufunc-wrap temporaries are reclaimed; a mask stored into a masked out is detached (it lives in the caller's array).

Exceptions

AttributeError

Complex data into a masked out.

UFuncOutputCastingError

out's dtype cannot hold the rounded values.

ValueError

out has another size than the operand (invalid output shape).

array(object, DType, bool, char?, object, object, bool, bool?, bool, int)

Builds a masked array — NumPy's np.ma.array(data, dtype=None, copy=False, order=None, mask=nomask, fill_value=None, keep_mask=True, hard_mask=False, shrink=True, subok=True, ndmin=0), the function form of the MaskedArray.new constructor (masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?)), with NumPy's parameter ORDER: the dtype comes second and the mask fifth, so a positional mask must be named (mask:).

public NDMaskedArray array(object data, DType dtype = null, bool copy = false, char? order = null, object mask = null, object fill_value = null, bool keep_mask = true, bool? hard_mask = false, bool shrink = true, int ndmin = 0)

Parameters

data object

Data array-like (a NDMaskedArray's own mask, fill value and hard-mask flag ride along).

dtype DType

Optional dtype: an array (or masked array) is CAST to it; a C# array-like is converted INTO it (NumPy's np.array(data, dtype=dtype): new object[] { "ab", null } with StringDType(na_object: null) holds an NA element, numbers with StringDType(coerce: false) are refused).

copy bool

When true, copies the data (NumPy's copy=, in order's layout — the data's own for the default), the inherited mask and a given mask array; default false aliases them — a given boolean mask array of the data's shape is ADOPTED (the masked array then writes into it, as NumPy's does, and getmask(object) returns it), the data's own mask is shared through a view.

order char?

The data's memory layout, NumPy's np.array(..., order=): null / 'K' keeps it, 'A' keeps a C- or F-contiguous one, 'C' / 'F' lay it out so (copying only when needed).

mask object

Optional mask array-like; null/omitted (or nomask) ⇒ no explicit mask. A C# true / false is NumPy's mask=True / mask=False: a FULL array of that value.

fill_value object

Optional default fill value for filled(object); null inherits data's. Checked against the dtype (CheckFillValue(object, DType)).

keep_mask bool

With a given mask, true (default) ORs it with data's own mask and false replaces that mask; without one, false erases the data's mask.

hard_mask bool?

True/false makes the result's mask HARD/soft (NumPy's hard_mask=: a hard mask refuses a plain-value assignment's unmasking, see harden_mask()); null inherits data's hardness. The default is false, NumPy's ma.array FUNCTION (hard_mask=False); masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?), NumPy's class, defaults to null.

shrink bool

With no mask and keep_mask false: true (default) leaves no mask (nomask), false a full all-False mask.

ndmin int

The minimum rank of the result: leading length-1 axes are prepended to the data (and its mask) as NumPy's np.array(..., ndmin=) does; 0 (the default) or less adds none.

Returns

NDMaskedArray

A new NDMaskedArray.

Remarks

The mask, as NumPy reconciles it. A mask of the data's shape is used as is; a ONE-element mask is repeated over the data (np.resize); a mask of the data's SIZE in another shape is reshaped; anything else is the MaskError. The sizes are tested before the mask's values are read, so a text mask of the wrong size reports the MaskError even though its strings could not be converted yet (NumPy converts first, but that conversion cannot fail).

NumPy's parameter order, order and ndmin arrived in API-parity batch 8 (2026-11-12): the order was (data, mask, fill_value, copy, dtype, hard_mask, keep_mask, shrink), under which np.ma.array(x, np.float32) handed the dtype to the MASK. subok is the parity plan's exclusion.

Scoped by hand: a scalar/array-like data or mask is first materialized, then (on a dtype cast / boolean coercion) replaced by the converted array — the superseded materializations are reclaimed on return and only the arrays the result carries leave.

Exceptions

MaskError

The mask is neither the data's shape, nor one element, nor the data's size (Mask and data not compatible: data size is 3, mask size is 2.).

TypeError

A string fill_value for numeric data, or a fill numpy.ma cannot convert to the data's dtype (see CheckFillValue(object, DType)).

ValueError

An order letter NumPy does not have (checked first, as np.array's parser does); ndmin past 64 (ndmin must be <= ndmax (64)); a C# array-like holding numbers with a StringDType(coerce: false) dtype, or text a numeric dtype cannot parse.

asanyarray(object, DType, char?)

NumPy's np.ma.asanyarray(a, dtype=None, order=None): a masked array whose dtype and layout already satisfy the request is returned ITSELF (NumPy's identity rule, gh-8666); anything else is the constructor's conversion without a copy.

public NDMaskedArray asanyarray(object a, DType dtype = null, char? order = null)

Parameters

a object

Array-like.

dtype DType

Optional dtype cast.

order char?

The data's layout: null, 'A' or 'K' keep a masked operand as it is; 'C' / 'F' keep it only when it is already so (NumPy's a.flags.carray — C-contiguous and writeable — / f_contiguous).

Returns

NDMaskedArray

a itself, or a masked array over its data.

Remarks

order arrived in API-parity batch 8.

Exceptions

TypeError

See asarray(object, DType, char?).

ValueError

See asarray(object, DType, char?).

asarray(object, DType, char?)

Converts an array-like to a NDMaskedArray without copying when it can — NumPy's np.ma.asarray(a, dtype=None, order=None): an incoming masked array keeps its mask, a plain array or scalar becomes unmasked.

public NDMaskedArray asarray(object a, DType dtype = null, char? order = null)

Parameters

a object

A NDMaskedArray, NDArray, or array-like/scalar.

dtype DType

Optional dtype to cast the data to (no copy when it already matches).

order char?

The data's layout: null is NumPy's order or 'C' — C order, so an F-ordered operand is COPIED into C; 'F', 'A', 'K' as for array(object, DType, bool, char?, object, object, bool, bool?, bool, int).

Returns

NDMaskedArray

A masked array over a's data (aliased when the dtype and layout allow).

Remarks

NumPy's masked_array(a, dtype=dtype, copy=False, keep_mask=True, subok=False, order=order or 'C'): the class constructor, so a masked operand also lends its fill value (converted to the dtype) and its hard-mask flag. order arrived in API-parity batch 8; before it, an F-ordered operand was aliased where NumPy copies it into C order.

Exceptions

TypeError

A masked operand's fill cannot be converted to dtype (numpy.ma's Cannot convert fill_value … to dtype …).

ValueError

An order letter NumPy does not have; text data that does not parse as a numeric dtype (NumPy's could not convert string to float: 'a').

atleast_1d(object)

At-least-1-D view (mask alike).

public NDMaskedArray atleast_1d(object a)

Parameters

a object

Operand.

Returns

NDMaskedArray

The masked array, rank ≥ 1.

atleast_1d(params object[])

At-least-1-D views of SEVERAL operands — NumPy's np.ma.atleast_1d(*arys) with more than one array (_fromnxfunction_allargs), which returns a list: each operand's data and full mask through np.atleast_1d, as atleast_1d(object) does for one.

public NDMaskedArray[] atleast_1d(params object[] arys)

Parameters

arys object[]

The operands (masked arrays, arrays, scalars, array-likes).

Returns

NDMaskedArray[]

One masked array per operand, in order (empty for no operand).

Remarks

C#'s params rule makes a LONE object[] the operand list itself, where NumPy reads a Python list as ONE array-like (np.ma.atleast_1d([a, b]) is one array): pass such a list as an array (or wrap it in a second object[]) to get NumPy's reading. Added in API-parity batch 8.

Exceptions

ArgumentNullException

arys or an operand is null.

atleast_2d(object)

At-least-2-D view (mask alike).

public NDMaskedArray atleast_2d(object a)

Parameters

a object

Operand.

Returns

NDMaskedArray

The masked array, rank ≥ 2.

atleast_2d(params object[])

At-least-2-D views of SEVERAL operands — NumPy's np.ma.atleast_2d(*arys) with more than one array, which returns a list (see atleast_1d(params object[])).

public NDMaskedArray[] atleast_2d(params object[] arys)

Parameters

arys object[]

The operands.

Returns

NDMaskedArray[]

One masked array per operand, rank ≥ 2, in order.

Remarks

A lone object[] is the operand list (C#'s params rule), not NumPy's one array-like. Added in API-parity batch 8.

Exceptions

ArgumentNullException

arys or an operand is null.

atleast_3d(object)

At-least-3-D view (mask alike).

public NDMaskedArray atleast_3d(object a)

Parameters

a object

Operand.

Returns

NDMaskedArray

The masked array, rank ≥ 3.

atleast_3d(params object[])

At-least-3-D views of SEVERAL operands — NumPy's np.ma.atleast_3d(*arys) with more than one array, which returns a list (see atleast_1d(params object[])).

public NDMaskedArray[] atleast_3d(params object[] arys)

Parameters

arys object[]

The operands.

Returns

NDMaskedArray[]

One masked array per operand, rank ≥ 3, in order.

Remarks

A lone object[] is the operand list (C#'s params rule), not NumPy's one array-like. Added in API-parity batch 8.

Exceptions

ArgumentNullException

arys or an operand is null.

average(object, int?, object, bool, bool)

Weighted average over unmasked elements - NumPy's ma.average(a, axis=None, weights=None, returned=False, *, keepdims): with no weights this is the mean; otherwise sum(a·w)/sum(w) with masked slots dropped from BOTH sums, and with returned the sum of weights too.

public MaskedArrayModule.AverageResult average(object a, int? axis = null, object weights = null, bool returned = false, bool keepdims = false)

Parameters

a object

Data.

axis int?

Axis or null.

weights object

Weights (same shape as a, or 1-D along axis); null ⇒ uniform.

returned bool

NumPy's returned: also return the sum of weights (the COUNT of unmasked elements, in the average's dtype, without weights).

keepdims bool

Keep the reduced axes as size-1 (NumPy 2.0 keepdims).

Returns

MaskedArrayModule.AverageResult

An MaskedArrayModule.AverageResult: the masked (weighted) average (it converts implicitly to NDMaskedArray) and, with returned, the sum of weights.

Remarks

Scoped by hand (a struct carrying a masked array is not a shape the weaver yields): the average's data / mask and, with returned, the sum of weights are handed back; everything else the core built (a sum of weights not asked for included) is reclaimed.

API-parity batch 11 (the owner's decision 3): NumPy's returned in NumPy's place (before keepdims, keyword-only in NumPy) and the MaskedArrayModule.AverageResult return; the NumSharp-only average_returned went.

Exceptions

AxisError

The axis is out of bounds (axis: axis 5 is out of bounds for array of dimension 1).

TypeError

Weights of another shape without an axis (Axis must be specified when shapes of a and weights differ.); text weights against a masked operand; a text operand.

ValueError

Weights that are not 1-D of the axis's length (Shape of weights must be consistent with shape of a along specified axis.).

bitwise_and(object, object, NDMaskedArray, NDArray, DType)

Bitwise AND; masked where either operand was.

public NDMaskedArray bitwise_and(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a&b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

bitwise_or(object, object, NDMaskedArray, NDArray, DType)

Bitwise OR; masked where either operand was.

public NDMaskedArray bitwise_or(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a|b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

bitwise_xor(object, object, NDMaskedArray, NDArray, DType)

Bitwise XOR; masked where either operand was.

public NDMaskedArray bitwise_xor(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a^b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

ceil(object, NDMaskedArray, NDArray, DType)

Ceiling; mask unchanged.

public NDMaskedArray ceil(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of ceil(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

choose(object, object[], NDMaskedArray, string)

Merges choice arrays by an index array — NumPy's np.ma.choose(indices, choices, out=None, mode='raise'): output[i] = choices[indices[i]][i]. The result element is masked iff the CHOSEN element was masked (or the index itself was masked) — the mask is chosen by the SAME index array, mirroring the data.

public NDMaskedArray choose(object indices, object[] choices, NDMaskedArray @out = null, string mode = "raise")

Parameters

indices object

Integer index array (each in [0, n-1]); a masked index masks its output (its data is read as 0).

choices object[]

The n choice arrays (NDMaskedArray/NDArray/array-like). A masked choice contributes its data FILLED with its own fill value (NumPy's fmask): hidden under the result's mask, but visible through a plain out.

out NDMaskedArray

NumPy's out: the chosen data is written into it (np.choose's shape and cast checks) and it is returned; a masked out then takes the result's mask through NumPy's setmask (a hard out only gains masked slots; nothing masked clears a soft out's mask and leaves a mask-less out mask-less). A plain array (converted) receives the data only. Added in API-parity batch 8.

mode string

Out-of-bounds policy: "raise" (default), "wrap", or "clip". It follows out, as in NumPy, so a positional mode is now written mode: "clip".

Returns

NDMaskedArray

The merged masked array (a new soft array with the default fill), or out.

Remarks

NumPy's statements: c = filled(indices, 0), the masks chosen and shrunk FIRST (make_mask(mask_or(np.choose(c, masks), getmask(indices)), shrink=True)), then the filled data chosen. Scoped by hand: the zero-filled index copy, the filled / materialized choices, the stand-in masks of unmasked choices and the pre-OR chosen mask are reclaimed; only the merged data and mask leave, and a mask created for out is detached (it lives in the caller's array).

Exceptions

ValueError

An index is out of range under mode="raise" (np.choose's invalid entry in choice array), checked before anything is written.

TypeError

out's shape is not the result's (choose: invalid shape for output array.).

clip(object, object, object, NDMaskedArray, object, object, object, bool?, DType)

Clamps each element into [a_min, a_max] — NumPy's ma.clip(a, a_min, a_max, out=None, *, min, max, fill_value=None, hardmask=False, dtype=None), which is np.clip(...) viewed as a masked array: the clip runs over the masked operand, so the result is masked wherever ANY operand is (a masked bound masks too).

public NDMaskedArray clip(object a, object a_min = null, object a_max = null, NDMaskedArray @out = null, object min = null, object max = null, object fill_value = null, bool? hardmask = null, DType dtype = null)

Parameters

a object

The operand: a masked array, or a plain array / array-like / scalar.

a_min object

Lower bound (array-like / scalar / masked array), or null (NumPy's None: no lower clip).

a_max object

Upper bound, or null (no upper clip). With both bounds and min / max null the result is a copy.

out NDMaskedArray

NumPy's out: the clipped data is written into it and a NEW masked view of it is returned (not the out object). A masked out's own mask is REPLACED by the operands' (the clip ufunc's wrap; a hard mask too) and keeps its fill value and hardness, which the returned view takes; a plain one (an NDArray converts) receives the data and the view is mask-less.

min object

NumPy 2.1's keyword alias of a_min, used when neither positional bound is given (np.clip's rule, with its TypeError / ValueError otherwise).

max object

NumPy 2.1's keyword alias of a_max.

fill_value object

NumPy's fill_value: set on the result through fill_value (NumPy's TypeError for a wrong kind); null keeps the inherited one. NumPy resets the fill for an explicit None, which C# cannot tell from "not given".

hardmask bool?

NumPy's hardmask: true hardens, false softens the result's mask; null (C#'s "not given") keeps what the result inherited (a hard operand gives a hard result). A bool? so that an explicit false softens, as NumPy's hardmask=False does.

dtype DType

NumPy's ufunc dtype: the dtype the clip computes in (its 'same_kind' casting).

Returns

NDMaskedArray

A new masked array: the clipped data, the OR of the operands' masks (nomask when nothing is masked), and the fill value and hardness of the first masked operand — or, with out, a view of the out. A fully masked 0-d result is NDMasked; a plain 0-d answer is wrapped mask-less (NumPy returns a scalar).

Remarks

NumPy 2.4.2's statements: clip = _convert2ma('clip', params={'fill_value': None, 'hardmask': False}), so result = np.clip(*args, **kwargs).view(MaskedArray), then result.fill_value = fill_value and result._hardmask = bool(hardmask) when given. np.clip runs a.clip(...), and MaskedArray has no clip of its own (it is ndarray.clip): _clip drops a Python-int bound past an integer dtype's range and routes to positive / minimum / maximum / clip, a ufunc over the masked operand whose array_wrap (ClipMethodCore(object, object, object, NDMaskedArray, DType, object, object)) sets the mask. Until API-parity batch 9 this was (a, a_min, a_max), which clipped the raw data and copied a's mask only: a masked bound's mask was lost. Scoped by hand: the bounds' materializations and the mask ORs are reclaimed.

Exceptions

TypeError

np.clip's argument rule: clip() missing 1 required positional argument: 'a_min' / 'a_max' when only one positional bound comes with a keyword bound; a wrong fill_value kind.

ValueError

Both positional bounds with min or max (Passing min or max keyword argument when a_min and a_max are provided is forbidden.), or the operands / out do not broadcast.

OverflowError

A C# integer bound that does not fit an integer operand's dtype.

UFuncTypeError

The clip refuses dtype or the out's dtype.

clump_masked(object)

Contiguous MASKED runs of a 1-D array as slices (NumPy's clump_masked).

public Slice[] clump_masked(object a)

Parameters

a object

1-D operand.

Returns

Slice[]

One Slice per contiguous masked run (empty when unmasked).

Remarks

Scoped by hand (the result holds no array): the raveled mask — a copy when the mask is not contiguous — is reclaimed before the slices are returned.

clump_unmasked(object)

Contiguous UNMASKED runs of a 1-D array as slices (NumPy's clump_unmasked).

public Slice[] clump_unmasked(object a)

Parameters

a object

1-D operand.

Returns

Slice[]

One Slice per contiguous unmasked run.

Remarks

Scoped by hand (the result holds no array): the inverted mask and any operand this method had to materialize are reclaimed before the slices are returned.

column_stack(params object[])

Stack 1-D arrays as columns of a 2-D result (masks alike).

public NDMaskedArray column_stack(params object[] tup)

Parameters

tup object[]

Operands.

Returns

NDMaskedArray

The stacked masked array.

common_fill_value(object, object)

The single fill value shared by both inputs, or null when they differ (NumPy's common_fill_value: t1 == t2 on the two get_fill_value results). Each operand's fill is its stored override, else its dtype default.

public object common_fill_value(object a, object b)

Parameters

a object

First operand.

b object

Second operand.

Returns

object

The common fill value (boxed; the FIRST operand's when they are equal), or null when the two differ.

Remarks

The comparison is Python's == between the two scalars: text by content (a str never equals a bytes, so a U and an S array share no fill), numbers by value (5.0 == 5), and a number never equals text.

Exceptions

ValueError

A fill value is an array (NumPy's deprecated non-scalar fill) and the elementwise comparison has more than one element: Python's truth test of the comparison raises.

compress(object, object, int?, NDMaskedArray)

Keeps only the elements where condition is truthy — NumPy's np.ma.compress(condition, a, axis=None, out=None); data AND mask are compressed alike so the survivors keep their masked-ness.

public NDMaskedArray compress(object condition, object a, int? axis = null, NDMaskedArray @out = null)

Parameters

condition object

1-D array-like selector, read by truth value (non-zero numbers, non-empty strings) over the flattened elements or along axis.

a object

Data.

axis int?

Axis to compress along, or null to flatten first.

out NDMaskedArray

NumPy's out: the compressed DATA is written into it (np.compress's shape and cast checks) and its mask is never touched. The result is then a NEW masked array over out's data whose mask is the operand's compressed mask — or, for an unmasked operand, out's own mask object (NumPy's out.view(type(self)) shares it). Added in API-parity batch 8.

Returns

NDMaskedArray

The compressed masked array; it keeps a masked a's fill value and hardness (also when it is a view of out).

Remarks

NumPy's MaskedArray.compress: condition = np.asarray(condition), then _new = _data.compress(condition, axis=axis, out=out).view(type(self)) — whose 1-d check, nonzero and take run in NumPy's order inside compress(NDArray, NDArray, int?, NDArray) — _new._update_from(self), and if _mask is not nomask: _new._mask = _mask.compress(condition, axis=axis), which rebinds the NEW array's mask only.

Exceptions

ArgumentException

The condition is not 1-D (NumPy's ValueError condition must be a 1-d array), checked before its values are read.

IndexError

A truthy condition entry past the axis length.

ValueError

out's shape is not the result's (output array does not match result of ndarray.take).

compress_cols(object)

Drops the COLUMNS of a 2-D array that contain ANY masked element (NumPy's compress_cols).

public NDArray compress_cols(object a)

Parameters

a object

2-D operand.

Returns

NDArray

The surviving columns (see compress_rows(object) for the unmasked and all-masked forms).

Remarks

NumPy's compress_rowcols(a, 1) after its own rank check. Scoped ([NDScoped]), as compress_rows(object).

Exceptions

NotImplementedError

a is not 2-D (NumPy's compress_cols works for 2D arrays only.).

compress_nd(object, int?)

Suppresses the slices (along each requested axis) that contain any masked value and returns the surviving DATA as a PLAIN array (NumPy's compress_nd). axis null compresses along EVERY axis; an explicit axis compresses only that one. The keep-mask for each axis is computed from the full original mask, so an N-D box is trimmed to the sub-block with no masked element on any face.

public NDArray compress_nd(object x, int? axis = null)

Parameters

x object

Operand.

axis int?

null (all axes) or a single axis (negative allowed).

Returns

NDArray

A plain NDArray of the surviving data (an unmasked input returns its data; a fully-masked input returns an empty array).

Remarks

Scoped ([NDScoped]): every per-axis reduction, keep-mask and intermediate compression is reclaimed; only the final compression (or the operand's own data, which the scope never owned) leaves.

Exceptions

AxisError

axis is out of range for the operand's rank — checked first, before the unmasked shortcut (NumPy's normalize_axis_tuple is compress_nd's first statement).

compress_rowcols(object, int?)

Drops the rows AND/OR columns of a 2-D array that contain any masked value (NumPy's compress_rowcols) — the 2-D specialization of compress_nd(object, int?). Returns a plain array.

public NDArray compress_rowcols(object x, int? axis = null)

Parameters

x object

2-D operand.

axis int?

null (rows AND cols), 0 (rows), or 1 (cols).

Returns

NDArray

The surviving data as a plain NDArray.

Remarks

Scoped ([NDScoped]): an array-like operand the rank check had to materialize is reclaimed; compress_nd(object, int?) scopes its own intermediates.

Exceptions

NotImplementedError

x is not 2-D (NumPy's compress_rowcols works for 2D arrays only.).

compress_rows(object)

Drops the ROWS of a 2-D array that contain ANY masked element (NumPy's compress_rows) — a plain NDArray.

public NDArray compress_rows(object a)

Parameters

a object

2-D operand.

Returns

NDArray

The surviving rows: the data ITSELF when nothing is masked, an empty float64 array when everything is (NumPy's compress_nd).

Remarks

NumPy's statements: a = asarray(a); if a.ndim != 2: raise NotImplementedError(...); return compress_rowcols(a, 0). Scoped ([NDScoped]): an array-like operand the rank check had to materialize is reclaimed.

Exceptions

NotImplementedError

a is not 2-D (NumPy's compress_rows works for 2D arrays only.).

compressed(object)

The 1-D array of the UNMASKED values in C-order (NumPy's compressed) — a plain NDArray, since a compressed result has, by definition, no mask.

public NDArray compressed(object a)

Parameters

a object

Operand.

Returns

NDArray

A 1-D NDArray of the unmasked data.

Remarks

NumPy's statements: data = ndarray.ravel(self._data), then data.compress(~ravel(mask)) when there is a mask. So an UNMASKED operand's result is its raveled data — a VIEW of contiguous data (writes reach the operand), a copy otherwise — and a masked one's a fresh selection. Scoped ([NDScoped]): the raveled mask and the negated selector are reclaimed.

concatenate(object[], int?)

Joins arrays along an existing axis (NumPy's ma.concatenate): the data joined, and the masks joined alike when some operand has one, shrunk to nomask when nothing is masked.

public NDMaskedArray concatenate(object[] arrays, int? axis = 0)

Parameters

arrays object[]

Operands (masked arrays, arrays, scalars or array-likes).

axis int?

Join axis, or null to join the flattened operands (NumPy's axis=None, which ma.setxor1d and ma.union1d use).

Returns

NDMaskedArray

The joined masked array: a NEW array (soft, no fill value), as NumPy's d.view(rcls).

Exceptions

ArgumentNullException

arrays or an operand is null.

ValueError

A 0-d operand with an axis (zero-dimensional arrays cannot be concatenated).

IncorrectShapeException

The operands' ranks or non-axis dimensions differ (NumPy's ValueError texts).

conjugate(object, NDMaskedArray, NDArray, DType)

Complex conjugate (real data passes through); mask unchanged.

public NDMaskedArray conjugate(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of conj(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

convolve(object, object, string, bool)

Discrete linear convolution of two 1-D sequences, propagating the mask (NumPy's ma.convolve). Default mode is "full".

public NDMaskedArray convolve(object a, object v, string mode = "full", bool propagate_mask = true)

Parameters

a object

First sequence.

v object

Second sequence.

mode string

"full" (default), "same", or "valid".

propagate_mask bool

Mask a result if ANY masked cell contributed (true) vs only if NO unmasked cell did (false).

Returns

NDMaskedArray

The masked convolution.

copy(object, char)

Deep copy of a as a masked array (NumPy's module-level ma.copy, the _arraymethod('copy')): the data AND the mask are copied, so mutating either the source or the copy never affects the other, and the copy takes the source's fill value and hard-mask flag (_update_from(self)).

public NDMaskedArray copy(object a, char order = 'C')

Parameters

a object

Array-like/masked-array to copy.

order char

The copy's layout, NumPy's copy(order='C'): 'C' (the default), 'F', 'A' or 'K' (keep the source's) — data and mask alike.

Returns

NDMaskedArray

A masked array over a fresh copy of the data (mask copied when present).

Remarks

Scoped by hand: a scalar/array-like operand's materialization (the source of the copy) is reclaimed; only the copies leave. order arrived in API-parity batch 7 (NumPy's _frommethod('copy') passes it on to MaskedArray.copy).

Exceptions

ValueError

An order letter NumPy does not have.

corrcoef(object, object, bool, bool)

Pearson correlation coefficients from the pairwise-complete covariance (NumPy's ma.corrcoef): cov(x) normalized by the outer product of the per-variable standard deviations.

public NDMaskedArray corrcoef(object x, object y = null, bool rowvar = true, bool allow_masked = true)

Parameters

x object

Observations (see cov(object, object, bool, bool, bool, int?)).

y object

Optional additional variables.

rowvar bool

True (default): each row is a variable.

allow_masked bool

When false, raise if any value is masked.

Returns

NDMaskedArray

The masked correlation matrix.

Remarks

Scoped by hand: the covariance, its diagonal, the standard deviations and their outer product only feed the final division and are reclaimed.

Exceptions

ValueError

allow_masked is false and data is masked.

correlate(object, object, string, bool)

Cross-correlation of two 1-D sequences, propagating the mask (NumPy's ma.correlate). Default mode is "valid" (unlike convolve(object, object, string, bool)).

public NDMaskedArray correlate(object a, object v, string mode = "valid", bool propagate_mask = true)

Parameters

a object

First sequence.

v object

Second sequence.

mode string

"valid" (default), "same", or "full".

propagate_mask bool

Mask a result if ANY masked cell contributed (true) vs only if NO unmasked cell did (false).

Returns

NDMaskedArray

The masked cross-correlation.

cos(object, NDMaskedArray, NDArray, DType)

Cosine; mask unchanged.

public NDMaskedArray cos(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of cos(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

cosh(object, NDMaskedArray, NDArray, DType)

Hyperbolic cosine; mask unchanged.

public NDMaskedArray cosh(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of cosh(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

count(object, int, bool)

The owner's kept int form of count(object, NDAxis?, bool).

public NDArray count(object a, int axis, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDArray

The int64 count of the unmasked elements (a plain array, never masked).

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis.

count(object, int[], bool)

The owner's kept int[] form of count(object, NDAxis?, bool).

public NDArray count(object a, int[] axis, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

keepdims bool

Keep the reduced axes with length 1.

Returns

NDArray

The int64 count of the unmasked elements (a plain array, never masked).

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis.

count(object, NDAxis?, bool)

Number of UNMASKED elements along the axis or axes — NumPy's np.ma.count(a, axis=None, keepdims): a plain int64 array, never masked.

public NDArray count(object a, NDAxis? axis = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

keepdims bool

Keep the reduced axes with length 1.

Returns

NDArray

The int64 count of the unmasked elements (a plain array, never masked).

Remarks

Scoped ([NDScoped]): the negated-mask (or all-True) indicator the count sums is reclaimed. NumPy's statements: with a mask, (~m).sum(axis, dtype=intp) (a ufunc reduction: duplicate value in 'axis'); without one, the counts from the SHAPE — normalize_axis_tuple (repeated axis) and np.full(out_dims, items); a 0-d operand accepts only the axis 0 or None (a tuple, even (0,), is NumPy's AxisError naming the tuple). The tuple axis arrived in API-parity batch 8.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis.

count_masked(object, int?)

Number of MASKED elements along the axis (NumPy's count_masked) — a plain int64 array.

public NDArray count_masked(object a, int? axis = null)

Parameters

a object

Operand.

axis int?

Axis or null.

Returns

NDArray

An int64 count of masked elements.

Remarks

Scoped ([NDScoped]): the all-False stand-in of an unmasked operand is reclaimed.

cov(object, object, bool, bool, bool, int?)

Estimates the covariance matrix, PAIRWISE-COMPLETE over the mask (NumPy's ma.cov): each entry divides by the number of observations where both variables are unmasked, minus ddof. Any entry whose pairwise count is ≤ 0 (no complete observation) is MASKED.

public NDMaskedArray cov(object x, object y = null, bool rowvar = true, bool bias = false, bool allow_masked = true, int? ddof = null)

Parameters

x object

Observations (rows are variables when rowvar, else columns).

y object

Optional additional variables, stacked onto x (a common mask is taken when same-shape).

rowvar bool

True (default): each ROW is a variable. False: each column is.

bias bool

Normalize by N (true) instead of N-1 — overridden by ddof.

allow_masked bool

When false, raise if any value is masked (NumPy's flag).

ddof int?

Explicit delta DOF (divisor is pairwise-count − ddof); null uses bias.

Returns

NDMaskedArray

The masked covariance matrix (squeezed to a scalar for a single variable).

Remarks

Scoped by hand: the centered/filled data, the not-mask indicator, the pairwise counts, the transposed products and the unsqueezed result are reclaimed; only the (squeezed) covariance and its mask leave.

Exceptions

ValueError

allow_masked is false and data is masked.

cumprod(object, int?, DType, NDMaskedArray)

Cumulative product along the axis — NumPy's np.ma.cumprod(a, axis=None, dtype=None, out=None) (MaskedArray.cumprod): masked slots contribute 1 but stay masked in the result.

public NDMaskedArray cumprod(object a, int? axis = null, DType dtype = null, NDMaskedArray @out = null)

Parameters

a object

Operand.

axis int?

Axis or null (flatten, C-order).

dtype DType

Accumulator dtype.

out NDMaskedArray

NumPy's out, as cumsum(object, int?, DType, NDMaskedArray)'s: the scan is written into it and a masked out takes the operand's mask through setmask. Added in API-parity batch 8.

Returns

NDMaskedArray

The masked cumulative product, or out.

Exceptions

IncorrectShapeException

out's shape is not the scan's, or a hard masked out the operand's mask does not broadcast to (raised after the data was written).

AxisError

axis is out of range.

TypeError

A text operand: the scan has no string loop.

cumsum(object, int?, DType, NDMaskedArray)

Cumulative sum along the axis — NumPy's np.ma.cumsum(a, axis=None, dtype=None, out=None) (MaskedArray.cumsum): masked slots contribute 0 to the running total but their POSITIONS stay masked in the result.

public NDMaskedArray cumsum(object a, int? axis = null, DType dtype = null, NDMaskedArray @out = null)

Parameters

a object

Operand.

axis int?

Axis or null (flatten, C-order).

dtype DType

Accumulator dtype.

out NDMaskedArray

NumPy's out: the scan is written into it (np.cumsum's shape and cast checks) and it is returned. A masked out then takes the operand's mask through NumPy's setmask — a hard out only gains masked slots, a soft one takes the values (flattened in C order for axis = null), and an unmasked operand clears a soft out's mask and leaves a mask-less out mask-less. A plain array (converted) receives the data only. Added in API-parity batch 8.

Returns

NDMaskedArray

The masked cumulative sum, or out.

Exceptions

IncorrectShapeException

out's shape is not the scan's (NumPy's ValueError operands could not be broadcast together with remapped shapes ..., nothing written), or a HARD masked out whose shape the operand's mask does not broadcast to (axis=null over a 2-D operand: NumPy's |= refusal, raised after the data was written).

AxisError

axis is out of range.

TypeError

A text operand: the scan has no string loop.

default_fill_value(DType)

The default fill value NumPy assigns per dtype kind (default_fill_value, its default_filler table): True for boolean, 999999 for integers, 1e20 for float, (1e20+0j) for complex, the text 'N/A' for a U dtype and the bytes b'N/A' for an S dtype. Used by filled(object) and the fill_value getter when the array holds no fill of its own.

public object default_fill_value(DType obj)

Parameters

obj DType

NumPy's obj: the data dtype to pick a fill for; null is NumPy's None (see remarks). The owner's 2026-11-11 call keeps this typed overload beside NumPy's default_fill_value(obj) (default_fill_value(object)); both answer alike, and the parameter is NumPy's name.

Returns

object

A boxed scalar of a type castable into obj: a string for a U dtype and a fresh byte[] for an S dtype.

Remarks

An INSTANCE method (like minimum_fill_value(object)/maximum_fill_value(object)), so np.ma.default_fill_value(dtype) ports from NumPy verbatim. An array or a scalar takes the default_fill_value(object) overload.

The text default is NOT sized to the dtype: NumPy stores np.array('N/A') (a <U3), so the fill value of a <U1 array reads all three characters, and only filled(object) truncates it, when it copies the fill into the data's width ('N/' into <U2). The bytes default is a NEW array on every call, because a byte[] is mutable and the caller owns it.

A null argument binds THIS overload (a DType is the better conversion target than object) and is NumPy's default_fill_value(None): np.asanyarray(None) is a 0-d OBJECT array, whose default is the string '?' (default_filler['O']). Footgun: a null DType variable therefore answers "?" rather than throwing.

default_fill_value(object)

NumPy's default_fill_value(obj) for an ARRAY or a SCALAR: the default of _get_dtype_of(obj) — a descriptor as is, a masked array's or array's own dtype, otherwise np.asanyarray(obj).dtype (ma.default_fill_value(np.array([1], np.uint8)) is 999999, ma.default_fill_value(1.5) 1e20).

public object default_fill_value(object obj)

Parameters

obj object

An NDMaskedArray, an NDArray, a DType, a C# scalar, a C# array, List or object[] (a Python list), or a byte[] (NumPy's bytes scalar, the house map).

Returns

object

See default_fill_value(DType).

Remarks

Only the dtype's KIND decides the value (every integer 999999, every float 1e20, bool True, complex (1e20+0j), text 'N/A' / b'N/A'), so a C# int literal answers like NumPy's Python int although its array would be int32 here and int64 in NumPy. A string argument binds the DType overload (the implicit dtype-string conversion: "f8" is float64), where NumPy reads a str as text ('N/A'); pass the string typed as object, or np.array(s), for NumPy's reading. null binds the DType overload too (NumPy's '?').

Exceptions

NotSupportedException

An object np.asanyarray cannot make an array of (NumPy would make an object array of it, whose default is '?').

diag(object, int)

Diagonal: 1-D input CONSTRUCTS a matrix with the values (and mask) on the k-th diagonal; 2-D input EXTRACTS the k-th diagonal (and its mask). NumPy's ma.diag.

public NDMaskedArray diag(object v, int k = 0)

Parameters

v object

Operand.

k int

Diagonal offset.

Returns

NDMaskedArray

The masked array.

diagflat(object, int)

Flatten the input and build a diagonal matrix from it (mask alike).

public NDMaskedArray diagflat(object v, int k = 0)

Parameters

v object

Operand.

k int

Diagonal offset.

Returns

NDMaskedArray

The masked diagonal matrix.

diagonal(object, int, int, int)

Extracts the offset-th diagonal of a 2-D (or stacked) array (NumPy's ma.diagonal, the _arraymethod('diagonal')); the mask is extracted alike so each diagonal element keeps its masked-ness, and the result takes the operand's fill value and hard-mask flag.

public NDMaskedArray diagonal(object a, int offset = 0, int axis1 = 0, int axis2 = 1)

Parameters

a object

Data (rank ≥ 2).

offset int

Diagonal offset (0 = main).

axis1 int

First plane axis.

axis2 int

Second plane axis.

Returns

NDMaskedArray

The masked diagonal: read-only VIEWS of the data and of the mask (np.diagonal's), as in NumPy.

diff(object, int, int, object, object)

The n-th discrete difference along an axis, preserving the mask (NumPy's ma.diff): an output element is masked iff ANY of the n+1 input elements folded into it was masked.

public NDMaskedArray diff(object a, int n = 1, int axis = -1, object prepend = null, object append = null)

Parameters

a object

Data (rank ≥ 1).

n int

Number of times to difference (0 returns the input; must be ≥ 0).

axis int

Axis along which to difference (default last).

prepend object

Values prepended along axis before differencing, or null.

append object

Values appended along axis before differencing, or null.

Returns

NDMaskedArray

The masked differences (axis length reduced by n), with a's fill value and hard mask when nothing is prepended or appended; a ITSELF for n == 0.

Remarks

Scoped by hand: the prepend/append concatenation, the per-step dropped-edge takes and their index ranges, and every intermediate OR'd mask are reclaimed; only the differences and the final mask leave.

Exceptions

ArgumentException

n is negative or a is 0-D.

divide(object, object, NDMaskedArray, NDArray, DType)

True division; additionally MASKS positions where the denominator is (near) zero, so a masked divide never surfaces an inf/NaN from division by zero.

public NDMaskedArray divide(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Numerator.

b object

Denominator.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the zero divisors, whose slots take 1 and get no data back (a plain out gets the dividend). An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a/b with unsafe divides masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

dot(object, object, bool, NDMaskedArray)

Dot product with masked slots treated as 0; a result element is masked only if NO valid (both-unmasked) term contributed to it — NumPy's np.ma.dot(a, b, strict=False, out=None). With strict the mask is PROPAGATED first — any masked value in a contracted row/column masks that whole vector — so a result element is masked whenever a masked value touched it (NumPy's strict=True).

public NDMaskedArray dot(object a, object b, bool strict = false, NDMaskedArray @out = null)

Parameters

a object

Left operand.

b object

Right operand.

strict bool

Propagate masks along the contracted axes before the product (default false = treat masked as 0).

out NDMaskedArray

NumPy's out, which must be a MASKED array: the product is written into its data (np.dot's rules: the product's exact dtype, C-contiguous, the product's shape) and the no-valid-pair mask into its mask in place — a hard mask overwritten too, a mask-less out given a mask of the product's shape — and it is returned. Added in API-parity batch 8.

Returns

NDMaskedArray

The masked dot product, soft with the default fill value: an array result always carries a mask ARRAY (all-False when every slot has a valid pair); a 0-d result is unmasked or carries a 0-d True mask. Or out.

Remarks

Scoped by hand: the propagated operands, the zero-filled copies, the validity indicators and their product are reclaimed; only the product and its mask leave (a mask created for out is detached: it lives in the caller's array). Over text NumPy's product refuses by dtype (dot not available for this type, or a scalar operand's multiply loop) after formatting the fill, and that refusal is raised over the unfilled data.

Exceptions

AttributeError

out is a plain array ('numpy.ndarray' object has no attribute '_data'), raised before the product.

ValueError

out has another dtype than the product's or is not C-contiguous (output array is not acceptable (must have the right datatype, number of dimensions, and be a C-Array)), or another shape (output array has wrong dimensions).

TypeError

A 0-d out without a mask: NumPy hands its nomask to the mask product ('out' must be an array), after the data was written.

IncorrectShapeException

The operands' shapes are not aligned.

dstack(params object[])

Stack along the third axis (masks alike).

public NDMaskedArray dstack(params object[] tup)

Parameters

tup object[]

Operands.

Returns

NDMaskedArray

The stacked masked array.

ediff1d(object, object, object)

Differences between consecutive UNMASKED-aware elements of the flattened input (NumPy's ediff1d), optionally bracketed by to_begin/to_end.

public NDMaskedArray ediff1d(object arr, object to_end = null, object to_begin = null)

Parameters

arr object

Data.

to_end object

Values appended to the end (array-like), or null.

to_begin object

Values prepended (array-like), or null.

Returns

NDMaskedArray

The masked consecutive differences.

empty(Shape, DType, char, string, object, bool)

Masked array of uninitialized values (no element masked) — NumPy's np.ma.empty(shape, dtype=None, order='C', *, device=None, fill_value=None, hardmask=False).

public NDMaskedArray empty(Shape shape, DType dtype = null, char order = 'C', string device = null, object fill_value = null, bool hardmask = false)

Parameters

shape Shape

Result shape.

dtype DType

Element dtype (null ⇒ float64).

order char

The memory layout, 'C' (the default) or 'F'.

device string

NumPy's Array-API device: null or "cpu".

fill_value object

The result's fill value (converted to the dtype); null leaves the default.

hardmask bool

True gives the result a hard mask.

Returns

NDMaskedArray

An unmasked masked array of arbitrary contents.

Remarks

Keywords as in zeros(Shape, DType, char, string, object, bool) (API-parity batch 7).

Exceptions

ValueError

A bad order letter (first), or a device other than "cpu".

TypeError

fill_value cannot be stored in the dtype.

empty_like(object, DType, char, Shape?, string)

Masked uninitialized array shaped like a (NumPy's ma.empty_like): the prototype's mask (a copy), fill value and hardness ride along, as in zeros_like(object, DType, char, Shape?, string).

public NDMaskedArray empty_like(object a, DType dtype = null, char order = 'K', Shape? shape = null, string device = null)

Parameters

a object

Prototype array-like.

dtype DType

Override dtype.

order char

NumPy's layout ('K' keeps the prototype's); the copied mask follows the result.

shape Shape?

Override shape: the mask is reshaped when the sizes match, dropped when they do not.

device string

NumPy's Array-API device: null or "cpu".

Returns

NDMaskedArray

A masked array of arbitrary contents (a U result is zero-filled, as NumPy's is).

Remarks

Keywords as in zeros_like(object, DType, char, Shape?, string) (API-parity batch 7).

Exceptions

ValueError

A bad order letter or device.

TypeError

See zeros_like(object, DType, char, Shape?, string).

equal(object, object, NDMaskedArray, NDArray, DType)

Element-wise equality; masked where either operand was.

public NDMaskedArray equal(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a==b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

exp(object, NDMaskedArray, NDArray, DType)

e^x; mask unchanged.

public NDMaskedArray exp(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of exp(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

expand_dims(object, NDAxis)

Insert size-1 axes, the mask expanded alike — NumPy's np.ma.expand_dims(a, axis): each listed position of the RESULT becomes a new length-1 axis.

public NDMaskedArray expand_dims(object a, NDAxis axis)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis

The new axes' positions in the result: an int, a tuple or an int[] (negative counts from the end of the result).

Returns

NDMaskedArray

A masked array viewing the operand's data and mask, with its fill value and hard-mask flag.

Remarks

NumPy's tuple axis arrived in API-parity batch 8 (it was one int).

Exceptions

AxisError

A position out of range for the result's rank.

ValueError

A repeated position.

expand_dims(object, int)

Insert ONE size-1 axis — the owner's kept int form beside expand_dims(object, NDAxis).

public NDMaskedArray expand_dims(object a, int axis)

Parameters

a object

The operand.

axis int

The new axis' position in the result.

Returns

NDMaskedArray

The expanded masked array.

Exceptions

AxisError

The position is out of range.

expand_dims(object, int[])

Insert the listed size-1 axes — the owner's kept int[] form beside expand_dims(object, NDAxis).

public NDMaskedArray expand_dims(object a, int[] axis)

Parameters

a object

The operand.

axis int[]

The new axes' positions in the result.

Returns

NDMaskedArray

The expanded masked array.

Exceptions

AxisError

A position is out of range.

ValueError

A repeated position.

ArgumentNullException

axis is null.

fabs(object, NDMaskedArray, NDArray, DType)

Float-only absolute value (promotes ints to float); mask unchanged.

public NDMaskedArray fabs(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of the float |data|.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

filled(object, object)

Substitutes fill_value for masked elements of a and returns a plain array (NumPy's module-level ma.filled). A non-masked input is returned as an array unchanged.

public NDArray filled(object a, object fill_value = null)

Parameters

a object

A NDMaskedArray or array-like.

fill_value object

Fill for masked slots; null uses the dtype default.

Returns

NDArray

A plain NDArray with masked slots filled.

fix_invalid(object, object, bool, object)

Masks the non-finite (NaN/±inf) elements of a AND writes the fill value into their data slots (NumPy's fix_invalid) — like masked_invalid(object, bool) but the hidden data becomes the fill rather than the original non-finite value. The result keeps a's own fill_value; fill_value only chooses what is WRITTEN into the masked slots (matching NumPy, whose param sets the data, not the attribute).

public NDMaskedArray fix_invalid(object a, object mask = null, bool copy = true, object fill_value = null)

Parameters

a object

Data array-like (an existing mask is preserved and OR'd with the invalid mask).

mask object

Optional extra mask to OR in (NumPy's mask=, read as array(object, DType, bool, char?, object, object, bool, bool?, bool, int) reads it); null = none.

copy bool

Copy the data (default true) vs alias it (then the fill is written into a's data, as NumPy does).

fill_value object

Value written at the newly-masked (invalid) slots; null uses the result's own fill value (a's, else the dtype default).

Returns

NDMaskedArray

A masked array with non-finite slots masked and their data replaced by the fill.

Remarks

NumPy's statements: a = masked_array(a, copy=copy, mask=mask, subok=True); invalid = np.logical_not(np.isfinite(a._data)); if not invalid.any(): return a; a._mask |= invalid; a._data[invalid] = fill_value. So the mask stage runs first (its MaskError wins), the mask is never shrunk (an explicit all-False mask stays an array), and only the newly caught non-finite slots are overwritten — pre-existing masked-but-finite data is left alone.

Scoped by hand: the partial masks, the fill scalar and any operand materializations are reclaimed; only the result's data and mask leave.

Exceptions

MaskError

The mask's size is neither one nor the data's (NumPy's constructor check, raised before the data is examined).

TypeError

Text data: NumPy's np.isfinite has no loop for it, whatever the size.

flatnotmasked_contiguous(object)

Contiguous UNMASKED runs of the flattened array (NumPy's flatnotmasked_contiguous); same as clump_unmasked(object) for a 1-D input.

public Slice[] flatnotmasked_contiguous(object a)

Parameters

a object

Operand.

Returns

Slice[]

One Slice per contiguous unmasked run.

Remarks

Scoped by hand (the result holds no array): the raveled operand — a copy of a non-contiguous input — is reclaimed once its runs are read.

flatnotmasked_edges(object)

First and last UNMASKED flat indices (NumPy's flatnotmasked_edges), or null when every element is masked.

public NDArray flatnotmasked_edges(object a)

Parameters

a object

Operand.

Returns

NDArray

NumPy's int64 array [first, last] — [0, size - 1] when nothing is masked (an EMPTY operand included: [0, -1]) — or null (NumPy's None) when every element is masked.

Remarks

NumPy's statements: if m is nomask or not np.any(m): return np.array([0, a.size - 1]); unmasked = np.flatnonzero(~m); unmasked[[0, -1]] when there is one, else None. Scoped by hand: the inverted, raveled mask and any operand this method had to materialize are reclaimed; only the index array leaves.

flatten(object, char)

Flattened COPY (NumPy's flatten — always copies, unlike ravel(object, char)).

public NDMaskedArray flatten(object a, char order = 'C')

Parameters

a object

Operand.

order char

'C' or 'F'.

Returns

NDMaskedArray

The flattened masked copy.

flatten_mask(object)

Ravels a mask to a flat 1-D boolean array (NumPy's flatten_mask). In NumPy this collapses the nested per-field masks of a STRUCTURED dtype into one flat sequence of booleans; NumSharp has no structured dtypes, so the recursion never branches and this is exactly "ravel in C-order, then coerce to bool" — which is precisely what NumPy's own non-structured path does (np.array([...raveled...], dtype=bool)). Non-boolean input is coerced by non-zero-ness (astype(bool) ≡ != 0), so an integer/float mask flattens like NumPy's.

public NDArray flatten_mask(object mask)

Parameters

mask object

A mask array-like (NDArray, C# array, scalar, or the nomask sentinel). A 0-D input flattens to a length-1 array (matching NumPy).

Returns

NDArray

A fresh 1-D boolean NDArray in C-order.

Remarks

Returns a fresh array (never a view), matching NumPy which builds a new np.array. Scoped ([NDScoped]): the raveled intermediate (and a materialized array-like) are reclaimed.

Text. NumPy's _flatsequence recurses into every element that has __iter__, so over text it does not read truth values the way the numeric path does (see FlattenTextMask(NDArray)).

Exceptions

RuntimeError

A U array with a non-empty element (NumPy's RecursionError, see the remarks).

SystemError

A U element NumPy turns into a str holds a unit above U+10FFFF.

floor(object, NDMaskedArray, NDArray, DType)

Floor; mask unchanged.

public NDMaskedArray floor(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of floor(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

floor_divide(object, object, NDMaskedArray, NDArray, DType)

Floor division; masks positions where the denominator is (near) zero.

public NDMaskedArray floor_divide(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Numerator.

b object

Denominator.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the zero divisors, whose slots take 1 and get no data back (a plain out gets the dividend). An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a//b with unsafe divides masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

fmod(object, object, NDMaskedArray, NDArray, DType)

C-style remainder (sign follows dividend); masks positions where the denominator is (near) zero.

public NDMaskedArray fmod(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Numerator.

b object

Denominator.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the zero divisors, whose slots take 1 and get no data back (a plain out gets the dividend). An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of fmod(a, b) with unsafe divides masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

frombuffer(byte[], DType, long, long)

Interprets a byte buffer as a 1-D array (NumPy's ma.frombuffer) — an UNMASKED masked array wrapping frombuffer(byte[], DType, long, long).

public NDMaskedArray frombuffer(byte[] buffer, DType dtype = null, long count = -1, long offset = 0)

Parameters

buffer byte[]

The source bytes.

dtype DType

Element dtype (null ⇒ float64).

count long

Elements to read (-1 = all).

offset long

Start byte offset.

Returns

NDMaskedArray

An unmasked masked array over the buffer's values.

fromfunction(Func<NDArray, NDArray, NDArray>, Shape, DType)

Two-axis convenience for fromfunction(Func<NDArray[], NDArray>, Shape, DType) — matches NumPy's fromfunction(lambda i, j: …, (m, n)).

public NDMaskedArray fromfunction(Func<NDArray, NDArray, NDArray> function, Shape shape, DType dtype = null)

Parameters

function Func<NDArray, NDArray, NDArray>

Vectorized function of the row and column index grids.

shape Shape

Output 2-D shape.

dtype DType

Index-grid dtype (null ⇒ float64, NumPy's default).

Returns

NDMaskedArray

An unmasked masked array.

Remarks

Same ownership contract as the array-of-grids overload: the two grids handed to function are released after the call unless one IS the returned data.

fromfunction(Func<NDArray[], NDArray>, Shape, DType)

Builds an array by applying function to the coordinate grids of shape (NumPy's ma.fromfunction) — an UNMASKED result. The delegate receives one NDArray per axis (the i-th being that axis's index grid), matching NumPy's function(*indices); it must be vectorized (operate on the whole grids at once).

public NDMaskedArray fromfunction(Func<NDArray[], NDArray> function, Shape shape, DType dtype = null)

Parameters

function Func<NDArray[], NDArray>

Vectorized function of the per-axis index grids.

shape Shape

Output shape (the grids' shape).

dtype DType

Index-grid dtype; null ⇒ float64, NumPy's dtype=float default (probed 2.4.2: ma.fromfunction(lambda i, j: i + j, (3, 4)).dtype is float64). Pass int64 for integer grids.

Returns

NDMaskedArray

An unmasked masked array of function's result.

Remarks

The null default USED to fall through to indices(Shape, DType, bool)'s own default (int64), so every default-dtype call computed on integer grids where NumPy computes on float64 — a wrong result dtype (and integer arithmetic, e.g. division) for the most common spelling.

Ownership — the np.ma callback contract (apply_along_axis(Func<NDMaskedArray, NDMaskedArray>, int, object)): whatever function returns becomes the result's data and stays the CALLER's, so the call runs outside any scope of this method's (one would capture — and dispose — the callback's own allocations). The index grid and the per-axis grid views handed to function are this method's own and are released once it returns (on a throw too) — so a callback must not retain its ARGUMENTS past the call. A grid the callback returns as-is is the result's data and is kept; a view it returns holds its own reference to the grid buffer, so releasing the rest is safe.

getdata(object)

Returns the data of a as a plain NDArray — the underlying data for a NDMaskedArray, the array itself for an NDArray, or a fresh array for any other array-like/scalar (NumPy's getdata). The mask, if any, is discarded.

public NDArray getdata(object a)

Parameters

a object

A NDMaskedArray, NDArray, C# scalar, or array-like.

Returns

NDArray

The data as an NDArray, never copied: a new VIEW of a masked array's data (NumPy's a._data property — OWNDATA false, writes reach the masked array), a plain array itself, or a new array for a scalar / array-like.

Exceptions

ArgumentNullException

a is null.

getmask(object)

Returns the boolean mask of a, or nomask when it has none (NumPy's getmask). A plain NDArray or scalar has no mask.

public NDArray getmask(object a)

Parameters

a object

A NDMaskedArray, NDArray, or array-like/scalar.

Returns

NDArray

The mask array, or the nomask sentinel.

getmaskarray(object)

Returns the mask of a as a FULL boolean array of its data's shape, allocating an all-False array when there is no mask (NumPy's getmaskarray). Unlike getmask(object) this never returns the 0-D nomask sentinel, so callers can index it positionally.

public NDArray getmaskarray(object a)

Parameters

a object

A NDMaskedArray, NDArray, or array-like/scalar.

Returns

NDArray

A boolean NDArray matching the data shape.

Remarks

Scoped ([NDScoped]): a scalar/array-like operand is materialized only to read its shape, and that materialization is reclaimed; the returned mask is either a's own (owned by its masked array — the caller must NOT dispose it) or a fresh all-False array the caller owns.

greater(object, object, NDMaskedArray, NDArray, DType)

Element-wise greater-than; masked where either operand was.

public NDMaskedArray greater(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a>b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

greater_equal(object, object, NDMaskedArray, NDArray, DType)

Element-wise greater-or-equal; masked where either operand was.

public NDMaskedArray greater_equal(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a>=b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

harden_mask(object)

Makes a's mask HARD in place (NumPy's ma.harden_mask): a later plain-value assignment can no longer unmask a slot. A plain array is wrapped first (NumPy's asanyarray(a).harden_mask()), so it comes back HARD too (inert until the array gains a mask).

public NDMaskedArray harden_mask(object a)

Parameters

a object

Operand (a NDMaskedArray is mutated in place).

Returns

NDMaskedArray

The same masked array, now hard-masked.

hsplit(object, int)

Splits a COLUMN-wise into sections equal parts (NumPy's ma.hsplit); data AND mask are split alike so each part keeps its masked-ness.

public NDMaskedArray[] hsplit(object a, int sections)

Parameters

a object

Operand (rank ≥ 1; splits along axis 1, or axis 0 for a 1-D input).

sections int

Number of equal parts.

Returns

NDMaskedArray[]

The masked-array parts.

Remarks

Scoped by hand: an array-like operand this method had to materialize is reclaimed (each part is a view holding its own reference to that buffer); every part's data and mask leave.

hsplit(object, int[])

Splits a COLUMN-wise at the given cut points (NumPy's ma.hsplit with an index list); data AND mask split alike.

public NDMaskedArray[] hsplit(object a, int[] indices)

Parameters

a object

Operand.

indices int[]

Column cut points.

Returns

NDMaskedArray[]

The masked-array parts.

Remarks

Scoped by hand, as the sections overload.

hstack(params object[])

Stack column-wise / along the second axis (masks alike).

public NDMaskedArray hstack(params object[] tup)

Parameters

tup object[]

Operands.

Returns

NDMaskedArray

The stacked masked array.

Remarks

The loose form (np.ma.hstack(a, b)), kept beside NumPy's hstack(object[], DType, string) as np.hstack keeps its own (the owner's call, API-parity batch 3). A lone object[] binds HERE (C#'s params rule), which is NumPy's sequence anyway.

hstack(object[], DType, string)

Stack column-wise / along the second axis — NumPy's np.ma.hstack(tup, *, dtype=None, casting='same_kind'): np.hstack over the data and over the full masks, with the same keywords.

public NDMaskedArray hstack(object[] tup, DType dtype = null, string casting = "same_kind")

Parameters

tup object[]

The operands (masked arrays, arrays, array-likes).

dtype DType

The result's dtype, or null for the operands' common type. NumPy joins the MASKS in it too (then reads them back as bool), so casting also judges the bool to dtype cast.

casting string

NumPy's casting rule for both joins ("same_kind" by default).

Returns

NDMaskedArray

A new masked array; its mask is always an array (no fill value or hardness is inherited).

Remarks

numpy.ma's _fromnxfunction_seq. Added in API-parity batch 8.

Exceptions

InvalidCastException

The data or the masks do not cast to dtype under casting (NumPy's TypeError text; NumSharp's house mapping).

ValueError

The operands' shapes do not join, or an unknown casting.

hypot(object, object, NDMaskedArray, NDArray, DType)

Euclidean hypotenuse; masked where either operand was.

public NDMaskedArray hypot(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left leg.

b object

Right leg.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of hypot(a, b).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

identity(int, DType, object, bool)

Masked identity matrix (no element masked) — NumPy's np.ma.identity(n, dtype=None, *, fill_value=None, hardmask=False).

public NDMaskedArray identity(int n, DType dtype = null, object fill_value = null, bool hardmask = false)

Parameters

n int

Order.

dtype DType

Element dtype (null ⇒ float64).

fill_value object

The result's fill value (converted to the dtype); null leaves the default.

hardmask bool

True gives the result a hard mask.

Returns

NDMaskedArray

An unmasked masked identity.

Remarks

fill_value and hardmask arrived in API-parity batch 7 (numpy.ma's _convert2ma keywords); like= is the parity plan's exclusion.

Exceptions

TypeError

fill_value cannot be stored in the dtype.

ids(object)

The raw buffer addresses of the data and mask areas (NumPy's ids) — the mask address is 0 when the array is nomask. Diagnostic only; the values are unmanaged pointers into NumSharp's own buffers, not comparable across processes.

public (long data, long mask) ids(object a)

Parameters

a object

Operand.

Returns

(long low, long high)

A tuple of the data-buffer and mask-buffer addresses (mask 0 for nomask).

Remarks

Scoped by hand: an array-like operand this method had to materialize is reclaimed once its address is read — so, exactly as NumPy's ids of a temporary, the reported address names a buffer that no longer exists by the time the caller sees it. Only an array/masked-array operand yields an address that stays meaningful.

in1d(object, object, bool, bool)

Element-wise membership of a 1-D (or flattened) array in another (NumPy's ma.in1d): True where an element of ar1 is also in ar2, MASKED wherever NumPy's sorted comparison reads a masked slot.

public NDMaskedArray in1d(object ar1, object ar2, bool assume_unique = false, bool invert = false)

Parameters

ar1 object

The values to test (flattened; the result takes its shape).

ar2 object

The values to test against.

assume_unique bool

Treat both inputs as already unique (NumPy skips the two unique calls; the answer for non-unique inputs is then undefined, as in NumPy). ar1 is not flattened then: it must be 1-D for the concatenation and the result is 1-D.

invert bool

Return the complement (True where the element is NOT in ar2).

Returns

NDMaskedArray

The masked boolean flags, shaped like ar1 (1-D with assume_unique); a 0-d operand gives a 0-d result, or NDMasked when masked.

Remarks

NumPy's statements: ar1, rev_idx = unique(ar1, return_inverse=True); ar2 = unique(ar2); ar = ma.concatenate((ar1, ar2)); order = ar.argsort(kind='mergesort'); sar = ar[order]; bool_ar = (sar[1:] == sar[:-1]) (!= for invert) through the masked comparison; flag = ma.concatenate((bool_ar, [invert])); indx = order.argsort(kind='mergesort')[:len(ar1)]; and flag[indx][rev_idx]. A value whose sorted neighbour is masked is therefore masked: ma.in1d([3, 5], ma.array([3, 9], mask=[0, 1])) is [True, --]. See the file header for the tie-order divergence. An EMPTY ar1 with a text operand is answered without the text: NumPy formats the numbers into the concatenated text and selects nothing, so the result is the empty, unmasked flag array.

Scoped by hand: the unique values, the concatenation, the permutations and the flags are reclaimed; only the result's data and mask leave.

Exceptions

ArgumentNullException

An operand is null.

TypeError

assume_unique with a 0-d ar1 (len() of unsized object).

ValueError

assume_unique with operands np.concatenate cannot join.

TypeError

A StringDType operand: the argsort's Unsuitable type ... for calculating minimum. (of a masked ar1's inverse unique, of a masked ar2's sort, or of the concatenation), whichever NumPy reaches first.

DTypePromotionError

A StringDType operand beside a class it has no common DType with (the concatenation), when no refusal comes first.

indices(Shape, DType, object, bool)

Masked grid-index array for dimensions (no element masked) — NumPy's np.ma.indices(dimensions, dtype=int, *, fill_value=None, hardmask=False), numpy.ma's _convert2ma wrapper of indices(Shape, DType, bool).

public NDMaskedArray indices(Shape dimensions, DType dtype = null, object fill_value = null, bool hardmask = false)

Parameters

dimensions Shape

The grid's shape: a tuple, an int[] / long[] or a Shape (all convert implicitly; only the sizes are read).

dtype DType

The index dtype; null is int64 (NumPy's int).

fill_value object

The result's fill value, set through the converting setter (numpy.ma's TypeErrors for a value the dtype cannot hold); null leaves the dtype's default.

hardmask bool

True gives the result a hard mask.

Returns

NDMaskedArray

An unmasked masked index grid of shape (len(dimensions), *dimensions).

Remarks

One signature since API-parity batch 8 (2026-11-12): the int[] / long[] forms went (both convert to Shape), and fill_value / hardmask arrived. NumPy's sparse=True is not offered: NumPy's own np.ma.indices(..., sparse=True) fails (AttributeError: 'tuple' object has no attribute 'view').

Exceptions

ValueError

A negative dimension (np.indices' allocation).

TypeError

fill_value cannot be stored in the dtype; an arange of dtype refuses (np.indices).

inner(object, object)

Inner product with masked slots treated as 0 (NumPy's ma.inner).

public NDMaskedArray inner(object a, object b)

Parameters

a object

Left operand.

b object

Right operand.

Returns

NDMaskedArray

The masked inner product (mask dropped — result treats masked as 0).

Remarks

NumPy's statements: fa = filled(a, 0); fb = filled(b, 0); a 0-d one is reshaped to (1,) (so a scalar operand is a one-element vector, not np.inner's scalar product); then np.inner(fa, fb) viewed as a masked array with no mask. Scoped by hand: the zero-filled operand copies only feed the product.

Exceptions

IncorrectShapeException

The last axes differ (shapes (3,) and (1,) not aligned: ...); a 0-d operand counts as one element.

ValueError

A text operand (dot not available for this type).

innerproduct(object, object)

Inner product — alias of inner(object, object) (NumPy's innerproduct).

public NDMaskedArray innerproduct(object a, object b)

Parameters

a object

Left.

b object

Right.

Returns

NDMaskedArray

The masked inner product.

intersect1d(object, object, bool)

The sorted values common to both inputs (NumPy's ma.intersect1d). A masked value is a value: it is common when both inputs hold one, and the result keeps one masked slot then.

public NDMaskedArray intersect1d(object ar1, object ar2, bool assume_unique = false)

Parameters

ar1 object

First operand.

ar2 object

Second operand.

assume_unique bool

Treat both inputs as already unique (NumPy skips the two unique calls and concatenates them as given; the answer for non-unique inputs is then undefined).

Returns

NDMaskedArray

The masked array of common values, in the promoted dtype.

Remarks

NumPy's statements: aux = ma.concatenate((unique(ar1), unique(ar2))) (the operands themselves with assume_unique); aux.sort(); aux[:-1][aux[1:] == aux[:-1]], the masked == selecting by its data. The result's fill value is the concatenation's (none, or the text default the sort materialized).

Scoped by hand: the unique values, the joined copy and the comparison are reclaimed; only the result's data and mask leave.

Exceptions

ArgumentNullException

An operand is null.

ValueError

A StringDType operand whose sort compares a None-like NA (an NA object that is neither a string nor NaN-like): NumPy's Cannot compare null that is not a nan-like value.

TypeError

A StringDType operand: Unsuitable type ... for calculating minimum. (a masked operand's unique, or the joined copy's masked sort).

DTypePromotionError

A StringDType operand beside a class it has no common DType with.

isMA(object)

Alias of isMaskedArray(object) (NumPy's isMA).

public bool isMA(object x)

Parameters

x object

Any object.

Returns

bool

True for a masked array.

isMaskedArray(object)

True iff x is a NDMaskedArray (NumPy's isMaskedArray/is_masked type check). Does not inspect whether any element is actually masked.

public bool isMaskedArray(object x)

Parameters

x object

Any object.

Returns

bool

True for a NDMaskedArray (including the NDMasked constant).

is_mask(object)

True iff a is a boolean NDArray usable as a mask (NumPy's is_mask — a plain check on type/dtype, NOT whether any element is set).

public bool is_mask(object a)

Parameters

a object

Any object.

Returns

bool

True if a is an NDArray of boolean dtype.

is_masked(object)

True iff x has AT LEAST ONE masked element (NumPy's is_masked) — the VALUE predicate, DISTINCT from the isMaskedArray(object) TYPE check. A plain array, a nomask operand, an all-False mask, and every non-masked scalar all return false; only a masked array with a set mask bit (including the NDMasked singleton) returns true.

public bool is_masked(object x)

Parameters

x object

Any object.

Returns

bool

True when some element of x is actually masked.

isarray(object)

Alias of isMaskedArray(object) (NumPy's isarray).

public bool isarray(object x)

Parameters

x object

Any object.

Returns

bool

True for a masked array.

isin(object, object, bool, bool)

Element-wise membership test (NumPy's ma.isin): in1d(object, object, bool, bool) of element, reshaped to element's shape.

public NDMaskedArray isin(object element, object test_elements, bool assume_unique = false, bool invert = false)

Parameters

element object

Values to test.

test_elements object

The values to test against.

assume_unique bool

Treat both inputs as already unique (see in1d(object, object, bool, bool)).

invert bool

Return the complement.

Returns

NDMaskedArray

The masked boolean flags, shaped like element.

Remarks

NumPy's element = ma.asarray(element) (which keeps a masked operand's mask, fill value and hardness), then in1d(element, test_elements, ...).reshape(element.shape). The flags are masked wherever NumPy's sorted comparison reads a masked slot (see in1d(object, object, bool, bool)).

Scoped by hand, as in1d(object, object, bool, bool).

Exceptions

ArgumentNullException

An operand is null.

TypeError

See in1d(object, object, bool, bool).

ValueError

See in1d(object, object, bool, bool); also assume_unique with an N-D element, whose flags cannot take its shape.

TypeError

See in1d(object, object, bool, bool).

left_shift(object, object)

Bit shift left (a << n; NumPy's ma.left_shift(a, n)). Unlike the arithmetic/bitwise ma ops, NumPy's left_shift is a plain function (not a _MaskedBinaryOperation), so a bare shift-count scalar is NOT widened to int64 — the result keeps the value operand's dtype (ma.left_shift(int16, 1) → int16) — the masked slots are shifted from 0 (filled(a, 0)), and the result is a NEW masked array that inherits nothing from a (see Shift(object, object, bool)).

public NDMaskedArray left_shift(object a, object n)

Parameters

a object

Value to shift.

n object

Shift amount: a C# integer (a weak Python int), an array or a masked array. NumPy's name; until API-parity batch 9 it was b, which NumPy refuses (left_shift() got an unexpected keyword argument 'b').

Returns

NDMaskedArray

A masked array of a<<n in a's dtype.

Exceptions

MaskError

n broadcasts the result past a's mask (NumPy's masked_array(d, mask=m) size check).

TypeError

The shift has no loop for the operands (a float, complex or text value: NumPy's "not supported for the input types" text).

less(object, object, NDMaskedArray, NDArray, DType)

Element-wise less-than; masked where either operand was.

public NDMaskedArray less(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a<b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

less_equal(object, object, NDMaskedArray, NDArray, DType)

Element-wise less-or-equal; masked where either operand was.

public NDMaskedArray less_equal(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a<=b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

log(object, NDMaskedArray, NDArray, DType)

Natural log; additionally masks inputs <= 0.

public NDMaskedArray log(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 1.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of log(data) with non-positives masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

log10(object, NDMaskedArray, NDArray, DType)

Base-10 log; additionally masks inputs <= 0.

public NDMaskedArray log10(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 1.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of log10(data) with non-positives masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

log2(object, NDMaskedArray, NDArray, DType)

Base-2 log; additionally masks inputs <= 0.

public NDMaskedArray log2(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 1.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of log2(data) with non-positives masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

logical_and(object, object, NDMaskedArray, NDArray, DType)

Logical AND; masked where either operand was.

public NDMaskedArray logical_and(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a&&b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

logical_not(object, NDMaskedArray, NDArray, DType)

Logical NOT of the data; mask unchanged.

public NDMaskedArray logical_not(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of !data.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

logical_or(object, object, NDMaskedArray, NDArray, DType)

Logical OR; masked where either operand was.

public NDMaskedArray logical_or(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a||b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

logical_xor(object, object, NDMaskedArray, NDArray, DType)

Logical XOR; masked where either operand was.

public NDMaskedArray logical_xor(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a^b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

make_mask(object, bool, bool, DType)

Coerces an array-like to a boolean mask — NumPy's make_mask(m, copy=False, shrink=True, dtype=MaskType): np.array(filled(m, True), copy=None if not copy else True, dtype=bool). Any non-zero number and any non-empty string becomes True, and a masked array reads True at its masked slots. With shrink (default) an all-False result collapses to nomask — the standard "no mask needed" reduction — otherwise a full all-False array is returned.

public NDArray make_mask(object m, bool copy = false, bool shrink = true, DType dtype = null)

Parameters

m object

Array-like to coerce; null or nomask is nomask.

copy bool

NumPy's copy. False (the default) is NumPy's copy=None: a BOOLEAN array is handed back ITSELF — an unmasked masked array's data as a view of it (NumPy's filled returns self._data, a view) — so writing the result writes m; anything else is converted into a new array either way. True always returns a new array.

shrink bool

Collapse an all-False mask to nomask (default true).

dtype DType

NumPy's dtype, read through make_mask_descr: a dtype without fields — every NumSharp dtype — gives the bool mask type, so the result is bool whatever is passed.

Returns

NDArray

A boolean mask array, or nomask when it shrinks to empty.

Remarks

copy / dtype and NumPy's parameter order arrived in API-parity batch 8: before, a positional false in NumPy's copy slot was C#'s shrink, and a boolean input was always copied. Scoped ([NDScoped]): the operand's materialization and a coerced mask that shrinks to nomask are reclaimed. The shared nomask sentinel must never be disposed by the caller, nor a boolean m handed back as the result.

make_mask_descr(DType)

The dtype of the mask for a data dtype (NumPy's make_mask_descr) — ALWAYS boolean here. In NumPy this recurses over a STRUCTURED dtype to build a matching boolean-field mask descriptor; NumSharp has no structured dtypes, so every data dtype maps to the single scalar boolean mask descriptor NumPy returns for a non-structured dtype (dtype('bool')).

public DType make_mask_descr(DType dtype)

Parameters

dtype DType

The data dtype (a Type, NPTypeCode, dtype string or DType all convert in). Any invalid spelling throws at the DType boundary, as NumPy raises for a bad dtype.

Returns

DType

The boolean DType (bool).

make_mask_none(Shape, DType)

Builds an all-False boolean mask of the given shape — NumPy's make_mask_none(newshape, dtype=None), the "nothing masked yet, full array" starting mask.

public NDArray make_mask_none(Shape newshape, DType dtype = null)

Parameters

newshape Shape

The mask shape (an int, a long, a tuple or a Shape converts).

dtype DType

NumPy's dtype, read through make_mask_descr: a dtype without fields — every NumSharp dtype — gives the bool mask type. Added in API-parity batch 8.

Returns

NDArray

A new all-False boolean NDArray.

Exceptions

ValueError

newshape has a negative dimension (negative dimensions are not allowed).

mask_cols(object, int?)

Masks the ENTIRE columns of a 2-D array that contain any masked element (NumPy's mask_cols(a, axis=np._NoValue), which is mask_rowcols(a, 1)).

public NDMaskedArray mask_cols(object a, int? axis = null)

Parameters

a object

2-D operand.

axis int?

NumPy's deprecated axis, IGNORED as NumPy ignores it (see mask_rows(object, int?)): any value, null included, masks the columns.

Returns

NDMaskedArray

The column-masked array (over the operand's data, with a new mask).

Remarks

API-parity batch 11: axis was missing, so a ported call that passes it did not compile.

Exceptions

NotImplementedError

a is not 2-D (NumPy's mask_rowcols works for 2D arrays only.).

mask_or(object, object, bool, bool)

Combines two masks with logical-OR (NumPy's mask_or): a nomask / false operand contributes nothing (the other is make_mask(object, bool, bool, DType)'d alone), two operands of DIFFERENT dtypes are refused, and — with shrink (default) — an all-False OR collapses back to nomask.

public NDArray mask_or(object m1, object m2, bool copy = false, bool shrink = true)

Parameters

m1 object

First mask (any array-like), or null/nomask/false.

m2 object

Second mask (any array-like), or null/nomask/false.

copy bool

NumPy's copy, passed to make_mask(object, bool, bool, DType) when one operand is nomask: false (the default) hands a boolean other operand back ITSELF, true copies it. The OR of two operands is a new array either way, and one boolean mask passed twice is returned itself whatever copy says (NumPy's m1 is m2 shortcut). Added in API-parity batch 8, before shrink as in NumPy.

shrink bool

Collapse an all-False result to nomask (default true).

Returns

NDArray

The OR of the present masks, or nomask when neither contributes (or it shrinks).

Remarks

NumPy's statements, in order: m1 is nomask or m1 is False → make_mask(m2) (no dtype check: a text m2 is converted by its truth values), likewise for m2; one boolean mask passed twice → itself; then dtype1 != dtype2 → the ValueError; then make_mask(logical_or(m1, m2)). Only the Python literal False and the nomask object are "no mask": a 0-d False ARRAY is compared like any operand (Incompatible dtypes 'bool'<>'<U2'). C# null stands for nomask (NumSharp's masked arrays hold a null mask for it).

A NDMaskedArray operand is an ARRAY to NumPy, not a mask: its DATA joins the OR, and its masked slots read True (the ufunc's result is masked there, and make_mask fills masked slots with True).

Scoped ([NDScoped]): operands coerced to boolean and an OR that shrinks away are reclaimed. When one boolean mask is passed twice, or beside nomask without copy, the result IS that mask (NumPy returns it), so the caller must not dispose — or write — a result it did not create. Before API-parity batch 8 the nomask case always copied; callers that store the result as a mask of their own pass copy: true, as NumPy's do.

Exceptions

ValueError

The two operands' dtypes differ (Incompatible dtypes '<U2'<>'bool'; a C# scalar or an object[] list has no dtype and prints 'None'), or they do not broadcast.

AttributeError

Both operands are dtype-less scalars/lists: NumPy then reads None.names.

mask_rowcols(object, int?)

Masks whole rows and/or columns of a 2-D array that contain any masked element (NumPy's mask_rowcols): axis null masks BOTH, 0 masks rows, 1/-1 masks columns. The row/column sets are computed from the ORIGINAL mask (so masking a row does not spill into "every column now has a masked element") — the two are OR'd onto a fresh mask over the shared data.

public NDMaskedArray mask_rowcols(object a, int? axis = null)

Parameters

a object

2-D operand.

axis int?

null (rows AND cols), 0 (rows), or 1/-1 (cols).

Returns

NDMaskedArray

The row/column-masked array (an all-unmasked input is returned unchanged).

Remarks

Scoped by hand: the working mask copy, the per-axis reductions, their broadcasts and the superseded OR steps are reclaimed (on the rank throw too); only the result's data and final mask leave.

Exceptions

NotImplementedError

a is not 2-D (NumPy's mask_rowcols works for 2D arrays only.).

mask_rows(object, int?)

Masks the ENTIRE rows of a 2-D array that contain any masked element (NumPy's mask_rows(a, axis=np._NoValue), which is mask_rowcols(a, 0)).

public NDMaskedArray mask_rows(object a, int? axis = null)

Parameters

a object

2-D operand.

axis int?

NumPy's deprecated axis, IGNORED as NumPy ignores it (NumPy 1.18 deprecated passing it - "The axis argument has always been ignored, in future passing it will raise TypeError" - and NumSharp has no warnings): any value, null included, masks the rows.

Returns

NDMaskedArray

The row-masked array (over the operand's data, with a new mask).

Remarks

API-parity batch 11: axis was missing, so a ported call that passes it did not compile.

Exceptions

NotImplementedError

a is not 2-D: NumPy reports it from mask_rowcols (mask_rowcols works for 2D arrays only.).

masked_all(Shape, DType)

An empty masked array of the given shape with EVERY element masked (NumPy's masked_all) — the standard "fill me in" accumulator.

public NDMaskedArray masked_all(Shape shape, DType dtype = null)

Parameters

shape Shape

Result shape.

dtype DType

Element dtype (null ⇒ float64).

Returns

NDMaskedArray

A fully-masked array.

masked_all_like(object)

A fully-masked array shaped and typed like a (NumPy's masked_all_like, np.empty_like(arr).view(MaskedArray) with an all-True mask): a masked prototype also lends its fill value and hard-mask flag.

public NDMaskedArray masked_all_like(object a)

Parameters

a object

Prototype array-like.

Returns

NDMaskedArray

A fully-masked array (uninitialized data; a U one is zero-filled, as NumPy's is).

masked_array(object, object, DType, bool, int, object, bool, bool?, bool, char?)

The masked-array constructor — NumPy's np.ma.masked_array(data=None, mask=nomask, dtype=None, copy=False, subok=True, ndmin=0, fill_value=None, keep_mask=True, hard_mask=None, shrink=True, order=None) (MaskedArray.new), in NumPy's parameter ORDER: the mask second, the dtype third.

public NDMaskedArray masked_array(object data, object mask = null, DType dtype = null, bool copy = false, int ndmin = 0, object fill_value = null, bool keep_mask = true, bool? hard_mask = null, bool shrink = true, char? order = null)

Parameters

data object

Data array-like (a NDMaskedArray's own mask, fill value and hard-mask flag ride along). Required: NumPy's masked_array() is an object-dtype None, which NumSharp has no dtype for.

mask object

Optional mask array-like; null/omitted (or nomask) ⇒ no explicit mask. A C# true / false is NumPy's mask=True / mask=False: a FULL array of that value.

dtype DType

Optional dtype: an array (or masked array) is CAST to it; a C# array-like is converted INTO it (NumPy's np.array(data, dtype=dtype): new object[] { "ab", null } with StringDType(na_object: null) holds an NA element, numbers with StringDType(coerce: false) are refused).

copy bool

When true, copies the data (NumPy's copy=, in order's layout — the data's own for the default), the inherited mask and a given mask array; default false aliases them — a given boolean mask array of the data's shape is ADOPTED (the masked array then writes into it, as NumPy's does, and getmask(object) returns it), the data's own mask is shared through a view.

ndmin int

The minimum rank of the result: leading length-1 axes are prepended to the data (and its mask) as NumPy's np.array(..., ndmin=) does; 0 (the default) or less adds none.

fill_value object

Optional default fill value for filled(object); null inherits data's. Checked against the dtype (CheckFillValue(object, DType)).

keep_mask bool

With a given mask, true (default) ORs it with data's own mask and false replaces that mask; without one, false erases the data's mask.

hard_mask bool?

Hard/soft mask, or null (the default — NumPy's MaskedArray(hard_mask=None)) to inherit data's hardness; array(object, DType, bool, char?, object, object, bool, bool?, bool, int), NumPy's function, defaults to soft.

shrink bool

With no mask and keep_mask false: true (default) leaves no mask (nomask), false a full all-False mask.

order char?

The data's memory layout, NumPy's np.array(..., order=): null / 'K' keeps it, 'A' keeps a C- or F-contiguous one, 'C' / 'F' lay it out so (copying only when needed).

Returns

NDMaskedArray

A new NDMaskedArray.

Remarks

NumPy's parameter order, ndmin and order arrived in API-parity batch 8 (the third positional was the fill value, NumPy's is the dtype). subok is the parity plan's exclusion. See array(object, DType, bool, char?, object, object, bool, bool?, bool, int) for the mask rules.

Exceptions

MaskError

The mask is neither the data's shape, nor one element, nor the data's size (Mask and data not compatible: data size is 3, mask size is 2.).

TypeError

A string fill_value for numeric data, or a fill numpy.ma cannot convert to the data's dtype (see CheckFillValue(object, DType)).

ValueError

An order letter NumPy does not have (checked first, as np.array's parser does); ndmin past 64 (ndmin must be <= ndmax (64)); a C# array-like holding numbers with a StringDType(coerce: false) dtype, or text a numeric dtype cannot parse.

masked_equal(object, object, bool)

Masks where a == value (NumPy's masked_equal), and makes value the result's fill value.

public NDMaskedArray masked_equal(object a, object value, bool copy = true)

Parameters

a object

Data.

value object

Value to mask (a scalar or an array-like).

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array (fill_value = value, checked against the dtype).

Remarks

NumPy's statements: output = masked_where(equal(x, value), x, copy=copy); output.fill_value = value, with numpy.ma's masked equal: a bare scalar becomes a STRONG default-width array (getdata(1.5) is float64), so the comparison of float32 data runs in float64. Scoped by hand: the comparison only feeds masked_where's condition.

Exceptions

TypeError

NumPy's comparison has no loop for the operands (text against a number: (<class 'numpy.dtypes.StrDType'>, <class 'numpy.dtypes.Float64DType'>)), or the fill check refuses a string value for numeric data.

masked_greater(object, object, bool)

Masks where a > value (NumPy's masked_greater).

public NDMaskedArray masked_greater(object a, object value, bool copy = true)

Parameters

a object

Data.

value object

Threshold.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array.

Remarks

NumPy's masked_where(greater(x, value), x, copy=copy) with numpy.ma's masked comparison. Scoped by hand: the comparison only feeds masked_where's condition.

Exceptions

TypeError

NumPy's comparison has no loop for the operands (see masked_equal(object, object, bool)).

masked_greater_equal(object, object, bool)

Masks where a >= value (NumPy's masked_greater_equal).

public NDMaskedArray masked_greater_equal(object a, object value, bool copy = true)

Parameters

a object

Data.

value object

Threshold.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array.

Remarks

NumPy's masked_where(greater_equal(x, value), x, copy=copy) with numpy.ma's masked comparison. Scoped by hand: the comparison only feeds masked_where's condition.

Exceptions

TypeError

NumPy's comparison has no loop for the operands (see masked_equal(object, object, bool)).

masked_inside(object, object, object, bool)

Masks the CLOSED interval where v1 <= a <= v2 (bounds swapped if v2 < v1), NumPy's masked_inside.

public NDMaskedArray masked_inside(object a, object v1, object v2, bool copy = true)

Parameters

a object

Data.

v1 object

One bound: a number, a string / byte[] for text data, or an array-like.

v2 object

Other bound.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array.

Remarks

NumPy's statements: if v2 < v1: (v1, v2) = (v2, v1) (a Python comparison: a NaN bound never swaps), xf = filled(x), condition = (xf >= v1) & (xf <= v2) with the RAW bounds — a C# number is a weak Python scalar there, so float16/float32 data compare at their own width — then masked_where.

Scoped by hand: the two bound comparisons and their conjunction only feed masked_where.

Exceptions

TypeError

Python cannot order the bounds ('<' not supported between instances of 'str' and 'float'), or NumPy's comparison has no loop for the data and a bound (text data against a C# number names the Python scalar's class: (<class 'numpy.dtypes.StrDType'>, <class 'numpy.dtypes._PyFloatDType'>), whatever the data's size).

ValueError

Array bounds whose comparison has more than one element (Python's truth test of v2 < v1).

masked_invalid(object, bool)

Masks non-finite elements (NaN/±inf) — NumPy's masked_invalid. For exact dtypes nothing is masked (every value is finite), but the result always carries a mask ARRAY.

public NDMaskedArray masked_invalid(object a, bool copy = true)

Parameters

a object

Data.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array; its mask is an array even when nothing is masked (NumPy's gh-22842 rule).

Remarks

NumPy's statements: res = masked_where(~(np.isfinite(a)), a, copy=copy), then if res._mask is nomask: res._mask = make_mask_none(res.shape). Scoped by hand: the non-finite predicate (or its all-False stand-in) only feeds masked_where.

Exceptions

TypeError

Text data: NumPy's np.isfinite has no loop for it (ufunc 'isfinite' not supported for the input types, …), whatever the size.

masked_less(object, object, bool)

Masks where a < value (NumPy's masked_less).

public NDMaskedArray masked_less(object a, object value, bool copy = true)

Parameters

a object

Data.

value object

Threshold.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array.

Remarks

NumPy's masked_where(less(x, value), x, copy=copy) with numpy.ma's masked comparison. Scoped by hand: the comparison only feeds masked_where's condition.

Exceptions

TypeError

NumPy's comparison has no loop for the operands (see masked_equal(object, object, bool); the text names 'less').

masked_less_equal(object, object, bool)

Masks where a <= value (NumPy's masked_less_equal).

public NDMaskedArray masked_less_equal(object a, object value, bool copy = true)

Parameters

a object

Data.

value object

Threshold.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array.

Remarks

NumPy's masked_where(less_equal(x, value), x, copy=copy) with numpy.ma's masked comparison. Scoped by hand: the comparison only feeds masked_where's condition.

Exceptions

TypeError

NumPy's comparison has no loop for the operands (see masked_equal(object, object, bool)).

masked_not_equal(object, object, bool)

Masks where a != value (NumPy's masked_not_equal).

public NDMaskedArray masked_not_equal(object a, object value, bool copy = true)

Parameters

a object

Data.

value object

Value kept unmasked.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array.

Remarks

NumPy's masked_where(not_equal(x, value), x, copy=copy) with numpy.ma's masked comparison. Scoped by hand: the comparison only feeds masked_where's condition.

Exceptions

TypeError

NumPy's comparison has no loop for the operands (see masked_equal(object, object, bool)).

masked_object(object, object, bool, bool)

Masks elements exactly equal to value (NumPy's masked_object), and makes value the result's fill value.

public NDMaskedArray masked_object(object a, object value, bool copy = true, bool shrink = true)

Parameters

a object

Data.

value object

Value to mask (compared as a raw Python value).

copy bool

Copy the data.

shrink bool

Shrink the comparison's mask to no mask when nothing matched (NumPy's shrink=True).

Returns

NDMaskedArray

The masked array (fill_value = value, checked against the dtype).

Remarks

Unlike masked_equal(object, object, bool), NumPy compares with umath.equal(x._data, value) — the RAW value, a weak Python scalar — so float16/float32 data compare at their own width (masked_object(float32 [1.1], 1.1) masks the element, masked_equal does not). Then mask_or(x._mask, make_mask(condition, shrink=shrink), shrink=shrink) and masked_array(x, mask=mask, copy=copy, fill_value=value).

NumPy 2.5 passes shrink to mask_or too: with shrink=False an all-False (or empty) condition stays a full mask, where NumPy 2.4's mask_or shrank it back to nomask with its own default.

Scoped by hand: the comparison and the combined mask only feed the constructor.

Exceptions

TypeError

NumPy's equal has no loop for the data and the value (text data with a C# number names the Python scalar's class, _PyFloatDType / _PyLongDType; a bool names BoolDType), or the fill check refuses a string value for numeric data.

masked_outside(object, object, object, bool)

Masks OUTSIDE the closed interval, where a < v1 || a > v2 (bounds swapped if v2 < v1), NumPy's masked_outside.

public NDMaskedArray masked_outside(object a, object v1, object v2, bool copy = true)

Parameters

a object

Data.

v1 object

One bound (see masked_inside(object, object, object, bool)).

v2 object

Other bound.

copy bool

Copy the data.

Returns

NDMaskedArray

The masked array.

Remarks

NumPy's statements: the same swap, xf = filled(x), condition = (xf < v1) | (xf > v2), then masked_where. A NaN bound is not swapped away: masked_outside(x, nan, 2.0) masks x > 2.

Scoped by hand: the two bound comparisons and their disjunction only feed masked_where.

Exceptions

TypeError

See masked_inside(object, object, object, bool); the comparison refusal names 'less', the first comparison NumPy evaluates here.

ValueError

See masked_inside(object, object, object, bool).

masked_values(object, object, double, double, bool, bool)

Masks elements approximately equal to value (NumPy's masked_values: isclose with the given tolerances for float data, exact equality otherwise); the result's fill value becomes value.

public NDMaskedArray masked_values(object a, object value, double rtol = 1E-05, double atol = 1E-08, bool copy = true, bool shrink = true)

Parameters

a object

Data.

value object

Value to mask around: a number, a string / byte[] for text data, or an array-like.

rtol double

Relative tolerance.

atol double

Absolute tolerance.

copy bool

Copy the data.

shrink bool

Collapse an all-False mask to no mask (NumPy's shrink=True).

Returns

NDMaskedArray

The masked array (fill_value = value, checked against the dtype).

Remarks

NumPy's statements: xnew = filled(x, value), the mask from isclose (float) or umath.equal(xnew, value), masked_array(xnew, mask=mask, copy=copy, fill_value=value), then shrink_mask(). For text data and a C# number NumPy formats the number into the masked slots first, which cannot fail and keeps the dtype, so the comparison's TypeError is its answer: it is raised up front.

Scoped by hand: the fill-substituted copy (when a further copy is taken), the comparison scalars and a mask that shrinks away are reclaimed; only the result's data and mask leave.

Exceptions

TypeError

Text data with a C# number (NumPy's equal has no loop: the text names the Python scalar's class, _PyFloatDType / _PyLongDType), or a masked numeric array with a string value (the fill check).

DTypePromotionError

Float data with a text value (np.isclose cannot promote it).

masked_where(object, object, bool)

Masks a wherever condition is True, OR'ing onto any existing mask (NumPy's masked_where — the primitive the rest of this family builds on).

public NDMaskedArray masked_where(object condition, object a, bool copy = true)

Parameters

condition object

Array-like of truth values (make_mask(object, bool, bool, DType): non-zero numbers, non-empty strings; a masked condition reads True at its masked slots); True ⇒ mask that element. A 0-d condition applies to every element.

a object

Data array-like.

copy bool

Copy the data (default true). False makes the result a VIEW of a and masks a masked a IN PLACE, as NumPy's does: the combined mask is written into its mask buffer (the result shares it), or — when it had no mask — it adopts the result's new mask.

Returns

NDMaskedArray

A masked array of a's data with the new mask; it keeps a masked a's fill value and hardness.

Remarks

NumPy's statements: cond = make_mask(condition, shrink=False), then if cshape and cshape != ashape the IndexError (a condition is never broadcast, only a 0-d one fills the array), then mask_or(cond, a._mask) for a masked input and result.mask = _shrink_mask(cond). The shape test runs first here: NumPy's conversion before it cannot fail, so the shapes decide the error even for a text condition.

The mask's FORM follows NumPy's: an all-False condition over an input without a mask leaves no mask (mask=False in the repr), while an input that already had a mask array keeps an array (the setter writes the condition into it).

Scoped by hand: the boolean-coerced condition copy (when an existing mask is OR'd onto it) and any materialized operand are reclaimed; only the result's data and mask leave.

Exceptions

IndexError

A condition with dimensions whose shape is not a's (Inconsistent shape between the condition and the input (got (2,) and (3,))).

max(object, int, NDMaskedArray, object, bool)

public NDMaskedArray max(object a, int axis, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The value the masked slots take before the reduction, or null for maximum_fill_value(object).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked maximum, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

max(object, int[], NDMaskedArray, object, bool)

The owner's kept int[] form of max(object, NDAxis?, NDMaskedArray, object, bool).

public NDMaskedArray max(object a, int[] axis, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The value the masked slots take before the reduction, or null for maximum_fill_value(object).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked maximum, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

max(object, NDAxis?, NDMaskedArray, object, bool)

Maximum over the unmasked elements — NumPy's np.ma.max(obj, axis=None, out=None, fill_value=None, keepdims): the masked slots filled with the dtype's smallest value (or fill_value).

public NDMaskedArray max(object a, NDAxis? axis = null, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The value the masked slots take before the reduction, or null for maximum_fill_value(object).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked maximum, or out.

Remarks

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

maximum(object, object)

Element-wise maximum of two operands (mask = OR): NumPy's ma.maximum(a, b), the _extrema_operation call where(greater(a, b), a, b).

public NDMaskedArray maximum(object a, object b)

Parameters

a object

First operand.

b object

Second operand (required, as in NumPy 2.x, whose call(self, a, b) has no default: the reduction is max(object,int?,object,bool)).

Returns

NDMaskedArray

The element-wise masked maximum.

Exceptions

TypeError

The operands have no comparison loop (text against numbers): NumPy's ufunc 'greater' did not contain a loop ..., raised by greater(a, b) in that operand order.

maximum_fill_value(object)

The value NumPy fills masked elements with for a MAXIMUM/argmax (the dtype's SMALLEST value): -inf for float/complex, MinValue for integers/decimal, the integer 0 for bool, and null for a text dtype. NumPy's maximum_fill_value.

public object maximum_fill_value(object a)

Parameters

a object

A DType, or an array-like whose dtype selects the value (NumPy's _get_dtype_of).

Returns

object

A boxed scalar castable into the dtype, or null for a text dtype.

Remarks

See minimum_fill_value(object): NumPy's max_filler holds None for text and the Python int 0 for bool.

Exceptions

TypeError

A NEP 55 StringDType operand or dtype: Unsuitable type StringDType() for calculating maximum. (see ThrowIfUnsuitableExtremum(DType, string)).

mean(object, int, DType, NDMaskedArray, bool)

public NDMaskedArray mean(object a, int axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked mean, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

mean(object, int[], DType, NDMaskedArray, bool)

The owner's kept int[] form of mean(object, NDAxis?, DType, NDMaskedArray, bool).

public NDMaskedArray mean(object a, int[] axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked mean, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

mean(object, NDAxis?, DType, NDMaskedArray, bool)

Mean over the unmasked elements: NumPy's MaskedArray.mean, statement for statement. With a mask (even an all-False one) it is self.sum(axis, dtype) * 1. / self.count(axis) in masked arithmetic, so a slice whose mean is not finite (an unmasked inf or NaN in it) is MASKED, and a fully masked slice is masked. Without a mask it is numpy's _mean run on a masked array: an inf mean (or a mean of at least count / tiny) comes back masked with data 1.0.

public NDMaskedArray mean(object a, NDAxis? axis = null, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

dtype DType

NumPy's dtype=, the sum's loop. When null an integer, bool or char input sums in float64 and a float16 input in float32 with the mean cast back to float16; every other input sums in its own dtype.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked mean: the NDMasked singleton for a masked 0-d result, an unmasked 0-d array for a scalar, otherwise an array with the mask NumPy gives it (null for nomask) — or out. With a mask the dtype is float64 for an integer, bool, char, float32 or float64 input (NumPy's * 1. multiplies by a STRONG float64), float16 for float16, complex128 for complex128; without one it is numpy's _mean dtype (float32 stays float32).

Remarks

Scoped by hand (a masked-array return): the filled copy, the sums, counts and quotients are reclaimed; only the result's data and mask leave. With out: out.flat = result (a masked result writes its data, 0), and a masked out's mask becomes getmask(result) flat (a mask created if it had none). Tuple axis, out and NumPy's parameter order since API-parity batch 8.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

median(object, int, NDMaskedArray, bool, bool)

median(object, NDAxis?, NDMaskedArray, bool, bool) with the axis as one int: the overload a C# integer binds (its identity conversion beats NDAxis' implicit one), forwarding to the NDAxis form.

public NDMaskedArray median(object a, int axis, NDMaskedArray @out = null, bool overwrite_input = false, bool keepdims = false)

Parameters

a object

Data: a masked array, or a plain array / array-like.

axis int

The axis (a negative value counts from the end).

out NDMaskedArray

NumPy's out (see the NDAxis form).

overwrite_input bool

NumPy's overwrite_input (see the NDAxis form).

keepdims bool

Keep the reduced axis as size 1.

Returns

NDMaskedArray

The masked median, or out (see the NDAxis form).

Exceptions

AxisError

axis is outside the operand.

ValueError

out has another shape than the result.

TypeError

A plain out for an inexact masked operand, or a text operand (see the NDAxis form).

median(object, int[], NDMaskedArray, bool, bool)

median(object, NDAxis?, NDMaskedArray, bool, bool) with the axes as an int[]: the overload an int[] binds; a null array is NumPy's None, any other array NumPy's tuple.

public NDMaskedArray median(object a, int[] axis, NDMaskedArray @out = null, bool overwrite_input = false, bool keepdims = false)

Parameters

a object

Data: a masked array, or a plain array / array-like.

axis int[]

The axes as NumPy's tuple, or null for None.

out NDMaskedArray

NumPy's out (see the NDAxis form).

overwrite_input bool

NumPy's overwrite_input (see the NDAxis form).

keepdims bool

Keep the reduced axes as size 1.

Returns

NDMaskedArray

The masked median, or out (see the NDAxis form).

Exceptions

AxisError

An axis is outside the operand.

ValueError

A repeated axis, or out has another shape than the result.

TypeError

A plain out for an inexact masked operand, or a text operand (see the NDAxis form).

median(object, NDAxis?, NDMaskedArray, bool, bool)

Median over unmasked elements — NumPy's ma.median(a, axis=None, out=None, overwrite_input=False, keepdims=False). Supports the flat case, the unmasked-axis case, a masked array with an explicit axis (the per-slice masked median — the axis is masked-sorted, then the low/high middle of each slice's unmasked count is averaged) and several axes at once (merged into one, as NumPy's _ureduce does).

public NDMaskedArray median(object a, NDAxis? axis = null, NDMaskedArray @out = null, bool overwrite_input = false, bool keepdims = false)

Parameters

a object

Data: a masked array, or a plain array / array-like (NumPy's np.median then answers).

axis NDAxis?

The axis, a tuple of axes ((0, 2), new[] { 0, 2 }), or null for the flattened array.

out NDMaskedArray

NumPy's out, of the result's shape (the keepdims shape with keepdims): the median is written into it and it is returned. A masked out takes the result's mask as an array (the reduction's outmask.flat = newmask), except where NumPy's flattened path halves an even count through a ufunc into the out, whose wrap leaves nomask; with keepdims NumPy writes through a view of the out, so a mask-less out stays mask-less. A plain out (an NDArray converts) receives the data, but NumPy refuses it for an inexact operand reduced along an axis (see the exceptions). Added in API-parity batch 9.

overwrite_input bool

NumPy's overwrite_input: true lets the call sort a masked operand IN PLACE (the flattened array, or along axis): its data and mask are reordered, masked slots last. The median is the same. A flattened operand that is not contiguous is sorted in a copy (NumPy's ravel), and several axes are merged into a reshaped array first, which is the operand only when the reshape is a view. Added in API-parity batch 9.

keepdims bool

Keep the reduced axes as size-1 (NumPy 2.0 keepdims).

Returns

NDMaskedArray

The masked median (a slice with no unmasked element is NDMasked; an unmasked NaN in a slice makes that slice's median NaN, matching NumPy), or out. NumPy returns a scalar for a full reduction and a plain array for a full reduction with keepdims; NumSharp's static type returns a mask-less masked array.

Remarks

NumPy's statements: a plain operand is np.median(getdata(a), axis, out, overwrite_input, keepdims), wrapped by masked_array(m, copy=False) when N-d; a masked one runs _ureduce(a, func=_median, keepdims, axis, out, overwrite_input) — the axes normalized (normalize_axis_tuple), several merged (the kept axes swapped to the front, the rest reshaped into one last axis), _median run, the reduced axes re-inserted for keepdims, and out returned when given. _median sorts with fill_value=np.inf for an inexact dtype (in place for overwrite_input), then averages the middles; a 1-D sorted array takes mid.sum(out=out) and, for an even count, np.true_divide(s, 2., out=out).

One signature (with your int / int[] forms) since API-parity batch 9: the positional order is NumPy's, so np.ma.median(m, 1, true) (true is NumPy's out) no longer compiles; write keepdims: true.

Scoped by hand: the compressed copy, the masked sort, the merged reshape, the middle-index arithmetic, the gathered middles and the NaN probe (see MedianAxisMasked(NDMaskedArray, int, bool)) are all reclaimed here; only the median and its mask leave (an out's arrays are the caller's; a mask created for it is detached).

Exceptions

AxisError

An axis is outside the operand.

ValueError

The same axis twice (repeated axis), or out has another shape than the result.

TypeError

A plain out for an inexact masked operand reduced along an axis: NumPy's np.true_divide(s.data, 2., out=s.data) reads a plain array's .data, a memoryview (return arrays must be of ArrayType). A text operand: NumPy's _median averages the middles with mean, whose add.reduce has no string loop (the resolved dtypes are not compatible with add.reduce); a StringDType operand with a mask (an all-False one included) stops earlier, at the masked sort's Unsuitable type ... for calculating minimum.

InvalidOperationException

Never for a caller's input: the mean of a masked text median returned instead of refusing (a wiring error inside NumSharp).

min(object, int, NDMaskedArray, object, bool)

public NDMaskedArray min(object a, int axis, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The value the masked slots take before the reduction, or null for minimum_fill_value(object).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked minimum, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

min(object, int[], NDMaskedArray, object, bool)

The owner's kept int[] form of min(object, NDAxis?, NDMaskedArray, object, bool).

public NDMaskedArray min(object a, int[] axis, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The value the masked slots take before the reduction, or null for minimum_fill_value(object).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked minimum, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

min(object, NDAxis?, NDMaskedArray, object, bool)

Minimum over the unmasked elements — NumPy's np.ma.min(obj, axis=None, out=None, fill_value=None, keepdims): the masked slots filled with the dtype's largest value (or fill_value) so they are never selected; a result cell is masked exactly where its whole slice was.

public NDMaskedArray min(object a, NDAxis? axis = null, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The value the masked slots take before the reduction, or null for minimum_fill_value(object).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked minimum, or out.

Remarks

Tuple axis, out and NumPy's parameter order (out before fill_value, keepdims last) since API-parity batch 8. A plain out refuses an integer or bool dtype (MaskError, after the data was written) and takes NaN at the masked cells; a masked out takes the mask. The first parameter keeps the name a (NumPy's obj is among batch 1's deferred numpy.ma renames).

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

minimum(object, object)

Element-wise minimum of two operands (mask = OR): NumPy's ma.minimum(a, b), the _extrema_operation call where(less(a, b), a, b).

public NDMaskedArray minimum(object a, object b)

Parameters

a object

First operand.

b object

Second operand (required, as in NumPy 2.x; the reduction is min(object,int?,object,bool)).

Returns

NDMaskedArray

The element-wise masked minimum.

Exceptions

TypeError

The operands have no comparison loop: NumPy's ufunc 'less' did not contain a loop ..., naming the operands in call order.

minimum_fill_value(object)

The value NumPy fills masked elements with for a MINIMUM/argmin (the dtype's LARGEST value, so a masked slot can never win a min): +inf for float/complex, MaxValue for integers/decimal/char, the integer 1 for bool, and null for a text dtype. NumPy's minimum_fill_value.

public object minimum_fill_value(object a)

Parameters

a object

A DType, or an array-like whose dtype selects the value (NumPy's _get_dtype_of).

Returns

object

A boxed scalar castable into the dtype, or null for a text dtype.

Remarks

NumPy's min_filler table holds None for str_/bytes_ (no largest text), and its reductions then fill with the array's own fill value (self.filled(None)); the bool entry is the Python int 1, which is why the result is a long rather than true.

Exceptions

TypeError

A NEP 55 StringDType operand or dtype: Unsuitable type StringDType() for calculating minimum. (see ThrowIfUnsuitableExtremum(DType, string)).

mod(object, object, NDMaskedArray, NDArray, DType)

public NDMaskedArray mod(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Numerator.

b object

Denominator.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the zero divisors, whose slots take 1 and get no data back (a plain out gets the dividend). An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a%b with unsafe divides masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

moveaxis(object, int, int)

Move an axis (mask moved alike).

public NDMaskedArray moveaxis(object a, int source, int destination)

Parameters

a object

Operand.

source int

Source axis.

destination int

Destination axis.

Returns

NDMaskedArray

The masked array.

multiply(object, object, NDMaskedArray, NDArray, DType)

Element-wise product; masked where either operand was.

public NDMaskedArray multiply(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a*b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

ndenumerate(object, bool)

Enumerates (index, value) pairs in C-order — NumPy's ma.ndenumerate(a, compressed=True). By default the masked positions are SKIPPED (unlike ndenumerate(NDArray), which yields every element); with compressed false they yield (index, np.ma.masked) instead, so the walk covers every position. Each index is a fresh long[] coordinate.

public IEnumerable<(long[] index, object value)> ndenumerate(object a, bool compressed = true)

Parameters

a object

Operand: a masked array, a plain array or an array-like (a plain operand has no masked position, so both settings yield every element).

compressed bool

NumPy's compressed: true (the default) skips the masked positions; false yields them with the NDMasked constant as the value (added in API-parity batch 9).

Returns

IEnumerable<(long[] index, object value)>

The (index, value) pairs: the unmasked ones, or every one with NDMasked at the masked positions.

Remarks

An ITERATOR, so it cannot hold an NDScope (a scope is per-thread and would straddle every yield — the consumer's own scopes would interleave with it). It releases its two own arrays explicitly instead: the raveled mask (a copy when the mask is not contiguous) as soon as it has been read into the managed flag array, and an array-like operand AsData(object) had to materialize when the walk ends — including when the consumer stops early and disposes the enumerator. An array or masked-array operand is the caller's and is never released.

NumPy's statements: for it, mask in zip(np.ndenumerate(a), getmaskarray(a).flat): if not mask: yield it; elif not compressed: yield it[0], masked.

ndim(object)

Number of dimensions of the data (NumPy's module-level ma.ndim).

public int ndim(object a)

Parameters

a object

Array-like/masked-array/scalar.

Returns

int

The rank of the data (0 for a scalar).

Remarks

Scoped ([NDScoped]): a scalar/array-like operand is materialized only to be measured.

negative(object, NDMaskedArray, NDArray, DType)

Element-wise negation; mask unchanged.

public NDMaskedArray negative(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of -data.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

nonzero(object)

Indices of the non-zero UNMASKED elements (NumPy's ma.nonzero): masked slots are filled with 0 so they never count as non-zero. One plain int64 index array per dimension.

public NDArray<long>[] nonzero(object a)

Parameters

a object

Data.

Returns

NDArray<long>[]

An array of int64 index arrays (the house tuple convention).

Remarks

NumPy's np.asarray(self.filled(0)).nonzero(); over text the fill is formatted first, so a 0-d operand's rank refusal still wins (see FilledForNumericOp(object, object, ref Exception, bool)). Scoped ([NDScoped]): the zero-filled copy the indices are read from is reclaimed.

Exceptions

ValueError

A 0-d operand (Calling nonzero on 0d arrays is not allowed).

not_equal(object, object, NDMaskedArray, NDArray, DType)

Element-wise inequality; masked where either operand was.

public NDMaskedArray not_equal(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked boolean array of a!=b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

notmasked_contiguous(object, int?)

Contiguous UNMASKED runs of the array as slices (NumPy's notmasked_contiguous). Its return is POLYMORPHIC, exactly like NumPy's: for axis null or a 1-D input it is a flat Slice[] (one Slice per run); for a 2-D array with an explicit axis it is a Slice[][] — one inner Slice[] per line along the OTHER axis (NumPy's list-of-lists), an empty inner array for a fully-masked line. Only ≤ 2-D is supported (NumPy's own limit).

public object notmasked_contiguous(object a, int? axis = null)

Parameters

a object

Operand.

axis int?

null (flatten) or the axis along which each line's runs are collected.

Returns

object

Slice[] for the flat/1-D case; Slice[][] for a 2-D explicit axis. Returned as object because the nesting depends on the runtime axis, as it does in NumPy — cast at the call site.

Remarks

Scoped by hand (the result holds no array): the masked operand wrapper, every per-line view and the raveled/inverted masks behind each line's runs are reclaimed before the slices are returned.

Exceptions

NotImplementedError

The input has more than 2 dimensions (NumPy's NotImplementedError("Currently limited to at most 2D array."), type and text).

AxisError

axis is out of range for the operand's rank.

notmasked_edges(object, int?)

First and last UNMASKED indices along an axis (NumPy's notmasked_edges). Its return is POLYMORPHIC, exactly like NumPy's (which returns a Python list): for axis null or a 1-D input it is the flat long[] {first, last} (or null when every element is masked); for an explicit axis on a >1-D array it is NDArray[][] = { mins, maxs }, where mins/maxs each hold ONE NDArray per dimension — the compressed first/last unmasked coordinate along that dimension — matching NumPy's [tuple(mins), tuple(maxs)].

public object notmasked_edges(object a, int? axis = null)

Parameters

a object

Operand.

axis int?

null (flatten) or the axis along which to find the edges.

Returns

object

NumPy's int64 [first, last] array (or null) for the flat/1-D case (see flatnotmasked_edges(object)); NDArray[][] {mins, maxs} for a >1-D explicit axis. Returned as object because the shape depends on the runtime axis, as it does in NumPy — cast at the call site.

Remarks

Scoped by hand (the weaver does not wrap an object return): the full mask, the coordinate grids, their per-axis reductions and the masked wrappers are reclaimed; every compressed edge array in the returned jagged pair is handed back to the caller's scope.

Exceptions

AxisError

axis is out of range for the operand's rank.

ones(Shape, DType, char, string, object, bool)

Masked array of ones (no element masked) — NumPy's np.ma.ones(shape, dtype=None, order='C', *, device=None, fill_value=None, hardmask=False).

public NDMaskedArray ones(Shape shape, DType dtype = null, char order = 'C', string device = null, object fill_value = null, bool hardmask = false)

Parameters

shape Shape

Result shape.

dtype DType

Element dtype (null ⇒ float64).

order char

The memory layout, 'C' (the default) or 'F'.

device string

NumPy's Array-API device: null or "cpu".

fill_value object

The result's fill value (converted to the dtype); null leaves the default.

hardmask bool

True gives the result a hard mask.

Returns

NDMaskedArray

An unmasked masked array of ones.

Remarks

Keywords as in zeros(Shape, DType, char, string, object, bool) (API-parity batch 7).

Exceptions

ValueError

A bad order letter (first), or a device other than "cpu".

TypeError

fill_value cannot be stored in the dtype.

ones_like(object, DType, char, Shape?, string)

Masked ones shaped like a (NumPy's ma.ones_like): the prototype's mask (a copy), fill value and hardness ride along, as in zeros_like(object, DType, char, Shape?, string).

public NDMaskedArray ones_like(object a, DType dtype = null, char order = 'K', Shape? shape = null, string device = null)

Parameters

a object

Prototype array-like.

dtype DType

Override dtype.

order char

NumPy's layout ('K' keeps the prototype's); the copied mask follows the result.

shape Shape?

Override shape: the mask is reshaped when the sizes match, dropped when they do not.

device string

NumPy's Array-API device: null or "cpu".

Returns

NDMaskedArray

A masked array of ones.

Remarks

Keywords as in zeros_like(object, DType, char, Shape?, string) (API-parity batch 7).

Exceptions

ValueError

A bad order letter or device.

TypeError

See zeros_like(object, DType, char, Shape?, string).

outer(object, object)

Outer product with masked slots treated as 0; result[i,j] is masked iff a[i] or b[j] was masked (NumPy's ma.outer).

public NDMaskedArray outer(object a, object b)

Parameters

a object

Left operand.

b object

Right operand.

Returns

NDMaskedArray

The masked outer product.

Remarks

Scoped by hand: the zero-filled operand copies, the stand-in all-False masks and the raveled / reshaped mask views are reclaimed; only the product and its mask leave. Over text NumPy's np.outer(filled(a, 0).ravel(), ...) refuses by dtype (the multiply loops) after formatting the fill.

outerproduct(object, object)

Outer product — alias of outer(object, object) (NumPy's outerproduct).

public NDMaskedArray outerproduct(object a, object b)

Parameters

a object

Left.

b object

Right.

Returns

NDMaskedArray

The masked outer product.

polyfit(object, object, int, double?, bool, object, object)

Least-squares polynomial fit that DROPS masked observations first (NumPy's ma.polyfit): a masked x or w entry — or, for 2-D y, a masked entry ANYWHERE in a row — removes that whole observation, and the surviving (x, y[, w]) rows are handed to polyfit(NDArray, NDArray, int, double?, bool, NDArray, object). Because it composes on polyfit(NDArray, NDArray, int, double?, bool, NDArray, object) — which solves through np.linalg.lstsq — it inherits that method's backend requirement: with no LAPACK-capable BLAS installed it throws exactly as np.polyfit does (an OpenBlasMissingBackendException), never a silently-wrong fit. The coefficients are PLAIN arrays, as in NumPy (the masked rows are gone, so nothing in the result is masked).

public PolyfitResult polyfit(object x, object y, int deg, double? rcond = null, bool full = false, object w = null, object cov = null)

Parameters

x object

x-coordinates, shape (M,); a masked entry drops its observation.

y object

y-coordinates, shape (M,) or (M, K); for 2-D y a masked entry anywhere in a row drops that row (NumPy's mask_rows reduction).

deg int

Degree of the fitting polynomial.

rcond double?

Relative condition number (null ⇒ len(x)·eps), forwarded to np.polyfit.

full bool

When true the PolyfitResult also carries the SVD diagnostics.

w object

Optional weights, shape (M,); a masked entry drops its observation.

cov object

null/false, true, or the string "unscaled" — forwarded to np.polyfit's covariance return.

Returns

PolyfitResult

The PolyfitResult of the fit over the UNMASKED observations; it converts implicitly to the coefficient array and deconstructs to the full/cov tuples.

Remarks

Scoped ([NDScoped]; PolyfitResult is an INDArrayCarrier, so the weaver yields its parts): the unioned observation mask, the row reduction of a 2-D y's mask, the keep-mask and the selected observation rows are reclaimed — on the backend-missing throw too.

Exceptions

TypeError

y is not 1-D or 2-D, or w is not 1-D or has a length differing from y (NumPy's verbatim texts).

power(object, object, object)

Masked power (NumPy's ma.power, a plain function rather than a masked ufunc): masked positions take the base's data; a non-finite result is additionally masked and its data set to the RESULT's fill value — the base's own when the base is a masked array (result._update_from(a)), the dtype default otherwise. The third modulus slot exists ONLY for signature parity — NumPy rejects a 3-argument masked power, and so does this.

public NDMaskedArray power(object a, object b, object third = null)

Parameters

a object

Base.

b object

Exponent.

third object

Must be null — a non-null modulus raises MaskError, matching NumPy.

Returns

NDMaskedArray

The masked power: it inherits the fill value and hard mask of a ONLY (a plain base with a masked exponent gives the defaults); NDMasked for a 0-D result with a mask or a non-finite value.

Remarks

NumPy's statements: m = mask_or(getmask(a), getmask(b)) — which SHRINKS an all-False mask to nomask —; result = np.where(m, fa, umath.power(fa, fb)).view(basetype); result._update_from(a); invalid = ~isfinite(result); with a mask the result's mask is m | invalid (a 0-D result is masked); without one it is invalid when any slot is invalid, else nomask; the invalid slots get result.fill_value.

Scoped by hand: the widening casts, the raw power, the base-restoring select, the non-finite predicate, the fill scalar and the broadcast mask view are reclaimed; only the result's data and mask leave (the computed value too when a 0-D result collapses to NDMasked).

Exceptions

MaskError

third is non-null (NumPy's "3-argument power not supported.").

prod(object, int, DType, NDMaskedArray, bool)

public NDMaskedArray prod(object a, int axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked product, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

prod(object, int[], DType, NDMaskedArray, bool)

The owner's kept int[] form of prod(object, NDAxis?, DType, NDMaskedArray, bool).

public NDMaskedArray prod(object a, int[] axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked product, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

prod(object, NDAxis?, DType, NDMaskedArray, bool)

Product over the unmasked elements — NumPy's np.ma.prod(a, axis=None, dtype=None, out=None, keepdims): the masked slots filled with 1; a result cell is masked exactly where its whole slice was.

public NDMaskedArray prod(object a, NDAxis? axis = null, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked product, or out.

Remarks

Tuple axis, out and NumPy's parameter order since API-parity batch 8 (see sum(object, NDAxis?, DType, NDMaskedArray, bool)).

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

product(object, int, DType, NDMaskedArray, bool)

public NDMaskedArray product(object a, int axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked product, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

product(object, int[], DType, NDMaskedArray, bool)

public NDMaskedArray product(object a, int[] axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked product, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

product(object, NDAxis?, DType, NDMaskedArray, bool)

Alias of prod(object, NDAxis?, DType, NDMaskedArray, bool) (NumPy's np.ma.product).

public NDMaskedArray product(object a, NDAxis? axis = null, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked product, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

ptp(object, int, NDMaskedArray, object, bool)

public NDMaskedArray ptp(object a, int axis, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The fill passed to both max and min, or null for their defaults.

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked range (max − min), or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

ptp(object, int[], NDMaskedArray, object, bool)

The owner's kept int[] form of ptp(object, NDAxis?, NDMaskedArray, object, bool).

public NDMaskedArray ptp(object a, int[] axis, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The fill passed to both max and min, or null for their defaults.

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked range (max − min), or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

ptp(object, NDAxis?, NDMaskedArray, object, bool)

Peak-to-peak (max − min) over the unmasked elements — NumPy's np.ma.ptp(obj, axis=None, out=None, fill_value=None, keepdims=False).

public NDMaskedArray ptp(object a, NDAxis? axis = null, NDMaskedArray @out = null, object fill_value = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

fill_value object

The fill passed to both max and min, or null for their defaults.

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked range (max − min), or out.

Remarks

NumPy's statements: without out, the masked max minus the masked min; with out, out.flat = self.max(axis, out=out, ...) (max's out rules: the mask, or NaN / MaskError for a plain out), then np.subtract(out, min_value, out=out, casting='unsafe'), whose array_wrap sets a masked out's mask to the shrunk OR of its own and the minimum's. Tuple axis and out since API-parity batch 8.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

MaskError

A plain integer or bool out (NumPy's Masked data information would be lost in one or more location.).

TypeError

A StringDType operand (no extremum fill).

put(object, NDArray, object, string)

IN-PLACE flat scatter, NumPy's ma.put and MaskedArray.put statement for statement: writes values into a.flat[indices] through ndarray.put (cycling them), then masks the written slots where values is masked and unmasks them where it is not. Under a HARD mask NumPy first drops the indices that fall on masked slots, with consequences listed in the remarks.

public void put(object a, NDArray indices, object values, string mode = "raise")

Parameters

a object

The NDMaskedArray to mutate; a plain NDArray is written as ndarray.put writes it; any other operand is converted, written and dropped (NumPy writes into np.asarray(a), a temporary).

indices NDArray

The flat target indices (any integer array; a bool array indexes as NumPy's put does, False as 0 and True as 1).

values object

A scalar, a C# array, an NDArray, an NDMaskedArray or the masked constant. A masked array's DATA is written, masked slots included (the masked constant writes its 0.0, cast).

mode string

Out-of-bounds policy: "raise" (default) / "wrap" / "clip"; null is NumPy's None (raise).

Remarks

The hard-mask branch is NumPy's mask = self._mask[indices]; indices = narray(indices); values = narray(values, subok=True); values.resize(indices.shape); indices = indices[~mask]; values = values[~mask], and its consequences are NumPy's too, kept for parity:

  • an N-D target always raises an IndexError and writes nothing (above);
  • values.resize ZERO-PADS or truncates rather than cycling: put([0, 2, 3], 5) writes 5, 0, 0 (a C# number or array is a fresh np.array, which resizes);
  • a masked values always raises, and an NDArray of another size than indices raises (the caller holds it);
  • the mask lookup ignores mode, but the write does not: under "clip" a negative index passes the lookup as the LAST element and is written (and unmasked) at index 0 — put([-1], [7], mode: "clip") on [--, 2, 3, 4] gives [7, 2, 3, 4], unmasked;
  • a C# literal is converted before the cast, so it wraps (300 into int8 is 44) where the soft branch raises NumPy's OverflowError.

One divergence ([Misaligned]): for an NDArray values of the indices' size but another shape NumPy reshapes the caller's array in place; NumSharp relabels an alias of it, because data and mask hand out a masked array's own arrays (NumPy hands out fresh views), so an in-place relabel could reshape a masked array's data under its mask. The values written are the same: the relabel keeps the memory order, F order included.

The mask update is NumPy's: nothing when neither the target nor the values are masked; otherwise getmaskarray(self) (the mask itself, written IN PLACE, so a view sharing it sees the change — or a fresh all-False mask for nomask), put(indices, False) or put(indices, values._mask) (cycled), and make_mask(m, shrink=True): an all-False result becomes nomask.

Scoped by hand: the hard branch's lookups and conversions, the plain branch's conversion and a fresh mask that shrinks back to nomask are reclaimed — on a throw too. A mask the call KEEPS is a field store and is detached from the scope (Own(NDArray)). When an existing mask shrinks to nomask the dropped mask array is NOT disposed: another masked array may share it (NumPy's _sharedmask), so it is left to its remaining owners and, finally, the GC.

Exceptions

ArgumentNullException

a, indices or values is null.

IndexError

Under a hard mask (a mask array present, even an all-False one), from self._mask[indices]: an index out of bounds for the mask's FIRST axis whatever mode is (index 9 is out of bounds for axis 0 with size 4), a float index array, a 0-d target. Then, for an N-D target, from indices[~mask]: self._mask[indices] indexed the mask's first axis, so the boolean array has more dimensions than the index array (too many indices for array: array is 1-dimensional, but 2 were indexed) — every hard-masked N-D put raises one of these before it writes.

Otherwise ndarray.put's (put(NDArray, NDArray, NDArray, string)): an out-of-bounds index under raise, a non-empty index list into an empty target.

ValueError

Under a hard mask: a masked values (the masked constant included) cannot be resized (A masked array does not own its data and therefore cannot be resized.); otherwise a bad mode (NumPy's clipmode_parser texts) or a read-only target.

IncorrectShapeException

Under a hard mask, ndarray.resize's errors for an NDArray values of another size than indices (the caller holds it, so NumPy's reference check refuses: cannot resize an array that references or is referenced by another object in this way. Use the np.resize function to get a new resized copy or set refcheck=False to disable this check; a view: cannot resize this array: it does not own its data) or of a non-contiguous layout (resize only works on single-segment arrays). The house type of NumSharp's ndarray.resize errors; NumPy raises ValueError.

TypeError

A float or complex index array (ndarray.put's safe cast).

OverflowError

Without a hard mask: a C# literal out of the target's range (NumPy's PyArray_Pack); under a hard mask the literal becomes an int64 / float64 array first and is cast.

putmask(object, object, object)

IN-PLACE conditional write (NumPy's ma.putmask): writes values into a's data wherever mask is True, and reconciles the mask there — masked values mask those slots, plain values UNMASK them. Unlike put(object, NDArray, object, string), alignment is by copyto(NDArray, NDArray, string, NDArray) broadcast (not cycling).

public void putmask(object a, object mask, object values)

Parameters

a object

The NDMaskedArray (or plain array) to mutate.

mask object

Boolean array selecting the write positions (a C# bool[] converts to one; NumPy's np.copyto(..., where=mask) takes it, so a numeric or text array is refused).

values object

Scalar/array/NDMaskedArray supplying the data (and, if masked, the mask). A C# number is getdata(values): a strong default-width array (an int is int64, a float float64).

Remarks

NumPy's copies all use np.copyto's default same_kind casting: a float written into int data is refused, an int64 written into int8 data wraps.

Scoped by hand: the hard-mask working copy, the stand-in all-False value mask and any array-like operand this method had to materialize are reclaimed. A mask the call CREATES on a nomask target is a field store and is detached from every scope (it lives as long as the target); the hard-mask branch ORs into the existing mask IN PLACE — NumPy's a.mask |= m — rather than replacing the field, so no mask array is orphaned.

Exceptions

ArgumentException

A mask that is not boolean: NumPy's TypeError Cannot cast array data from dtype('int64') to dtype('bool') according to the rule 'safe' (the house ArgumentException of copyto(NDArray, NDArray, string, NDArray)), raised whatever the size — an empty text mask included.

InvalidCastException

values cannot reach the data's dtype by a same_kind cast (Cannot cast scalar from dtype('float64') to dtype('int64') according to the rule 'same_kind'; text values for numeric data whatever the mask holds).

ravel(object, char)

Flattened VIEW in the given order (mask flattened alike). NumPy's ravel.

public NDMaskedArray ravel(object a, char order = 'C')

Parameters

a object

Operand.

order char

'C' or 'F'.

Returns

NDMaskedArray

The flattened masked array.

remainder(object, object, NDMaskedArray, NDArray, DType)

Remainder (floored, sign follows divisor); masks positions where the denominator is (near) zero.

public NDMaskedArray remainder(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Numerator.

b object

Denominator.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the zero divisors, whose slots take 1 and get no data back (a plain out gets the dividend). An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a%b with unsafe divides masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

repeat(object, int, int?)

Repeat elements (mask repeated alike, so repeated masked entries stay masked).

public NDMaskedArray repeat(object a, int repeats, int? axis = null)

Parameters

a object

Operand.

repeats int

Repeat count.

axis int?

Axis or null (flatten).

Returns

NDMaskedArray

The masked array.

reshape(object, Shape, char)

Reshape to new_shape, the mask reshaped alike — NumPy's np.ma.reshape(a, new_shape, order='C'), which is a.reshape(new_shape, order=order).

public NDMaskedArray reshape(object a, Shape new_shape, char order = 'C')

Parameters

a object

The operand: a masked array, an array or an array-like.

new_shape Shape

The new dimensions as ONE argument: an int, a tuple, an int[] / long[] or a Shape (one entry may be -1, the unknown dimension).

order char

The index order: 'C' (the default), 'F', or 'A' (F when the operand is F-contiguous and not C-contiguous); 'K' is refused, as by np.reshape.

Returns

NDMaskedArray

A masked array viewing the operand's data (and mask) when the new layout allows it, else a copy; it takes the operand's fill value and hard-mask flag (result._update_from(self)).

Remarks

One signature since API-parity batch 8 (2026-11-12): the params int[] new_shape form went — NumPy's np.ma.reshape(a, 2, 3) reads the 3 as the order (TypeError: order must be str, not int), so write (2, 3). NumPy hands a PLAIN array operand back as a plain array (its own reshape); NumSharp's static type returns a masked array without a mask.

Exceptions

IncorrectShapeException

The size does not match (cannot reshape array of size 6 into shape (4,), NumPy's ValueError text).

ValueError

A bad order, or more than one unknown dimension.

resize(object, Shape)

Returns a NEW masked array of new_shape filled with repeated copies of x's data AND mask (NumPy's ma.resize) — always a masked array, never in place. Enlarging TILES the input (data and mask alike, so a masked element recurs masked); shrinking truncates.

public NDMaskedArray resize(object x, Shape new_shape)

Parameters

x object

Operand.

new_shape Shape

Target shape.

Returns

NDMaskedArray

A fresh masked array of new_shape.

Remarks

Scoped by hand: an array-like operand this method had to materialize is reclaimed once it has been tiled; only the tiled data and mask leave.

right_shift(object, object)

Bit shift right (a >> n; NumPy's ma.right_shift(a, n)): the statements of left_shift(object, object) with umath.right_shift — the value operand's dtype is kept for a bare scalar shift count, the masked slots are shifted from 0, and the result inherits nothing (see Shift(object, object, bool)).

public NDMaskedArray right_shift(object a, object n)

Parameters

a object

Value to shift.

n object

Shift amount: a C# integer (a weak Python int), an array or a masked array. NumPy's name; until API-parity batch 9 it was b.

Returns

NDMaskedArray

A masked array of a>>n in a's dtype.

Exceptions

MaskError

n broadcasts the result past a's mask.

TypeError

The shift has no loop for the operands (a float, complex or text value: NumPy's "not supported for the input types" text).

round(object, int, NDMaskedArray)

Rounds each element to decimals places (half-to-even), preserving the mask — NumPy's np.ma.round(a, decimals=0, out=None) (round_; without an out, MaskedArray.round). Masked positions carry their rounded data but stay masked.

public NDMaskedArray round(object a, int decimals = 0, NDMaskedArray @out = null)

Parameters

a object

Data.

decimals int

Decimal places (negative rounds to the left of the decimal point).

out NDMaskedArray

NumPy's out: np.round(getdata(a), decimals, out) writes the rounded data into it and it is returned. A MASKED out then takes the operand's mask OBJECT itself (out._mask = getmask(a): shared, its hardness ignored, an unmasked operand leaving it mask-less), and its data went through NumPy's in-place ufunc chain, so an infinite result is written as 1.0 (10**-decimals for negative decimals) — see RoundInto(NDArray, int, NDMaskedArray, bool). A plain array (converted) receives the rounded data only. Added in API-parity batch 8.

Returns

NDMaskedArray

The masked, rounded array: it SHARES the operand's mask object and takes its fill value and hard-mask flag; a 0-d result is NDMasked when masked, else an unmasked 0-d array — or out.

Exceptions

AttributeError

Complex data into a masked out (property 'real' of 'MaskedArray' object has no setter), before anything is written.

UFuncOutputCastingError

out's dtype cannot hold the rounded values (Cannot cast ufunc 'multiply' output from dtype('float64') to dtype('int64') with casting rule 'same_kind'; 'rint' for decimals 0, 'divide' for negative decimals).

ValueError

out has another size than the operand (invalid output shape).

round_(object, int, NDMaskedArray)

Round to decimals places — alias of round(object, int, NDMaskedArray) (NumPy's round_(a, decimals=0, out=None), whose body round is).

public NDMaskedArray round_(object a, int decimals = 0, NDMaskedArray @out = null)

Parameters

a object

Operand.

decimals int

Decimal places.

out NDMaskedArray

Where to write the rounded data; a masked out takes the operand's mask object (see round(object, int, NDMaskedArray)). Added in API-parity batch 8.

Returns

NDMaskedArray

The masked, rounded array, or out.

Exceptions

AttributeError

Complex data into a masked out.

UFuncOutputCastingError

out's dtype cannot hold the rounded values.

ValueError

out has another size than the operand.

row_stack(params object[])

Stack along the first axis — NumPy's ma.row_stack, which IS ma.vstack (the loose form, vstack(params object[])).

public NDMaskedArray row_stack(params object[] tup)

Parameters

tup object[]

Operands.

Returns

NDMaskedArray

The stacked masked array.

Remarks

The loose form (np.ma.row_stack(a, b)), kept beside row_stack(object[], DType, string) as vstack keeps its own. A lone object[] binds HERE (C#'s params rule), which is NumPy's sequence anyway.

row_stack(object[], DType, string)

Stack along the first axis — NumPy's ma.row_stack(tup, *, dtype=None, casting='same_kind'), which IS ma.vstack (ma.row_stack is ma.vstack): vstack(object[], DType, string).

public NDMaskedArray row_stack(object[] tup, DType dtype = null, string casting = "same_kind")

Parameters

tup object[]

The operands (masked arrays, arrays, array-likes).

dtype DType

The result's dtype, or null for the operands' common type; NumPy joins the masks in it too.

casting string

NumPy's casting rule for both joins: "no", "equiv", "safe", "same_kind" (the default) or "unsafe".

Returns

NDMaskedArray

A new masked array; its mask is always an array (no fill value or hardness is inherited).

Remarks

Added in API-parity batch 9, the keyword form vstack gained in batch 8.

Exceptions

InvalidCastException

The data or the masks do not cast to dtype under casting (NumPy's TypeError text; NumSharp's house mapping).

ValueError

The operands' shapes do not join, or an unknown casting.

set_fill_value(object, object)

Sets the fill value of a in place (NumPy's module-level set_fill_value). Has effect ONLY on a NDMaskedArray (a plain array has no fill slot); a non-masked operand is silently ignored, matching NumPy.

public void set_fill_value(object a, object fill_value)

Parameters

a object

The masked array to mutate.

fill_value object

The new fill value (null restores the dtype default).

Exceptions

TypeError

See fill_value: NumPy's method IS the property setter, so the same _check_fill_value runs.

setdiff1d(object, object, bool)

The sorted unique values of ar1 that are not in ar2 (NumPy's ma.setdiff1d), in ar1's dtype.

public NDMaskedArray setdiff1d(object ar1, object ar2, bool assume_unique = false)

Parameters

ar1 object

The operand to keep values from.

ar2 object

The operand whose values are removed.

assume_unique bool

Treat both inputs as already unique: ar1 is only flattened (NumPy's ma.asarray(ar1).ravel()) and ar2 is used as given.

Returns

NDMaskedArray

The masked array of ar1's remaining values.

Remarks

NumPy's statements: ar1 = unique(ar1); ar2 = unique(ar2), then ar1[in1d(ar1, ar2, assume_unique=True, invert=True)], the masked flags selecting by their data. So a value of ar1 is kept wherever the inverted flag's data is True — including a flag that is masked. An empty ar1 beside text selects nothing (see in1d(object, object, bool, bool)).

Scoped by hand: the unique values and the flags are reclaimed; only the result's data and mask leave.

Exceptions

ArgumentNullException

An operand is null.

ValueError

A StringDType operand whose sort compares a None-like NA (an NA object that is neither a string nor NaN-like): NumPy's Cannot compare null that is not a nan-like value.

TypeError

A StringDType operand: Unsuitable type ... for calculating minimum. (a masked operand's unique, or in1d's argsort of the joined uniques).

DTypePromotionError

A StringDType operand beside a class it has no common DType with.

setxor1d(object, object, bool)

The sorted values in exactly one of the inputs (NumPy's ma.setxor1d), computed over the FILLED values of the joined uniques.

public NDMaskedArray setxor1d(object ar1, object ar2, bool assume_unique = false)

Parameters

ar1 object

First operand.

ar2 object

Second operand.

assume_unique bool

Treat both inputs as already unique (NumPy skips the two unique calls).

Returns

NDMaskedArray

The masked array of the symmetric difference, in the promoted dtype.

Remarks

NumPy's statements: ar1 = unique(ar1); ar2 = unique(ar2); aux = ma.concatenate((ar1, ar2), axis=None); an empty aux is the result; aux.sort(); auxf = aux.filled(); flag = ma.concatenate(([True], auxf[1:] != auxf[:-1], [True])); aux[flag[1:] == flag[:-1]]. The neighbours are compared FILLED with the default fill value, so a masked slot equals an unmasked value equal to that fill (999999 for an integer dtype) — NumPy's answer, reproduced.

Scoped by hand: the unique values, the joined copy, the filled copy and the flags are reclaimed; only the result's data and mask leave.

Exceptions

ArgumentNullException

An operand is null.

ValueError

A StringDType operand whose sort compares a None-like NA (an NA object that is neither a string nor NaN-like): NumPy's Cannot compare null that is not a nan-like value.

TypeError

A StringDType operand: Unsuitable type ... for calculating minimum. (a masked operand's unique, or the joined copy's masked sort).

DTypePromotionError

A StringDType operand beside a class it has no common DType with.

shape(object)

Data shape as a long[] (NumPy's module-level ma.shape; NumSharp dims are 64-bit).

public long[] shape(object a)

Parameters

a object

Array-like/masked-array/scalar.

Returns

long[]

The shape (empty for a scalar).

shrink_mask(object)

Drops an all-False mask back to nomask IN PLACE (the module form of NumPy's MaskedArray.shrink_mask, as _frommethod builds them: asanyarray(a).shrink_mask()).

public NDMaskedArray shrink_mask(object a)

Parameters

a object

Operand (a NDMaskedArray is changed in place and returned; a plain array is wrapped, with no mask).

Returns

NDMaskedArray

The masked array, with a redundant all-False mask removed.

sin(object, NDMaskedArray, NDArray, DType)

Sine; mask unchanged.

public NDMaskedArray sin(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of sin(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

sinh(object, NDMaskedArray, NDArray, DType)

Hyperbolic sine; mask unchanged.

public NDMaskedArray sinh(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of sinh(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

size(object, int?)

The element count, or the length of one axis (NumPy's module-level ma.size(obj, axis=None): np.size(getdata(obj), axis)).

public long size(object obj, int? axis = null)

Parameters

obj object

Array-like / masked array / scalar (NumPy's keyword obj).

axis int?

NumPy's axis: null (None, the default) counts every element; an axis (negative counts from the end) gives that axis' length.

Returns

long

The element count (1 for a scalar), or the axis' length.

Remarks

Scoped ([NDScoped]): a scalar/array-like operand is materialized only to be measured. NumPy's keywords since 2026-11-11 (the operand was a, and axis was missing).

Exceptions

AxisError

axis is out of range for the data's rank (a scalar has no axis: "axis 0 is out of bounds for array of dimension 0").

soften_mask(object)

Makes a's mask SOFT again in place (NumPy's ma.soften_mask, the default): a plain-value assignment unmasks the assigned slots. A plain array is wrapped first (asanyarray(a).soften_mask()).

public NDMaskedArray soften_mask(object a)

Parameters

a object

Operand (a NDMaskedArray is mutated in place).

Returns

NDMaskedArray

The same masked array, now soft-masked.

sometrue(object, int?, DType)

Logical-OR reduction along an axis (NumPy's ma.sometrue — logical_or.reduce of the masked logical_or, NOT an alias of any(object, NDAxis?, NDMaskedArray, bool)): the masked slots are filled with 0 (False), the result is masked where its whole slice was masked, and the default axis is 0.

public NDMaskedArray sometrue(object target, int? axis = 0, DType dtype = null)

Parameters

target object

Operand.

axis int?

The reduced axis (default 0, as NumPy's), or null for the flattened array.

dtype DType

NumPy's dtype= of the reduction (used only when target has a mask; only bool has a logical_or loop).

Returns

NDMaskedArray

See alltrue(object, int?, DType).

Exceptions

AxisError

axis is outside the operand.

TypeError

A masked operand with a non-bool dtype.

sort(object, int?, string, object, bool, object, bool?, bool?)

Sorts along an axis with masked entries pushed to the END (or, with endwith false, the FRONT) and re-masked there (NumPy's ma.sort). The masked slots' key is NaN for a floating dtype and the dtype's LARGEST value otherwise when endwith (so they sort last, ascending), its SMALLEST value otherwise; their ORIGINAL data rides along to the end/front rather than the fill value a plain sort-of-filled would leave behind.

public NDMaskedArray sort(object a, int? axis = -1, string kind = null, object order = null, bool endwith = true, object fill_value = null, bool? stable = null, bool? descending = null)

Parameters

a object

Operand.

axis int?

Sort axis (default last; negative counts from the end), or null to sort the flattened array.

kind string

NumPy's sort kind ("quicksort", "mergesort", "heapsort", "stable" and their prefixes), or null for the default; validated by sort(NDArray, int?, string, object, bool?, bool?) with NumPy's text (sort kind must be one of 'quick', 'heap', or 'stable' (got 'bogus')). Added in API-parity batch 9, in NumPy's third slot, where C# had endwith.

order object

NumPy's structured-array field order; numeric data has no fields, so any value is NumPy's ValueError: Cannot specify order when the array has no fields.

endwith bool

True (default) pushes masked entries to the END; false to the FRONT.

fill_value object

Override the masked sort key; null uses the endwith default (see SortFill(object, bool)).

stable bool?

NumPy's keyword-only stable: true on a masked operand is NumPy's ValueError: stable parameter is not supported for masked arrays. (MaskedArray.sort refuses it); a plain operand passes it on to sort(NDArray, int?, string, object, bool?, bool?).

descending bool?

NumPy 2.5's keyword-only descending: true on a masked operand is NumPy's ValueError: descending parameter is not supported for masked arrays.; a plain operand passes it on to sort(NDArray, int?, string, object, bool?, bool?), which sorts descending.

Returns

NDMaskedArray

The sorted masked array — a copy finalized from a: its hard-mask flag and fill value.

Remarks

NumPy's statements: a = np.array(a, copy=True, subok=True) (a copy that keeps the subclass, so it finalizes from the operand), a = a.flatten(); axis = 0 for axis=None, then MaskedArray.sort(axis, kind, order, endwith, fill_value, stable=stable) (a plain operand: ndarray.sort(axis, kind, order, stable=stable)): if stable: raise ValueError(...); without a mask the data is sorted in place (ndarray.sort(self, axis, kind, order)); with one sidx = a.argsort(axis, kind=, order=, endwith=, fill_value=) and a[...] = np.take_along_axis(a, sidx, axis). That last write goes through setitem, so on a HARD-masked operand the slots that were masked keep their old data and the masks are OR-ed — NumPy's (surprising) answer, reproduced here through this module's indexer.

Scoped by hand: the filled sort keys, the permutation and the gathered values are reclaimed (as is an array-like operand this method had to materialize); only the sorted copy leaves.

NumPy's order since API-parity batch 9 (kind / order / stable added): a positional third argument is the kind, so np.ma.sort(x, 0, false) no longer compiles (NumPy: sort kind must be str, not bool); write endwith: false.

Exceptions

AxisError

axis is outside the operand.

ValueError

stable or descending true on a masked operand (checked before the axis and the kind, as NumPy's method does first; stable first), an unknown kind, or an order.

sqrt(object, NDMaskedArray, NDArray, DType)

Square root; additionally MASKS inputs < 0 (and non-finite results) rather than letting them produce NaN, which is the whole point of the masked variant.

public NDMaskedArray sqrt(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 0.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of sqrt(data) with negatives masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

squeeze(object, int, object, bool)

Remove ONE size-1 axis — the owner's kept int form beside squeeze(object, NDAxis?, object, bool) (NumPy's np.ma.squeeze(a, 1)).

public NDMaskedArray squeeze(object a, int axis, object fill_value = null, bool hardmask = false)

Parameters

a object

The operand.

axis int

The size-1 axis to drop (negative counts from the end).

fill_value object

The result's fill value, or null.

hardmask bool

True hardens the result's mask.

Returns

NDMaskedArray

The squeezed masked array.

Exceptions

ValueError

The axis' length is not 1.

AxisError

The axis is out of range.

TypeError

fill_value cannot be stored in the dtype.

squeeze(object, int[], object, bool)

Remove the listed size-1 axes — the owner's kept int[] form beside squeeze(object, NDAxis?, object, bool); a null array is NumPy's None (every size-1 axis).

public NDMaskedArray squeeze(object a, int[] axis, object fill_value = null, bool hardmask = false)

Parameters

a object

The operand.

axis int[]

The size-1 axes to drop, or null for all.

fill_value object

The result's fill value, or null.

hardmask bool

True hardens the result's mask.

Returns

NDMaskedArray

The squeezed masked array.

Exceptions

ValueError

An axis' length is not 1, or an axis repeats.

AxisError

An axis is out of range.

TypeError

fill_value cannot be stored in the dtype.

squeeze(object, NDAxis?, object, bool)

Remove size-1 axes, the mask squeezed alike — NumPy's np.ma.squeeze(a, axis=None, *, fill_value=None, hardmask=False) (_convert2ma over np.squeeze). With axis null EVERY size-1 axis is dropped; an axis or a tuple of axes drops ONLY those (each must be size 1).

public NDMaskedArray squeeze(object a, NDAxis? axis = null, object fill_value = null, bool hardmask = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The size-1 axis or axes to drop (an int, a tuple, an int[]; negative counts from the end), or null to drop every size-1 axis.

fill_value object

The result's fill value, set through the converting setter; null leaves the operand's.

hardmask bool

True hardens the result's mask (false leaves the hardness the result inherited).

Returns

NDMaskedArray

The squeezed masked array (a view of the operand's data and mask), with the operand's fill value and hard-mask flag unless the keywords set them.

Remarks

NumPy's tuple axis, fill_value and hardmask arrived in API-parity batch 8 (the axis was one int?). An explicit hardmask: false does not soften an inherited hard mask (NumPy's does): C#'s default cannot tell it from an omitted argument.

Exceptions

ValueError

An axis whose length is not 1 (cannot select an axis to squeeze out which has size not equal to one) or a repeated axis.

AxisError

An axis out of range.

TypeError

fill_value cannot be stored in the dtype (numpy.ma's _check_fill_value).

stack(object[], int, DType, string)

Join a sequence along a NEW axis — NumPy's np.ma.stack(arrays, axis=0, out=None, *, dtype=None, casting='same_kind'): np.stack over the data and over the full masks, with the same keywords.

public NDMaskedArray stack(object[] arrays, int axis = 0, DType dtype = null, string casting = "same_kind")

Parameters

arrays object[]

The operands (masked arrays, arrays, array-likes), all of one shape.

axis int

The new axis' position in the result (negative counts from the end).

dtype DType

The result's dtype, or null for the operands' common type. NumPy joins the MASKS in it too (then reads them back as bool), so casting also judges the bool to dtype cast.

casting string

NumPy's casting rule for both joins ("same_kind" by default).

Returns

NDMaskedArray

A new masked array; its mask is always an array (no fill value or hardness is inherited).

Remarks

numpy.ma's _fromnxfunction_seq. dtype / casting arrived in API-parity batch 8; NumPy's out= is not offered: NumPy's ma.stack hands the SAME out to the data join and then to the mask join, so the result's data is the mask (a quirk left for a decision of its own).

Exceptions

InvalidCastException

The data or the masks do not cast to dtype under casting (NumPy's TypeError text; NumSharp's house mapping).

ValueError

The operands differ in shape (all input arrays must have the same shape), an empty sequence, or an unknown casting.

AxisError

axis is out of range for the result's rank.

std(object, int, DType, NDMaskedArray, int, bool, object)

public NDMaskedArray std(object a, int axis, DType dtype = null, NDMaskedArray @out = null, int ddof = 0, bool keepdims = false, object mean = null)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

ddof int

Delta degrees of freedom: the divisor is the count minus ddof.

keepdims bool

Keep the reduced axes with length 1.

mean object

Accepted for NumPy's signature and IGNORED: NumPy's ma.std does not forward it to var.

Returns

NDMaskedArray

The masked standard deviation, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

AttributeError

A 0-d result of a masked operand into a masked out (NumPy's numpy scalar has no mask).

MaskError

A masked 0-d result into a plain integer or bool out.

std(object, int[], DType, NDMaskedArray, int, bool, object)

public NDMaskedArray std(object a, int[] axis, DType dtype = null, NDMaskedArray @out = null, int ddof = 0, bool keepdims = false, object mean = null)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

ddof int

Delta degrees of freedom: the divisor is the count minus ddof.

keepdims bool

Keep the reduced axes with length 1.

mean object

Accepted for NumPy's signature and IGNORED: NumPy's ma.std does not forward it to var.

Returns

NDMaskedArray

The masked standard deviation, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

AttributeError

A 0-d result of a masked operand into a masked out (NumPy's numpy scalar has no mask).

MaskError

A masked 0-d result into a plain integer or bool out.

std(object, NDAxis?, DType, NDMaskedArray, int, bool, object)

Standard deviation: NumPy's MaskedArray.std, sqrt(self.var(axis, dtype, out, ddof, keepdims)) through ma's domained sqrt, which masks a non-finite or negative variance (and keeps the variance's own mask). A masked variance is returned as is.

public NDMaskedArray std(object a, NDAxis? axis = null, DType dtype = null, NDMaskedArray @out = null, int ddof = 0, bool keepdims = false, object mean = null)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

dtype DType

The variance's dtype= (see var(object, NDAxis?, DType, NDMaskedArray, int, bool, object)).

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

ddof int

Delta degrees of freedom: the divisor is the count minus ddof.

keepdims bool

Keep the reduced axes with length 1.

mean object

Accepted for signature parity but IGNORED — NumPy's ma.std forwards only keepdims to var, never mean (a NumPy quirk: ma.std(mean=X) yields the PLAIN std, unlike ma.var(mean=X)). Reproduced here so a ported call behaves identically.

Returns

NDMaskedArray

The masked standard deviation, or out.

Remarks

With out: the variance's out rules, then np.power(out, 0.5, out=out, casting='unsafe'), whose array_wrap leaves a masked out's mask as the shrunk OR of its own (an all-False mask becomes nomask). Tuple axis, out and NumPy's parameter order since API-parity batch 8.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

AttributeError

A 0-d result of a masked operand into a masked out (NumPy's numpy scalar has no mask).

MaskError

A masked 0-d result into a plain integer or bool out.

subtract(object, object, NDMaskedArray, NDArray, DType)

Element-wise difference; masked where either operand was.

public NDMaskedArray subtract(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Left operand.

b object

Right operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, nomask. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a-b.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

sum(object, int, DType, NDMaskedArray, bool)

public NDMaskedArray sum(object a, int axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked sum (the masked singleton for a fully masked 0-d result), or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

sum(object, int[], DType, NDMaskedArray, bool)

The owner's kept int[] form of sum(object, NDAxis?, DType, NDMaskedArray, bool).

public NDMaskedArray sum(object a, int[] axis, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked sum (the masked singleton for a fully masked 0-d result), or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

sum(object, NDAxis?, DType, NDMaskedArray, bool)

Sum over the unmasked elements — NumPy's np.ma.sum(a, axis=None, dtype=None, out=None, keepdims) (MaskedArray.sum): the data with the masked slots filled with 0, reduced; a result cell is masked exactly where its whole slice was. NEP 50: an integer input sums in int64.

public NDMaskedArray sum(object a, NDAxis? axis = null, DType dtype = null, NDMaskedArray @out = null, bool keepdims = false)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

keepdims bool

Keep the reduced axes with length 1.

Returns

NDMaskedArray

The masked sum (the masked singleton for a fully masked 0-d result), or out.

Remarks

NumPy's tuple axis and out arrived in API-parity batch 8, with NumPy's parameter order (keepdims after out). A masked out takes outmask.flat = newmask (a mask created if it had none); a plain out the data only.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

swapaxes(object, int, int)

Swap two axes (mask swapped alike).

public NDMaskedArray swapaxes(object a, int axis1, int axis2)

Parameters

a object

Operand.

axis1 int

First axis.

axis2 int

Second axis.

Returns

NDMaskedArray

The masked array with swapped axes.

take(object, NDArray, int?, NDMaskedArray, string)

Gather elements by index — NumPy's np.ma.take(a, indices, axis=None, out=None, mode='raise') (MaskedArray.take): the data and the mask are gathered alike, so a taken element keeps its masked-ness. mode selects the out-of-bounds policy, applied identically to both gathers.

public NDMaskedArray take(object a, NDArray indices, int? axis = null, NDMaskedArray @out = null, string mode = "raise")

Parameters

a object

Operand (a masked array, an array or an array-like).

indices NDArray

Integer index array (a 0-d index with a null axis gives a 0-d result).

axis int?

Axis, or null to index the flattened operand.

out NDMaskedArray

NumPy's out: the gathered data is written into it (np.take's shape and cast checks; under mode="raise" nothing is written when an index is out of bounds), then a masked out takes the gathered mask through NumPy's setmask — a hard out only gains masked slots, and an unmasked operand clears a soft out's mask and leaves a mask-less out mask-less. A plain array (converted) receives the data only. Added in API-parity batch 8.

mode string

Out-of-bounds policy: "raise" (default) / "wrap" / "clip". It follows out, as in NumPy, so a positional mode is now written mode: "clip".

Returns

NDMaskedArray

NumPy's out[()]: the gathered masked array — a NEW soft array with the default fill (NumPy views the plain gather, no _update_from), or out — and for a 0-d result NDMasked when its element is masked, else an unmasked 0-d array holding the value (NumPy's scalar, detached from out).

Remarks

NumPy's statements (masked_array(a).take(...)); the indices are a plain array, so NumPy's maskindices is nomask. Scoped by hand: a materialized operand and the gathered mask a masked out copies are reclaimed; a mask created for out is detached (it lives in the caller's array).

Exceptions

IndexError

An index is out of bounds under mode="raise".

ValueError

out's shape is not the result's (output array does not match result of ndarray.take).

AxisError

axis is out of range.

tan(object, NDMaskedArray, NDArray, DType)

Tangent; additionally masks inputs near its poles (|cos(x)| < 1e-35).

public NDMaskedArray tan(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the inputs outside the domain, whose slots first take the ufunc's fill 0.0. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of tan(data) with pole-neighbors masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

tanh(object, NDMaskedArray, NDArray, DType)

Hyperbolic tangent; mask unchanged.

public NDMaskedArray tanh(object a, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Operand.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's, an all-False array. An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of tanh(data).

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

trace(object, int, int, int, DType, NDArray)

Sum of the diagonal, treating masked slots as 0 — NumPy's np.ma.trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None) (MaskedArray.trace). Returns a PLAIN array, and — matching NumPy's astype(None) quirk — the result is float64 unless dtype is given (so ma.trace of an int matrix is float64, not int).

public NDArray trace(object a, int offset = 0, int axis1 = 0, int axis2 = 1, DType dtype = null, NDArray @out = null)

Parameters

a object

Data (rank ≥ 2).

offset int

Diagonal offset.

axis1 int

First plane axis.

axis2 int

Second plane axis.

dtype DType

Result dtype; null ⇒ float64 (NumPy's default).

out NDArray

NumPy's out (np.sum's / np.trace's checks). A MASKED operand's trace is summed into it (in dtype, then cast to the out's dtype) and it is returned. An UNMASKED operand's trace is written into it WITHOUT dtype (NumPy passes only the axes) and the result is then out.astype(dtype) — a new float64 (or dtype) copy, not the out. Added in API-parity batch 8.

Returns

NDArray

A plain NDArray trace: out for a masked operand, else a new array.

Remarks

NumPy's statements: with no mask, super().trace(offset, axis1, axis2, out=out).astype(dtype); with a mask, D = self.diagonal(offset, axis1, axis2); return D.astype(dtype).filled(0).sum(axis=-1, out=out) — the cast comes BEFORE the fill, so the diagonal is summed in the result dtype (float64 by default), and a rank error is the diagonal's own. Scoped ([NDScoped]): the diagonal, its cast and the zero-filled copy are reclaimed; a returned out is the caller's and is never released.

Exceptions

ArgumentException

The operand has fewer than two dimensions (NumPy's ValueError diag requires an array of at least two dimensions), or the axes are invalid.

TypeError

A nomask text operand: the diagonal sum has no string loop.

ValueError

A masked text operand whose diagonal does not parse as float64: NumPy casts the diagonal first (D.astype(None): could not convert string to float); or an out of the wrong rank (output parameter for reduction operation add has the wrong number of dimensions: Found 1 but expected 0).

transpose(object, int[])

Permute axes (mask transposed alike); reverses all axes when axes is null.

public NDMaskedArray transpose(object a, int[] axes = null)

Parameters

a object

Operand.

axes int[]

Permutation, or null to reverse.

Returns

NDMaskedArray

The transposed masked array.

true_divide(object, object, NDMaskedArray, NDArray, DType)

public NDMaskedArray true_divide(object a, object b, NDMaskedArray @out = null, NDArray where = null, DType dtype = null)

Parameters

a object

Numerator.

b object

Denominator.

out NDMaskedArray

NumPy's out: the ufunc writes its result into it, the masked slots get the input's data back, and the call returns a NEW masked array over that data (the out itself only for a 0-d result). A masked out's own mask becomes the ufunc wrap's: the zero divisors, whose slots take 1 and get no data back (a plain out gets the dividend). An NDArray converts (NumPy's plain out); null allocates. Added in API-parity batch 9.

where NDArray

NumPy's where: the ufunc computes only where it is True; elsewhere an out keeps its values (without one those slots are unspecified, as in NumPy). The masked slots get the input's data back wherever they are.

dtype DType

NumPy's dtype: the dtype the ufunc loop computes in (its 'same_kind' input and output casts apply).

Returns

NDMaskedArray

A masked array of a/b with unsafe divides masked.

Exceptions

UFuncTypeError

The ufunc refuses the operand(s), the dtype or the out's dtype (a UFuncCastingError with NumPy's text, raised before anything is written).

ValueError

The operands, out or where do not broadcast together.

union1d(object, object)

The sorted unique values of both inputs together (NumPy's ma.union1d): unique(object, bool, bool) of their flattened concatenation.

public NDMaskedArray union1d(object ar1, object ar2)

Parameters

ar1 object

First operand.

ar2 object

Second operand.

Returns

NDMaskedArray

The masked array of the union, in the promoted dtype.

Remarks

NumPy's unique(ma.concatenate((ar1, ar2), axis=None)).

    <p>Scoped by hand: the joined copy is reclaimed; only the result's data and mask leave.</p>

Exceptions

ArgumentNullException

An operand is null.

TypeError

A StringDType join with a masked element: the masked sort's argsort refuses it (Unsuitable type StringDType() for calculating minimum.).

ValueError

A StringDType operand whose sort compares a None-like NA (an NA object that is neither a string nor NaN-like): NumPy's Cannot compare null that is not a nan-like value.

unique(object, bool, bool)

Finds the unique elements of an array, with NumPy's optional index outputs (ma.unique(ar1, return_index=False, return_inverse=False)).

public MaskedArrayModule.UniqueResult unique(object ar1, bool return_index = false, bool return_inverse = false)

Parameters

ar1 object

Operand (NDMaskedArray, NDArray, scalar or array-like).

return_index bool

Also return the index of each unique value's first occurrence in the flattened operand (NumPy sorts with the stable 'mergesort' here).

return_inverse bool

Also return the indices into the unique values that rebuild the operand, shaped like the operand (NumPy 2.x).

Returns

MaskedArrayModule.UniqueResult

The MaskedArrayModule.UniqueResult: the values - the 1-D masked array of unique values, every masked element sorting and comparing as ONE value; it inherits a masked operand's hard-mask flag and fill value (converted to the dtype) - and the requested int64 index arrays.

Remarks

With a flag NumPy argsorts instead of sorting in place (perm = ar.argsort(kind='mergesort' if return_index else 'quicksort'), aux = ar[perm]), then perm[mask] and inv_idx[perm] = cumsum(mask) - 1. Only return_inverse without return_index uses NumPy's unstable kind.

Without a flag NumPy sorts in place: ar = ar.flatten(); without a masked element the integer / complex dtypes take the hash path (sorted distinct values); otherwise ar.sort() (masked slots last, keyed by the fill value) and mask[1:] = aux[1:] != aux[:-1] through the masked !=, so all masked slots collapse into the first one in sorted order. See the file header for the tie-order divergence.

Scoped by hand: the flattened copy, the sort permutation and the keep mask are reclaimed; the values' data and mask and the index arrays leave.

API-parity batch 11: this is the only overload (the flag-less NDMaskedArray unique(object) went); a flag-less call returns the struct, which converts to the masked array.

Exceptions

ArgumentNullException

ar1 is null.

TypeError

A masked StringDType operand that NumPy argsorts (return_inverse, or a masked element): Unsuitable type StringDType() for calculating minimum.

ValueError

A StringDType operand whose sort compares a None-like NA (an NA object that is neither a string nor NaN-like): NumPy's Cannot compare null that is not a nan-like value.

vander(object, int?)

Vandermonde matrix of a 1-D input; a masked input element ZEROES its whole row and the result is a PLAIN array (NumPy's ma.vander: "masked values result in rows of zeros").

public NDArray vander(object x, int? n = null)

Parameters

x object

1-D data.

n int?

Number of columns (null ⇒ len(x)). Lowercase to match NumPy's vander(x, n=…) keyword — a call spelled n: ports verbatim.

Returns

NDArray

A plain NDArray Vandermonde matrix with masked rows zeroed.

Remarks

Scoped ([NDScoped]): the reshaped mask column, its broadcast and the zero scalar are reclaimed; only the matrix leaves.

var(object, int, DType, NDMaskedArray, int, bool, object)

public NDMaskedArray var(object a, int axis, DType dtype = null, NDMaskedArray @out = null, int ddof = 0, bool keepdims = false, object mean = null)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int

The one axis to reduce (negative counts from the end).

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

ddof int

Delta degrees of freedom: the divisor is the count minus ddof.

keepdims bool

Keep the reduced axes with length 1.

mean object

NumPy 2's precomputed mean, or null to compute it.

Returns

NDMaskedArray

The masked variance, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

AttributeError

A 0-d result of a masked operand into a masked out (NumPy's numpy scalar has no mask).

MaskError

A masked 0-d result into a plain integer or bool out.

var(object, int[], DType, NDMaskedArray, int, bool, object)

public NDMaskedArray var(object a, int[] axis, DType dtype = null, NDMaskedArray @out = null, int ddof = 0, bool keepdims = false, object mean = null)

Parameters

a object

The operand: a masked array, an array or an array-like.

axis int[]

The axes to reduce, or null (NumPy's None) for every axis.

dtype DType

The accumulator / result dtype, or null for NumPy's default.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

ddof int

Delta degrees of freedom: the divisor is the count minus ddof.

keepdims bool

Keep the reduced axes with length 1.

mean object

NumPy 2's precomputed mean, or null to compute it.

Returns

NDMaskedArray

The masked variance, or out.

Exceptions

AxisError

An axis is out of range.

ValueError

A repeated axis, or an out whose shape does not match the result.

AttributeError

A 0-d result of a masked operand into a masked out (NumPy's numpy scalar has no mask).

MaskError

A masked 0-d result into a plain integer or bool out.

var(object, NDAxis?, DType, NDMaskedArray, int, bool, object)

Variance over the unmasked elements: NumPy's MaskedArray.var, statement for statement. With a mask (even an all-False one) the anomaly is formed against the MASKED mean, squared in place (danom *= danom; complex abs(danom) ** 2, masked where not finite), summed over its unmasked slots, divided by count - ddof in ma's domained divide, and then the mask is REPLACED by mask_or(self._mask.all(axis), cnt <= 0). A slice with an unmasked inf or NaN therefore gives 0.0, unmasked, and a flat result with count - ddof < 0 is a plain (negative-zero or negative) scalar. Without a mask it is numpy's _var run on a masked array (ma's divide domain on the mean and on the result; see the section header).

public NDMaskedArray var(object a, NDAxis? axis = null, DType dtype = null, NDMaskedArray @out = null, int ddof = 0, bool keepdims = false, object mean = null)

Parameters

a object

Operand: a NDMaskedArray (its mask decides the path), an NDArray, a C# array or scalar (no mask).

axis NDAxis?

The axis or axes to reduce — an int, a tuple or an int[] (negative counts from the end) — or null for every axis.

dtype DType

NumPy's dtype=. With a mask it only selects the MEAN's sum loop (the squared anomalies sum in their own dtype), so a complex dtype makes a real input's variance complex; without a mask it is _var's loop of both sums.

out NDMaskedArray

Where to write the result, or null for a new one: a masked array receives the data and the mask, a plain NDArray converts and receives the data only (NumPy reads isinstance(out, MaskedArray)).

ddof int

Delta degrees of freedom: the divisor is count - ddof (with a mask, possibly ≤ 0) or max(n - ddof, 0) (without).

keepdims bool

Keep the reduced axes with length 1.

mean object

NumPy 2's mean=, or null to compute it. With a mask it is subtracted through ma.subtract, which makes a C# number a STRONG array (int64 / float64 / complex128, as numpy.ma's getdata does); without a mask it reaches _var as given, so a C# number stays WEAK there. An NDMaskedArray mean brings its mask.

Returns

NDMaskedArray

The masked variance: NDMasked for a masked 0-d result, an unmasked 0-d scalar, or an array with NumPy's mask (null for nomask) — or out. Its dtype is float64 for every input but float16 without a mask (float16), and complex128 when dtype (or mean) is complex.

Remarks

Scoped by hand (a masked-array return): the mean, the anomaly, its squares, the sums and counts are reclaimed; only the variance's data and mask leave. out follows NumPy's statements: without a mask, numpy's _var(out=out) writes the quotient (a masked out's array_wrap fills ma's divide domain with 1 and sets its mask, which out.setmask(nomask) then clears unless it is hard; a plain out takes the plain quotient); with a mask, out.flat = dvar and out.setmask(dvar.mask), a masked 0-d result writing 0 and a full mask (NaN into a plain float out). Tuple axis, out and NumPy's parameter order since API-parity batch 8.

Exceptions

AxisError

An axis is outside the operand.

ValueError

A repeated axis, or an out of the wrong shape; and without a mask, NumPy's two failures of _var on a masked array:

  • "output array is read-only" — a 0-d operand whose mean is masked (in ma's divide domain, or a masked mean): the 0-d subtract returns the read-only masked singleton, which the next in-place ufunc writes into.
  • "Changing the dtype to a subarray type is only supported if the total itemsize is unchanged" — a complex (or bool with a complex dtype) operand whose deviation carries a mask: numpy's x.view(dtype=(f8, (2,))) cannot view that mask.
AttributeError

A 0-d result of a MASKED operand into a masked out: NumPy's out.setmask(dvar.mask) reads the mask of a numpy scalar ('numpy.float64' object has no attribute 'mask'), after the data was written.

MaskError

A masked 0-d result into a plain integer or bool out.

vstack(params object[])

Stack row-wise / along the first axis (masks alike).

public NDMaskedArray vstack(params object[] tup)

Parameters

tup object[]

Operands.

Returns

NDMaskedArray

The stacked masked array.

Remarks

The loose form (np.ma.vstack(a, b)), kept beside NumPy's vstack(object[], DType, string) as np.vstack keeps its own (the owner's call, API-parity batch 3). A lone object[] binds HERE (C#'s params rule), which is NumPy's sequence anyway.

vstack(object[], DType, string)

Stack row-wise / along the first axis — NumPy's np.ma.vstack(tup, *, dtype=None, casting='same_kind'): np.vstack over the data and over the full masks, with the same keywords.

public NDMaskedArray vstack(object[] tup, DType dtype = null, string casting = "same_kind")

Parameters

tup object[]

The operands (masked arrays, arrays, array-likes).

dtype DType

The result's dtype, or null for the operands' common type. NumPy joins the MASKS in it too (then reads them back as bool), so casting also judges the bool to dtype cast.

casting string

NumPy's casting rule for both joins: "no", "equiv", "safe", "same_kind" (the default) or "unsafe".

Returns

NDMaskedArray

A new masked array; its mask is always an array (no fill value or hardness is inherited).

Remarks

numpy.ma's _fromnxfunction_seq. Added in API-parity batch 8.

Exceptions

InvalidCastException

The data or the masks do not cast to dtype under casting, with NumPy's TypeError text (Cannot cast array data from dtype('int64') to dtype('float32') according to the rule 'no'; NumSharp's house mapping).

ValueError

The operands' shapes do not join, or an unknown casting.

where(object)

The one-argument np.ma.where(condition): NumPy's where with neither x nor y is nonzero(condition) — the indices of the non-zero, UNMASKED elements (a masked slot counts as False).

public NDArray<long>[] where(object condition)

Parameters

condition object

The condition (a masked array, an array or an array-like); read through filled(0).

Returns

NDArray<long>[]

One int64 index array per dimension (the house tuple convention), as nonzero(object).

Remarks

NumPy's "Must provide both 'x' and 'y' or neither." cannot arise: C# has no two-argument form. Added in API-parity batch 8.

Exceptions

ValueError

A 0-d condition (Calling nonzero on 0d arrays is not allowed).

where(object, object, object)

Masked where (NumPy's ma.where): picks x where the condition is True, else y; a masked or False condition selects y, and a masked condition (or a masked chosen value) masks the result.

public NDMaskedArray where(object condition, object x, object y)

Parameters

condition object

Boolean array-like selector.

x object

Values chosen where the condition is True.

y object

Values chosen where the condition is False/masked.

Returns

NDMaskedArray

The masked selection.

Remarks

Scoped by hand: the boolean condition copy, the widening casts, the three full masks and the intermediate mask selects are reclaimed; only the selected data and the final mask leave.

zeros(Shape, DType, char, string, object, bool)

Masked array of zeros (no element masked) — NumPy's np.ma.zeros(shape, dtype=None, order='C', *, device=None, fill_value=None, hardmask=False), the _convert2ma wrapper of np.zeros. float64 by default.

public NDMaskedArray zeros(Shape shape, DType dtype = null, char order = 'C', string device = null, object fill_value = null, bool hardmask = false)

Parameters

shape Shape

Result shape.

dtype DType

Element dtype (null ⇒ float64).

order char

The memory layout, 'C' (the default) or 'F' — np.zeros' own check refuses the rest.

device string

NumPy's Array-API device: null or "cpu".

fill_value object

The result's fill value, set through fill_value (converted to the dtype, so 7.9 into int64 stores 7); null leaves the dtype's default, exactly as NumPy's omitted (or None) argument does.

hardmask bool

True gives the result a HARD mask (hardmask).

Returns

NDMaskedArray

An unmasked masked array of zeros.

Remarks

The order, device, fill_value and hardmask keywords arrived in API-parity batch 7; like= is the parity plan's exclusion.

Exceptions

ValueError

An order letter NumPy does not have (checked first), or a device other than "cpu" (Device not understood. Only "cpu" is allowed, but received: gpu).

TypeError

fill_value cannot be stored in the dtype (Cannot set fill value of string with array of dtype float64, Cannot convert fill_value 300 to dtype int8).

zeros_like(object, DType, char, Shape?, string)

Masked zeros shaped like a (NumPy's ma.zeros_like, np.zeros_like of the masked array): a masked prototype lends a COPY of its mask (its masked slots stay masked over the zeros), its fill value (converted to the result dtype) and its hard-mask flag; a plain prototype gives an unmasked result.

public NDMaskedArray zeros_like(object a, DType dtype = null, char order = 'K', Shape? shape = null, string device = null)

Parameters

a object

Prototype array-like.

dtype DType

Override dtype (null ⇒ prototype's).

order char

NumPy's layout: 'K' (the default) keeps the prototype's, 'A' / 'C' / 'F' as in np.zeros_like; the copied mask follows the RESULT's layout.

shape Shape?

Override shape (null ⇒ the prototype's). A masked prototype's mask is reshaped (C order) to it when the sizes match and dropped when they do not, as NumPy's array_finalize does (self._mask.shape = self.shape, a ValueError read as "no mask").

device string

NumPy's Array-API device: null or "cpu".

Returns

NDMaskedArray

A masked array of zeros.

Remarks

NumPy's zeros_like(a, dtype=None, order='K', subok=True, shape=None, *, device=None) — subok is the parity plan's exclusion (as for np.zeros_like); order, shape and device arrived in API-parity batch 7.

Exceptions

ValueError

A bad order letter or device (np.zeros_like's checks).

TypeError

The prototype's fill cannot be converted to the result dtype: a text class that cannot encode / decode it, or a text fill a numeric dtype cannot parse (numpy.ma's Cannot convert fill_value … to dtype …).