Numpy nonzero/flatnonzero index order; order of returned elements in boolean indexing

Question

I'm wondering about the order of indices returned by numpy.nonzero / numpy.flatnonzero.

I couldn't find anything in the docs about it. It just says:

A[nonzero(flag)] == A[flag]

While in most cases this is enough, there are some when you need a sorted list of indices. Is it guaranteed that returned indices are sorted in case of 1-D or I need to sort them explicitly? (A similar question is the order of elements returned simply by selecting with a boolean array (A[flag]) which must be the same according to the docs.)

Example: finding the "gaps" between True elements in flag:

flag=np.array([True,False,False,True],dtype=bool)
iflag=flatnonzero(flag)
gaps= iflag[1:] - iflag[:-1]

Thanks.

Answer 1

Given the specification for advanced (or "fancy") indexing with integers , the guarantee that A[nonzero(flag)] == A[flag] is also a guarantee that the values are sorted low-to-high in the 1-d case. However, in higher dimensions, the result (while "sorted") has a different structure than you might expect.

In short, given a 1-dimensional array of integers ind and a 1-dimensional array x to be indexed, we have the following for all valid i defined for ind :

result[i] = x[ind[i]]

result takes the shape of ind , and contains the values of x at the indices indicated by ind . This means that we can deduce that if x[flag] maintains the original order of x , and if x[nonzero(flag)] is the same as x[flag] , then nonzero(flag) must always produce indices in sorted order.

The only catch is that for multidimensional arrays, the indices are stored as distinct arrays for each dimension being indexed. So in other words,

x[array([0, 1, 2]), array([0, 0, 0])]

is equal to

array([x[0, 0], x[1, 0], x[2, 0]])

The values are still sorted, but each dimension is broken out into its own array. (You can do interesting things with broadcasting as a result; but that's beyond the scope of this answer.)

The only problem with this line of reasoning is that -- to my great surprise -- I can't find an explicit statement guaranteeing that boolean indexing preserves the original order of the array. Nonetheless, I'm quite certain from experience that it does. More generally, it would be unbelievably perverse to have x[[True, True, True]] return a reversed version of x .