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:float64.

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

Try it in your browser!

>>>importnumpyasnp

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

Go BackOpen In Tab

Generic types

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

number,inexact,floating	float64
complexfloating	complex128
integer,signedinteger	int_
unsignedinteger	uint
generic,flexible	void

Deprecated since version 1.19:This conversion of generic scalar types is deprecated.This is because it can be unexpected in a context such asarr.astype(dtype=np.floating), which casts an array offloat32to an array offloat64, even thoughfloat32 is a subdtype ofnp.floating.

Built-in Python types

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

Python type	NumPy type
int	int_
bool	bool_
float	float64
complex	complex128
bytes	bytes_
str	str_
memoryview	void
(all others)	object_

Note thatstr_ corresponds to UCS4 encoded unicode strings.

Example

Try it in your browser!

>>>importnumpyasnp

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

Go BackOpen In Tab

Note

All other types map toobject_ for convenience. Code should expectthat such types may map to a specific (new) dtype in the future.

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

Try it in your browser!

>>>importnumpyasnp

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

Go BackOpen In Tab

Array-protocol type strings (seeThe array interface protocol)

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

Try it in your browser!

>>>importnumpyasnp

>>>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('S25')# 25-length zero-terminated bytes>>>dt=np.dtype('U25')# 25-character string

Go BackOpen In Tab

Note on string types

For backward compatibility with existing code originally written to supportPython 2,S anda typestrings are zero-terminated bytes.For unicode strings, useU,numpy.str_. For signed bytes that do notneed zero-terminationb ori1 can be used.

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

Try it in your browser!

Go BackOpen In Tab

• 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

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

  >>>importnumpyasnp>>>dt=np.dtype("S3, 3u8, (3,4)S10")

Type strings

Any string name of a NumPy dtype, e.g.:

Example

Try it in your browser!

>>>importnumpyasnp

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

Go BackOpen In Tab

(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

Try it in your browser!

>>>importnumpyasnp

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

Go BackOpen In Tab

(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 used to be equivalent to fixed dtype. This behaviour isdeprecated since NumPy 1.17 and will raise an error in the future.Ifshape is a tuple, then the new dtype defines a sub-array of the givenshape.

Example

Try it in your browser!

>>>importnumpyasnp

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

Go BackOpen In Tab

[(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

Try it in your browser!

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

>>>importnumpyasnp

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

Go BackOpen In Tab

{'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(limited toctypes.c_int) for each field, while thetitles value is alist of titles for each field (None can be used if no title isdesired for that field). Thetitles can be any object, but when astr object 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. Total dtypeitemsize is limited toctypes.c_int.

Example

Try it in your browser!

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

>>>importnumpyasnp

>>>dt=np.dtype({'names':['r','g','b','a'],...'formats':[np.uint8,np.uint8,np.uint8,np.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']})

Go BackOpen In Tab

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

Try it in your browser!

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

>>>importnumpyasnp

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

Go BackOpen In Tab

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

Example

Try it in your browser!

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

>>>importnumpyasnp

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

Go BackOpen In Tab

Checking the data type#

When checking for a specific data type, use== comparison.

>>>importnumpyasnp

>>>a=np.array([1,2],dtype=np.float32)>>>a.dtype==np.float32True

As opposed to Python types, a comparison usingis should not be used.

First, NumPy treats data type specifications (everything that can be passed tothedtype constructor) as equivalent to the data type object itself.This equivalence can only be handled through==, not throughis.

>>>importnumpyasnp

>>>a=np.array([1,2],dtype=float)>>>a.dtype==np.dtype(np.float64)True>>>a.dtype==np.float64True>>>a.dtype==floatTrue>>>a.dtype=="float64"True>>>a.dtype=="d"True

Second, there is no guarantee that data type objects are singletons.

>>>importnumpyasnp

>>>np.dtype(float)isnp.dtype(float)True>>>np.dtype([('a',float)])isnp.dtype([('a',float)])False

dtype#

NumPy data type descriptions are instances of thedtype class.