\chapter{Array Functions}
\label{cha:array-functions}

Most of the useful manipulations on arrays are done with functions. This might
be surprising given Python's object-oriented framework, and that many of these
functions could have been implemented using methods instead. Choosing functions
means that the same procedures can be applied to arbitrary python sequences,
not just to arrays. For example, while \code{transpose([[1,2],[3,4]])} works
just fine, \code{[[1,2],[3,4]].transpose()} does not. This approach also allows
uniformity in interface between functions defined in the numarray Python
system, whether implemented in C or in Python, and functions defined in
extension modules. We've already covered two functions which operate on arrays:
\code{reshape} and \code{resize}.

\begin{funcdesc}{take}{array, indices, axis=0, clipmode=CLIP}
   \label{sec:array-functions:take}
   \label{func:take}
   The function \code{take} is a generalized indexing/slicing of the array.  In 
   its simplest form, it is equivalent to indexing:
\begin{verbatim}
>>> a1 = array([10,20,30,40])
>>> print a1[[1,3]]
[20 40]
>>> print take(a1,[1,3])
[20 40]
\end{verbatim}
   See the description of index
   arrays in the Array Basics section for an alternative to \code{take} 
   and \code{put}. \code{take}
   selects the elements of the array (the first argument) based on the
   indices (the second argument). Unlike slicing, however, the array
   returned by \code{take} has the same rank as the input array.  
   Some 2-D examples:
\begin{verbatim}
>>> print a2
[[ 0  1  2  3  4]
 [ 5  6  7  8  9]
 [10 11 12 13 14]
 [15 16 17 18 19]]
>>> print take(a2, (0,))                 # first row
[[0 1 2 3 4]]
>>> print take(a2, (0,1))                # first and second row
[[0 1 2 3 4]
 [5 6 7 8 9]]
>>> print take (a2, (0, -1))             # index relative to dimension end
[[ 0 1 2 3 4]
[15 16 17 18 19]]
\end{verbatim}
   The optional third argument specifies the axis along which the selection
   occurs, and the default value (as in examples above) is 0, the first
   axis.  If you want a different axis, then you need to specify it:
\begin{verbatim}
>>> print take(a2, (0,), axis=1)         # first column
[[ 0]
 [ 5]
 [10]
 [15]]
>>> print take(a2, (0,1), axis=1)        # first and second column
[[ 0  1]
 [ 5  6]
 [10 11]
 [15 16]]
>>> print take(a2, (0,4), axis=1)        # first and last column
[[ 0  4]
 [ 5  9]
 [10 14]
 [15 19]]
\end{verbatim}
   
   This is considered to be a \var{structural} operation, because its 
   result does
   not depend on the content of the arrays or the result of a computation on
   those contents but uniquely on the structure of the array. Like all such
   structural operations, the default axis is 0 (the first rank). 
   Later in this tutorial, we will see other functions with a default axis 
   of -1.
   
   \function{take} is often used to create multidimensional arrays with the
   indices from a rank-1 array. As in the earlier examples, the shape of the
   array returned by \function{take} is a combination of the shape of its first
   argument and the shape of the array that elements are "taken" from -- when
   that array is rank-1, the shape of the returned array has the same shape as
   the index sequence. This, as with many other facets of numarray, is best
   understood by experiment.
\begin{verbatim}
>>> x = arange(10) * 100
>>> print x
[  0 100 200 300 400 500 600 700 800 900]
>>> print take(x, [[2,4],[1,2]])
[[200 400]
 [100 200]]
\end{verbatim}
   A typical example of using \function{take} is to replace the grey values in
   an image according to a "translation table."  For example, suppose \code{m51}
   is a 2-D array of type \code{UInt8} containing a greyscale image. We can
   create a table mapping the integers 0--255 to integers 0--255 using a
   "compressive nonlinearity":
\begin{verbatim}
>>> table = (255 - arange(256)**2 / 256).astype(UInt8)
\end{verbatim}
   Then we can perform the take() operation
\begin{verbatim}
>>> m51b = take(table, m51)
\end{verbatim}
The numarray version of \function{take} can also take a sequence as its 
axis value:
\begin{verbatim}
>>> print take(a2, [0,1], [0,1])
1
>>> print take(a2, [0,1], [1,0])
5
\end{verbatim}
In this case, it functions like indexing: a2[0,1] and a2[1,0] respectively.
\end{funcdesc}


\begin{funcdesc}{put}{array, indices, values, axis=0, clipmode=CLIP}
  \label{func:put}
   \function{put} is the opposite of \function{take}. The values of \var{array}
   at the locations specified in \var{indices} are set to the corresponding
   \var{values}.  The \var{array} must be a contiguous array. The \var{indices}
   can be any integer sequence object with values suitable for indexing into
   the flat form of \var{array}.  The \var{values} must be any sequence of
   values that can be converted to the type of \var{a}.
\begin{verbatim}
>>> x = arange(6)
>>> put(x, [2,4], [20,40])
>>> print x
[ 0  1 20  3 40  5]
\end{verbatim}
   Note that the target \var{array} is not required to be one-dimensional.
   Since \var{array} is contiguous and stored in row-major order, the
   \var{indices} can be treated as indexing \var{array}'s elements in storage
   order.  The routine \function{put} is thus equivalent to the following
   (although the loop is in C for speed):
\begin{verbatim}
ind = array(indices, copy=0)
v = array(values, copy=0).astype(a.type())
for i in range(len(ind)): a.flat[i] = v[i]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{putmask}{array, mask, values}
   \function{putmask} sets those elements of \var{array} for which 
   \var{mask} is true to the corresponding value in \var{values}. 
   The array \var{array} must be contiguous. The argument \var{mask} 
   must be an integer sequence of the same size (but not necessarily the 
   same shape) as \var{array}. The argument \var{values} will be 
   repeated as necessary; in particular it can be a
   scalar. The array values must be convertible to the type of \var{array}.
\begin{verbatim}
>>> x=arange(5)
>>> putmask(x, [1,0,1,0,1], [10,20,30,40,50])
>>> print x
[10  1 30  3 50]
>>> putmask(x, [1,0,1,0,1], [-1,-2])
>>> print x
[-1  1 -1  3 -1]
\end{verbatim}
   Note how in the last example, the third argument was treated as if it were
   \code{[-1, -2, -1, -2, -1]}.
\end{funcdesc}


\begin{funcdesc}{transpose}{array, axes=None}
   \function{transpose} takes an array \var{array} and returns a new 
   array which corresponds to \var{a} with the order of axes specified 
   by the second argument \var{axes} which is a sequence of dimension 
   indices.  The default is to reverse the order of all axes, i.e. 
   \code{axes=arange(a.rank)[::-1]}.
\begin{verbatim}
>>> a2=arange(6,shape=(2,3)); print a2
[[0 1 2]
 [3 4 5]]
>>> print transpose(a2)  # same as transpose(a2, axes=(1,0))
[[0 3]
 [1 4]
 [2 5]]
>>> a3=arange(24,shape=(2,3,4)); print a3
[[[ 0  1  2  3]
  [ 4  5  6  7]
  [ 8  9 10 11]]

 [[12 13 14 15]
  [16 17 18 19]
  [20 21 22 23]]]
>>> print transpose(a3)  # same as transpose(a3, axes=(2,1,0))
[[[ 0 12]
  [ 4 16]
  [ 8 20]]

 [[ 1 13]
  [ 5 17]
  [ 9 21]]

 [[ 2 14]
  [ 6 18]
  [10 22]]

 [[ 3 15]
  [ 7 19]
  [11 23]]]
>>> print transpose(a3, axes=(1,0,2))
[[[ 0  1  2  3]
  [12 13 14 15]]

 [[ 4  5  6  7]
  [16 17 18 19]]

 [[ 8  9 10 11]
  [20 21 22 23]]]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{repeat}{array, repeats, axis=0}
   \function{repeat} takes an array \var{array} and returns an array 
   with each element in the input array repeated as often as indicated by the
   corresponding elements in the second array. It operates along the specified
   axis. So, to stretch an array evenly, one needs the repeats array to contain
   as many instances of the integer scaling factor as the size of the specified
   axis:
\begin{verbatim}
>>> print a
[[0 1 2]
 [3 4 5]]
>>> print repeat(a, 2*ones(a.shape[0]))   # i.e. repeat(a, (2,2)), broadcast 
                   # rules apply, so this is also equivalent to repeat(a, 2)
[[0 1 2]
 [0 1 2]
 [3 4 5]
 [3 4 5]]
>>> print repeat(a, 2*ones(a.shape[1]), 1)  # i.e. repeat(a, (2,2,2), 1), or
                                            # repeat(a, 2, 1)
[[0 0 1 1 2 2]
 [3 3 4 4 5 5]]
>>> print repeat(a, (1,2))
[[0 1 2]
 [3 4 5]
 [3 4 5]]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{where}{condition, x, y, out=None}
  \label{func:where}
   The \function{where} function creates an array whose values are those of
   \var{x} at those indices where \var{condition} is true, and those of \var{y}
   otherwise.  The shape of the result is the shape of \var{condition}. The
   type of the result is determined by the types of \var{x} and \var{y}. Either
   \var{x} or \var{y} (or both) can be a scalar, which is then used for all
   appropriate elements of condition.  \var{out} can be used to specify an
   output array.
\begin{verbatim}
>>> where(arange(10) >= 5, 1, 2)
array([2, 2, 2, 2, 2, 1, 1, 1, 1, 1])
\end{verbatim}

   Starting with numarray-0.6, \function{where} supports a one parameter form
   that is equivalent to the \var{nonzero} function but reads better:

\begin{verbatim}
>>> where(arange(10) % 2)
(array([1, 3, 5, 7, 9]),)   # indices where expression is true 
\end{verbatim}
   Note that in this case, the output is a tuple.

   Like \function{nonzero}, the one parameter form of \function{where} can be
   used to do array indexing:

\begin{verbatim}
>>> a = arange(10,20)
>>> a[ where( a % 2 ) ]
array([11, 13, 15, 17, 19])
\end{verbatim}

   Note that for array indices which are boolean arrays, using \function{where}
   is not necessary but is still OK:

\begin{verbatim}
>>> a[(a % 2) != 0]
array([11, 13, 15, 17, 19])
>>> a[where((a%2) != 0)]
array([11, 13, 15, 17, 19])
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{choose}{selector, population, outarr=None, clipmode=RAISE}
   The function \function{choose} provides a more general mechanism for
   selecting members of a \var{population} based on a \var{selector} array.
   Unlike \function{where}, \function{choose} can select values from more than
   two arrays.  \var{selector} is an array of integers between \constant{0} and
   \constant{n}. The resulting array will have the same shape as
   \var{selector}, with element selected from \code{population=(b0, ..., bn)}
   as indicated by the value of the corresponding element in \var{selector}.
   Assume \var{selector} is an array that you want to "clip" so that no values
   are greater than \constant{100.0}.
\begin{verbatim}
>>> choose(greater(a, 100.0), (a, 100.0))
\end{verbatim}
   Everywhere that \code{greater(a, 100.0)} is false (i.e.\ \constant{0}) this
   will ``choose'' the corresponding value in \var{a}. Everywhere else 
   it will ``choose'' \constant{100.0}.  This works as well with arrays. 
   Try to figure out what the following does:
\begin{verbatim}
>>> ret = choose(greater(a,b), (c,d))
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{ravel}{array}
   Returns the argument \var{array} as a 1-D array. It is 
   equivalent to \code{reshape(a, (-1,))}. There is a \method{ravel} 
   method which reshapes the array in-place. Unlike \code{a.ravel()}, 
   however, the \function{ravel} function works with non-contiguous arrays.
\begin{verbatim}
>>> a=arange(25)
>>> a.setshape(5,5)
>>> a.transpose()
>>> a.iscontiguous()
0
>>> a
array([[ 0,  5, 10, 15, 20],
  [ 1,  6, 11, 16, 21],
  [ 2,  7, 12, 17, 22],
  [ 3,  8, 13, 18, 23],
  [ 4,  9, 14, 19, 24]])
>>> a.ravel()
Traceback (most recent call last):
...
TypeError: Can't reshape non-contiguous arrays
>>> ravel(a)
array([ 0,  5, 10, 15, 20,  1,  6, 11, 16, 21,  2,  7, 12, 17, 22,  3,
        8, 13, 18, 23,  4,  9, 14, 19, 24])
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{nonzero}{a}
   \function{nonzero} returns a tuple of arrays containing the indices of the
   elements in \var{a} that are nonzero.

\begin{verbatim}
>>> a = array([-1, 0, 1, 2])
>>> nonzero(a)
(array([0, 2, 3]),)
>>> print a2
[[-1  0  1  2]
 [ 9  0  4  0]]
>>> print nonzero(a2)
(array([0, 0, 0, 1, 1]), array([0, 2, 3, 0, 2]))
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{compress}{condition, a, axis=0}
  \label{func:compress}
   Returns those elements of a corresponding to those elements of condition
   that are nonzero. \var{condition} must be the same size as the given axis of
   \var{a}.  Alternately, \var{condition} may match \var{a} in shape; in this
   case the result is a 1D array and \var{axis} should not be specified.
\begin{verbatim}
>>> print x
[1 0 6 2 3 4]
>>> print greater(x, 2)
[0 0 1 0 1 1]
>>> print compress(greater(x, 2), x)
[6 3 4]
>>> print a2
[[-1  0  1  2]
 [ 9  0  4  0]]
>>> print compress(a2>1, a2)
[2 9 4]
>>> a = array([[1,2],[3,4]])
>>> print compress([1,0], a, axis = 1)
[[1]
[3]]
>>> print compress([[1,0],[0,1]], a)
[1, 4]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{diagonal}{a, offset=0, axis1=0, axis2=1}
   Returns the entries along the diagonal of \var{a} specified by \var{offset}.
   The \var{offset} is relative to the \var{axis2} axis.  This is designed for
   2-D arrays. For arrays of higher ranks, it will return the diagonal of each
   2-D sub-array.  The 2-D array does not have to be square.

   Warning:  in Numeric (and numarray 0.7 or before), there is a bug in 
   the \function{diagonal} function which will give erronous result for 
   arrays of 3-D or higher.
\begin{verbatim}
>>> print x
[[ 0  1  2  3  4]
 [ 5  6  7  8  9]
 [10 11 12 13 14]
 [15 16 17 18 19]
 [20 21 22 23 24]]
>>> print diagonal(x)
[ 0  6 12 18 24]
>>> print diagonal(x, 1)
[ 1  7 13 19]
>>> print diagonal(x, -1)
[ 5 11 17 23]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{trace}{a, offset=0, axis1=0, axis2=1}
   Returns the sum of the elements in a along the diagonal specified by offset.

   Warning:  in Numeric (and numarray 0.7 or before), there is a bug in 
   the \function{trace} function which will give erronous result for 
   arrays of 3-D or higher.
\begin{verbatim}
>>> print x
[[ 0  1  2  3  4]
 [ 5  6  7  8  9]
 [10 11 12 13 14]
 [15 16 17 18 19]
 [20 21 22 23 24]]
>>> print trace(x)                      # 0 + 6 + 12 + 18 + 24
60
>>> print trace(x, -1)                  # 5 + 11 + 17 + 23
56
>>> print trace(x, 1)                   # 1 + 7 + 13 + 19
40
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{searchsorted}{bin, values}
   Called with a rank-1 array sorted in ascending order,
   \function{searchsorted} will return the indices of the positions in 
   \var{bin} where the corresponding \var{values} would fit.
\begin{verbatim}
>>> print bin_boundaries
[ 0.   0.1  0.2  0.3  0.4  0.5  0.6  0.7  0.8  0.9  1. ]
>>> print data
[ 0.31  0.79  0.82  5.  -2.  -0.1 ]
>>> print searchsorted(bin_boundaries, data)
[4 8 9 11 0 0]
\end{verbatim}
   This can be used for example to write a simple histogramming function:
\begin{verbatim}
>>> def histogram(a, bins):
...         # Note that the argument names below are reverse of the 
...         # searchsorted argument names
...         n = searchsorted(sort(a), bins)
...         n = concatenate([n, [len(a)]])
...         return n[1:]-n[:-1]
...
>>> print histogram([0,0,0,0,0,0,0,.33,.33,.33], arange(0,1.0,.1))
[7 0 0 3 0 0 0 0 0 0]
>>> print histogram(sin(arange(0,10,.2)), arange(-1.2, 1.2, .1))
[0 0 4 2 2 2 0 2 1 2 1 3 1 3 1 3 2 3 2 3 4 9 0 0]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{sort}{array, axis=-1}
   This function returns an array containing a copy of the data in 
   \var{array}, with the same shape as \var{array}, but with the 
   order of the elements along the specified \var{axis} sorted. The shape 
   of the returned array is the same as \var{array}'s.  Thus, 
   \code{sort(a, 3)} will be an array of the same shape as \var{array}, 
   where the elements of \var{array} have been sorted along the fourth
   axis.
\begin{verbatim}
>>> print data
[[5 0 1 9 8]
 [2 5 8 3 2]
 [8 0 3 7 0]
 [9 6 9 5 0]
 [9 0 9 7 7]]
>>> print sort(data)                    # Axis -1 by default
[[0 1 5 8 9]
 [2 2 3 5 8]
 [0 0 3 7 8]
 [0 5 6 9 9]
 [0 7 7 9 9]]
>>> print sort(data, 0)
[[2 0 1 3 0]
 [5 0 3 5 0]
 [8 0 8 7 2]
 [9 5 9 7 7]
 [9 6 9 9 8]]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{argsort}{array, axis=-1}
   \function{argsort} will return the indices of the elements of the array
   needed to produce \code{sort(array)}. In other words, for a 1-D array,
   \code{take(a.flat, argsort(a))} is the same as \code{sort(a)}... but slower.
\begin{verbatim}
>>> print data
[5 0 1 9 8]
>>> print sort(data)
[0 1 5 8 9]
>>> print argsort(data)
[1 2 0 4 3]
>>> print take(data, argsort(data))
[0 1 5 8 9]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{argmax}{array, axis=-1}
\end{funcdesc}
\begin{funcdesc}{argmin}{array, axis=-1}
   The \function{argmax} function returns an array (or scalar for a 1D array)
   with the index(es) of the maximum value(s) of its input \var{array} along
   the given \var{axis}. The returned array will have one less dimension than
   \var{array}. \function{argmin} is just like \function{argmax}, except that
   it returns the indices of the minima along the given axis.
\begin{verbatim}
>>> print data
[[9 6 1 3 0]
 [0 0 8 9 1]
 [7 4 5 4 0]
 [5 2 7 7 1]
 [9 9 7 9 7]]
>>> print argmax(data)
[0 3 0 3 1]
>>> print argmax(data, 0)
[4 4 1 4 4]
>>> print argmin(data)
[4 1 4 4 4]
>>> print argmin(data, 0)
[1 1 0 0 2]
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{fromstring}{datastring, type, shape=None}
   Will return the array formed by the binary data given in 
   \var{datastring}, of the specified \var{type}. This is mainly 
   used for reading binary data to and from files, it can also be used to 
   exchange binary data with other modules that use python strings as 
   storage (e.g.\ PIL). Note that this representation is dependent on the 
   byte order. To find out the byte ordering used, use the 
   \method{isbyteswapped} method described on page 
   \pageref{arraymethod:byteswap}.  If \var{shape} is not specified, the 
   created array will be one dimensional.
\end{funcdesc}

\begin{funcdesc}{fromfile}{file, type, shape=None}
  If \var{file} is a string then it is interpreted as the name of a 
  file which is opened and read.  Otherwise, \var{file} must be a 
  Python file object which is read as a source of binary array data.  
  \function{fromfile} reads directly into the newly created array buffer 
  with no intermediate string, but otherwise is similar to fromstring, 
  treating the contents of the specified file as a binary data string.
\end{funcdesc}

\begin{funcdesc}{dot}{a, b}
   The \function{dot} function returns the dot product of \var{a} and
   \var{b}. This is equivalent to matrix multiply for rank-2 arrays (without
   the transposition).  This function is identical to the
   \function{matrixmultiply} function.
\begin{verbatim}
>>> print a
[1 2]
>>> print b
[10 11]
# kind of like vector inner product with implicit transposition 
>>> print dot(a,b), dot(b,a) 
32 32
>>> print a
[[1 2]
 [5 7]]
>>> print b
[[  0   1]
 [ 10 100]]
>>> print dot(a,b)
[[ 20 201]
 [ 70 705]]
>>> print dot(b,a)
[[  5   7]
 [510 720]]
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{matrixmultiply}{a, b}
   This function multiplies matrices or matrices and vectors as matrices rather
   than elementwise. This function is identical to \function{dot}.  Compare:
\begin{verbatim}
>>> print a
[[0 1 2]
 [3 4 5]]
>>> print b
[1 2 3]
>>> print a*b
[[ 0  2  6]
 [ 3  8 15]]
>>> print matrixmultiply(a,b)
[ 8 26]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{clip}{m, m_min, m_max}
   The clip function creates an array with the same shape and type as 
   \var{m}, but where every entry in \var{m} that is less than 
   \var{m_min} is replaced by \var{m_min}, and every entry greater 
   than \var{m_max} is replaced by \var{m_max}.  Entries within 
   the range \var{[m_min, m_max]} are left unchanged.
\begin{verbatim}
>>> a = arange(9, type=Float32)
>>> print clip(a, 1.5, 7.5)
[1.5 1.5 2. 3. 4. 5. 6. 7. 7.5]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{indices}{shape, type=None}
   The indices function returns an array corresponding to the \var{shape} 
   given. The array returned is an array of a new shape which is based on 
   the specified \var{shape}, but has an added dimension of length 
   the number of dimensions in the specified shape.  For example, if 
   \code{shape=(3,4)}, then the shape of the array returned will be
   \code{(2,3,4)} since the length of \code{(3,4)} is \var{2} and if 
   \code{shape=(5,6,7)}, the returned array's shape will be \code{(3,5,6,7)}. 
   The contents of the returned arrays are such that the \var{i}th subarray 
   (along index 0, the first dimension) contains the indices for that axis 
   of the elements in the array.  An example makes things clearer:
\begin{verbatim}
>>> i = indices((4,3))
>>> i.getshape()
(2, 4, 3)
>>> print i[0]
[[0 0 0]
 [1 1 1]
 [2 2 2]
 [3 3 3]]
>>> print i[1]
[[0 1 2]
 [0 1 2]
 [0 1 2]
 [0 1 2]]
\end{verbatim}
   So, \code{i[0]} has an array of the specified shape, and each element in
   that array specifies the index of that position in the subarray for axis 0.
   Similarly, each element in the subarray in \code{i[1]} contains the index of
   that position in the subarray for axis 1.
\end{funcdesc}


\begin{funcdesc}{swapaxes}{array, axis1, axis2}
   Returns a new array which \var{shares} the data of \var{array}, but 
   has the two axes specified by \var{axis1} and \var{axis2} 
   swapped. If \var{array} is of rank 0 or 1, swapaxes simply returns a 
   new reference to \var{array}.
\begin{verbatim}
>>> x = arange(10)
>>> x.setshape((5,2,1))
>>> print x
[[[0]
  [1]]

 [[2]
  [3]]

 [[4]
  [5]]

 [[6]
  [7]]

 [[8]
  [9]]]
>>> y = swapaxes(x, 0, 2)
>>> y.getshape()
(1, 2, 5)
>>> print y
[[[0 2 4 6 8]
 [1 3 5 7 9]]]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{concatenate}{arrs, axis=0}
   Returns a new array containing copies of the data contained in all arrays
   of \var{arrs= (a0, a1, ... an)}.  The arrays \var{ai} will be 
   concatenated along the specified \var{axis} (default=0). All 
   arrays \var{ai} must have the same shape along every axis except for 
   the one specified in \var{axis}. To concatenate arrays along a
   newly created axis, you can use \code{array((a0, ..., an))}, as long as all
   arrays have the same shape.
\begin{verbatim}
>>> print x
[[ 0  1  2  3]
 [ 5  6  7  8]
 [10 11 12 13]]
>>> print concatenate((x,x))
[[ 0  1  2  3]
 [ 5  6  7  8]
 [10 11 12 13]
 [ 0  1  2  3]
 [ 5  6  7  8]
 [10 11 12 13]]
>>> print concatenate((x,x), 1)
[[ 0  1  2  3  0  1  2  3]
 [ 5  6  7  8  5  6  7  8]
 [10 11 12 13 10 11 12 13]]
>>> print array((x,x))   # Note: one extra dimension
[[[ 0  1  2  3]
  [ 5  6  7  8]
  [10 11 12 13]]
 [[ 0  1  2  3]
  [ 5  6  7  8]
  [10 11 12 13]]]
>>> print a
[[1 2]]
>>> print b
[[3 4 5]]
>>> print concatenate((a,b),1)
[[1 2 3 4 5]]
>>> print concatenate((a,b),0)
ValueError: _concat array shapes must match except 1st dimension
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{innerproduct}{a, b}
   \function{innerproduct} produces the inner product of arrays \var{a} and
   \var{b}. It is equivalent to \code{matrixmultiply(a, transpose(b))}.
\end{funcdesc}


\begin{funcdesc}{outerproduct}{a,b}
   \function{outerproduct} produces the outer product of vectors \var{a} and
   \var{b}, that is \code{result[i, j] = a[i] * b[j]}.
\end{funcdesc}


\begin{funcdesc}{array_repr}{a, max_line_width=None, precision=None, supress_small=None}
   See section \ref{TBD} on Textual Representations of arrays.
\end{funcdesc}


\begin{funcdesc}{array_str}{a, max_line_width=None, precision=None, supress_small=None}
   See section \ref{TBD} Textual Representations of arrays.
\begin{verbatim}
>>> print a
[  1.00000000e+00   1.10000000e+00   1.11600000e+00   1.11380000e+00
   1.20000000e-02   1.34560000e-04]
>>> print array_str(a,precision=4,suppress_small=1)
[ 1.      1.1     1.116   1.1138  0.012   0.0001]
>>> print array_str(a,precision=3,suppress_small=1)
[ 1.     1.1    1.116  1.114  0.012  0.   ]
>>> print array_str(a,precision=3)
[  1.000e+00   1.100e+00   1.116e+00   1.114e+00   1.200e-02
   1.346e-04]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{resize}{array, shape}
  \label{func:resize}
   The \function{resize} function takes an array and a shape, and returns a new
   array with the specified \var{shape}, and filled with the data in 
   the input \var{array}.  Unlike the \function{reshape} function, the 
   new shape does not have to yield the same size as the original array. 
   If the new size of is less than that of the input \var{array}, the 
   returned array contains the appropriate data from the "beginning" of the 
   old array. If the new size is greater than that of the input array, the 
   data in the input \var{array} is repeated as many times as needed
   to fill the new array.
\begin{verbatim}
>>> x = arange(10)
>>> y = resize(x, (4,2))                # note that 4*2 < 10
>>> print x
[0 1 2 3 4 5 6 7 8 9]
>>> print y
[[0 1]
 [2 3]
 [4 5]
 [6 7]]
>>> print resize(array((0,1)), (5,5))   # note that 5*5 > 2
[[0 1 0 1 0]
 [1 0 1 0 1]
 [0 1 0 1 0]
 [1 0 1 0 1]
 [0 1 0 1 0]]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{identity}{n, type=None}
   The identity function returns an \var{n} by \var{n} array 
   where the diagonal elements are 1, and the off-diagonal elements are 0.
\begin{verbatim}
>>> print identity(5)
[[1 0 0 0 0]
 [0 1 0 0 0]
 [0 0 1 0 0]
 [0 0 0 1 0]
 [0 0 0 0 1]]
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{sum}{a, axis=0}
   The sum function is a synonym for the \method{reduce} method of the
   \function{add} ufunc. It returns the sum of all of the elements in the
   sequence given along the specified axis (first axis by default).
\begin{verbatim}
>>> print x
[[ 0  1  2  3]
 [ 4  5  6  7]
 [ 8  9 10 11]
 [12 13 14 15]
 [16 17 18 19]]
>>> print sum(x)
[40 45 50 55]                           # 0+4+8+12+16, 1+5+9+13+17,
2+6+10+14+18, ...
>>> print sum(x, 1)
[ 6 22 38 54 70]                        # 0+1+2+3, 4+5+6+7, 8+9+10+11, ...
\end{verbatim}
\end{funcdesc}


\begin{funcdesc}{cumsum}{a, axis=0}
   The cumsum function is a synonym for the \method{accumulate} method of the
   \function{add} ufunc.
\end{funcdesc}


\begin{funcdesc}{product}{a, axis=0}
   The product function is a synonym for the \method{reduce} method of the
   \function{multiply} ufunc.
\end{funcdesc}


\begin{funcdesc}{cumproduct}{a, axis=0}
   The cumproduct function is a synonym for the \method{accumulate} method of
   the \function{multiply} ufunc.
\end{funcdesc}


\begin{funcdesc}{alltrue}{a, axis=0}
   The alltrue function is a synonym for the \method{reduce} method of the
   \function{logical_and} ufunc.
\end{funcdesc}


\begin{funcdesc}{sometrue}{a, axis=0}
   The sometrue function is a synonym for the \method{reduce} method of the
   \function{logical_or} ufunc.
\end{funcdesc}


\begin{funcdesc}{all}{a}
   \function{all} is a synonym for the \method{reduce} method of the
   \function{logical_and} ufunc, preceded by a \function{ravel} which converts
   arrays with \(rank>1\) to \(rank=1\).  Thus, \function{all} tests that all
   the elements of a multidimensional array are nonzero.
\end{funcdesc}


\begin{funcdesc}{any}{a}
   The \function{any} function is a synonym for the \method{reduce} method of
   the \function{logical_and} ufunc, preceded by a \function{ravel} which
   converts arrays with \(rank>1\) to \(rank=1\).  Thus, \function{any} tests
   that at least one of the elements of a multidimensional array is nonzero.
\end{funcdesc}


\begin{funcdesc}{allclose}{a, b, rtol=1.e-5, atol=1.e-8}
   This function tests whether or not arrays \var{x} and \var{y} 
   of an integer or real type are equal subject to the given relative and 
   absolute tolerances: \code{rtol, atol}. The formula used is:
   \begin{equation}
      \left| x - y \right| < atol + rtol * \left| y \right|
   \end{equation}
   This means essentially that both elements are small compared to \var{atol}
   or their difference divided by \var{y}'s value is small compared to
   \var{rtol}.
\end{funcdesc}



\begin{seealso}
   \seemodule{numarray.convolve}{The \function{convolve} function is implemented in the
      optional \module{numarray.convolve} package.}%
   \seemodule{numarray.convolve}{The \function{correlation} function is implemented in
      the optional \module{numarray.convolve} package.}%
\end{seealso} 




%% 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: