User guide

NumPy User Guide, Release 1.9.0
>>> x = np.zeros(3, dtype=’3int8, float32, (2,3)float64’)
>>> x
array([([0, 0, 0], 0.0, [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]),
([0, 0, 0], 0.0, [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]),
([0, 0, 0], 0.0, [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]])],
dtype=[(’f0’, ’|i1’, 3), (’f1’, ’>f4’), (’f2’, ’>f8’, (2, 3))])
By using strings to define the record structure, it precludes being able to name the fields in the original definition. The
names can be changed as shown later, however.
2) Tuple argument: The only relevant tuple case that applies to record structures is when a structure is mapped to an
existing data type. This is done by pairing in a tuple, the existing data type with a matching dtype definition (using
any of the variants being described here). As an example (using a definition using a list, so see 3) for further details):
>>> x = np.zeros(3, dtype=(’i4’,[(’r’,’u1’), (’g’,’u1’), (’b’,’u1’), (’a’,’u1’)]))
>>> x
array([0, 0, 0])
>>> x[’r’]
array([0, 0, 0], dtype=uint8)
In this case, an array is produced that looks and acts like a simple int32 array, but also has definitions for fields that
use only one byte of the int32 (a bit like Fortran equivalencing).
3) List argument: In this case the record structure is defined with a list of tuples. Each tuple has 2 or 3 elements
specifying: 1) The name of the field (‘’ is permitted), 2) the type of the field, and 3) the shape (optional). For example:
>>> x = np.zeros(3, dtype=[(’x’,’f4’),(’y’,np.float32),(’value’,’f4’,(2,2))])
>>> x
array([(0.0, 0.0, [[0.0, 0.0], [0.0, 0.0]]),
(0.0, 0.0, [[0.0, 0.0], [0.0, 0.0]]),
(0.0, 0.0, [[0.0, 0.0], [0.0, 0.0]])],
dtype=[(’x’, ’>f4’), (’y’, ’>f4’), (’value’, ’>f4’, (2, 2))])
4) Dictionary argument: two different forms are permitted. The first consists of a dictionary with two required keys
(‘names’ and ‘formats’), each having an equal sized list of values. The format list contains any type/shape specifier
allowed in other contexts. The names must be strings. There are two optional keys: ‘offsets’ and ‘titles’. Each must
be a correspondingly matching list to the required two where offsets contain integer offsets for each field, and titles
are objects containing metadata for each field (these do not have to be strings), where the value of None is permitted.
As an example:
>>> x = np.zeros(3, dtype={’names’:[’col1’, ’col2’], ’formats’:[’i4’,’f4’]})
>>> x
array([(0, 0.0), (0, 0.0), (0, 0.0)],
dtype=[(’col1’, ’>i4’), (’col2’, ’>f4’)])
The other dictionary form permitted is a dictionary of name keys with tuple values specifying type, offset, and an
optional title.
>>> x = np.zeros(3, dtype={’col1’:(’i1’,0,’title 1’), ’col2’:(’f4’,1,’title 2’)})
>>> x
array([(0, 0.0), (0, 0.0), (0, 0.0)],
dtype=[((’title 1’, ’col1’), ’|i1’), ((’title 2’, ’col2’), ’>f4’)])
Accessing and modifying field names
The field names are an attribute of the dtype object defining the record structure. For the last example:
2.7. Structured arrays (aka “Record arrays”) 33