python - What does `x[False]` do in numpy?

Question

Say I have an array x = np.arange(6).reshape(3, 2).

What is the meaning of x[False], or x[np.asanyarray(False)]? Both result in array([], shape=(0, 3, 2), dtype=int64), which is unexpected.

I expected to get an IndexError because of an improperly sized mask, as from something like x[np.ones((2, 2), dtype=np.bool)].

This behavior is consistent for x[True] and x[np.asanyarray(True)], as both result in an additional dimension: array([[[0, 1], [2, 3], [4, 5]]]).

I am using numpy 1.13.1. It appears that the behavior has changed recently, so while it is nice to have answers for older versions, please mention your version in the answers.

EDIT

Just for completeness, I filed https://github.com/numpy/numpy/issues/9515 based on the commentary on this question.

EDIT 2

And closed it almost immeditely.

Answer 1

There's technically no requirement that the dimensionality of a mask match the dimensionality of the array you index with it. (In previous versions, there were even fewer restrictions, and you could get away with some extreme shape mismatches.)

The docs describe boolean indexing as

A single boolean index array is practically identical to x[obj.nonzero()] where, as described above, obj.nonzero() returns a tuple (of length obj.ndim) of integer index arrays showing the True elements of obj.

but nonzero is weird for 0-dimensional input, so this case is one of the ways that "practically identical" turns out to be not identical:

the nonzero equivalence for Boolean arrays does not hold for zero dimensional boolean arrays.

NumPy has a special case for a 0-dimensional boolean index, motivated by the desire to have the following behavior:

In [3]: numpy.array(3)[True]
Out[3]: array([3])

In [4]: numpy.array(3)[False]
Out[4]: array([], dtype=int64)

I'll refer to a comment in the source code that handles a 0-dimensional boolean index:

if (PyArray_NDIM(arr) == 0) {
    /*
     * This can actually be well defined. A new axis is added,
     * but at the same time no axis is "used". So if we have True,
     * we add a new axis (a bit like with np.newaxis). If it is
     * False, we add a new axis, but this axis has 0 entries.
     */

While this is primarily intended for a 0-dimensional index to a 0-dimensional array, it also applies to indexing multidimensional arrays with booleans. Thus,

x[True]

is equivalent to x[np.newaxis], producing a result with a new length-1 axis in front, and

x[False]

produces a result with a new axis in front of length 0, selecting no elements.