Numpy multi-dimensional array indexing swaps axis order

I am working with multi-dimensional Numpy arrays. I have noticed some inconsistent behavior when accessing these arrays with other index arrays. For example:

import numpy as np
start = np.zeros((7,5,3))
a     = start[:,:,np.arange(2)]
b     = start[0,:,np.arange(2)]
c     = start[0,:,:2]
print 'a:', a.shape
print 'b:', b.shape
print 'c:', c.shape

In this example, I get the result:

a: (7, 5, 2)
b: (2, 5)
c: (5, 2)

This confuses me. Why do “b” and “c” not have the same dimensions? Why does “b” swap the axis order, but not “a”?

I have been able to design my code around these inconsistencies thanks to lots of unit tests, but understanding what is going on would be appreciated.

For reference, I am using Python 2.7.3, and Numpy 1.6.2 via MacPorts.

Best answer

Syntactically, this looks like an inconsistency, but semantically, you’re doing two very different things here. In your definition of a and b, you’re doing advanced indexing, sometimes called fancy indexing, which returns a copy of the data. In your definition of c, you’re doing basic slicing, which returns a view of the data.

To tell the difference, it helps to understand how indices are passed to python objects. Here are some examples:

>>> class ShowIndex(object):
...     def __getitem__(self, index):
...         print index
... 
>>> ShowIndex()[:,:]
(slice(None, None, None), slice(None, None, None))
>>> ShowIndex()[...,:]
(Ellipsis, slice(None, None, None))
>>> ShowIndex()[0:5:2,::-1]
(slice(0, 5, 2), slice(None, None, -1))
>>> ShowIndex()[0:5:2,np.arange(3)]
(slice(0, 5, 2), array([0, 1, 2]))
>>> ShowIndex()[0:5:2]
slice(0, 5, 2)
>>> ShowIndex()[5, 5]
(5, 5)
>>> ShowIndex()[5]
5
>>> ShowIndex()[np.arange(3)]
[0 1 2]

As you can see, there are many different possible configurations. First, individual items may be passed, or tuples of items may be passed. Second, the tuples may contain slice objects, Ellipsis objects, plain integers, or numpy arrays.

Basic slicing is activated when you pass only objects like int, slice, or Ellipsis objects, or None (which is the same as numpy.newaxis). These can be passed singly or in a tuple. Here’s what the docs have to say about how basic slicing is activated:

Basic slicing occurs when obj is a slice object (constructed by start:stop:step notation inside of brackets), an integer, or a tuple of slice objects and integers. Ellipsis and newaxis objects can be interspersed with these as well. In order to remain backward compatible with a common usage in Numeric, basic slicing is also initiated if the selection object is any sequence (such as a list) containing slice objects, the Ellipsis object, or the newaxis object, but no integer arrays or other embedded sequences.

Advanced indexing is activated when you pass a numpy array, a non-tuple sequence containing only integers or containing subsequences of any kind, or a tuple containing an array or subsequence.

For details on how advanced indexing and basic slicing differ, see the docs (linked to above). But in this particular case, it’s clear to me what’s happening. It has to do with the following behavior when using partial indexing:

The rule for partial indexing is that the shape of the result (or the interpreted shape of the object to be used in setting) is the shape of x with the indexed subspace replaced with the broadcasted indexing subspace. If the index subspaces are right next to each other, then the broadcasted indexing space directly replaces all of the indexed subspaces in x. If the indexing subspaces are separated (by slice objects), then the broadcasted indexing space is first, followed by the sliced subspace of x.

In your definition of a, which uses advanced indexing, you effectively pass the sequence [0, 1] in as the third item of the tuple, and since no broadcasting happens (because there is no other sequence), everything happens as expected.

In your definition of b, also using advanced indexing, you effectively pass two sequences, [0], the first item (which is converted into an intp array), and [0, 1], the third item. These two items are broadcast together, and the result has the same shape as the third item. However, since broadcasting has happened, we’re faced with a problem: where in the new shape tuple do we insert the broadcasted shape? As the docs say,

there is no unambiguous place to drop in the indexing subspace, thus it is tacked-on to the beginning.

So the 2 that results from broadcasting is moved to the beginning of the shape tuple, producing an apparent transposition.