colour.utilities.index_along_last_axis

colour.utilities.index_along_last_axis(a: ArrayLike, indexes: ArrayLike) → ndarray[Any, dtype[_ScalarType_co]]

Reduce the dimension of array \(a\) by one, by using an array of indexes to pick elements off the last axis.

Parameters:

• a (ArrayLike) – Array \(a\) to be indexed.

• indexes (ArrayLike) – integer array with the same shape as a but with one dimension fewer, containing indices to the last dimension of a. All elements must be numbers between 0 and m - 1.

Returns:

Indexed array \(a\).

Return type:

numpy.ndarray

Raises:

• ValueError – If the array \(a\) and indexes have incompatible shapes.

• IndexError – If indexes has elements outside of the allowed range of 0 to m - 1 or if it’s not an integer array.

Examples

>>> a = np.array(
...     [
...         [
...             [0.3, 0.5, 6.9],
...             [3.3, 4.4, 1.6],
...             [4.4, 7.5, 2.3],
...             [2.3, 1.6, 7.4],
...         ],
...         [
...             [2.0, 5.9, 2.8],
...             [6.2, 4.9, 8.6],
...             [3.7, 9.7, 7.3],
...             [6.3, 4.3, 3.2],
...         ],
...         [
...             [0.8, 1.9, 0.7],
...             [5.6, 4.0, 1.7],
...             [6.7, 8.2, 1.7],
...             [1.2, 7.1, 1.4],
...         ],
...         [
...             [4.0, 4.8, 8.9],
...             [4.0, 0.3, 6.9],
...             [3.5, 7.1, 4.5],
...             [1.4, 1.9, 1.6],
...         ],
...     ]
... )
>>> indexes = np.array([[2, 0, 1, 1], [2, 1, 1, 0], [0, 0, 1, 2], [0, 0, 1, 2]])
>>> index_along_last_axis(a, indexes)
array([[ 6.9,  3.3,  7.5,  1.6],
       [ 2.8,  4.9,  9.7,  6.3],
       [ 0.8,  5.6,  8.2,  1.4],
       [ 4. ,  4. ,  7.1,  1.6]])

This function can be used to compute the result of np.min() along the last axis given the corresponding np.argmin() indexes.

>>> indexes = np.argmin(a, axis=-1)
>>> np.array_equal(index_along_last_axis(a, indexes), np.min(a, axis=-1))
True

In particular, this can be used to manipulate the indexes given by functions like np.min() before indexing the array. For example, to get elements directly following the smallest elements:

>>> index_along_last_axis(a, (indexes + 1) % 3)
array([[ 0.5,  3.3,  4.4,  7.4],
       [ 5.9,  8.6,  9.7,  6.3],
       [ 0.8,  5.6,  6.7,  7.1],
       [ 4.8,  6.9,  7.1,  1.9]])