Show Sidebar Hide Sidebar

Dtype

How to create data type objects in NumPy which describe arrays with certain values inside them.

New to Plotly?

Plotly's Python library is free and open source! Get started by downloading the client and reading the primer.
You can set up Plotly to work in online or offline mode, or in jupyter notebooks.
We also have a quick-reference cheatsheet (new!) to help you get started!

Imports

This tutorial imports Numpy.

In [1]:
import numpy as np

DType

You can create a data type object using np.dtype(). Such an object is an array which describes how many fields or elements are contained within the array which the input array describes, and what data type these values are (eg. integers, strings, floats, etc).

In [2]:
np.dtype([('f1', np.uint), ('f2', np.int32)])
Out[2]:
dtype([('f1', '<u8'), ('f2', '<i4')])
In [3]:
np.dtype([('hello',(np.int,3)),('world',np.void,10)])
Out[3]:
dtype([('hello', '<i8', (3,)), ('world', 'V10')])
In [2]:
help(np.dtype)
Help on class dtype in module numpy:

class dtype(__builtin__.object)
 |  dtype(obj, align=False, copy=False)
 |  
 |  Create a data type object.
 |  
 |  A numpy array is homogeneous, and contains elements described by a
 |  dtype object. A dtype object can be constructed from different
 |  combinations of fundamental numeric types.
 |  
 |  Parameters
 |  ----------
 |  obj
 |      Object to be converted to a data type object.
 |  align : bool, optional
 |      Add padding to the fields to match what a C compiler would output
 |      for a similar C-struct. Can be ``True`` only if `obj` is a dictionary
 |      or a comma-separated string. If a struct dtype is being created,
 |      this also sets a sticky alignment flag ``isalignedstruct``.
 |  copy : bool, optional
 |      Make a new copy of the data-type object. If ``False``, the result
 |      may just be a reference to a built-in data-type object.
 |  
 |  See also
 |  --------
 |  result_type
 |  
 |  Examples
 |  --------
 |  Using array-scalar type:
 |  
 |  >>> np.dtype(np.int16)
 |  dtype('int16')
 |  
 |  Structured type, one field name 'f1', containing int16:
 |  
 |  >>> np.dtype([('f1', np.int16)])
 |  dtype([('f1', '<i2')])
 |  
 |  Structured type, one field named 'f1', in itself containing a structured
 |  type with one field:
 |  
 |  >>> np.dtype([('f1', [('f1', np.int16)])])
 |  dtype([('f1', [('f1', '<i2')])])
 |  
 |  Structured type, two fields: the first field contains an unsigned int, the
 |  second an int32:
 |  
 |  >>> np.dtype([('f1', np.uint), ('f2', np.int32)])
 |  dtype([('f1', '<u4'), ('f2', '<i4')])
 |  
 |  Using array-protocol type strings:
 |  
 |  >>> np.dtype([('a','f8'),('b','S10')])
 |  dtype([('a', '<f8'), ('b', '|S10')])
 |  
 |  Using comma-separated field formats.  The shape is (2,3):
 |  
 |  >>> np.dtype("i4, (2,3)f8")
 |  dtype([('f0', '<i4'), ('f1', '<f8', (2, 3))])
 |  
 |  Using tuples.  ``int`` is a fixed type, 3 the field's shape.  ``void``
 |  is a flexible type, here of size 10:
 |  
 |  >>> np.dtype([('hello',(np.int,3)),('world',np.void,10)])
 |  dtype([('hello', '<i4', 3), ('world', '|V10')])
 |  
 |  Subdivide ``int16`` into 2 ``int8``'s, called x and y.  0 and 1 are
 |  the offsets in bytes:
 |  
 |  >>> np.dtype((np.int16, {'x':(np.int8,0), 'y':(np.int8,1)}))
 |  dtype(('<i2', [('x', '|i1'), ('y', '|i1')]))
 |  
 |  Using dictionaries.  Two fields named 'gender' and 'age':
 |  
 |  >>> np.dtype({'names':['gender','age'], 'formats':['S1',np.uint8]})
 |  dtype([('gender', '|S1'), ('age', '|u1')])
 |  
 |  Offsets in bytes, here 0 and 25:
 |  
 |  >>> np.dtype({'surname':('S25',0),'age':(np.uint8,25)})
 |  dtype([('surname', '|S25'), ('age', '|u1')])
 |  
 |  Methods defined here:
 |  
 |  __eq__(...)
 |      x.__eq__(y) <==> x==y
 |  
 |  __ge__(...)
 |      x.__ge__(y) <==> x>=y
 |  
 |  __getitem__(...)
 |      x.__getitem__(y) <==> x[y]
 |  
 |  __gt__(...)
 |      x.__gt__(y) <==> x>y
 |  
 |  __hash__(...)
 |      x.__hash__() <==> hash(x)
 |  
 |  __le__(...)
 |      x.__le__(y) <==> x<=y
 |  
 |  __len__(...)
 |      x.__len__() <==> len(x)
 |  
 |  __lt__(...)
 |      x.__lt__(y) <==> x<y
 |  
 |  __mul__(...)
 |      x.__mul__(n) <==> x*n
 |  
 |  __ne__(...)
 |      x.__ne__(y) <==> x!=y
 |  
 |  __reduce__(...)
 |  
 |  __repr__(...)
 |      x.__repr__() <==> repr(x)
 |  
 |  __rmul__(...)
 |      x.__rmul__(n) <==> n*x
 |  
 |  __setstate__(...)
 |  
 |  __str__(...)
 |      x.__str__() <==> str(x)
 |  
 |  newbyteorder(...)
 |      newbyteorder(new_order='S')
 |      
 |      Return a new dtype with a different byte order.
 |      
 |      Changes are also made in all fields and sub-arrays of the data type.
 |      
 |      Parameters
 |      ----------
 |      new_order : string, optional
 |          Byte order to force; a value from the byte order specifications
 |          below.  The default value ('S') results in swapping the current
 |          byte order.  `new_order` codes can be any of:
 |      
 |          * 'S' - swap dtype from current to opposite endian
 |          * {'<', 'L'} - little endian
 |          * {'>', 'B'} - big endian
 |          * {'=', 'N'} - native order
 |          * {'|', 'I'} - ignore (no change to byte order)
 |      
 |          The code does a case-insensitive check on the first letter of
 |          `new_order` for these alternatives.  For example, any of '>'
 |          or 'B' or 'b' or 'brian' are valid to specify big-endian.
 |      
 |      Returns
 |      -------
 |      new_dtype : dtype
 |          New dtype object with the given change to the byte order.
 |      
 |      Notes
 |      -----
 |      Changes are also made in all fields and sub-arrays of the data type.
 |      
 |      Examples
 |      --------
 |      >>> import sys
 |      >>> sys_is_le = sys.byteorder == 'little'
 |      >>> native_code = sys_is_le and '<' or '>'
 |      >>> swapped_code = sys_is_le and '>' or '<'
 |      >>> native_dt = np.dtype(native_code+'i2')
 |      >>> swapped_dt = np.dtype(swapped_code+'i2')
 |      >>> native_dt.newbyteorder('S') == swapped_dt
 |      True
 |      >>> native_dt.newbyteorder() == swapped_dt
 |      True
 |      >>> native_dt == swapped_dt.newbyteorder('S')
 |      True
 |      >>> native_dt == swapped_dt.newbyteorder('=')
 |      True
 |      >>> native_dt == swapped_dt.newbyteorder('N')
 |      True
 |      >>> native_dt == native_dt.newbyteorder('|')
 |      True
 |      >>> np.dtype('<i2') == native_dt.newbyteorder('<')
 |      True
 |      >>> np.dtype('<i2') == native_dt.newbyteorder('L')
 |      True
 |      >>> np.dtype('>i2') == native_dt.newbyteorder('>')
 |      True
 |      >>> np.dtype('>i2') == native_dt.newbyteorder('B')
 |      True
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  alignment
 |      The required alignment (bytes) of this data-type according to the compiler.
 |      
 |      More information is available in the C-API section of the manual.
 |  
 |  base
 |  
 |  byteorder
 |      A character indicating the byte-order of this data-type object.
 |      
 |      One of:
 |      
 |      ===  ==============
 |      '='  native
 |      '<'  little-endian
 |      '>'  big-endian
 |      '|'  not applicable
 |      ===  ==============
 |      
 |      All built-in data-type objects have byteorder either '=' or '|'.
 |      
 |      Examples
 |      --------
 |      
 |      >>> dt = np.dtype('i2')
 |      >>> dt.byteorder
 |      '='
 |      >>> # endian is not relevant for 8 bit numbers
 |      >>> np.dtype('i1').byteorder
 |      '|'
 |      >>> # or ASCII strings
 |      >>> np.dtype('S2').byteorder
 |      '|'
 |      >>> # Even if specific code is given, and it is native
 |      >>> # '=' is the byteorder
 |      >>> import sys
 |      >>> sys_is_le = sys.byteorder == 'little'
 |      >>> native_code = sys_is_le and '<' or '>'
 |      >>> swapped_code = sys_is_le and '>' or '<'
 |      >>> dt = np.dtype(native_code + 'i2')
 |      >>> dt.byteorder
 |      '='
 |      >>> # Swapped code shows up as itself
 |      >>> dt = np.dtype(swapped_code + 'i2')
 |      >>> dt.byteorder == swapped_code
 |      True
 |  
 |  char
 |      A unique character code for each of the 21 different built-in types.
 |  
 |  descr
 |      Array-interface compliant full description of the data-type.
 |      
 |      The format is that required by the 'descr' key in the
 |      `__array_interface__` attribute.
 |  
 |  fields
 |      Dictionary of named fields defined for this data type, or ``None``.
 |      
 |      The dictionary is indexed by keys that are the names of the fields.
 |      Each entry in the dictionary is a tuple fully describing the field::
 |      
 |        (dtype, offset[, title])
 |      
 |      If present, the optional title can be any object (if it is a string
 |      or unicode then it will also be a key in the fields dictionary,
 |      otherwise it's meta-data). Notice also that the first two elements
 |      of the tuple can be passed directly as arguments to the ``ndarray.getfield``
 |      and ``ndarray.setfield`` methods.
 |      
 |      See Also
 |      --------
 |      ndarray.getfield, ndarray.setfield
 |      
 |      Examples
 |      --------
 |      >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
 |      >>> print(dt.fields)
 |      {'grades': (dtype(('float64',(2,))), 16), 'name': (dtype('|S16'), 0)}
 |  
 |  flags
 |      Bit-flags describing how this data type is to be interpreted.
 |      
 |      Bit-masks are in `numpy.core.multiarray` as the constants
 |      `ITEM_HASOBJECT`, `LIST_PICKLE`, `ITEM_IS_POINTER`, `NEEDS_INIT`,
 |      `NEEDS_PYAPI`, `USE_GETITEM`, `USE_SETITEM`. A full explanation
 |      of these flags is in C-API documentation; they are largely useful
 |      for user-defined data-types.
 |  
 |  hasobject
 |      Boolean indicating whether this dtype contains any reference-counted
 |      objects in any fields or sub-dtypes.
 |      
 |      Recall that what is actually in the ndarray memory representing
 |      the Python object is the memory address of that object (a pointer).
 |      Special handling may be required, and this attribute is useful for
 |      distinguishing data types that may contain arbitrary Python objects
 |      and data-types that won't.
 |  
 |  isalignedstruct
 |      Boolean indicating whether the dtype is a struct which maintains
 |      field alignment. This flag is sticky, so when combining multiple
 |      structs together, it is preserved and produces new dtypes which
 |      are also aligned.
 |  
 |  isbuiltin
 |      Integer indicating how this dtype relates to the built-in dtypes.
 |      
 |      Read-only.
 |      
 |      =  ========================================================================
 |      0  if this is a structured array type, with fields
 |      1  if this is a dtype compiled into numpy (such as ints, floats etc)
 |      2  if the dtype is for a user-defined numpy type
 |         A user-defined type uses the numpy C-API machinery to extend
 |         numpy to handle a new array type. See
 |         :ref:`user.user-defined-data-types` in the Numpy manual.
 |      =  ========================================================================
 |      
 |      Examples
 |      --------
 |      >>> dt = np.dtype('i2')
 |      >>> dt.isbuiltin
 |      1
 |      >>> dt = np.dtype('f8')
 |      >>> dt.isbuiltin
 |      1
 |      >>> dt = np.dtype([('field1', 'f8')])
 |      >>> dt.isbuiltin
 |      0
 |  
 |  isnative
 |      Boolean indicating whether the byte order of this dtype is native
 |      to the platform.
 |  
 |  itemsize
 |      The element size of this data-type object.
 |      
 |      For 18 of the 21 types this number is fixed by the data-type.
 |      For the flexible data-types, this number can be anything.
 |  
 |  kind
 |      A character code (one of 'biufcmMOSUV') identifying the general kind of data.
 |      
 |      =  ======================
 |      b  boolean
 |      i  signed integer
 |      u  unsigned integer
 |      f  floating-point
 |      c  complex floating-point
 |      m  timedelta
 |      M  datetime
 |      O  object
 |      S  (byte-)string
 |      U  Unicode
 |      V  void
 |      =  ======================
 |  
 |  metadata
 |  
 |  name
 |      A bit-width name for this data-type.
 |      
 |      Un-sized flexible data-type objects do not have this attribute.
 |  
 |  names
 |      Ordered list of field names, or ``None`` if there are no fields.
 |      
 |      The names are ordered according to increasing byte offset. This can be
 |      used, for example, to walk through all of the named fields in offset order.
 |      
 |      Examples
 |      --------
 |      >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
 |      >>> dt.names
 |      ('name', 'grades')
 |  
 |  num
 |      A unique number for each of the 21 different built-in types.
 |      
 |      These are roughly ordered from least-to-most precision.
 |  
 |  shape
 |      Shape tuple of the sub-array if this data type describes a sub-array,
 |      and ``()`` otherwise.
 |  
 |  str
 |      The array-protocol typestring of this data-type object.
 |  
 |  subdtype
 |      Tuple ``(item_dtype, shape)`` if this `dtype` describes a sub-array, and
 |      None otherwise.
 |      
 |      The *shape* is the fixed shape of the sub-array described by this
 |      data type, and *item_dtype* the data type of the array.
 |      
 |      If a field whose dtype object has this attribute is retrieved,
 |      then the extra dimensions implied by *shape* are tacked on to
 |      the end of the retrieved array.
 |  
 |  type
 |      The type object used to instantiate a scalar of this data-type.
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  __new__ = <built-in method __new__ of type object>
 |      T.__new__(S, ...) -> a new object with type S, a subtype of T

Still need help?
Contact Us

For guaranteed 24 hour response turnarounds, upgrade to a Developer Support Plan.