\chapter{Array Methods}
\label{cha:array-methods}

As we discussed at the beginning of the last chapter, there are very few array
methods for good reasons, and these all depend on the implementation
details. They're worth knowing, though.

\begin{methoddesc}[numarray]{argmax}{axis=-1}
  \label{arraymethod:argmax}
  The \method{argmax} method returns the index of the largest element in a 1D
  array.  In the case of a multi-dimensional array, it returns and array of
  indices.
\begin{verbatim}
>>> array([1,2,4,3]).argmax()
2
>>> arange(100, shape=(10,10)).argmax()
array([9, 9, 9, 9, 9, 9, 9, 9, 9, 9])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{argmin}{axis=-1}
  \label{arraymethod:argmin}
  The \method{argmin} method returns the index of the smallest element in a 1D
  array.  In the case of a multi-dimensional array, it returns and array of
  indices.
\end{methoddesc}


\begin{methoddesc}[numarray]{argsort}{axis=-1}
  \label{arraymethod:argsort}
  The \method{argsort} method returns the array of indices which if taken from
  the array using \function{take} would return a sorted copy of the array.  For
  multi-dimensional arrays, \method{argsort} computes the indices for each 1D
  subarray independently and aggregates them all into a single array result;
  The \method{argsort} of a multi-dimensional array does not produce a sorted
  copy of the array when applied directly to it using \function{take}; instead,
  each 1D subarray must be passed to \function{take} independently.
\begin{verbatim}
  >>> array([1,2,4,3]).argsort()
  array([0, 1, 3, 2])
  >>> take([1,2,4,3], argsort([1,2,4,3]))
  array([1, 2, 3, 4])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{astype}{type}
  \label{arraymethod:astype}
  The \method{astype} method returns a copy of the array converted to the
  specified type.  As with any copy, the new array is aligned, contiguous, and
  in native machine byte order.  If the specified type is the same as current
  type, a copy is \emph{still} made.
\begin{verbatim}
  >>> arange(5).astype('Float64')
  array([ 0.,  1.,  2.,  3.,  4.])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{byteswap}{}
   \label{arraymethod:byteswap}
   The \method{byteswap} method performs a byte swapping operation on all the
   elements in the array, working inplace (i.e.\ it returns None).
   \method{byteswap} does not affect the array's byte order state variable.
   See \method{togglebyteorder} for changing the array's byte order state
   in addition to or rather than physically swapping bytes.
\begin{verbatim}
>>> print a
[1 2 3]
>>> a.byteswap()
>>> print a
[16777216 33554432 50331648]
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{byteswapped}{}
  \label{arraymethod:byteswapped} 
  The \method{byteswapped} method returns a byteswapped copy of the array.
  \method{byteswapped} does not affect the array's own byte order state
  variable.  The result of \method{byteswapped} is logically in native byte
  order.
\begin{verbatim}
>>> array([1,2,3]).byteswapped()
array([16777216, 33554432, 50331648])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{conjugate}{}
  \label{arraymethod:conjugate}
   The \method{conjugate} method returns the complex conjugate of an array.
\begin{verbatim}
>>> (arange(3) + 1j).conjugate()
array([ 0.-1.j,  1.-1.j,  2.-1.j])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{copy}{}
  \label{arraymethod:copy}
   The \method{copy} method returns a copy of an array. When making an
   assignment or taking a slice, a new array object is created and has its own
   attributes, except that the data attribute just points to the data of the
   first array (a "view").  The \method{copy} method is used when it is
   important to obtain an independent copy.  \method{copy} returns arrays which
   are contiguous, aligned, and not byteswapped, i.e. well behaved.
\begin{verbatim}
>>> c = a[3:8:2].copy()
>>> print c.iscontiguous()
1
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{diagonal}{}
  \label{arraymethod:diagonal}
   The \method{diagonal} method returns the diagonal elements of the array,
   those elements where the row and column indices are equal.
\begin{verbatim}
>>> arange(25,shape=(5,5)).diagonal()
array([ 0,  6, 12, 18, 24])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{info}{}
   \label{arraymethod:info} Calling an array's \method{info}
   method prints out information about the array which is useful for debugging.
\begin{verbatim}
>>> arange(10).info()
class: <class 'numarray.numarraycore.NumArray'>
shape: (10,)
strides: (4,)
byteoffset: 0
bytestride: 4
itemsize: 4
aligned: 1
contiguous: 1
data: <memory at 0x08931d18 with size:0x00000028 held by object 0x3ff91bd8 aliasing object 0x00000000>
byteorder: little
byteswap: 0
type: Int32
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{isaligned}{}
  \label{arraymethod:isaligned} \method{isaligned} returns 1 IFF the buffer
  address for an array modulo the array itemsize is 0.  When the array
  itemsize exceeds 8 (sizeof(double)) aligment is done modulo 8.
\end{methoddesc}


\begin{methoddesc}[numarray]{isbyteswapped}{}
  \label{arraymethod:isbyteswapped} \method{isbyteswapped} returns 1 IFF the 
  array's binary data is not in native machine byte order, possibly because it
  originated on a machine with a different native order.
\end{methoddesc}


\begin{methoddesc}[numarray]{iscontiguous}{}
  \label{arraymethod:iscontiguous} \method{iscontiguous} returns 1 IFF
   an array is C-contiguous and 0 otherwise.  An array is C-contiguous if its
   smallest stride corresponds to the innermost dimension and its other strides
   strictly increase in size from the innermost dimension to the outermost,
   with each stride being the product of the previous inner stride and shape.
   A non-contiguous array can be converted to a contiguous array by the
   \method{copy} method.
\begin{verbatim}
>>> a=arange(25, shape=(5,5))
>>> a
array([[ 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]])
>>> a.iscontiguous()
1
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{is_c_array}{}
   \label{arraymethod:is-c-array} 
   \method{is_c_array} returns 1 IFF an array is C-contiguous, aligned, and
   not byteswapped, and returns 0 otherwise.
\begin{verbatim}
>>> a=arange(25, shape=(5,5))
>>> a.is_c_array()
1
>>> a.is_f_array()
0
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{is_fortran_contiguous}{}
   \label{arraymethod:is-fortran-contiguous} 
   \method{is_fortran_contiguous} returns 1 IFF an array is Fortran-contiguous
   and 0 otherwise.  An array is Fortran-contiguous if its smallest stride
   corresponds to its outermost dimension and each succesive stride is the
   product of the previous stride and shape element.
\begin{verbatim}
>>> a=arange(25, shape=(5,5))
>>> a.transpose()
>>> 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.iscontiguous()
0
>>> a.is_fortran_contiguous()
1
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{is_f_array}{}
   \label{arraymethod:is-f-array} \method{is_f_array} returns 1 IFF
   an array is Fortran-contiguous, aligned, and not byteswapped, and returns 0
   otherwise.
\begin{verbatim}
>>> a=arange(25, shape=(5,5))
>>> a.transpose()
>>> a.is_f_array()
1
>>> a.is_c_array()
0
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{itemsize}{}
  \label{arraymethod:itemsize} The \method{itemsize} method 
  returns the number of bytes used by any one of its elements.
\begin{verbatim}
>>> a = arange(10)
>>> a.itemsize()
4
>>> a = array([1.0])
>>> a.itemsize()
8
>>> a = array([1], type=Complex64)
>>> a.itemsize()
16
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{max}{}
  \label{arraymethod:max}
  The \method{max} method returns the largest element in an array.
\begin{verbatim}
>>> arange(100, shape=(10,10)).max()
99
\end{verbatim}
\end{methoddesc}
\begin{methoddesc}[numarray]{mean}{}
  \label{arraymethod:mean}
  The \method{mean} method returns the average of all elements in an array.
\begin{verbatim}
>>> arange(10).mean() 4.5
\end{verbatim}
\end{methoddesc}
\begin{methoddesc}[numarray]{min}{}
  \label{arraymethod:min}
  The \method{min} method returns the smallest element in an array.
\begin{verbatim}
>>> arange(10).min()
0
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{nelements}{}
  \label{arraymethod:nelements}
  \method{nelements} returns the total number of elements in this array.
  Synonymous with \method{size}.
\begin{verbatim}
>>> arange(100).nelements()
100
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{new}{type=None}
  \label{arraymethod:new}
   \method{new} returns a new array of the specified type with the same shape
   as this array.  The new array is uninitialized.
\end{methoddesc}


\begin{methoddesc}[numarray]{nonzero}{axis=-1}
  \label{arraymethod:nonzero}
   \method{nonzero} returns a tuple of arrays containing the indices of the
   elements that are nonzero.
\begin{verbatim}
>>> arange(5).nonzero()
(array([1, 2, 3, 4]),)
>>> b = arange(9, shape=(3,3)) % 2; b
array([[0, 1, 0],
       [1, 0, 1],
       [0, 1, 0]])
>>>b.nonzero()
(array([0, 1, 1, 2]), array([1, 0, 2, 1]))
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{repeat}{r, axis=0}
  \label{arraymethod:repeat}
   The \method{repeat} method returns a new array with each element self[i]
   (along the specified axis) repeated r[i] times.
\begin{verbatim}
>>> a=arange(25, shape=(5,5))
>>> a
array([[ 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]])
>>> a.repeat(arange(5)%2*2)
array([[ 5,  6,  7,  8,  9],
       [ 5,  6,  7,  8,  9],
       [15, 16, 17, 18, 19],
       [15, 16, 17, 18, 19]])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{resize}{shape}
  \label{arraymethod:resize}
   \method{resize} shrinks/grows the array to new \var{shape}, possibly
    replacing the underlying buffer object.
\begin{verbatim}
>>> a = array([0, 1, 2, 3])
>>> a.resize(10)
array([0, 1, 2, 3, 0, 1, 2, 3, 0, 1])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{size}{}
  \label{arraymethod:size}
  \method{size} returns the total number of elements in this array.
  Synonymous with \method{nelements}.
\begin{verbatim}
>>> arange(100).size()
100
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{type}{}
  \label{arraymethod:type}
   The \method{type} method returns the type of the array it is applied to.
   While we've been talking about them as Float32, Int16, etc., it is important
   to note that they are not character strings, they are instances of
   NumericType classes. 
\begin{verbatim}
>>> a = array([1,2,3])
>>> a.type()
Int32
>>> a = array([1], type=Complex64)
>>> a.type()
Complex64
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{typecode}{}
  \label{arraymethod:typecode}
   The \method{typecode} method returns the typecode character of the array it
   is applied to.  \method{typecode} exists for backward compatibility with
   Numeric but the \method{type} method is preferred.
\begin{verbatim}
>>> a = array([1,2,3])
>>> a.typecode()
'l'
>>> a = array([1], type=Complex64)
>>> a.typecode()
'D'
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{tofile}{file}
  \label{arraymethod:tofile}
  The \method{tofile} method writes the binary data of the array into
  \constant{file}.  If \constant{file} is a Python string, it is interpreted 
  as the name of a file to be created.  Otherwise, \constant{file} must be 
  Python file object to which the data will be written.  
\begin{verbatim}
>>> a = arange(65,100)
>>> a.tofile('test.dat')   # writes a's binary data to file 'test.dat'.
>>> f = open('test2.dat', 'w')
>>> a.tofile(f)            # writes a's binary data to file 'test2.dat'
\end{verbatim}
   Note that the binary representation of array data depends on the platform,
   with some platforms being little endian (sys.byteorder == 'little') and
   others being big endian.  The byte order of the array data is \emph{not}
   recorded in the file, nor are the array's shape and type.
\end{methoddesc}


\begin{methoddesc}[numarray]{tolist}{}
  \label{arraymethod:tolist}
   Calling an array's \method{tolist} method returns a hierarchical python list
   version of the same array:
\begin{verbatim}
>>> print a
[[65 66 67 68 69 70 71]
 [72 73 74 75 76 77 78]
 [79 80 81 82 83 84 85]
 [86 87 88 89 90 91 92]
 [93 94 95 96 97 98 99]]
>>> print a.tolist()
[[65, 66, 67, 68, 69, 70, 71], [72, 73, 74, 75, 76, 77, 78], [79, 80,
81, 82, 83, 84, 85], [86, 87, 88, 89, 90, 91, 92], [93, 94, 95, 96, 97,
98, 99]]
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{tostring}{}
  \label{arraymethod:tostring}
   The \method{tostring} method returns a string representation of the 
   array data.
\begin{verbatim}
>>> a = arange(65,70)
>>> a.tostring()
'A\x00\x00\x00B\x00\x00\x00C\x00\x00\x00D\x00\x00\x00E\x00\x00\x00'
\end{verbatim}
Note that the arangement of the printable characters and interspersed NULL
characters is dependent on machine architecture.  The layout shown here is
for little endian platform.
\end{methoddesc}


\begin{methoddesc}[numarray]{transpose}{axis=-1}
  \label{arraymethod:transpose}
  \method{transpose} re-shapes the array by permuting it's dimensions
  as specified by 'axes'.  If 'axes' is none, \method{transpose}
  reverses the array's dimensions.  \method{transpose} operates
  in-place and returns None.
\begin{verbatim}
>>> a = arange(9, shape=(3,3))
>>> a.transpose()
>>> a
array([[0, 3, 6],
       [1, 4, 7],
       [2, 5, 8]])
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{stddev}{}
  \label{arraymethod:stddev}
  The \method{stddev} method returns the standard deviation of all elements in
  an array.
\begin{verbatim}
>>> arange(10).stddev()
3.0276503540974917
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{sum}{}
  \label{arraymethod:sum}
  The \method{sum} method returns the sum of all elements in an array.
\begin{verbatim}
>>> arange(10).sum()
45
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{swapaxes}{axis1, axis2}
  \label{arraymethod:swapaxes}
  The \method{swapaxes} method adjusts the strides of an array so that
  the two specified axes appear to be swapped.  \method{swapaxes} operates
  in place and returns None.
\begin{verbatim}
>>> a = arange(25, shape=(5,5))
>>> a.swapaxes(0,1)
>>> 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{methoddesc}


\begin{methoddesc}[numarray]{togglebyteorder}{}
  \label{arraymethod:togglebyteorder}
  The \method{togglebyteorder} method adjusts the byte order state 
  variable for an array, with ``little'' being replaced by ``big'' and ``big''
  being replaced by ``little''.  \method{togglebyteorder} just reinterprets
  the existing data, it does not actually rearrange bytes.
\begin{verbatim}
>>> a = arange(4)
>>> a.togglebyteorder()
>>> a
array([       0, 16777216, 33554432, 50331648])
\end{verbatim}
\end{methoddesc}

\begin{methoddesc}[numarray]{trace}{}
  \label{arraymethod:togglebyteorder}
  The \method{trace} method returns the sum of the diagonal elements
  of an array.
\begin{verbatim}
>>> a = arange(25, shape=(5,5))
>>> a.trace()
60
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{view}{}
  \label{arraymethod:view} The \method{view} method returns a new
  state object for an array but does not actually copy the array's
  data; views are used to reinterpret an existing data buffer by 
  changing the array's properties.
\begin{verbatim}
>>> a = arange(4)
>>> b = a.view()
>>> b.shape = (2,2)
>>> a
array([0, 1, 2, 3])
>>> b
array([[0, 1],
       [2, 3]])
>>> a is b
False
>>> a._data is b._data
True
\end{verbatim}
\end{methoddesc}


When using Python 2.2 or later, there are four public attributes which
correspond to those of Numeric type objects. These are \member{shape},
\member{flat}, \member{real}, and \member{imag} (or \member{imaginary}). The
following methods are used to implement and provide an alternative to using
these attributes.


\begin{methoddesc}[numarray]{getshape}{}
\end{methoddesc}
\begin{methoddesc}[numarray]{setshape}{}
   The \method{getshape} method returns the tuple that gives the shape of the
   array.  \method{setshape} assigns its argument (a tuple) to the internal
   attribute which defines the array shape. When using Python 2.2 or later, the
   \member{shape} attribute can be accessed or assigned to, which is equivalent
   to using these methods.
\begin{verbatim}
>>> a = arange(12)
>>> a.setshape((3,4))
>>> print a.getshape()
(3, 4)
>>> print a
[[ 0  1  2  3]
 [ 4  5  6  7]
 [ 8  9 10 11]]
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{getflat}{}
   The \method{getflat} method is equivalent to using the \member{flat}
   attribute of Numeric. For compatibility with Numeric, there is no
   \method{setflat} method, although the attribute can in fact be set using
   \method{setshape}.
\begin{verbatim}
>>> print a
[[ 0  1  2  3]
 [ 4  5  6  7]
 [ 8  9 10 11]]
>>> print a.getflat()
[ 0  1  2  3  4  5  6  7  8  9 10 11]
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{getreal}{}
\end{methoddesc}
\begin{methoddesc}[numarray]{setreal}{}
   The \method{getreal} and \method{setreal} methods can be used to access or
   assign to the real part of an array containing imaginary elements.
\end{methoddesc}


\begin{methoddesc}[numarray]{getimag}{}
\end{methoddesc}
\begin{methoddesc}[numarray]{getimaginary}{}
\end{methoddesc}
\begin{methoddesc}[numarray]{setimag}{}
\end{methoddesc}
\begin{methoddesc}[numarray]{setimaginary}{}
   The \method{getimag} and \method{setimag} methods can be used to access or
   assign to the imaginary part of an array containing imaginary elements.
   \method{getimaginary} is equivalent to \method{getimag}, and
   \method{setimaginary} is equivalent to \method{setimag}.
\end{methoddesc}

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