take

take(x: array, indices: array, /, *, axis: int | None = None) → array

Returns elements of an array along an axis.

Parameters:

  • x (array) – input array. Should have one or more dimensions (axes).

  • indices (array) – array indices. The array must be one-dimensional and have an integer data type. If an index is negative, the function must determine the element to select along a specified axis (dimension) by counting from the last element (where -1 refers to the last element).

  • axis (Optional[int]) –

    axis over which to select values. If axis is negative, the function must determine the axis along which to select values by counting from the last dimension (where -1 refers to the last dimension).

    If x is a one-dimensional array, providing an axis is optional; however, if x has more than one dimension, providing an axis is required.

Returns:

out (array) – an array having the same data type as x. The output array must have the same rank (i.e., number of dimensions) as x and must have the same shape as x, except for the axis specified by axis whose size must equal the number of elements in indices.

Notes

  • Conceptually, take(x, indices, axis=3) is equivalent to x[:,:,:,indices,...]; however, explicit indexing via arrays of indices is not currently supported in this specification due to concerns regarding __setitem__ and array mutation semantics.

  • This specification does not require bounds checking. The behavior for out-of-bounds indices is left unspecified.

  • When x is a zero-dimensional array, behavior is unspecified and thus implementation-defined.

New in version 2022.12.

Changed in version 2023.12: Out-of-bounds behavior is explicitly left unspecified.

Changed in version 2024.12: Behavior when provided a zero-dimensional input array is explicitly left unspecified.

Changed in version 2024.12: Clarified support for negative indices.