
\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]{itemsize}{}
   The \method{itemsize} method applied to an array 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]{iscontiguous}{}
   \label{arraymethod:iscontiguous} Calling an array's \method{iscontiguous}
   method returns true if the memory used by the array is contiguous. A
   non-contiguous array can be converted to a contiguous array by the
   \method{copy} method. This is useful for interfacing to C routines only, as
   far as I know.
\begin{verbatim}
>>> b = a[3:8:2]
>>> print a.iscontiguous()
1
>>> print b.iscontiguous()
0
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{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.  Another application, as mentioned 
   above, is to obtain a contiguous array from a non-contiguous array.
\begin{verbatim}
>>> c = a[3:8:2].copy()
>>> print c.iscontiguous()
1
\end{verbatim}
\end{methoddesc}


\begin{methoddesc}[numarray]{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]{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).
\begin{verbatim}
>>> print a
[1 2 3]
>>> a.byteswap()
>>> print a
[16777216 33554432 50331648]
\end{verbatim}
\end{methoddesc}

\begin{methoddesc}[numarray]{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]{tofile}{file}
  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}{}
   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}
   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 provided as an alternative to using these attributes,
   either as a matter of preference or for those using versions of Python prior
   to 2.2.
\end{methoddesc}


\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}

\begin{methoddesc}[numarray]{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]{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}{}
  The \method{min} method returns the smallest element in an array.
\begin{verbatim}
>>> arange(10).min()
0
\end{verbatim}
\end{methoddesc}
\begin{methoddesc}[numarray]{max}{}
  The \method{max} method returns the largest element in an array.
\begin{verbatim}
>>> arange(10).max()
9
\end{verbatim}
\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:
