pyvista.core._validation.validate.validate_array

Contents

pyvista.core._validation.validate.validate_array#

validate_array(
arr: float | ArrayLike[float],
/,
*,
must_have_shape: _ShapeLike | list[_ShapeLike] | None = None,
must_have_ndim: int | VectorLike[int] | None = None,
must_have_dtype: npt.DTypeLike | None = None,
must_have_length: int | VectorLike[int] | None = None,
must_have_min_length: int | None = None,
must_have_max_length: int | None = None,
must_be_nonnegative: bool = False,
must_be_finite: bool = False,
must_be_real: bool = True,
must_be_integer: bool = False,
must_be_sorted: bool | dict[str, Any] = False,
must_be_in_range: VectorLike[float] | None = None,
strict_lower_bound: bool = False,
strict_upper_bound: bool = False,
reshape_to: int | tuple[int, ...] | None = None,
broadcast_to: int | tuple[int, ...] | None = None,
dtype_out: npt.DTypeLike = None,
as_any: bool = True,
copy: bool = False,
to_list: bool = False,
to_tuple: bool = False,
name: str = 'Array',
)[source]#

Check and validate a numeric array meets specific requirements.

Validate an array to ensure it is numeric, has a specific shape, data-type, and/or has values that meet specific requirements such as being sorted, integer-like, or finite.

The array’s output can also be reshaped or broadcast, cast as a nested tuple or list array, or cast to a specific data type.

Parameters:
arrarray_like

Array to be validated, in any form that can be converted to a np.ndarray. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays.

must_have_shapeint | tuple[int, …] | list[int, tuple[int, …]], optional

Check if the array has a specific shape. Specify a single shape or a list of any allowable shapes. If an integer, the array must be 1-dimensional with that length. Use a value of -1 for any dimension where its size is allowed to vary. Use () to allow scalar values (i.e. 0-dimensional). Set to None if the array can have any shape (default).

must_have_ndimint | VectorLike[int], optional

Check if the array has the specified number of dimension(s). Specify a single dimension or a sequence of allowable dimensions. If a sequence, the array must have at least one of the specified number of dimensions.

must_have_dtypeDTypeLike | list[DTypeLike, …], optional

Check if the array’s data-type has the given dtype. Specify a np.dtype object or dtype-like base class which the array’s data must be a subtype of. If a list, the array’s data must be a subtype of at least one of the specified dtypes.

must_have_lengthint | VectorLike[int], optional

Check if the array has the given length. If multiple values are given, the array’s length must match one of the values.

Note

The array’s length is determined after reshaping the array (if reshape is not None) and after broadcasting (if broadcast_to is not None). Therefore, the values of length` should take the array’s new shape into consideration if applicable.

must_have_min_lengthint, optional

Check if the array’s length is this value or greater.

must_have_max_lengthint, optional

Check if the array’ length is this value or less.

must_be_nonnegativebool, default: False

Check if all elements of the array are nonnegative.

must_be_finitebool, default: False

Check if all elements of the array are finite, i.e. not infinity and not Not a Number (NaN).

must_be_realbool, default: True

Check if the array has real numbers, i.e. its data type is integer or floating.

must_be_integerbool, default: False

Check if the array’s values are integer-like (i.e. that np.all(arr, np.floor(arr))).

must_be_sortedbool | dict, default: False

Check if the array’s values are sorted. If True, the check is performed with default parameters:

  • ascending=True: the array must be sorted in ascending order

  • strict=False: sequential elements with the same value are allowed

  • axis=-1: the sorting is checked along the array’s last axis

To check for descending order, enforce strict ordering, or to check along a different axis, use a dict with keyword arguments that will be passed to check_sorted.

must_be_in_rangeVectorLike[float], optional

Check if the array’s values are all within a specific range. Range must be array-like with two elements specifying the minimum and maximum data values allowed, respectively. By default, the range endpoints are inclusive, i.e. values must be >= minimum and <= maximum. Use strict_lower_bound and/or strict_upper_bound to further restrict the allowable range.

..note

Use ``np.inf`` to check for open intervals, e.g.:

* ``[-np.inf, upper_bound]`` to check if values are less
  than (or equal to)  ``upper_bound``
* ``[lower_bound, np.inf]`` to check if values are greater
  than (or equal to) ``lower_bound``
strict_lower_boundbool, default: False

Enforce a strict lower bound for the range specified by must_be_in_range, i.e. array values must be strictly greater than the specified minimum.

strict_upper_boundbool, default: False

Enforce a strict upper bound for the range specified by must_be_in_range, i.e. array values must be strictly less than the specified maximum.

reshape_toint | tuple[int, …], optional

Reshape the output array to a new shape with np.reshape(). The shape should be compatible with the original shape. If an integer, then the result will be a 1-D array of that length. One shape dimension can be -1.

broadcast_toint | tuple[int, …], optional

Broadcast the array with np.broadcast_to() to a read-only view with the specified shape. Broadcasting is done after reshaping (if reshape_to is not None).

dtype_outDTypeLike, optional

Set the data-type of the returned array. By default, the dtype is inferred from the input data.

as_anybool, default: True

Allow subclasses of np.ndarray to pass through without making a copy.

copybool, default: False

If True, a copy of the array is returned. A copy is always returned if the array:

  • is a nested sequence

  • is a subclass of np.ndarray and as_any is False.

A copy may also be made to satisfy dtype_out requirements.

to_listbool, default: False

Return the validated array as a list or nested list. Scalar values are always returned as a Number (i.e. int or float). Has no effect if to_tuple=True.

to_tuplebool, default: False

Return the validated array as a tuple or nested tuple. Scalar values are always returned as a Number (i.e. int or float).

namestr, default: “Array”

Variable name to use in the error messages if any of the validation checks fail.

Returns:
array_like

Validated array. Returned object is:

  • an instance of np.ndarray (default), or

  • a nested list (if to_list=True), or

  • a nested tuple (if to_tuple=True), or

  • a Number (i.e. int or float) if the input is a scalar.

See also

validate_number

Specialized function for single numbers.

validate_array3

Specialized function for 3-element arrays.

validate_arrayN

Specialized function for one-dimensional arrays.

validate_arrayNx3

Specialized function for Nx3 dimensional arrays.

validate_data_range

Specialized function for data ranges.

Examples

Validate a one-dimensional array has at least length two, is monotonically increasing (i.e. has strict ascending order), and is within some range.

>>> from pyvista import _validation
>>> array_in = (1, 2, 3, 5, 8, 13)
>>> rng = (0, 20)
>>> _validation.validate_array(
...     array_in,
...     must_have_shape=(-1),
...     must_have_min_length=2,
...     must_be_sorted=dict(strict=True),
...     must_be_in_range=rng,
... )
array([ 1,  2,  3,  5,  8, 13])
Contents