8. 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.

itemsize( )

The itemsize method applied to an array returns the number of bytes used by any one of its elements.

>>> a = arange(10)
>>> a.itemsize()
4
>>> a = array([1.0])
>>> a.itemsize()
8
>>> a = array([1], type=Complex64)
>>> a.itemsize()
16

iscontiguous( )

Calling an array's 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 copy method. This is useful for interfacing to C routines only, as far as I know.

>>> b = a[3:8:2]
>>> print a.iscontiguous()
1
>>> print b.iscontiguous()
0

copy( )

The 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 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.

>>> c = a[3:8:2].copy()
>>> print c.iscontiguous()
1

type( )

The 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.

>>> a = array([1,2,3])
>>> a.type()
Int32
>>> a = array([1], type=Complex64)
>>> a.type()
Complex64

byteswap( )

The byteswap method performs a byte swapping operation on all the elements in the array, working inplace (i.e. it returns None).

>>> print a
[1 2 3]
>>> a.byteswap()
>>> print a
[16777216 33554432 50331648]

tostring( )

The tostring method returns a string representation of the array data.

>>> a = arange(65,70)
>>> a.tostring()
'A\x00\x00\x00B\x00\x00\x00C\x00\x00\x00D\x00\x00\x00E\x00\x00\x00'

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.

tofile( file)

The tofile method writes the binary data of the array into file. If file is a Python string, it is interpreted as the name of a file to be created. Otherwise, file must be Python file object to which the data will be written.

>>> 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'

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 not recorded in the file, nor are the array's shape and type.

tolist( )

Calling an array's tolist method returns a hierarchical python list version of the same array:

>>> 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]]

When using Python 2.2 or later, there are four public attributes which correspond to those of Numeric type objects. These are shape, flat, real, and imag (or 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.

getshape( )

setshape( )

The getshape method returns the tuple that gives the shape of the array. setshape assigns its argument (a tuple) to the internal attribute which defines the array shape. When using Python 2.2 or later, the shape attribute can be accessed or assigned to, which is equivalent to using these methods.

>>> 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]]

getflat( )

The getflat method is equivalent to using the flat attribute of Numeric. For compatibility with Numeric, there is no setflat method, although the attribute can in fact be set using setshape.

>>> 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]

getreal( )

setreal( ): The getreal and setreal methods can be used to access or assign to the real part of an array containing imaginary elements.

getimag( )

getimaginary( )

setimag( )

setimaginary( ): The getimag and setimag methods can be used to access or assign to the imaginary part of an array containing imaginary elements. getimaginary is equivalent to getimag, and setimaginary is equivalent to setimag.

sum( )

The sum method returns the sum of all elements in an array.

>>> arange(10).sum()
45

mean( )

The mean method returns the average of all elements in an array.

>>> arange(10).mean()
4.5

min( )

The min method returns the smallest element in an array.

>>> arange(10).min()
0

max( )

The max method returns the largest element in an array.

>>> arange(10).max()
9

Send comments to the NumArray community.