syncopy.shared.parsers.array_parser#

syncopy.shared.parsers.array_parser(var, varname='', ntype=None, hasinf=None, hasnan=None, lims=None, dims=None, issorted=None)[source]#

Parse array-like objects

Parameters:

var (array_like) – Array object to verify
varname (str) – Local variable name used in caller, see Examples for details.
ntype (None or str) – Expected data type of var. Possible options are any valid builtin type, all NumPy dtypes as as well as “numeric” (a catch-all to ensure var only contains numeric elements) and “int_like”` (all elements of var are expected to have no significant digits after the decimal point, e.g., 3.0, -12.0 etc.). If ntype is None the data type of var is not checked.
hasinf (None or bool) – If hasinf is False the input array var is considered invalid if it contains non-finite elements (np.inf), vice-versa if hasinf is True. If hasinf is None elements of var are not probed for finiteness.
hasnan (None or bool) – If hasnan is False the input array var is considered invalid if it contains undefined elements (np.nan), vice-versa if hasnan is True. If hasnan is None elements of var are not probed for well-posedness.
lims (None or two-element list_like) – Lower (lims[0]) and upper (lims[1]) bounds for legal values of var’s elements. Note that the code checks for non-strict inequality, i.e., var[i] = lims[0] or var[i] = lims[1] are both considered to be valid elements of var. For complex arrays bounds-checking is performed on both real and imaginary parts of each component of var. That is, all elements of var have to satisfy lims[0] <= var[i].real <= lims[1] as well as lims[0] <= var[i].imag <= lims[1] (see Examples for details). Note that np.inf and np.nan entries are ignored during bounds- checking. Use the keywords hasinf and hasnan to probe an array for infinite and non-numeric entries, respectively. If lims is None bounds-checking is not performed.
dims (None or int or tuple) – Expected number of dimensions (if dims is an integer) or shape (if dims is a tuple) of var. By default, singleton dimensions of var are ignored if dims is a tuple, i.e., for dims = (10, ) an array var with var.shape = (10, 1) is considered valid. However, if singleton dimensions are explicitly queried by setting dims = (10, 1) any array var with var.shape = (10, ) or var.shape = (1, 10) is considered invalid. Unknown dimensions can be represented as None, i.e., for dims = (10, None) arrays with shape (10, 1), (10, 100) or (10, 0) are all considered valid, however, any 1d-array (e.g., var.shape = (10,)) is invalid. If dims is an integer, var.ndim has to match dims exactly, i.e., any array var with var.shape = (10, ) is considered invalid if dims = 2 and conversely, dims = 1 and var.shape = (10, 1) triggers an exception.
issorted (None or bool) – If issorted is True, var is expected to be a 1d-array (or 2d-array with a single singleton-dimension, i.e., a row- or column-vector) with elements in ascending order. Conversely, if issorted is False, var is considered invalid if its elements are ordered by magnitude. If issorted is None, order of array elements is not inspected.

Returns:

Nothing

Return type:

None

Examples

Assume time is supposed to be a 1d-array with floating point components bounded by 0 and 10. The following calls confirm the validity of time

>>> time = np.linspace(0, 10, 100)
>>> array_parser(time, varname="time", lims=[0, 10], dims=1)
>>> array_parser(time, varname="time", lims=[0, 10], dims=(100,))

Ensure additionally that all elements of time are ordered by magnitude

>>> array_parser(time, varname="time", lims=[0, 10], dims=(100,), issorted=True)

Artificially appending a singleton dimension to time does not affect parsing:

>>> time = time[:,np.newaxis]
>>> time.shape
(100, 1)
>>> array_parser(time, varname="time", lims=[0, 10], dims=(100,), issorted=True)

However, explicitly querying for a row-vector fails

>>> array_parser(time, varname="time", lims=[0, 10], dims=(1,100))

Complex arrays are parsed analogously:

>>> spec = np.array([np.complex(2,3), np.complex(2,-2)])
>>> array_parser(spec, varname="spec", dims=1)
>>> array_parser(spec, varname="spec", dims=(2,))

Note that bounds-checking is performed component-wise on both real and imaginary parts:

>>> array_parser(spec, varname="spec", lims=[-3, 5])    # valid
>>> array_parser(spec, varname="spec", lims=[-1, 5])    # invalid since spec[1].imag < lims[0]

However, complex numbers do not admit an order relationship:

>>> array_parser(spec, varname="spec", lims=[-3, 5], issorted=True)  # invalid

Character lists can be parsed as well:

>>> channels = ["channel1", "channel2", "channel3"]
>>> array_parser(channels, varname="channels", dims=1)
>>> array_parser(channels, varname="channels", dims=(3,))

syncopy.shared.parsers.array_parser

Contents

syncopy.shared.parsers.array_parser#