Example

A simple data type containing a 32-bit big-endian integer:(seeSpecifying and constructing data types for details on construction)

>>>dt=np.dtype('>i4')>>>dt.byteorder'>'>>>dt.itemsize4>>>dt.name'int32'>>>dt.typeisnp.int32True

The corresponding array scalar type isint32.

Example

A structured data type containing a 16-character string (in field ‘name’)and a sub-array of two 64-bit floating-point number (in field ‘grades’):

>>>dt=np.dtype([('name',np.unicode_,16),('grades',np.float64,(2,))])>>>dt['name']dtype('|U16')>>>dt['grades']dtype(('float64',(2,)))

Items of an array of this data type are wrapped in anarrayscalar type that also has two fields:

>>>x=np.array([('Sarah',(8.0,7.0)),('John',(6.0,7.0))],dtype=dt)>>>x[1]('John', [6.0, 7.0])>>>x[1]['grades']array([ 6.,  7.])>>>type(x[1])<type 'numpy.void'>>>>type(x[1]['grades'])<type 'numpy.ndarray'>

Specifying and constructing data types¶

Whenever a data-type is required in a NumPy function or method, eitheradtype object or something that can be converted to one canbe supplied. Such conversions are done by thedtypeconstructor:

What can be converted to a data-type object is described below:

dtype object

Used as-is.

None

The default data type:float_.

Array-scalar types

The 24 built-inarray scalar type objects all convert to an associated data-type object.This is true for their sub-classes as well.

Note that not all data-type information can be supplied with atype-object: for example,flexible data-types havea defaultitemsize of 0, and require an explicitly given sizeto be useful.

Example

>>>dt=np.dtype(np.int32)# 32-bit integer>>>dt=np.dtype(np.complex128)# 128-bit complex floating-point number

Generic types

The generic hierarchical type objects convert to correspondingtype objects according to the associations:

number,inexact,floating	float
complexfloating	cfloat
integer,signedinteger	int_
unsignedinteger	uint
character	string
generic,flexible	void

Built-in Python types

Several python types are equivalent to a correspondingarray scalar when used to generate adtype object:

int	int_
bool	bool_
float	float_
complex	cfloat
bytes	bytes_
str	bytes_ (Python2) orunicode_ (Python3)
unicode	unicode_
buffer	void
(all others)	object_

Note thatstr refers to either null terminated bytes or unicode stringsdepending on the Python version. In code targeting both Python 2 and 3np.unicode_ should be used as a dtype for strings.SeeNote on string types.

Example

>>>dt=np.dtype(float)# Python-compatible floating-point number>>>dt=np.dtype(int)# Python-compatible integer>>>dt=np.dtype(object)# Python object

Types with.dtype

Any type object with adtype attribute: The attribute will beaccessed and used directly. The attribute must return somethingthat is convertible into a dtype object.

Several kinds of strings can be converted. Recognized strings can beprepended with'>' (big-endian),'<'(little-endian), or'=' (hardware-native, the default), tospecify the byte order.

One-character strings

Each built-in data-type has a character code(the updated Numeric typecodes), that uniquely identifies it.

Example

>>>dt=np.dtype('b')# byte, native byte order>>>dt=np.dtype('>H')# big-endian unsigned short>>>dt=np.dtype('<f')# little-endian single-precision float>>>dt=np.dtype('d')# double-precision floating-point number

Array-protocol type strings (seeThe Array Interface)

The first character specifies the kind of data and the remainingcharacters specify the number of bytes per item, except for Unicode,where it is interpreted as the number of characters. The item sizemust correspond to an existing type, or an error will be raised. Thesupported kinds are

'?'	boolean
'b'	(signed) byte
'B'	unsigned byte
'i'	(signed) integer
'u'	unsigned integer
'f'	floating-point
'c'	complex-floating point
'm'	timedelta
'M'	datetime
'O'	(Python) objects
'S','a'	zero-terminated bytes (not recommended)
'U'	Unicode string
'V'	raw data (void)

Example

>>>dt=np.dtype('i4')# 32-bit signed integer>>>dt=np.dtype('f8')# 64-bit floating-point number>>>dt=np.dtype('c16')# 128-bit complex floating-point number>>>dt=np.dtype('a25')# 25-length zero-terminated bytes>>>dt=np.dtype('U25')# 25-character string

Note on string types

For backward compatibility with Python 2 theS anda typestringsremain zero-terminated bytes andnp.string_ continues to map tonp.bytes_.To use actual strings in Python 3 useU ornp.unicode_.For signed bytes that do not need zero-terminationb ori1 can beused.

String with comma-separated fields

A short-hand notation for specifying the format of a structured data type isa comma-separated string of basic formats.

A basic format in this context is an optional shape specifierfollowed by an array-protocol type string. Parenthesis are requiredon the shape if it has more than one dimension. NumPy allows a modificationon the format in that any string that can uniquely identify thetype can be used to specify the data-type in a field.The generated data-type fields are named'f0','f1', …,'f<N-1>' where N (>1) is the number of comma-separated basicformats in the string. If the optional shape specifier is provided,then the data-type for the corresponding field describes a sub-array.

Example

• field namedf0 containing a 32-bit integer
• field namedf1 containing a 2 x 3 sub-arrayof 64-bit floating-point numbers
• field namedf2 containing a 32-bit floating-point number

>>>dt=np.dtype("i4, (2,3)f8, f4")

• field namedf0 containing a 3-character string
• field namedf1 containing a sub-array of shape (3,)containing 64-bit unsigned integers
• field namedf2 containing a 3 x 4 sub-arraycontaining 10-character strings

>>>dt=np.dtype("a3, 3u8, (3,4)a10")

Type strings

Any string innumpy.sctypeDict.keys():

Example

>>>dt=np.dtype('uint32')# 32-bit unsigned integer>>>dt=np.dtype('Float64')# 64-bit floating-point number

(flexible_dtype,itemsize)

The first argument must be an object that is converted to azero-sized flexible data-type object, the second argument isan integer providing the desired itemsize.

Example

>>>dt=np.dtype((np.void,10))# 10-byte wide data block>>>dt=np.dtype(('U',10))# 10-character unicode string

(fixed_dtype,shape)

The first argument is any object that can be converted into afixed-size data-type object. The second argument is the desiredshape of this type. If the shape parameter is 1, then thedata-type object is equivalent to fixed dtype. Ifshape is atuple, then the new dtype defines a sub-array of the given shape.

Example

>>>dt=np.dtype((np.int32,(2,2)))# 2 x 2 integer sub-array>>>dt=np.dtype(('U10',1))# 10-character string>>>dt=np.dtype(('i4, (2,3)f8, f4',(2,3)))# 2 x 3 structured sub-array

[(field_name,field_dtype,field_shape),...]

obj should be a list of fields where each field is described by atuple of length 2 or 3. (Equivalent to thedescr item in the__array_interface__ attribute.)

The first element,field_name, is the field name (if this is'' then a standard field name,'f#', is assigned). Thefield name may also be a 2-tuple of strings where the first stringis either a “title” (which may be any string or unicode string) ormeta-data for the field which can be any object, and the secondstring is the “name” which must be a valid Python identifier.

The second element,field_dtype, can be anything that can beinterpreted as a data-type.

The optional third elementfield_shape contains the shape if thisfield represents an array of the data-type in the secondelement. Note that a 3-tuple with a third argument equal to 1 isequivalent to a 2-tuple.

This style does not acceptalign in thedtypeconstructor as it is assumed that all of the memory is accountedfor by the array interface description.

Example

Data-type with fieldsbig (big-endian 32-bit integer) andlittle (little-endian 32-bit integer):

>>>dt=np.dtype([('big','>i4'),('little','<i4')])

Data-type with fieldsR,G,B,A, each being anunsigned 8-bit integer:

>>>dt=np.dtype([('R','u1'),('G','u1'),('B','u1'),('A','u1')])

{'names':...,'formats':...,'offsets':...,'titles':...,'itemsize':...}

This style has two required and three optional keys. Thenamesandformats keys are required. Their respective values areequal-length lists with the field names and the field formats.The field names must be strings and the field formats can be anyobject accepted bydtype constructor.

When the optional keysoffsets andtitles are provided,their values must each be lists of the same length as thenamesandformats lists. Theoffsets value is a list of byte offsets(integers) for each field, while thetitles value is a list oftitles for each field (None can be used if no title isdesired for that field). Thetitles can be anystringorunicode object and will add another entry to thefields dictionary keyed by the title and referencing the samefield tuple which will contain the title as an additional tuplemember.

Theitemsize key allows the total size of the dtype to beset, and must be an integer large enough so all the fieldsare within the dtype. If the dtype being constructed is aligned,theitemsize must also be divisible by the struct alignment.

Example

Data type with fieldsr,g,b,a, each beingan 8-bit unsigned integer:

>>>dt=np.dtype({'names':['r','g','b','a'],...'formats':[uint8,uint8,uint8,uint8]})

Data type with fieldsr andb (with the given titles),both being 8-bit unsigned integers, the first at byte position0 from the start of the field and the second at position 2:

>>>dt=np.dtype({'names':['r','b'],'formats':['u1','u1'],...'offsets':[0,2],...'titles':['Red pixel','Blue pixel']})

{'field1':...,'field2':...,...}

This usage is discouraged, because it is ambiguous with theother dict-based construction method. If you have a fieldcalled ‘names’ and a field called ‘formats’ there will bea conflict.

This style allows passing in thefieldsattribute of a data-type object.

obj should contain string or unicode keys that refer to(data-type,offset) or(data-type,offset,title) tuples.

Example

Data type containing fieldcol1 (10-character string atbyte position 0),col2 (32-bit float at byte position 10),andcol3 (integers at byte position 14):

>>>dt=np.dtype({'col1':('U10',0),'col2':(float32,10),    'col3': (int, 14)})

(base_dtype,new_dtype)

In NumPy 1.7 and later, this form allowsbase_dtype to be interpreted asa structured dtype. Arrays created with this dtype will have underlyingdtypebase_dtype but will have fields and flags taken fromnew_dtype.This is useful for creating custom structured dtypes, as done inrecord arrays.

This form also makes it possible to specify struct dtypes with overlappingfields, functioning like the ‘union’ type in C. This usage is discouraged,however, and the union mechanism is preferred.

Both arguments must be convertible to data-type objects with the same totalsize... admonition:: Example

32-bit integer, whose first two bytes are interpreted as an integervia fieldreal, and the following two bytes via fieldimag.

>>>dt=np.dtype((np.int32,{'real':(np.int16,0),'imag':(np.int16,2)})

32-bit integer, which is interpreted as consisting of a sub-arrayof shape(4,) containing 8-bit integers:

>>>dt=np.dtype((np.int32,(np.int8,4)))

32-bit integer, containing fieldsr,g,b,a thatinterpret the 4 bytes in the integer as four unsigned integers:

>>>dt=np.dtype(('i4',[('r','u1'),('g','u1'),('b','u1'),('a','u1')]))

dtype¶

NumPy data type descriptions are instances of thedtype class.