User guide

NumPy User Guide, Release 1.9.0
Here we have created a one-dimensional array of length 2. Each element of this array is a record that contains three
items, a 32-bit integer, a 32-bit float, and a string of length 10 or less. If we index this array at the second position we
get the second record:
>>> x[1]
(2,3.,"World")
Conveniently, one can access any field of the array by indexing using the string that names that field. In this case the
fields have received the default names ‘f0’, ‘f1’ and ‘f2’.
>>> y = x[’f1’]
>>> y
array([ 2., 3.], dtype=float32)
>>> y[:] = 2
*
y
>>> y
array([ 4., 6.], dtype=float32)
>>> x
array([(1, 4.0, ’Hello’), (2, 6.0, ’World’)],
dtype=[(’f0’, ’>i4’), (’f1’, ’>f4’), (’f2’, ’|S10’)])
In these examples, y is a simple float array consisting of the 2nd field in the record. But, rather than being a copy of
the data in the structured array, it is a view, i.e., it shares exactly the same memory locations. Thus, when we updated
this array by doubling its values, the structured array shows the corresponding values as doubled as well. Likewise, if
one changes the record, the field view also changes:
>>> x[1] = (-1,-1.,"Master")
>>> x
array([(1, 4.0, ’Hello’), (-1, -1.0, ’Master’)],
dtype=[(’f0’, ’>i4’), (’f1’, ’>f4’), (’f2’, ’|S10’)])
>>> y
array([ 4., -1.], dtype=float32)
Defining Structured Arrays
One defines a structured array through the dtype object. There are several alternative ways to define the fields of
a record. Some of these variants provide backward compatibility with Numeric, numarray, or another module, and
should not be used except for such purposes. These will be so noted. One specifies record structure in one of four
alternative ways, using an argument (as supplied to a dtype function keyword or a dtype object constructor itself). This
argument must be one of the following: 1) string, 2) tuple, 3) list, or 4) dictionary. Each of these is briefly described
below.
1) String argument (as used in the above examples). In this case, the constructor expects a comma-separated list of
type specifiers, optionally with extra shape information. The type specifiers can take 4 different forms:
a) b1, i1, i2, i4, i8, u1, u2, u4, u8, f2, f4, f8, c8, c16, a<n>
(representing bytes, ints, unsigned ints, floats, complex and
fixed length strings of specified byte lengths)
b) int8,...,uint8,...,float16, float32, float64, complex64, complex128
(this time with bit sizes)
c) older Numeric/numarray type specifications (e.g. Float32).
Don’t use these in new code!
d) Single character type specifiers (e.g H for unsigned short ints).
Avoid using these unless you must. Details can be found in the
Numpy book
These different styles can be mixed within the same string (but why would you want to do that?). Furthermore, each
type specifier can be prefixed with a repetition number, or a shape. In these cases an array element is created, i.e., an
array within a record. That array is still referred to as a single field. An example:
32 Chapter 2. Numpy basics