\chapter{Array Indexing}
\label{cha:array-indexing}

This chapter discusses the rich and varied ways of indexing numarray
objects to specify individual elements, sub-arrays, sub-samplings, and
even random collections of elements.

\section{Getting and Setting array values}
\label{sec:get-set-array-values}

Just like other Python sequences, array contents are manipulated with the
\code{[]} notation. For rank-1 arrays, there are no differences between list
and array notations:
\begin{verbatim}
>>> a = arange(10)
>>> print a[0]                          # get first element
0
>>> print a[1:5]                        # get second through fifth elements
[1 2 3 4]
>>> print a[-1]                         # get last element
9
>>> print a[:-1]                        # get all but last element
[0 1 2 3 4 5 6 7 8]
\end{verbatim}
If an array is multidimensional (of rank > 1), then specifying a single 
integer index will return an array of
dimension one less than the original array.

\begin{verbatim}
>>> a = arange(9, shape=(3,3))
>>> print a
[[0 1 2]
 [3 4 5]
 [6 7 8]]
>>> print a[0]                          # get first row, not first element!
[0 1 2]
>>> print a[1]                          # get second row
[3 4 5]
\end{verbatim}
To get to individual elements in a rank-2 array, one specifies both indices
separated by commas:
\begin{verbatim}
>>> print a[0,0]                        # get element at first row, first column
0
>>> print a[0,1]                        # get element at first row, second column
1
>>> print a[1,0]                        # get element at second row, first column
3
>>> print a[2,-1]                       # get element at third row, last column
8
\end{verbatim}
Of course, the \code{[]} notation can be used to set values as well:
\begin{verbatim}
>>> a[0,0] = 123
>>> print a
[[123   1   2]
 [  3   4   5]
 [  6   7   8]]
\end{verbatim}
Note that when referring to rows, the right hand side of the equal sign needs
to be a sequence which ``fits'' in the referred array subset, as described 
by the broadcast rule (in the code sample below, a 3-element row):
\begin{verbatim}
>>> a[1] = [10,11,12] ; print a
[[123   1   2]
 [ 10  11  12]
 [  6   7   8]]
>>> a[2] = 99 ; print a
[[123   1   2]
 [ 10  11  12]
 [ 99  99  99]]
\end{verbatim}

Note also that when assigning floating point values to integer arrays that
the values are silently truncated:
\begin{verbatim}
>>> a[1] = 93.999432
[[123   1   2]
 [ 93  93  93]
 [ 99  99  99]]
\end{verbatim}

\newpage
\section{Slicing Arrays}
\label{sec:slicing-arrays}

The standard rules of Python slicing apply to arrays, on a per-dimension basis.
Assuming a 3x3 array:
\begin{verbatim}
>>> a = reshape(arange(9),(3,3))
>>> print a
[[0 1 2]
 [3 4 5]
 [6 7 8]]
\end{verbatim}
The plain \code{[:]} operator slices from beginning to end:
\begin{verbatim}
>>> print a[:,:]
[[0 1 2]
 [3 4 5]
 [6 7 8]]
\end{verbatim}
In other words, \code{[:]} with no arguments is the same as \code{[:]} for
lists --- it can be read ``all indices along this axis''.  (Actually, there is
an important distinction; see below.) So, to get the second row along the
second dimension:
\begin{verbatim}
>>> print a[:,1]
[1 4 7]
\end{verbatim}
Note that what was a ``column'' vector is now a ``row'' vector.  Any ``integer
slice'' (as in the 1 in the example above) results in a returned array with
rank one less than the input array.  

There is one important distinction between
slicing arrays and slicing standard Python sequence objects. A slice of a
\class{list} is a new copy of that subset of the \class{list}; a slice of an
array is just a view into the data of the first array.  To force a copy, you
can use the \function{copy} method. For example:
\begin{verbatim}
>>> a = arange (20)
>>> b = a[3:8]
>>> c = a[3:8].copy()
>>> a[5] = -99
>>> print b
[  3   4 -99   6   7]
>>> print c
[3 4 5 6 7]
\end{verbatim}
If one does not specify as many slices as there are dimensions in an array,
then the remaining slices are assumed to be ``all''. If \var{A} is a rank-3
array, then
\begin{verbatim}
A[1] == A[1,:] == A[1,:,:]
\end{verbatim}
An additional slice notation for arrays which does not exist for Python
lists (before Python 2.3), i. e. the optional third argument, meaning 
the ``step size'', also called \index{stride}stride or increment. Its 
default value is 1, meaning return every element in the specified range.  
Alternate values allow one to skip some of the elements in the slice:
\begin{verbatim}
>>> a = arange(12)
>>> print a
[ 0  1  2  3  4  5  6  7  8  9 10 11]
>>> print a[::2]                        # return every *other* element
[ 0  2  4  6  8 10]
\end{verbatim}
\index{stride!Negative}Negative strides are allowed as long as the starting
index is greater than the stopping index:
\begin{verbatim}
>>> a = reshape(arange(9),(3,3))                                                                                          Array Basics
>>> print a
[[0 1 2]
 [3 4 5]
 [6 7 8]]
>>> print a[:, 0]
[0 3 6]
>>> print a[0:3, 0]
[0 3 6]
>>> print a[2::-1, 0]
[6 3 0]
\end{verbatim}
If a negative stride is specified and the starting or stopping indices are
omitted, they default to ``end of axis'' and ``beginning of axis''
respectively.  Thus, the following two statements are equivalent for the array
given:
\begin{verbatim}
>>> print a[2::-1, 0]
[6 3 0]
>>> print a[::-1, 0]
[6 3 0]
>>> print a[::-1]                       # this reverses only the first axis
[[6 7 8]
 [3 4 5]
 [0 1 2]]
>>> print a[::-1,::-1]                  # this reverses both axes
[[8 7 6]
 [5 4 3]
 [2 1 0]]
\end{verbatim}
One final way of slicing arrays is with the keyword \samp{...} This keyword is
somewhat complicated. It stands for ``however many `:' I need depending on the
rank of the object I'm indexing, so that the indices I \emph{do} specify are at
the end of the index list as opposed to the usual beginning''.

So, if one has a rank-3 array \var{A}, then \code{A[...,0]} is the same thing
as \code{A[:,:,0]}, but if \var{B} is rank-4, then \code{B[...,0]} is the same
thing as: \code{B[:,:,:,0]}. Only one \samp{...} is expanded in an index
expression, so if one has a rank-5 array \var{C}, then \code{C[...,0,...]} is
the same thing as \code{C[:,:,:,0,:]}.

When assigment source and destination locations overlap, i.e. when an array is
assigned onto itself at overlapping indices, it may produce something
"surprising":

\begin{verbatim}
>>> n=numarray.arange(36)
>>> n[11:18]=n[7:14]
>>> n
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10,  7,  8,  9, 10,  7,
        8,  9, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31,
       32, 33, 34, 35])
\end{verbatim}

If the slice on the right hand side (RHS) is AFTER that on the left hand side
(LHS) for 1-D array, then it works fine:

\begin{verbatim}
>>> n=numarray.arange(36)
>>> n[1:8]=n[7:14]       
>>> n
array([ 0,  7,  8,  9, 10, 11, 12, 13,  8,  9, 10, 11, 12, 13, 14, 15,
       16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31,
       32, 33, 34, 35])
\end{verbatim}

Actually, this behavior can be undedrstood if we follow the pixel by pixel
copying logic.  Parts of the slice start to get the "updated" values when the
RHS is before the LHS.

An easy solution which is guaranteed to work is to use the copy() method on the
righ hand side:

\begin{verbatim}
>>> n=numarray.arange(36)
>>> n[11:18]=n[7:14].copy()
>>> n
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10,  7,  8,  9, 10, 11,
       12, 13, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31,
       32, 33, 34, 35])
\end{verbatim}

\newpage
\section{Pseudo Indices}
This section discusses pseudo-indices, which allow arrays to have their shapes
modified by adding axes, sometimes only for the duration of the evaluation of a
Python expression.

Consider multiplication of a rank-1 array by a scalar:
\begin{verbatim}
>>> a = array([1,2,3])
>>> print a * 2
[2 4 6]
\end{verbatim}
This should be trivial by now; we've just multiplied a rank-1 array by a
scalar . The scalar was converted to a rank-0 array which was then broadcast to
the next rank. This works for adding some two rank-1 arrays as well:
\begin{verbatim}
>>> print a
[1 2 3]
>>> a + array([4])
[5 6 7]
\end{verbatim}
but it won't work if either of the two rank-1 arrays have non-matching
dimensions which aren't 1.  In other words, broadcast only works for
dimensions which are either missing (e.g. a lower-rank array) or for dimensions
of 1.

With this in mind, consider a classic task, matrix multiplication. Suppose we
want to multiply the row vector [10,20] by the column vector [1,2,3].
\begin{verbatim}
>>> a = array([10,20])
>>> b = array([1,2,3])
>>> a * b
ValueError: Arrays have incompatible shapes
\end{verbatim}
% In "This makes sense - we're ..." the hyphen disappears in the PDF.
This makes sense: we're trying to multiply a rank-1 array of shape (2,) with a
rank-1 array of shape (3,). This violates the laws of broadcast. What we really
want to do is make the second vector a vector of shape (3,1), so that the first
vector can be broadcast across the second axis of the second vector. One way to
do this is to use the reshape function:
\begin{verbatim}
>>> a.getshape()
(2,)
>>> b.getshape()
(3,)
>>> b2 = reshape(b, (3,1))
>>> print b2
[[1]
 [2]
 [3]]
>>> b2.getshape()
(3, 1)
>>> print a * b2    # Note: b2 * a gives the same result
[[10 20]
 [20 40]
 [30 60]]
\end{verbatim}
This is such a common operation that a special feature was added (it turns out
to be useful in many other places as well) -- the NewAxis "pseudo-index",
originally developed in the Yorick language. NewAxis is an index, just like
integers, so it is used inside of the slice brackets []. It can be thought of
as meaning "add a new axis here," in much the same ways as adding a 1 to an
array's shape adds an axis. Again, examples help clarify the situation:
\begin{verbatim}
>>> print b
[1 2 3]
>>> b.getshape()
(3,)
>>> c = b[:, NewAxis]
>>> print c
[[1]
 [2]
 [3]]
>>> c.getshape()
(3,1)
\end{verbatim}
Why use such a pseudo-index over the reshape function or setshape assignments?
Often one doesn't really want a new array with a new axis, one just wants it
for an intermediate computation. Witness the array multiplication mentioned
above, without and with pseudo-indices:
\begin{verbatim}
>>> without = a * reshape(b, (3,1))
>>> with = a * b[:,NewAxis]
\end{verbatim}
The second is much more readable (once you understand how NewAxis works), and
it's much closer to the intended meaning. Also, it's independent of the
dimensions of the array b. You might counter that using something like
reshape(b, (-1,1)) is also dimension-independent, but 
it's less readable and impossible with rank-3 or higher arrays? The
NewAxis-based idiom also works nicely with higher rank arrays, and with the ...
"rubber index" mentioned earlier. Adding an axis before the last axis in an
array can be done simply with:
\begin{verbatim}
>>> a[...,NewAxis,:]
\end{verbatim}
Note that \code{NewAxis} is a \code{numarray} object, so if you used 
\code{import numarray} instead of \code{from numarray import *}, you'll 
need \code{numarray.NewAxis}.

\newpage
\section{Index Arrays}
\label{sec:index-arrays}

Arrays used as subscripts have special meanings which implicitly invoke the
functions \function{put} (page \pageref{func:put}), \function{take} (page
\pageref{func:take}), or \function{compress} (page \pageref{func:compress}). If
the array is of \class{Bool} type, then the indexing will be treated as the
equivalent of the compress function. If the array is of an integer type, then a
\function{take} or \function{put} operation is implied. We will generalize the
existing take and put as follows: If \var{ind1}, \var{ind2}, ...  \var{indN}
are index arrays (arrays of integers whose values indicate the index into
another array), then \code{x[ind1, ind2]} forms a new array with the same shape
as \var{ind1}, \var{ind2} (they all must be broadcastable to the same shape)
and values such: \samp{result[i,j,k] = x[ind1[i,j,k], ind2[i,j,k]]} In this
example, \var{ind1}, \var{ind2} are index arrays with 3 dimensions (but they
could have an arbitrary number of dimensions).  To illustrate with some
specific examples:
\begin{verbatim}
>>> x=2*arange(10)
>>> ind1=[0,4,3,7]
>>> x[ind1]
array([ 0,  8,  6, 14])
>>> ind1=[[0,4],[3,7]]
>>> x[ind1]
array([[ 0,  8],
       [ 6, 14]])
\end{verbatim}
This shows that the same elements in the same order are extracted from x by
both forms of ind1, but the result shares the shape of ind1 Something similar
happens in two dimensions:
\begin{verbatim}
>>> x=reshape(arange(12),(3,4))
>>> x
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])
>>> ind1=array([2,1])
>>> ind2=array([0,3])
>>> x[ind1,ind2]
array([8, 7])
\end{verbatim}
Notice this pulls out x[2,0] and x[1,3] as a one-dimensional array.
\begin{verbatim}
>>> ind1=array([[2,2],[1,0]])
>>> ind2=array([[0,1],[3,2]])
>>> x[ind1,ind2]
array([[8, 9],
       [7, 2]])
\end{verbatim}
This pulls out x[2,0], x[2,1], x[1,3], and x[0,2], reading the ind1 and ind2
arrays left to right, and then reshapes the result to the same (2,2) shape as
ind1 and ind2 have.
\begin{verbatim}
>>> ind1.shape=(4,)
>>> ind2.shape=(4,)
>>> x[ind1,ind2]
array([8, 9, 7, 2])
\end{verbatim}

\newpage
Notice this is the same values in the same order, but now as a one-d array.
One index array does a broadcast:
\begin{verbatim}
>>> x[ind1]
array([[ 8,  9, 10, 11],
       [ 8,  9, 10, 11],
       [ 4,  5,  6,  7],
       [ 0,  1,  2,  3]])
>>> ind1.shape=(2,2)
>>> x[ind1]
array([[[ 8,  9, 10, 11],
        [ 8,  9, 10, 11]],

       [[ 4,  5,  6,  7],
        [ 0,  1,  2,  3]]])
\end{verbatim}

Again, note that the same 'elements', in this case rows of x, are returned in
both cases.  But in the second case, ind1 had two dimensions, and so using it
to index only one dimension of a two-d array results in a three-d output of
shape (2,2,4);  i.e., a 2 by 2 'array' of 4-element rows.

When using constants for some of the index positions, then the result uses that
constant for all values. Slices and strides (at least initially) will not be
permitted in the same subscript as index arrays. So
\begin{verbatim}
>>> x[ind1, 2]
array([[10, 10],
  [ 6,  2]])
\end{verbatim}
would be legal, but
\begin{verbatim}
>>> x[ind1, 1:3]
Traceback (most recent call last):
...
IndexError: Cannot mix arrays and slices as indices
\end{verbatim}
would not be.  Similarly for assignment:
\begin{verbatim}
x[ind1, ind2, ind3] = values
\end{verbatim}
will form a new array such that:
\begin{verbatim}
x[ind1[i,j,k], ind2[i,j,k], ind3[i,j,k]] = values[i,j,k]
\end{verbatim}

The index arrays and the value array must be broadcast consistently. (As an
example: \code{ind1.setshape((5,4))}, \code{ind2.setshape((5,))},
\code{ind3.setshape((1,4))}, and \code{values.setshape((1,))}.)
\begin{verbatim}
>>> x=zeros((10,10))
>>> x[[2,5,6],array([0,1,9,3])[:,NewAxis]]=array([1,2,3,4])[:,NewAxis]
>>> x
array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [1, 2, 0, 4, 0, 0, 0, 0, 0, 3],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [1, 2, 0, 4, 0, 0, 0, 0, 0, 3],
       [1, 2, 0, 4, 0, 0, 0, 0, 0, 3],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])
\end{verbatim}
If indices are repeated, the last value encountered will be stored.  When an
index is too large, Numarray raises an IndexError exception. When an index is
negative, Numarray will interpret it in the usual Python style, counting
backwards from the end.  Use of the equivalent \index{take}\function{take} and
\index{put}\function{put} functions will allow other interpretations of the
indices (clip out of bounds indices, allow negative indices to work backwards
as they do when used individually, or for indices to wrap around). The same
behavior applies for functions such as choose and where.

%% Local Variables:
%% mode: LaTeX
%% mode: auto-fill
%% fill-column: 79
%% indent-tabs-mode: nil
%% ispell-dictionary: "american"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "numarray"
%% TeX-parse-self: t
%% End: