Chris@87: """ Chris@87: ============ Chris@87: Array basics Chris@87: ============ Chris@87: Chris@87: Array types and conversions between types Chris@87: ========================================= Chris@87: Chris@87: Numpy supports a much greater variety of numerical types than Python does. Chris@87: This section shows which are available, and how to modify an array's data-type. Chris@87: Chris@87: ========== ========================================================== Chris@87: Data type Description Chris@87: ========== ========================================================== Chris@87: bool_ Boolean (True or False) stored as a byte Chris@87: int_ Default integer type (same as C ``long``; normally either Chris@87: ``int64`` or ``int32``) Chris@87: intc Identical to C ``int`` (normally ``int32`` or ``int64``) Chris@87: intp Integer used for indexing (same as C ``ssize_t``; normally Chris@87: either ``int32`` or ``int64``) Chris@87: int8 Byte (-128 to 127) Chris@87: int16 Integer (-32768 to 32767) Chris@87: int32 Integer (-2147483648 to 2147483647) Chris@87: int64 Integer (-9223372036854775808 to 9223372036854775807) Chris@87: uint8 Unsigned integer (0 to 255) Chris@87: uint16 Unsigned integer (0 to 65535) Chris@87: uint32 Unsigned integer (0 to 4294967295) Chris@87: uint64 Unsigned integer (0 to 18446744073709551615) Chris@87: float_ Shorthand for ``float64``. Chris@87: float16 Half precision float: sign bit, 5 bits exponent, Chris@87: 10 bits mantissa Chris@87: float32 Single precision float: sign bit, 8 bits exponent, Chris@87: 23 bits mantissa Chris@87: float64 Double precision float: sign bit, 11 bits exponent, Chris@87: 52 bits mantissa Chris@87: complex_ Shorthand for ``complex128``. Chris@87: complex64 Complex number, represented by two 32-bit floats (real Chris@87: and imaginary components) Chris@87: complex128 Complex number, represented by two 64-bit floats (real Chris@87: and imaginary components) Chris@87: ========== ========================================================== Chris@87: Chris@87: Additionally to ``intc`` the platform dependent C integer types ``short``, Chris@87: ``long``, ``longlong`` and their unsigned versions are defined. Chris@87: Chris@87: Numpy numerical types are instances of ``dtype`` (data-type) objects, each Chris@87: having unique characteristics. Once you have imported NumPy using Chris@87: Chris@87: :: Chris@87: Chris@87: >>> import numpy as np Chris@87: Chris@87: the dtypes are available as ``np.bool_``, ``np.float32``, etc. Chris@87: Chris@87: Advanced types, not listed in the table above, are explored in Chris@87: section :ref:`structured_arrays`. Chris@87: Chris@87: There are 5 basic numerical types representing booleans (bool), integers (int), Chris@87: unsigned integers (uint) floating point (float) and complex. Those with numbers Chris@87: in their name indicate the bitsize of the type (i.e. how many bits are needed Chris@87: to represent a single value in memory). Some types, such as ``int`` and Chris@87: ``intp``, have differing bitsizes, dependent on the platforms (e.g. 32-bit Chris@87: vs. 64-bit machines). This should be taken into account when interfacing Chris@87: with low-level code (such as C or Fortran) where the raw memory is addressed. Chris@87: Chris@87: Data-types can be used as functions to convert python numbers to array scalars Chris@87: (see the array scalar section for an explanation), python sequences of numbers Chris@87: to arrays of that type, or as arguments to the dtype keyword that many numpy Chris@87: functions or methods accept. Some examples:: Chris@87: Chris@87: >>> import numpy as np Chris@87: >>> x = np.float32(1.0) Chris@87: >>> x Chris@87: 1.0 Chris@87: >>> y = np.int_([1,2,4]) Chris@87: >>> y Chris@87: array([1, 2, 4]) Chris@87: >>> z = np.arange(3, dtype=np.uint8) Chris@87: >>> z Chris@87: array([0, 1, 2], dtype=uint8) Chris@87: Chris@87: Array types can also be referred to by character codes, mostly to retain Chris@87: backward compatibility with older packages such as Numeric. Some Chris@87: documentation may still refer to these, for example:: Chris@87: Chris@87: >>> np.array([1, 2, 3], dtype='f') Chris@87: array([ 1., 2., 3.], dtype=float32) Chris@87: Chris@87: We recommend using dtype objects instead. Chris@87: Chris@87: To convert the type of an array, use the .astype() method (preferred) or Chris@87: the type itself as a function. For example: :: Chris@87: Chris@87: >>> z.astype(float) #doctest: +NORMALIZE_WHITESPACE Chris@87: array([ 0., 1., 2.]) Chris@87: >>> np.int8(z) Chris@87: array([0, 1, 2], dtype=int8) Chris@87: Chris@87: Note that, above, we use the *Python* float object as a dtype. NumPy knows Chris@87: that ``int`` refers to ``np.int_``, ``bool`` means ``np.bool_``, Chris@87: that ``float`` is ``np.float_`` and ``complex`` is ``np.complex_``. Chris@87: The other data-types do not have Python equivalents. Chris@87: Chris@87: To determine the type of an array, look at the dtype attribute:: Chris@87: Chris@87: >>> z.dtype Chris@87: dtype('uint8') Chris@87: Chris@87: dtype objects also contain information about the type, such as its bit-width Chris@87: and its byte-order. The data type can also be used indirectly to query Chris@87: properties of the type, such as whether it is an integer:: Chris@87: Chris@87: >>> d = np.dtype(int) Chris@87: >>> d Chris@87: dtype('int32') Chris@87: Chris@87: >>> np.issubdtype(d, int) Chris@87: True Chris@87: Chris@87: >>> np.issubdtype(d, float) Chris@87: False Chris@87: Chris@87: Chris@87: Array Scalars Chris@87: ============= Chris@87: Chris@87: Numpy generally returns elements of arrays as array scalars (a scalar Chris@87: with an associated dtype). Array scalars differ from Python scalars, but Chris@87: for the most part they can be used interchangeably (the primary Chris@87: exception is for versions of Python older than v2.x, where integer array Chris@87: scalars cannot act as indices for lists and tuples). There are some Chris@87: exceptions, such as when code requires very specific attributes of a scalar Chris@87: or when it checks specifically whether a value is a Python scalar. Generally, Chris@87: problems are easily fixed by explicitly converting array scalars Chris@87: to Python scalars, using the corresponding Python type function Chris@87: (e.g., ``int``, ``float``, ``complex``, ``str``, ``unicode``). Chris@87: Chris@87: The primary advantage of using array scalars is that Chris@87: they preserve the array type (Python may not have a matching scalar type Chris@87: available, e.g. ``int16``). Therefore, the use of array scalars ensures Chris@87: identical behaviour between arrays and scalars, irrespective of whether the Chris@87: value is inside an array or not. NumPy scalars also have many of the same Chris@87: methods arrays do. Chris@87: Chris@87: """ Chris@87: from __future__ import division, absolute_import, print_function