arkouda.array_api.utility_functions¶

Functions¶

`all`(→ arkouda.array_api.array_object.Array)	Check whether all elements of an array evaluate to True along a given axis.
`any`(→ arkouda.array_api.array_object.Array)	Check whether any elements of an array evaluate to True along a given axis.
`clip`(→ arkouda.array_api.array_object.Array)	Clip (limit) the values in an array to a given range.
`diff`(→ arkouda.array_api.array_object.Array)	Calculate the n-th discrete difference along the given axis.
`pad`(→ arkouda.array_api.array_object.Array)	Pad an array.
`trapezoid`(→ arkouda.array_api.array_object.Array)
`trapz`(→ arkouda.array_api.array_object.Array)	Integrate along the given axis using the composite trapezoidal rule.

Module Contents¶

arkouda.array_api.utility_functions.all(x: arkouda.array_api.array_object.Array, /, *, axis: int | Tuple[int, Ellipsis] | None = None, keepdims: bool = False) → arkouda.array_api.array_object.Array[source]¶

Check whether all elements of an array evaluate to True along a given axis.

Parameters:

x (Array) – The array to check for all True values
axis (int or Tuple[int], optional) – The axis or axes along which to check for all True values. If None, check all elements.
keepdims (bool, optional) – Whether to keep the singleton dimensions along axis in the result.

arkouda.array_api.utility_functions.any(x: arkouda.array_api.array_object.Array, /, *, axis: int | Tuple[int, Ellipsis] | None = None, keepdims: bool = False) → arkouda.array_api.array_object.Array[source]¶

Check whether any elements of an array evaluate to True along a given axis.

Parameters:

x (Array) – The array to check for any True values
axis (int or Tuple[int], optional) – The axis or axes along which to check for any True values. If None, check all elements.
keepdims (bool, optional) – Whether to keep the singleton dimensions along axis in the result.

arkouda.array_api.utility_functions.clip(a: arkouda.array_api.array_object.Array, a_min, a_max, /) → arkouda.array_api.array_object.Array[source]¶

Clip (limit) the values in an array to a given range.

Parameters:

a (Array) – The array to clip
a_min (scalar) – The minimum value
a_max (scalar) – The maximum value

arkouda.array_api.utility_functions.diff(a: arkouda.array_api.array_object.Array, /, n: int = 1, axis: int = -1, prepend=None, append=None) → arkouda.array_api.array_object.Array[source]¶

Calculate the n-th discrete difference along the given axis.

Parameters:

a (Array) – The array to calculate the difference
n (int, optional) – The order of the finite difference. Default is 1.
axis (int, optional) – The axis along which to calculate the difference. Default is the last axis.
prepend (Array, optional) – Array to prepend to a along axis before calculating the difference.
append (Array, optional) – Array to append to a along axis before calculating the difference.

Returns:

diff – The n-th differences. The shape of the output is the same as a except along axis where the dimension is smaller by n. The type of the output is the same as the type of the difference between any two elements of a. This is the same as the type of a in most cases. A notable exception is datetime64, which results in a timedelta64 output array.

Return type:

ndarray

Notes

Type is preserved for boolean arrays, so the result will contain False when consecutive elements are the same and True when they differ.

For unsigned integer arrays, the results will also be unsigned. This should not be surprising, as the result is consistent with calculating the difference directly.

If this is not desirable, then the array should be cast to a larger integer type first:

Examples

>>> import arkouda as ak
>>> import arkouda.array_api as xp
>>> x = xp.asarray(ak.array([1, 2, 4, 7, 0]))
>>> xp.diff(x)
[ 1,  2,  3, -7]
>>> xp.diff(x, n=2)
[  1,   1, -10]

>>> x = xp.asarray(ak.array([[1, 3, 6, 10], [0, 5, 6, 8]]))
>>> xp.diff(x)
[[2, 3, 4], [5, 1, 2]]
>>> xp.diff(x, axis=0)
array([[-1,  2,  0, -2]])

arkouda.array_api.utility_functions.pad(array: arkouda.array_api.array_object.Array, pad_width, mode='constant', **kwargs) → arkouda.array_api.array_object.Array[source]¶

Pad an array.

Parameters:

array (Array) – The array to pad
pad_width (int or Tuple[int, int] or Tuple[Tuple[int, int], ...]) – Number of values padded to the edges of each axis. If a single int, the same value is used for all axes. If a tuple of two ints, those values are used for all axes. If a tuple of tuples, each inner tuple specifies the number of values padded to the beginning and end of each axis.
mode (str, optional) – Padding mode. Only ‘constant’ is currently supported. Use the constant_values keyword argument to specify the padding value or values (in the same format as pad_width).

arkouda.array_api.utility_functions.trapezoid(y: arkouda.array_api.array_object.Array, x: arkouda.array_api.array_object.Array | None = None, dx: float | None = 1.0, axis: int = -1) → arkouda.array_api.array_object.Array[source]¶

arkouda.array_api.utility_functions.trapz(y: arkouda.array_api.array_object.Array, x: arkouda.array_api.array_object.Array | None = None, dx: float | None = 1.0, axis: int = -1) → arkouda.array_api.array_object.Array[source]¶

Integrate along the given axis using the composite trapezoidal rule.

If x is provided, the integration happens in sequence along its elements - they are not sorted.

Integrate y (x) along each 1d slice on the given axis, compute \(\int y(x) dx\). When x is specified, this integrates along the parametric curve, computing \(\int_t y(t) dt = \int_t y(t) \left.\frac{dx}{dt}\right|_{x=x(t)} dt\).

See https://numpy.org/doc/1.26/reference/generated/numpy.trapz.html#numpy.trapz

Parameters:

y (array_like) – Input array to integrate.
x (array_like, optional) – The sample points corresponding to the y values. If x is None, the sample points are assumed to be evenly spaced dx apart. The default is None.
dx (scalar, optional) – The spacing between sample points when x is None. The default is 1.
axis (int, optional) – The axis along which to integrate.

Returns:

trapezoid – Definite integral of y = n-dimensional array as approximated along a single axis by the trapezoidal rule. If y is a 1-dimensional array, then the result is a float. If n is greater than 1, then the result is an n-1 dimensional array.

Return type:

float or pdarray

Notes

Image [2] illustrates trapezoidal rule – y-axis locations of points will be taken from y array, by default x-axis distances between points will be 1.0, alternatively they can be provided with x array or with dx scalar. Return value will be equal to combined area under the red lines.

References

Examples

>>> y = xp.asarray(ak.array([1, 2, 3]))

Use the trapezoidal rule on evenly spaced points: >>> xp.trapz(y) 4.0

The spacing between sample points can be selected by either the x or dx arguments:

>>> x = xp.asarray(ak.array([4, 6, 8]))
>>> xp.trapz(y, x)
8.0
>>> xp.trapz(y, dx=2.0)
8.0

Using a decreasing x corresponds to integrating in reverse:

>>> x = xp.asarray(ak.array([8, 6, 4]))
>>> xp.trapz(y, x)
-8.0

More generally x is used to integrate along a parametric curve. We can estimate the integral \(\int_0^1 x^2 = 1/3\) using:

>>> x = xp.linspace(0, 1, num=50)
>>> y = x**2
>>> xp.trapz(y, x)
0.33340274885464394

Or estimate the area of a circle, noting we repeat the sample which closes the curve:

>>> theta = xp.linspace(0, 2 * xp.pi, num=1000, endpoint=True)
>>> xp.trapz(xp.cos(theta), x=xp.sin(theta))
3.141571941375841

np.trapz can be applied along a specified axis to do multiple computations in one call:

>>> a = xp.asarray(ak.arange(6).reshape(2, 3))
>>> a
[[0, 1, 2], [3, 4, 5]]
>>> xp.trapz(a, axis=0)
[1.5, 2.5, 3.5]
>>> xp.trapz(a, axis=1)
[2.0,  8.0]