arkouda.array_api.manipulation_functions¶

Functions¶

`broadcast_arrays`(...)	Broadcast arrays to a common shape.
`broadcast_to`(→ arkouda.array_api.array_object.Array)	Broadcast the array to the specified shape.
`concat`(→ arkouda.array_api.array_object.Array)	Concatenate arrays along an axis.
`expand_dims`(→ arkouda.array_api.array_object.Array)	Create a new array with an additional dimension inserted at the specified axis.
`flip`(→ arkouda.array_api.array_object.Array)	Reverse an array's values along a particular axis or axes.
`moveaxis`(→ arkouda.array_api.array_object.Array)	Move axes of an array to new positions.
`permute_dims`(→ arkouda.array_api.array_object.Array)	Permute the dimensions of an array.
`repeat`(→ arkouda.array_api.array_object.Array)	Repeat elements of an array.
`reshape`(→ arkouda.array_api.array_object.Array)	Reshape an array to a new shape.
`roll`(→ arkouda.array_api.array_object.Array)	Roll the values in an array by the specified shift(s) along the specified axis or axes.
`squeeze`(→ arkouda.array_api.array_object.Array)	Remove degenerate (size one) dimensions from an array.
`stack`(→ arkouda.array_api.array_object.Array)	Stack arrays along a new axis.
`tile`(→ arkouda.array_api.array_object.Array)	Tile an array with the specified number of repetitions along each dimension.
`unstack`(→ Tuple[arkouda.array_api.array_object.Array, ...)	Decompose an array along an axis into multiple arrays of the same shape.

Module Contents¶

arkouda.array_api.manipulation_functions.broadcast_arrays(*arrays: arkouda.array_api.array_object.Array) → List[arkouda.array_api.array_object.Array][source]¶

Broadcast arrays to a common shape.

Parameters:: arrays (Array) – The arrays to broadcast. Must be broadcastable to a common shape.
Returns:: A list whose elements are the given Arrays broadcasted to the common shape.
Return type:: List
Raises:: ValueError – Raised by broadcast_to if a common shape cannot be determined.

Examples

>>> import arkouda as ak
>>> import arkouda.array_api as xp
>>> a = xp.asarray(ak.arange(10).reshape(1,2,5))
>>> b = xp.asarray(ak.arange(20).reshape(4,1,5))
>>> c = xp.broadcast_arrays(a,b)
>>> c[0][0,:,:]
Arkouda Array ((2, 5), int64)[[0 1 2 3 4] [5 6 7 8 9]]
>>> c[1][:,0,0]
Arkouda Array ((4,), int64)[0 5 10 15]

arkouda.array_api.manipulation_functions.broadcast_to(x: arkouda.array_api.array_object.Array, /, shape: Tuple[int, Ellipsis]) → arkouda.array_api.array_object.Array[source]¶

Broadcast the array to the specified shape.

Parameters:

x (Array) – The array to be broadcast.
shape (Tuple[int, ...]) – The shape to which the array is to be broadcast.

Returns:

A new array which is x broadcast to the provided shape.

Return type:

Array

Raises:

ValueError – Raised server-side if the broadcast fails.

Examples

>>> import arkouda as ak
>>> import arkouda.array_api as xp
>>> a = xp.asarray(ak.arange(5))
>>> xp.broadcast_to(a,(2,5))
Arkouda Array ((2, 5), int64)[[0 1 2 3 4] [0 1 2 3 4]]

See: https://data-apis.org/array-api/latest/API_specification/broadcasting.html for details.

arkouda.array_api.manipulation_functions.concat(arrays: Tuple[arkouda.array_api.array_object.Array, Ellipsis] | List[arkouda.array_api.array_object.Array], /, *, axis: int | None = 0) → arkouda.array_api.array_object.Array[source]¶

Concatenate arrays along an axis.

Parameters:

arrays (Tuple[Array, ...] or List[Array]) – The arrays to concatenate. Must have the same shape except along the concatenation axis.
axis (int, optional) – The axis along which to concatenate the arrays. The default is 0. If None, the arrays are flattened before concatenation.

Raises:

IndexError – Raised if axis is not a valid axis for the given arrays.
ValueError – Raised if array shapes are incompatible with concat.

Returns:

A new Array which is the concatention of the given Arrays along the given axis.

Return type:

Array

arkouda.array_api.manipulation_functions.expand_dims(x: arkouda.array_api.array_object.Array, /, *, axis: int) → arkouda.array_api.array_object.Array[source]¶

Create a new array with an additional dimension inserted at the specified axis.

Parameters:

x (Array) – The array to expand
axis (int) – The axis at which to insert the new (size one) dimension. Must be in the range [-x.ndim-1, x.ndim].

Raises:

IndexError – Raised if axis is not a valid axis for the given result.

Returns:

A new Array with a new dimension equal to 1, inserted at the given axis.

Return type:

Array

arkouda.array_api.manipulation_functions.flip(x: arkouda.array_api.array_object.Array, /, *, axis: int | Tuple[int, Ellipsis] | None = None) → arkouda.array_api.array_object.Array[source]¶

Reverse an array’s values along a particular axis or axes.

Parameters:

x (Array) – The array to flip
axis (int or Tuple[int, ...], optional) – The axis or axes along which to flip the array. If None, flip the array along all axes.

Raises:

IndexError – Raised if the axis/axes is/are invalid for the given array, or if the flip fails server-side.

Returns:

A copy of x with the results reversed along the given axis or axes.

Return type:

Array

arkouda.array_api.manipulation_functions.moveaxis(x: arkouda.array_api.array_object.Array, source: int | Tuple[int, Ellipsis], destination: int | Tuple[int, Ellipsis], /) → arkouda.array_api.array_object.Array[source]¶

Move axes of an array to new positions.

Parameters:

x (Array) – The array whose axes are to be reordered
source (int or Tuple[int, ...]) – Original positions of the axes to move. Values must be unique and fall within the range [-x.ndim, x.ndim).
destination (int or Tuple[int, ...]) – Destination positions for each of the original axes. Must be the same length as source. Values must be unique and fall within the range [-x.ndim, x.ndim).

Raises:

ValueError – Raised if source and destination are not the same type (tuple or int).
IndexError – Raised if source, destination, or both are not valid for x.ndim.

Returns:

A new Array with the axes shifted per the givern source, destination.

Return type:

Array

arkouda.array_api.manipulation_functions.permute_dims(x: arkouda.array_api.array_object.Array, /, axes: Tuple[int, Ellipsis]) → arkouda.array_api.array_object.Array[source]¶

Permute the dimensions of an array.

Parameters:

x (Array) – The array whose dimensions are to be permuted
axes (Tuple[int, ...]) – The new order of the dimensions. Must be a permutation of the integers from 0 to x.ndim-1.

Raises:

IndexError – Raised if the given axes are not a valid reordering of the axes of x.

Returns:

A copy of x with the axes permuted as per the axes argument.

Return type:

Array

arkouda.array_api.manipulation_functions.repeat(x: arkouda.array_api.array_object.Array, repeats: int | arkouda.array_api.array_object.Array, /, *, axis: int | None = None) → arkouda.array_api.array_object.Array[source]¶

Repeat elements of an array.

Parameters:

x (Array) – The array whose values to repeat
repeats (int or Array) –
The number of repetitions for each element.
- If axis is None, must be an integer, or a 1D array of integers with the same size as x.
- If axis is not None, must be an integer, or a 1D array of integers whose size matches the number of elements along the specified axis.
axis (int, optional) – The axis along which to repeat elements. If None, the array is flattened before repeating, and each element is repeated repeats times.

Raises:

NotYetImplementedError – Raised if axis arg is used.

Returns:

A new 1D array with each element of x repeated repeats times.

Return type:

Array

arkouda.array_api.manipulation_functions.reshape(x: arkouda.array_api.array_object.Array, /, shape: Tuple[int, Ellipsis], *, copy: bool | None = None) → arkouda.array_api.array_object.Array[source]¶

Reshape an array to a new shape.

Parameters:

x (Array) – The array to reshape
shape (Tuple[int, ...]) – The new shape for the array. Must have the same number of elements as the original array.
copy (bool, optional) – Whether to create a copy of the array. WARNING: currently always creates a copy, ignoring the value of this parameter.

Raises:

ValueError – Raised if the given shape is invalid, or if more than one unknown dimension is specified.

Returns:

A reshaped version of x, as specified in shape.

Return type:

Array

arkouda.array_api.manipulation_functions.roll(x: arkouda.array_api.array_object.Array, /, shift: int | Tuple[int, Ellipsis], *, axis: int | Tuple[int, Ellipsis] | None = None) → arkouda.array_api.array_object.Array[source]¶

Roll the values in an array by the specified shift(s) along the specified axis or axes. Elements that roll beyond the last position are re-introduced at the first position.

Parameters:

x (Array) – The array to roll
shift (int or Tuple[int, ...]) – The number of positions by which to shift each axis. If axis and shift are both tuples, they must have the same length and the i-th element of shift is the number of positions to shift axis[i]. If axis is a tuple and shift is an integer, the same shift is applied to each axis. If axis is None, must be an integer or a one-tuple.
axis (int or Tuple[int, ...], optional) – The axis or axes along which to roll the array. If None, the array is flattened before rolling.

Raises:

IndexError – Raised if the axis/axes aren’t valid for the given array, or if axis and shift are both tuples but not of the same length, or if roll fails server-side.

Returns:

An array with the same shape as x, but with elements shifted as per axis and shift.

Return type:

Array

arkouda.array_api.manipulation_functions.squeeze(x: arkouda.array_api.array_object.Array, /, axis: int | Tuple[int, Ellipsis]) → arkouda.array_api.array_object.Array[source]¶

Remove degenerate (size one) dimensions from an array.

Parameters:

x (Array) – The array to squeeze
axis (int or Tuple[int, ...]) – The axis or axes to squeeze (must have a size of one).

Returns:

The input array, but with the axes specified in axis (which must be of length 1) removed.

Return type:

Array

arkouda.array_api.manipulation_functions.stack(arrays: Tuple[arkouda.array_api.array_object.Array, Ellipsis] | List[arkouda.array_api.array_object.Array], /, *, axis: int = 0) → arkouda.array_api.array_object.Array[source]¶

Stack arrays along a new axis.

The resulting array will have one more dimension than the input arrays with a size equal to the number of input arrays.

Parameters:

arrays (Tuple[Array, ...] or List[Array]) – The arrays to stack. Must have the same shape.
axis (int, optional) – The axis along which to stack the arrays. Must be in the range [-N, N), where N is the number of dimensions in the input arrays. The default is 0.

Raises:

ValueError – Raised if the arrays aren’t all the same shape.
IndexError – Raised if axis isn’t valid for the given arrays.

Returns:

A stacked array with rank 1 greater than the input arrays.

Return type:

Array

arkouda.array_api.manipulation_functions.tile(x: arkouda.array_api.array_object.Array, repetitions: Tuple[int, Ellipsis], /) → arkouda.array_api.array_object.Array[source]¶

Tile an array with the specified number of repetitions along each dimension.

Parameters:

x (Array) – The array to tile
repetitions (Tuple[int, ...]) – The number of repetitions along each dimension. If there are more repetitions than array dimensions, singleton dimensions are prepended to the array to make it match the number of repetitions. If there are more array dimensions than repetitions, ones are prepended to the repetitions tuple to make its length match the number of array dimensions.

Returns:

The tiled output array.

Return type:

Array

arkouda.array_api.manipulation_functions.unstack(x: arkouda.array_api.array_object.Array, /, *, axis: int = 0) → Tuple[arkouda.array_api.array_object.Array, Ellipsis][source]¶

Decompose an array along an axis into multiple arrays of the same shape.

Parameters:

x (Array) – The array to unstack
axis (int, optional) – The axis along which to unstack the array. The default is 0.

Raises:

IndexError – Raised if the axis is not valid for the given Array.

Returns:

A Tuple of unstacked Arrays.

Return type:

Tuple