User guide

NumPy User Guide, Release 1.9.0

>>> y[np.array([0,2,4]), np.array([0,1,2])]

array([ 0, 15, 30])

In this case, if the index arrays have a matching shape, and there is an index array for each dimension of the array

being indexed, the resultant array has the same shape as the index arrays, and the values correspond to the index set

for each position in the index arrays. In this example, the ﬁrst index value is 0 for both index arrays, and thus the ﬁrst

value of the resultant array is y[0,0]. The next value is y[2,1], and the last is y[4,2].

If the index arrays do not have the same shape, there is an attempt to broadcast them to the same shape. If they cannot

be broadcast to the same shape, an exception is raised:

>>> y[np.array([0,2,4]), np.array([0,1])]

<type ’exceptions.ValueError’>: shape mismatch: objects cannot be

broadcast to a single shape

The broadcasting mechanism permits index arrays to be combined with scalars for other indices. The effect is that the

scalar value is used for all the corresponding values of the index arrays:

>>> y[np.array([0,2,4]), 1]

array([ 1, 15, 29])

Jumping to the next level of complexity, it is possible to only partially index an array with index arrays. It takes a bit

of thought to understand what happens in such cases. For example if we just use one index array with y:

>>> y[np.array([0,2,4])]

array([[ 0, 1, 2, 3, 4, 5, 6],

[14, 15, 16, 17, 18, 19, 20],

[28, 29, 30, 31, 32, 33, 34]])

What results is the construction of a new array where each value of the index array selects one row from the array

being indexed and the resultant array has the resulting shape (size of row, number index elements).

An example of where this may be useful is for a color lookup table where we want to map the values of an image into

RGB triples for display. The lookup table could have a shape (nlookup, 3). Indexing such an array with an image with

shape (ny, nx) with dtype=np.uint8 (or any integer type so long as values are with the bounds of the lookup table) will

result in an array of shape (ny, nx, 3) where a triple of RGB values is associated with each pixel location.

In general, the shape of the resulant array will be the concatenation of the shape of the index array (or the shape that

all the index arrays were broadcast to) with the shape of any unused dimensions (those not indexed) in the array being

indexed.

2.4.6 Boolean or “mask” index arrays

Boolean arrays used as indices are treated in a different manner entirely than index arrays. Boolean arrays must be

of the same shape as the initial dimensions of the array being indexed. In the most straightforward case, the boolean

array has the same shape:

>>> b = y>20

>>> y[b]

array([21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34])

The result is a 1-D array containing all the elements in the indexed array corresponding to all the true elements in the

boolean array. As with index arrays, what is returned is a copy of the data, not a view as one gets with slices.

The result will be multidimensional if y has more dimensions than b. For example:

>>> b[:,5] # use a 1-D boolean whose first dim agrees with the first dim of y

array([False, False, False, True, True], dtype=bool)

2.4. Indexing 23