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 arraylike 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 catchall 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 nonfinite elements (np.inf), viceversa 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), viceversa if hasnan is True. If hasnan is None elements of var are not probed for wellposedness.
lims (None or twoelement list_like) – Lower (lims[0]) and upper (lims[1]) bounds for legal values of var’s elements. Note that the code checks for nonstrict inequality, i.e., var[i] = lims[0] or var[i] = lims[1] are both considered to be valid elements of var. For complex arrays boundschecking 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 nonnumeric entries, respectively. If lims is None boundschecking 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 1darray (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 1darray (or 2darray with a single singletondimension, i.e., a row or columnvector) 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
Examples
Assume time is supposed to be a 1darray 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 rowvector 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 boundschecking is performed componentwise 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,))
See also
scalar_parser()
similar functionality for parsing numeric scalars