NumPy Reference

Release 1.18.1

Written by the NumPy community

February 05, 2020

 CONTENTS

1 Array objects 3
1.1 The N-dimensional array (ndarray) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
1.3 Data type objects (dtype) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
1.4 Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
1.5 Iterating Over Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
1.6 Standard array subclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
1.7 Masked arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
1.8 The Array Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
1.9 Datetimes and Timedeltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

2 Constants 389

3 Universal functions (ufunc) 397

3.1 Broadcasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
3.2 Output type determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
3.3 Use of internal buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
3.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
3.5 Casting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
3.6 Overriding Ufunc behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
3.7 ufunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
3.8 Available ufuncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

4 Routines 421
4.1 Array creation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
4.2 Array manipulation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
4.3 Binary operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
4.4 String operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
4.5 C-Types Foreign Function Interface (numpy.ctypeslib) . . . . . . . . . . . . . . . . . . . . . . 554
4.6 Datetime Support Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
4.7 Data type routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
4.8 Optionally Scipy-accelerated routines (numpy.dual) . . . . . . . . . . . . . . . . . . . . . . . . . 578
4.9 Mathematical functions with automatic domain (numpy.emath) . . . . . . . . . . . . . . . . . . . 579
4.10 Floating point error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
4.11 Discrete Fourier Transform (numpy.fft) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
4.12 Financial functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
4.13 Functional programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
4.14 NumPy-specific help functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
4.15 Indexing routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
4.16 Input and output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667

i
 4.17 Linear algebra (numpy.linalg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
4.18 Logic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
4.19 Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
4.20 Matrix library (numpy.matlib) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
4.21 Miscellaneous routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
4.22 Padding Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
4.23 Polynomials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
4.24 Random sampling (numpy.random) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
4.25 Set routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1281
4.26 Sorting, searching, and counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286
4.27 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
4.28 Test Support (numpy.testing) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344
4.29 Window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366

5 Packaging (numpy.distutils) 1379

5.1 Modules in numpy.distutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379
5.2 Configuration class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
5.3 Building Installable C libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393
5.4 Conversion of .src files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394

6 NumPy Distutils - Users Guide 1395

6.1 SciPy structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395
6.2 Requirements for SciPy packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395
6.3 The setup.py file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
6.4 The __init__.py file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1403
6.5 Extra features in NumPy Distutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1403

7 NumPy C-API 1405

7.1 Python Types and C-Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
7.2 System configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1422
7.3 Data Type API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424
7.4 Array API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
7.5 Array Iterator API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1472
7.6 UFunc API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1489
7.7 Generalized Universal Function API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495
7.8 NumPy core libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
7.9 C API Deprecations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504

8 NumPy internals 1505

8.1 NumPy C Code Explanations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505
8.2 Memory Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
8.3 Internal organization of numpy arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514
8.4 Multidimensional Array Indexing Order Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515

9 NumPy and SWIG 1517

9.1 Testing the numpy.i Typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1532

10 Acknowledgements 1537

Bibliography 1539

Python Module Index 1553

Index 1555

ii
 NumPy Reference, Release 1.18.1

Release 1.18
Date February 05, 2020
This reference manual details functions, modules, and objects included in NumPy, describing what they are and what
they do. For learning how to use NumPy, see also user.

CONTENTS 1
NumPy Reference, Release 1.18.1

2 CONTENTS
 CHAPTER

ONE

ARRAY OBJECTS

NumPy provides an N-dimensional array type, the ndarray, which describes a collection of “items” of the same type.
The items can be indexed using for example N integers.
All ndarrays are homogenous: every item takes up the same size block of memory, and all blocks are interpreted in
exactly the same way. How each item in the array is to be interpreted is specified by a separate data-type object, one
of which is associated with every array. In addition to basic types (integers, floats, etc.), the data type objects can also
represent data structures.
An item extracted from an array, e.g., by indexing, is represented by a Python object whose type is one of the array
scalar types built in NumPy. The array scalars allow easy manipulation of also more complicated arrangements of
data.

Fig. 1: Figure Conceptual diagram showing the relationship between the three fundamental objects used to describe
the data in an array: 1) the ndarray itself, 2) the data-type object that describes the layout of a single fixed-size element
of the array, 3) the array-scalar Python object that is returned when a single element of the array is accessed.

1.1 The N-dimensional array (ndarray)

An ndarray is a (usually fixed-size) multidimensional container of items of the same type and size. The number of
dimensions and items in an array is defined by its shape, which is a tuple of N non-negative integers that specify
the sizes of each dimension. The type of items in the array is specified by a separate data-type object (dtype), one of
which is associated with each ndarray.
As with other container objects in Python, the contents of an ndarray can be accessed and modified by indexing or
slicing the array (using, for example, N integers), and via the methods and attributes of the ndarray.

3
NumPy Reference, Release 1.18.1

Different ndarrays can share the same data, so that changes made in one ndarray may be visible in another. That
is, an ndarray can be a “view” to another ndarray, and the data it is referring to is taken care of by the “base” ndarray.
ndarrays can also be views to memory owned by Python strings or objects implementing the buffer or array
interfaces.

Example
A 2-dimensional array of size 2 x 3, composed of 4-byte integer elements:

>>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)

>>> type(x)
<type 'numpy.ndarray'>
>>> x.shape
(2, 3)
>>> x.dtype
dtype('int32')

The array can be indexed using Python container-like syntax:

>>> # The element of x in the *second* row, *third* column, namely, 6.

>>> x[1, 2]

For example slicing can produce views of the array:

>>> y = x[:,1]
>>> y
array([2, 5])
>>> y[0] = 9 # this also changes the corresponding element in x
>>> y
array([9, 5])
>>> x
array([[1, 9, 3],
[4, 5, 6]])

1.1.1 Constructing arrays

New arrays can be constructed using the routines detailed in Array creation routines, and also by using the low-level
ndarray constructor:

ndarray(shape[, dtype, buffer, offset, . . . ]) An array object represents a multidimensional, homo-

geneous array of fixed-size items.

class numpy.ndarray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type
object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory,
whether it is an integer, a floating point number, or something else, etc.)
Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The
parameters given here refer to a low-level method (ndarray(. . . )) for instantiating an array.
For more information, refer to the numpy module and examine the methods and attributes of an array.
Parameters
(for the __new__ method; see Notes below)

4 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

shape [tuple of ints] Shape of created array.

dtype [data-type, optional] Any object that can be interpreted as a numpy data type.
buffer [object exposing buffer interface, optional] Used to fill the array with data.
offset [int, optional] Offset of array data in buffer.
strides [tuple of ints, optional] Strides of data in memory.
order [{‘C’, ‘F’}, optional] Row-major (C-style) or column-major (Fortran-style) order.
See also:

array Construct an array.

zeros Create an array, each element of which is zero.
empty Create an array, but leave its allocated memory unchanged (i.e., it contains “garbage”).
dtype Create a data-type.

Notes

There are two modes of creating an array using __new__:

1. If buffer is None, then only shape, dtype, and order are used.
2. If buffer is an object exposing the buffer interface, then all keywords are interpreted.
No __init__ method is needed because the array is fully initialized after the __new__ method.

Examples

These examples illustrate the low-level ndarray constructor. Refer to the See Also section above for easier
ways of constructing an ndarray.
First mode, buffer is None:
>>> np.ndarray(shape=(2,2), dtype=float, order='F')
array([[0.0e+000, 0.0e+000], # random
[ nan, 2.5e-323]])

Second mode:
>>> np.ndarray((2,), buffer=np.array([1,2,3]),
... offset=np.int_().itemsize,
... dtype=int) # offset = 1*itemsize, i.e. skip first element
array([2, 3])

Attributes
T [ndarray] The transposed array.
data [buffer] Python buffer object pointing to the start of the array’s data.
dtype [dtype object] Data-type of the array’s elements.
flags [dict] Information about the memory layout of the array.
flat [numpy.flatiter object] A 1-D iterator over the array.
imag [ndarray] The imaginary part of the array.

1.1. The N-dimensional array (ndarray) 5

NumPy Reference, Release 1.18.1

real [ndarray] The real part of the array.

size [int] Number of elements in the array.
itemsize [int] Length of one array element in bytes.
nbytes [int] Total bytes consumed by the elements of the array.
ndim [int] Number of array dimensions.
shape [tuple of ints] Tuple of array dimensions.
strides [tuple of ints] Tuple of bytes to step in each dimension when traversing an array.
ctypes [ctypes object] An object to simplify the interaction of the array with the ctypes mod-
ule.
base [ndarray] Base object if memory is from some other object.

Methods

all([axis, out, keepdims]) Returns True if all elements evaluate to True.

any([axis, out, keepdims]) Returns True if any of the elements of a evaluate to
True.
argmax([axis, out]) Return indices of the maximum values along the
given axis.
argmin([axis, out]) Return indices of the minimum values along the
given axis of a.
argpartition(kth[, axis, kind, order]) Returns the indices that would partition this array.
argsort([axis, kind, order]) Returns the indices that would sort this array.
astype(dtype[, order, casting, subok, copy]) Copy of the array, cast to a specified type.
byteswap([inplace]) Swap the bytes of the array elements
choose(choices[, out, mode]) Use an index array to construct a new array from a
set of choices.
clip([min, max, out]) Return an array whose values are limited to [min,
max].
compress(condition[, axis, out]) Return selected slices of this array along given axis.
conj() Complex-conjugate all elements.
conjugate() Return the complex conjugate, element-wise.
copy([order]) Return a copy of the array.
cumprod([axis, dtype, out]) Return the cumulative product of the elements along
the given axis.
cumsum([axis, dtype, out]) Return the cumulative sum of the elements along the
given axis.
diagonal([offset, axis1, axis2]) Return specified diagonals.
dot(b[, out]) Dot product of two arrays.
dump(file) Dump a pickle of the array to the specified file.
dumps() Returns the pickle of the array as a string.
fill(value) Fill the array with a scalar value.
flatten([order]) Return a copy of the array collapsed into one dimen-
sion.
getfield(dtype[, offset]) Returns a field of the given array as a certain type.
item(*args) Copy an element of an array to a standard Python
scalar and return it.
Continued on next page

6 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Table 2 – continued from previous page

itemset(*args) Insert scalar into an array (scalar is cast to array’s
dtype, if possible)
max([axis, out, keepdims, initial, where]) Return the maximum along a given axis.
mean([axis, dtype, out, keepdims]) Returns the average of the array elements along
given axis.
min([axis, out, keepdims, initial, where]) Return the minimum along a given axis.
newbyteorder([new_order]) Return the array with the same data viewed with a
different byte order.
nonzero() Return the indices of the elements that are non-zero.
partition(kth[, axis, kind, order]) Rearranges the elements in the array in such a way
that the value of the element in kth position is in the
position it would be in a sorted array.
prod([axis, dtype, out, keepdims, initial, . . . ]) Return the product of the array elements over the
given axis
ptp([axis, out, keepdims]) Peak to peak (maximum - minimum) value along a
given axis.
put(indices, values[, mode]) Set a.flat[n] = values[n] for all n in in-
dices.
ravel([order]) Return a flattened array.
repeat(repeats[, axis]) Repeat elements of an array.
reshape(shape[, order]) Returns an array containing the same data with a new
shape.
resize(new_shape[, refcheck]) Change shape and size of array in-place.
round([decimals, out]) Return a with each element rounded to the given
number of decimals.
searchsorted(v[, side, sorter]) Find indices where elements of v should be inserted
in a to maintain order.
setfield(val, dtype[, offset]) Put a value into a specified place in a field defined by
a data-type.
setflags([write, align, uic]) Set array flags WRITEABLE, ALIGNED, (WRITE-
BACKIFCOPY and UPDATEIFCOPY), respec-
tively.
sort([axis, kind, order]) Sort an array in-place.
squeeze([axis]) Remove single-dimensional entries from the shape
of a.
std([axis, dtype, out, ddof, keepdims]) Returns the standard deviation of the array elements
along given axis.
sum([axis, dtype, out, keepdims, initial, where]) Return the sum of the array elements over the given
axis.
swapaxes(axis1, axis2) Return a view of the array with axis1 and axis2 in-
terchanged.
take(indices[, axis, out, mode]) Return an array formed from the elements of a at the
given indices.
tobytes([order]) Construct Python bytes containing the raw data bytes
in the array.
tofile(fid[, sep, format]) Write array to a file as text or binary (default).
tolist() Return the array as an a.ndim-levels deep nested
list of Python scalars.
tostring([order]) Construct Python bytes containing the raw data bytes
in the array.
trace([offset, axis1, axis2, dtype, out]) Return the sum along diagonals of the array.
Continued on next page

1.1. The N-dimensional array (ndarray) 7

NumPy Reference, Release 1.18.1

Table 2 – continued from previous page

transpose(*axes) Returns a view of the array with axes transposed.
var([axis, dtype, out, ddof, keepdims]) Returns the variance of the array elements, along
given axis.
view([dtype, type]) New view of array with the same data.

method
ndarray.all(axis=None, out=None, keepdims=False)
Returns True if all elements evaluate to True.
Refer to numpy.all for full documentation.
See also:

numpy.all equivalent function

method
ndarray.any(axis=None, out=None, keepdims=False)
Returns True if any of the elements of a evaluate to True.
Refer to numpy.any for full documentation.
See also:

numpy.any equivalent function

method
ndarray.argmax(axis=None, out=None)
Return indices of the maximum values along the given axis.
Refer to numpy.argmax for full documentation.
See also:

numpy.argmax equivalent function

method
ndarray.argmin(axis=None, out=None)
Return indices of the minimum values along the given axis of a.
Refer to numpy.argmin for detailed documentation.
See also:

numpy.argmin equivalent function

method
ndarray.argpartition(kth, axis=-1, kind='introselect', order=None)
Returns the indices that would partition this array.
Refer to numpy.argpartition for full documentation.
New in version 1.8.0.
See also:

numpy.argpartition equivalent function

8 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

method
ndarray.argsort(axis=-1, kind=None, order=None)
Returns the indices that would sort this array.
Refer to numpy.argsort for full documentation.
See also:

numpy.argsort equivalent function

method
ndarray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
Copy of the array, cast to a specified type.
Parameters
dtype [str or dtype] Typecode or data-type to which the array is cast.
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout order of the result. ‘C’
means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran
contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements
appear in memory as possible. Default is ‘K’.
casting [{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional] Controls what kind of data
casting may occur. Defaults to ‘unsafe’ for backwards compatibility.
• ‘no’ means the data types should not be cast at all.
• ‘equiv’ means only byte-order changes are allowed.
• ‘safe’ means only casts which can preserve values are allowed.
• ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are
allowed.
• ‘unsafe’ means any data conversions may be done.
subok [bool, optional] If True, then sub-classes will be passed-through (default), otherwise
the returned array will be forced to be a base-class array.
copy [bool, optional] By default, astype always returns a newly allocated array. If this is
set to false, and the dtype, order, and subok requirements are satisfied, the input array is
returned instead of a copy.
Returns
arr_t [ndarray] Unless copy is False and the other conditions for returning the input array
are satisfied (see description for copy input parameter), arr_t is a new array of the same
shape as the input array, with dtype, order given by dtype, order.
Raises
ComplexWarning When casting from complex to float or int. To avoid this, one should use
a.real.astype(t).

1.1. The N-dimensional array (ndarray) 9

NumPy Reference, Release 1.18.1

Notes

Changed in version 1.17.0: Casting between a simple data type and a structured one is possible only for
“unsafe” casting. Casting to multiple fields is allowed, but casting from multiple fields is not.
Changed in version 1.9.0: Casting from numeric to string types in ‘safe’ casting mode requires that the
string dtype length is long enough to store the max integer/float value converted.

Examples

>>> x = np.array([1, 2, 2.5])

>>> x
array([1. , 2. , 2.5])

>>> x.astype(int)
array([1, 2, 2])

method
ndarray.byteswap(inplace=False)
Swap the bytes of the array elements
Toggle between low-endian and big-endian data representation by returning a byteswapped array, option-
ally swapped in-place. Arrays of byte-strings are not swapped. The real and imaginary parts of a complex
number are swapped individually.
Parameters
inplace [bool, optional] If True, swap bytes in-place, default is False.
Returns
out [ndarray] The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)

>>> list(map(hex, A))
['0x1', '0x100', '0x2233']
>>> A.byteswap(inplace=True)
array([ 256, 1, 13090], dtype=int16)
>>> list(map(hex, A))
['0x100', '0x1', '0x3322']

Arrays of byte-strings are not swapped

>>> A = np.array([b'ceg', b'fac'])

>>> A.byteswap()
array([b'ceg', b'fac'], dtype='|S3')

A.newbyteorder().byteswap() produces an array with the same values but different repre-
sentation in memory

10 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> A = np.array([1, 2, 3])

>>> A.view(np.uint8)
array([1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0,
0, 0], dtype=uint8)
>>> A.newbyteorder().byteswap(inplace=True)
array([1, 2, 3])
>>> A.view(np.uint8)
array([0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0,
0, 3], dtype=uint8)

method
ndarray.choose(choices, out=None, mode='raise')
Use an index array to construct a new array from a set of choices.
Refer to numpy.choose for full documentation.
See also:

numpy.choose equivalent function

method
ndarray.clip(min=None, max=None, out=None, **kwargs)
Return an array whose values are limited to [min, max]. One of max or min must be given.
Refer to numpy.clip for full documentation.
See also:

numpy.clip equivalent function

method
ndarray.compress(condition, axis=None, out=None)
Return selected slices of this array along given axis.
Refer to numpy.compress for full documentation.
See also:

numpy.compress equivalent function

method
ndarray.conj()
Complex-conjugate all elements.
Refer to numpy.conjugate for full documentation.
See also:

numpy.conjugate equivalent function

method
ndarray.conjugate()
Return the complex conjugate, element-wise.
Refer to numpy.conjugate for full documentation.
See also:

1.1. The N-dimensional array (ndarray) 11

NumPy Reference, Release 1.18.1

numpy.conjugate equivalent function

method
ndarray.copy(order='C')
Return a copy of the array.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout of the copy. ‘C’ means
C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’
means match the layout of a as closely as possible. (Note that this function and numpy.
copy are very similar, but have different default values for their order= arguments.)
See also:
numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
[0, 0, 0]])

>>> y
array([[1, 2, 3],
[4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True

method
ndarray.cumprod(axis=None, dtype=None, out=None)
Return the cumulative product of the elements along the given axis.
Refer to numpy.cumprod for full documentation.
See also:

numpy.cumprod equivalent function

method
ndarray.cumsum(axis=None, dtype=None, out=None)
Return the cumulative sum of the elements along the given axis.
Refer to numpy.cumsum for full documentation.
See also:

numpy.cumsum equivalent function

12 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

method
ndarray.diagonal(offset=0, axis1=0, axis2=1)
Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in
previous NumPy versions. In a future version the read-only restriction will be removed.
Refer to numpy.diagonal for full documentation.
See also:

numpy.diagonal equivalent function

method
ndarray.dot(b, out=None)
Dot product of two arrays.
Refer to numpy.dot for full documentation.
See also:

numpy.dot equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[2., 2.],
[2., 2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[8., 8.],
[8., 8.]])

method
ndarray.dump(file)
Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.
Parameters
file [str or Path] A string naming the dump file.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
method
ndarray.dumps()
Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an
array.
Parameters
None
method
ndarray.fill(value)
Fill the array with a scalar value.

1.1. The N-dimensional array (ndarray) 13

NumPy Reference, Release 1.18.1

Parameters
value [scalar] All elements of a will be assigned this value.

Examples

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

>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([1., 1.])

method
ndarray.flatten(order='C')
Return a copy of the array collapsed into one dimension.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] ‘C’ means to flatten in row-major (C-style) order. ‘F’
means to flatten in column-major (Fortran- style) order. ‘A’ means to flatten in column-
major order if a is Fortran contiguous in memory, row-major order otherwise. ‘K’ means
to flatten a in the order the elements occur in memory. The default is ‘C’.
Returns
y [ndarray] A copy of the input array, flattened to one dimension.
See also:

ravel Return a flattened array.

flat A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])

>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])

method
ndarray.getfield(dtype, offset=0)
Returns a field of the given array as a certain type.
A field is a view of the array data with a given data-type. The values in the view are determined by the
given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits
in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with
a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.
Parameters
dtype [str or dtype] The data type of the view. The dtype size of the view can not be larger
than that of the array itself.

14 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

offset [int] Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[1.+1.j, 0.+0.j],
[0.+0.j, 2.+4.j]])
>>> x.getfield(np.float64)
array([[1., 0.],
[0., 2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)

array([[1., 0.],
[0., 4.]])

method
ndarray.item(*args)
Copy an element of an array to a standard Python scalar and return it.
Parameters
*args [Arguments (variable number and type)]
• none: in this case, the method only works for arrays with one element (a.size == 1),
which element is copied into a standard Python scalar object and returned.
• int_type: this argument is interpreted as a flat index into the array, specifying which
element to copy and return.
• tuple of int_types: functions as does a single int_type argument, except that the argu-
ment is interpreted as an nd-index into the array.
Returns
z [Standard Python scalar object] A copy of the specified element of the array as a suitable
Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is
no available Python scalar that would not lose information. Void arrays return a buffer object for item(),
unless fields are defined, in which case a tuple is returned.
item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned.
This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the
array using Python’s optimized math.

1.1. The N-dimensional array (ndarray) 15

NumPy Reference, Release 1.18.1

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

method
ndarray.itemset(*args)
Insert scalar into an array (scalar is cast to array’s dtype, if possible)
There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is
equivalent to but faster than a[args] = item. The item should be a scalar value and args must select
a single item in the array a.
Parameters
*args [Arguments] If one argument: a scalar, only used in case a is of size 1. If two ar-
guments: the last argument is the value to be set and must be a scalar, the first argument
specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular
location in an ndarray, if you must do this. However, generally this is discouraged: among other
problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a
loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[2, 2, 6],
[1, 0, 6],
[1, 0, 9]])

method

16 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

ndarray.max(axis=None, out=None, keepdims=False, initial=<no value>, where=True)

Return the maximum along a given axis.
Refer to numpy.amax for full documentation.
See also:

numpy.amax equivalent function

method
ndarray.mean(axis=None, dtype=None, out=None, keepdims=False)
Returns the average of the array elements along given axis.
Refer to numpy.mean for full documentation.
See also:

numpy.mean equivalent function

method
ndarray.min(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
Return the minimum along a given axis.
Refer to numpy.amin for full documentation.
See also:

numpy.amin equivalent function

method
ndarray.newbyteorder(new_order='S')
Return the array with the same data viewed with a different byte order.
Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.
Parameters
new_order [string, optional] Byte order to force; a value from the byte order specifications
below. 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 default value (‘S’) results in swapping the current byte order. The code does a case-
insensitive check on the first letter of new_order for the alternatives above. For example,
any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns
new_arr [array] New array object with the dtype reflecting given change to the byte order.

1.1. The N-dimensional array (ndarray) 17

NumPy Reference, Release 1.18.1

method
ndarray.nonzero()
Return the indices of the elements that are non-zero.
Refer to numpy.nonzero for full documentation.
See also:

numpy.nonzero equivalent function

method
ndarray.partition(kth, axis=-1, kind='introselect', order=None)
Rearranges the elements in the array in such a way that the value of the element in kth position is in the
position it would be in a sorted array. All elements smaller than the kth element are moved before this
element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is
undefined.
New in version 1.8.0.
Parameters
kth [int or sequence of ints] Element index to partition by. The kth element value will be
in its final sorted position and all smaller elements will be moved before it and all equal
or greater elements behind it. The order of all elements in the partitions is undefined. If
provided with a sequence of kth it will partition all elements indexed by kth of them into
their sorted position at once.
axis [int, optional] Axis along which to sort. Default is -1, which means sort along the last
axis.
kind [{‘introselect’}, optional] Selection algorithm. Default is ‘introselect’.
order [str or list of str, optional] When a is an array with fields defined, this argument
specifies which fields to compare first, second, etc. A single field can be specified as a
string, and not all fields need to be specified, but unspecified fields will still be used, in the
order in which they come up in the dtype, to break ties.
See also:

numpy.partition Return a parititioned copy of an array.

argpartition Indirect partition.
sort Full sort.

Notes

See np.partition for notes on the different algorithms.

18 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> a = np.array([3, 4, 2, 1])

>>> a.partition(3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))

>>> a
array([1, 2, 3, 4])

method
ndarray.prod(axis=None, dtype=None, out=None, keepdims=False, initial=1, where=True)
Return the product of the array elements over the given axis
Refer to numpy.prod for full documentation.
See also:

numpy.prod equivalent function

method
ndarray.ptp(axis=None, out=None, keepdims=False)
Peak to peak (maximum - minimum) value along a given axis.
Refer to numpy.ptp for full documentation.
See also:

numpy.ptp equivalent function

method
ndarray.put(indices, values, mode='raise')
Set a.flat[n] = values[n] for all n in indices.
Refer to numpy.put for full documentation.
See also:

numpy.put equivalent function

method
ndarray.ravel([order ])
Return a flattened array.
Refer to numpy.ravel for full documentation.
See also:

numpy.ravel equivalent function

ndarray.flat a flat iterator on the array.

method

1.1. The N-dimensional array (ndarray) 19

NumPy Reference, Release 1.18.1

ndarray.repeat(repeats, axis=None)
Repeat elements of an array.
Refer to numpy.repeat for full documentation.
See also:

numpy.repeat equivalent function

method
ndarray.reshape(shape, order='C')
Returns an array containing the same data with a new shape.
Refer to numpy.reshape for full documentation.
See also:

numpy.reshape equivalent function

Notes

Unlike the free function numpy.reshape, this method on ndarray allows the elements of the shape
parameter to be passed in as separate arguments. For example, a.reshape(10, 11) is equivalent to
a.reshape((10, 11)).
method
ndarray.resize(new_shape, refcheck=True)
Change shape and size of array in-place.
Parameters
new_shape [tuple of ints, or n ints] Shape of resized array.
refcheck [bool, optional] If False, reference count will not be checked. Default is True.
Returns
None
Raises
ValueError If a does not own its own data or references or views to it exist, and the data
memory must be changed. PyPy only: will always raise if the data memory must be
changed, since there is no reliable way to determine if references or views to it exist.
SystemError If the order keyword argument is specified. This behaviour is a bug in NumPy.
See also:

resize Return a new array with the specified shape.

20 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.
The purpose of the reference count check is to make sure you do not use this array as a buffer for another
Python object and then reallocate the memory. However, reference counts can increase in other ways so if
you are sure that you have not shared the memory for this array with another Python object, then you may
safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and re-
shaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')

>>> a.resize((2, 1))
>>> a
array([[0],
[1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')

>>> a.resize((2, 1))
>>> a
array([[0],
[2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])

>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
[3, 0, 0]])

Referencing an array prevents resizing. . .

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that references or is referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)

>>> a
array([[0]])
>>> c
array([[0]])

method
ndarray.round(decimals=0, out=None)
Return a with each element rounded to the given number of decimals.
Refer to numpy.around for full documentation.

1.1. The N-dimensional array (ndarray) 21

NumPy Reference, Release 1.18.1

See also:

numpy.around equivalent function

method
ndarray.searchsorted(v, side='left', sorter=None)
Find indices where elements of v should be inserted in a to maintain order.
For full documentation, see numpy.searchsorted
See also:

numpy.searchsorted equivalent function

method
ndarray.setfield(val, dtype, offset=0)
Put a value into a specified place in a field defined by a data-type.
Place val into a’s field defined by dtype and beginning offset bytes into the field.
Parameters
val [object] Value to be placed in field.
dtype [dtype object] Data-type of the field in which to place val.
offset [int, optional] The number of bytes into the field at which to place val.
Returns
None
See also:
getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
[3, 3, 3],
[3, 3, 3]], dtype=int32)
>>> x
array([[1.0e+000, 1.5e-323, 1.5e-323],
[1.5e-323, 1.0e+000, 1.5e-323],
[1.5e-323, 1.5e-323, 1.0e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])

method

22 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

ndarray.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, (WRITEBACKIFCOPY and UPDATEIFCOPY), respectively.
These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The
ALIGNED flag can only be set to True if the data is actually aligned according to the type. The WRITE-
BACKIFCOPY and (deprecated) UPDATEIFCOPY flags can never be set to True. The flag WRITEABLE
can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a
writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done
without copying memory.)
Parameters
write [bool, optional] Describes whether or not a can be written to.
align [bool, optional] Describes whether or not a is aligned properly for its type.
uic [bool, optional] Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There
are 7 Boolean flags in use, only four of which can be changed by the user: WRITEBACKIFCOPY, UP-
DATEIFCOPY, WRITEABLE, and ALIGNED.
WRITEABLE (W) the data area can be written to;
ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the com-
piler);
UPDATEIFCOPY (U) (deprecated), replaced by WRITEBACKIFCOPY;
WRITEBACKIFCOPY (X) this array is a copy of some other array (referenced by .base). When the C-API
function PyArray_ResolveWritebackIfCopy is called, the base array will be updated with the contents of
this array.
All flags can be accessed using the single (upper case) letter as well as the full name.

Examples

>>> y = np.array([[3, 1, 7],

... [2, 0, 0],
... [8, 5, 9]])
>>> y
array([[3, 1, 7],
[2, 0, 0],
[8, 5, 9]])
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
OWNDATA : True
WRITEABLE : True
ALIGNED : True
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
(continues on next page)

1.1. The N-dimensional array (ndarray) 23

NumPy Reference, Release 1.18.1

(continued from previous page)

OWNDATA : True
WRITEABLE : False
ALIGNED : False
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: cannot set WRITEBACKIFCOPY flag to True

method
ndarray.sort(axis=-1, kind=None, order=None)
Sort an array in-place. Refer to numpy.sort for full documentation.
Parameters
axis [int, optional] Axis along which to sort. Default is -1, which means sort along the last
axis.
kind [{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] Sorting algorithm. The de-
fault is ‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers
and, in general, the actual implementation will vary with datatype. The ‘mergesort’ option
is retained for backwards compatibility.
Changed in version 1.15.0.: The ‘stable’ option was added.
order [str or list of str, optional] When a is an array with fields defined, this argument
specifies which fields to compare first, second, etc. A single field can be specified as a
string, and not all fields need be specified, but unspecified fields will still be used, in the
order in which they come up in the dtype, to break ties.
See also:

numpy.sort Return a sorted copy of an array.

numpy.argsort Indirect sort.
numpy.lexsort Indirect stable sort on multiple keys.
numpy.searchsorted Find elements in sorted array.
numpy.partition Partial sort.

Notes

See numpy.sort for notes on the different sorting algorithms.

24 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> a = np.array([[1,4], [3,1]])

>>> a.sort(axis=1)
>>> a
array([[1, 4],
[1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
[1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])

>>> a.sort(order='y')
>>> a
array([(b'c', 1), (b'a', 2)],
dtype=[('x', 'S1'), ('y', '<i8')])

method
ndarray.squeeze(axis=None)
Remove single-dimensional entries from the shape of a.
Refer to numpy.squeeze for full documentation.
See also:

numpy.squeeze equivalent function

method
ndarray.std(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
Returns the standard deviation of the array elements along given axis.
Refer to numpy.std for full documentation.
See also:

numpy.std equivalent function

method
ndarray.sum(axis=None, dtype=None, out=None, keepdims=False, initial=0, where=True)
Return the sum of the array elements over the given axis.
Refer to numpy.sum for full documentation.
See also:

numpy.sum equivalent function

method
ndarray.swapaxes(axis1, axis2)
Return a view of the array with axis1 and axis2 interchanged.
Refer to numpy.swapaxes for full documentation.
See also:

1.1. The N-dimensional array (ndarray) 25

NumPy Reference, Release 1.18.1

numpy.swapaxes equivalent function

method
ndarray.take(indices, axis=None, out=None, mode='raise')
Return an array formed from the elements of a at the given indices.
Refer to numpy.take for full documentation.
See also:

numpy.take equivalent function

method
ndarray.tobytes(order='C')
Construct Python bytes containing the raw data bytes in the array.
Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be
produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order
unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.
New in version 1.9.0.
Parameters
order [{‘C’, ‘F’, None}, optional] Order of the data for multidimensional arrays: C, Fortran,
or the same as for the original array.
Returns
s [bytes] Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')

>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

method
ndarray.tofile(fid, sep="", format="%s")
Write array to a file as text or binary (default).
Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can
be recovered using the function fromfile().
Parameters
fid [file or str or Path] An open file object, or a string containing a filename.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
sep [str] Separator between array items for text output. If “” (empty), a binary file is written,
equivalent to file.write(a.tobytes()).
format [str] Format string for text file output. Each entry in the array is formatted to text by
first converting it to the closest Python type, and then using “format” % item.

26 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision
is lost, so this method is not a good choice for files intended to archive data or transport data between
machines with different endianness. Some of these problems can be overcome by outputting the data as
text files, at the expense of speed and file size.
When fid is a file object, array contents are directly written to the file, bypassing the file object’s write
method. As a result, tofile cannot be used with files objects supporting compression (e.g., GzipFile) or
file-like objects that do not support fileno() (e.g., BytesIO).
method
ndarray.tolist()
Return the array as an a.ndim-levels deep nested list of Python scalars.
Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible
builtin Python type, via the item function.
If a.ndim is 0, then since the depth of the nested list is 0, it will not be a list at all, but a simple Python
scalar.
Parameters
none
Returns
y [object, or list of object, or list of list of object, or . . . ] The possibly nested list of array
elements.

Notes

The array may be recreated via a = np.array(a.tolist()), although this may sometimes lose
precision.

Examples

For a 1D array, a.tolist() is almost the same as list(a), except that tolist changes numpy
scalars to Python scalars:
>>> a = np.uint32([1, 2])
>>> a_list = list(a)
>>> a_list
[1, 2]
>>> type(a_list[0])
<class 'numpy.uint32'>
>>> a_tolist = a.tolist()
>>> a_tolist
[1, 2]
>>> type(a_tolist[0])
<class 'int'>

Additionally, for a 2D array, tolist applies recursively:

>>> a = np.array([[1, 2], [3, 4]])
>>> list(a)
[array([1, 2]), array([3, 4])]
(continues on next page)

1.1. The N-dimensional array (ndarray) 27

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> a.tolist()
[[1, 2], [3, 4]]

The base case for this recursion is a 0D array:

>>> a = np.array(1)
>>> list(a)
Traceback (most recent call last):
...
TypeError: iteration over a 0-d array
>>> a.tolist()
1

method
ndarray.tostring(order='C')
Construct Python bytes containing the raw data bytes in the array.
Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be
produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order
unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.
This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.
Parameters
order [{‘C’, ‘F’, None}, optional] Order of the data for multidimensional arrays: C, Fortran,
or the same as for the original array.
Returns
s [bytes] Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')

>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

method
ndarray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)
Return the sum along diagonals of the array.
Refer to numpy.trace for full documentation.
See also:

numpy.trace equivalent function

method
ndarray.transpose(*axes)
Returns a view of the array with axes transposed.

28 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

For a 1-D array this has no effect, as a transposed vector is simply the same vector. To convert a 1-
D array into a 2D column vector, an additional dimension must be added. np.atleast2d(a).T achieves
this, as does a[:, np.newaxis]. For a 2-D array, this is a standard matrix transpose. For an n-D array, if
axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided
and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape =
(i[n-1], i[n-2], ... i[1], i[0]).
Parameters
axes [None, tuple of ints, or n ints]
• None or no argument: reverses the order of the axes.
• tuple of ints: i in the j-th place in the tuple means a’s i-th axis becomes a.transpose()’s
j-th axis.
• n ints: same as an n-tuple of the same ints (this form is intended simply as a “conve-
nience” alternative to the tuple form)
Returns
out [ndarray] View of a, with axes suitably permuted.
See also:

ndarray.T Array property returning the array transposed.

ndarray.reshape Give a new shape to an array without changing its data.

Examples

>>> a = np.array([[1, 2], [3, 4]])

>>> a
array([[1, 2],
[3, 4]])
>>> a.transpose()
array([[1, 3],
[2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
[2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
[2, 4]])

method
ndarray.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
Returns the variance of the array elements, along given axis.
Refer to numpy.var for full documentation.
See also:

numpy.var equivalent function

method
ndarray.view(dtype=None, type=None)
New view of array with the same data.

1.1. The N-dimensional array (ndarray) 29

NumPy Reference, Release 1.18.1

Parameters
dtype [data-type or ndarray sub-class, optional] Data-type descriptor of the returned view,
e.g., float32 or int16. The default, None, results in the view having the same data-type as
a. This argument can also be specified as an ndarray sub-class, which then specifies the
type of the returned object (this is equivalent to setting the type parameter).
type [Python type, optional] Type of the returned view, e.g., ndarray or matrix. Again, the
default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory
with a different data-type. This can cause a reinterpretation of the bytes of memory.
a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance
of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinter-
pretation of the memory.
For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the pre-
vious dtype (for example, converting a regular array to a structured array), then the behavior of the view
cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on
exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a
slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)

>>> y
matrix([[513]], dtype=int16)
>>> print(type(y))
<class 'numpy.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])

>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
[3, 4]], dtype=int8)
>>> xv.mean(0)
array([2., 3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> x
array([(1, 20), (3, 4)], dtype=[('a', 'i1'), ('b', 'i1')])

Using a view to convert an array to a recarray:

30 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> z = x.view(np.recarray)
>>> z.a
array([1, 3], dtype=int8)

Views share data:

>>> x[0] = (9, 10)

>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices,
transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)

>>> y = x[:, 0:2]
>>> y
array([[1, 2],
[4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
...
ValueError: To change to a dtype of a different size, the array must be C-
˓→contiguous

>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
[(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])

1.1.2 Indexing arrays

Arrays can be indexed using an extended Python slicing syntax, array[selection]. Similar syntax is also used
for accessing fields in a structured data type.
See also:
Array Indexing.

1.1.3 Internal memory layout of an ndarray

An instance of class ndarray consists of a contiguous one-dimensional segment of computer memory (owned by
the array, or by some other object), combined with an indexing scheme that maps N integers into the location of an
item in the block. The ranges in which the indices can vary is specified by the shape of the array. How many bytes
each item takes and how the bytes are interpreted is defined by the data-type object associated with the array.
A segment of memory is inherently 1-dimensional, and there are many different schemes for arranging the items of
an N-dimensional array in a 1-dimensional block. NumPy is flexible, and ndarray objects can accommodate any
strided indexing scheme. In a strided scheme, the N-dimensional index (𝑛0 , 𝑛1 , ..., 𝑛𝑁 −1 ) corresponds to the offset
(in bytes):
𝑁
∑︁−1
𝑛offset = 𝑠𝑘 𝑛𝑘
𝑘=0

from the beginning of the memory block associated with the array. Here, 𝑠𝑘 are integers which specify the strides
of the array. The column-major order (used, for example, in the Fortran language and in Matlab) and row-major order

1.1. The N-dimensional array (ndarray) 31

NumPy Reference, Release 1.18.1

(used in C) schemes are just specific kinds of strided scheme, and correspond to memory that can be addressed by the
strides:
𝑘−1
∏︁ 𝑁
∏︁−1
𝑠column
𝑘 = itemsize 𝑑𝑗 , 𝑠row
𝑘 = itemsize 𝑑𝑗 .
𝑗=0 𝑗=𝑘+1

where 𝑑𝑗 = self.shape[j].
Both the C and Fortran orders are contiguous, i.e., single-segment, memory layouts, in which every part of the memory
block can be accessed by some combination of the indices.
While a C-style and Fortran-style contiguous array, which has the corresponding flags set, can be addressed with the
above strides, the actual strides may be different. This can happen in two cases:
1. If self.shape[k] == 1 then for any legal index index[k] == 0. This means that in the formula for
the offset 𝑛𝑘 = 0 and thus 𝑠𝑘 𝑛𝑘 = 0 and the value of 𝑠𝑘 = self.strides[k] is arbitrary.
2. If an array has no elements (self.size == 0) there is no legal index and the strides are never used. Any
array with no elements may be considered C-style and Fortran-style contiguous.
Point 1. means that self and self.squeeze() always have the same contiguity and aligned flags value. This
also means that even a high dimensional array could be C-style and Fortran-style contiguous at the same time.
An array is considered aligned if the memory offsets for all elements and the base offset itself is a multiple of
self.itemsize. Understanding memory-alignment leads to better performance on most hardware.

Note: Points (1) and (2) are not yet applied by default. Beginning with NumPy 1.8.0, they are applied consistently
only if the environment variable NPY_RELAXED_STRIDES_CHECKING=1 was defined when NumPy was built.
Eventually this will become the default.
You can check whether this option was enabled when your NumPy was built by looking at the value of np.
ones((10,1), order='C').flags.f_contiguous. If this is True, then your NumPy has relaxed strides
checking enabled.

Warning: It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous
arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Data in new ndarrays is in the row-major (C) order, unless otherwise specified, but, for example, basic array slicing
often produces views in a different scheme.

Note: Several algorithms in NumPy work on arbitrarily strided arrays. However, some algorithms require single-
segment arrays. When an irregularly strided array is passed in to such algorithms, a copy is automatically made.

1.1.4 Array attributes

Array attributes reflect information that is intrinsic to the array itself. Generally, accessing an array through its at-
tributes allows you to get and sometimes set intrinsic properties of the array without creating a new array. The exposed
attributes are the core parts of an array and only some of them can be reset meaningfully without creating a new array.
Information on each attribute is given below.

32 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Memory layout

The following attributes contain information about the memory layout of the array:

ndarray.flags Information about the memory layout of the array.

ndarray.shape Tuple of array dimensions.
ndarray.strides Tuple of bytes to step in each dimension when travers-
ing an array.
ndarray.ndim Number of array dimensions.
ndarray.data Python buffer object pointing to the start of the array’s
data.
ndarray.size Number of elements in the array.
ndarray.itemsize Length of one array element in bytes.
ndarray.nbytes Total bytes consumed by the elements of the array.
ndarray.base Base object if memory is from some other object.

attribute
ndarray.flags
Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased
attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.
Only the WRITEBACKIFCOPY, UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by
the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.
The array flags cannot be set arbitrarily:
• UPDATEIFCOPY can only be set False.
• WRITEBACKIFCOPY can only be set False.
• ALIGNED can only be set True if the data is truly aligned.
• WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory
exposes a writeable buffer interface or is a string.
Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays,
but can also be true for higher dimensional arrays.
Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.
shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1]
== self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for
Fortran-style contiguous arrays is true.
Attributes
C_CONTIGUOUS (C) The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) The data area can be written to. Setting this to False locks the data, making
it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time,
but a view of a writeable array may be subsequently locked while the base array remains

1.1. The N-dimensional array (ndarray) 33

NumPy Reference, Release 1.18.1

writeable. (The opposite is not true, in that a view of a locked array may not be made
writeable. However, currently, locking a base object does not lock any views that already
reference it, so under that circumstance it is possible to alter the contents of a locked array
via a previously created writeable view onto it.) Attempting to change a non-writeable array
raises a RuntimeError exception.
ALIGNED (A) The data and all elements are aligned appropriately for the hardware.
WRITEBACKIFCOPY (X) This array is a copy of some other array. The C-API function
PyArray_ResolveWritebackIfCopy must be called before deallocating to the base array will
be updated with the contents of this array.
UPDATEIFCOPY (U) (Deprecated, use WRITEBACKIFCOPY) This array is a copy of some
other array. When this array is deallocated, the base array will be updated with the contents
of this array.
FNC F_CONTIGUOUS and not C_CONTIGUOUS.
FORC F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) ALIGNED and WRITEABLE.
CARRAY (CA) BEHAVED and C_CONTIGUOUS.
FARRAY (FA) BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.
attribute
ndarray.shape
Tuple of array dimensions.
The shape property is usually used to get the current shape of an array, but may also be used to reshape the
array in-place by assigning a tuple of array dimensions to it. As with numpy.reshape, one of the new shape
dimensions can be -1, in which case its value is inferred from the size of the array and the remaining dimensions.
Reshaping an array in-place will fail if a copy is required.
See also:

numpy.reshape similar function

ndarray.reshape similar method

Examples

>>> x = np.array([1, 2, 3, 4])

>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
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.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged
>>> np.zeros((4,2))[::2].shape = (-1,)
(continues on next page)

34 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

(continued from previous page)

Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: incompatible shape for a non-contiguous array

attribute
ndarray.strides
Tuple of bytes to step in each dimension when traversing an array.
The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.
See also:
numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
[5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The
strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain
axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get
to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))

>>> y
array([[[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]],
[[12, 13, 14, 15],
[16, 17, 18, 19],
[20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)

>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
(continues on next page)

1.1. The N-dimensional array (ndarray) 35

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813

attribute
ndarray.ndim
Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])

>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3

attribute
ndarray.data
Python buffer object pointing to the start of the array’s data.
attribute
ndarray.size
Number of elements in the array.
Equal to np.prod(a.shape), i.e., the product of the array’s dimensions.

Notes

a.size returns a standard arbitrary precision Python integer. This may not be the case with other methods of
obtaining the same value (like the suggested np.prod(a.shape), which returns an instance of np.int_),
and may be relevant if the value is used further in calculations that may overflow a fixed size integer type.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)

>>> x.size
30
>>> np.prod(x.shape)
30

attribute
ndarray.itemsize
Length of one array element in bytes.

36 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = np.array([1,2,3], dtype=np.float64)

>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16

attribute
ndarray.nbytes
Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)

>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480

attribute
ndarray.base
Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True

1.1. The N-dimensional array (ndarray) 37

NumPy Reference, Release 1.18.1

Data type

See also:
Data type objects
The data type object associated with the array can be found in the dtype attribute:

ndarray.dtype Data-type of the array’s elements.

attribute
ndarray.dtype
Data-type of the array’s elements.
Parameters
None
Returns
d [numpy dtype object]
See also:
numpy.dtype

Examples

>>> x
array([[0, 1],
[2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>

Other attributes

ndarray.T The transposed array.

ndarray.real The real part of the array.
ndarray.imag The imaginary part of the array.
ndarray.flat A 1-D iterator over the array.
ndarray.ctypes An object to simplify the interaction of the array with
the ctypes module.

attribute
ndarray.T
The transposed array.
Same as self.transpose().
See also:
transpose

38 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = np.array([[1.,2.],[3.,4.]])
>>> x
array([[ 1., 2.],
[ 3., 4.]])
>>> x.T
array([[ 1., 3.],
[ 2., 4.]])
>>> x = np.array([1.,2.,3.,4.])
>>> x
array([ 1., 2., 3., 4.])
>>> x.T
array([ 1., 2., 3., 4.])

attribute
ndarray.real
The real part of the array.
See also:

numpy.real equivalent function

Examples

>>> x = np.sqrt([1+0j, 0+1j])

>>> x.real
array([ 1. , 0.70710678])
>>> x.real.dtype
dtype('float64')

attribute
ndarray.imag
The imaginary part of the array.

Examples

>>> x = np.sqrt([1+0j, 0+1j])

>>> x.imag
array([ 0. , 0.70710678])
>>> x.imag.dtype
dtype('float64')

attribute
ndarray.flat
A 1-D iterator over the array.
This is a numpy.flatiter instance, which acts similarly to, but is not a subclass of, Python’s built-in iterator
object.
See also:

flatten Return a copy of the array collapsed into one dimension.

1.1. The N-dimensional array (ndarray) 39

NumPy Reference, Release 1.18.1

flatiter

Examples

>>> x = np.arange(1, 7).reshape(2, 3)

>>> x
array([[1, 2, 3],
[4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
[2, 5],
[3, 6]])
>>> x.T.flat[3]
5
>>> type(x.flat)
<class 'numpy.flatiter'>

An assignment example:

>>> x.flat = 3; x
array([[3, 3, 3],
[3, 3, 3]])
>>> x.flat[[1,4]] = 1; x
array([[3, 1, 3],
[3, 1, 3]])

attribute
ndarray.ctypes
An object to simplify the interaction of the array with the ctypes module.
This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes
module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which
themselves return ctypes objects that can be used as arguments to a shared library.
Parameters
None
Returns
c [Python object] Possessing attributes data, shape, strides, etc.
See also:
numpy.ctypeslib

40 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted
undocumented public attributes, as well as documented private attributes):
_ctypes.data
A pointer to the memory area of the array as a Python integer. This memory area may contain data that
is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags
and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid
trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as
self._array_interface_['data'][0].
Note that unlike data_as, a reference will not be kept to the array: code like ctypes.c_void_p((a
+ b).ctypes.data) will result in a pointer to a deallocated array, and should be spelt (a + b).
ctypes.data_as(ctypes.c_void_p)
_ctypes.shape
(c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding
to dtype('p') on this platform. This base-type could be ctypes.c_int, ctypes.c_long, or
ctypes.c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.
ctypeslib. The ctypes array contains the shape of the underlying array.
_ctypes.strides
(c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape
attribute. This ctypes array contains the strides information from the underlying array. This strides in-
formation is important for showing how many bytes must be jumped to get to the next element in the
array.
_ctypes.data_as(self, obj)
Return the data pointer cast to a particular c-types object. For example, calling self.
_as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want
to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.
POINTER(ctypes.c_double)).
The returned pointer will keep a reference to the array.
_ctypes.shape_as(self, obj)
Return the shape tuple as an array of some other c-types type. For example: self.
shape_as(ctypes.c_short).
_ctypes.strides_as(self, obj)
Return the strides tuple as an array of some other c-types type. For example: self.
strides_as(ctypes.c_longlong).
If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful,
but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the
as_parameter attribute which will return an integer equal to the data attribute.

1.1. The N-dimensional array (ndarray) 41

NumPy Reference, Release 1.18.1

Examples

>>> import ctypes

>>> x
array([[0, 1],
[2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>

Array interface

See also:
The Array Interface.

__array_interface__ Python-side of the array interface

__array_struct__ C-side of the array interface

ctypes foreign function interface

ndarray.ctypes An object to simplify the interaction of the array with

the ctypes module.

1.1.5 Array methods

An ndarray object has many methods which operate on or with the array in some fashion, typically returning an
array result. These methods are briefly explained below. (Each method’s docstring has a more complete description.)
For the following methods there are also corresponding functions in numpy: all, any, argmax, argmin,
argpartition, argsort, choose, clip, compress, copy, cumprod, cumsum, diagonal, imag,
max, mean, min, nonzero, partition, prod, ptp, put, ravel, real, repeat, reshape, round,
searchsorted, sort, squeeze, std, sum, swapaxes, take, trace, transpose, var.

42 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Array conversion

ndarray.item(*args) Copy an element of an array to a standard Python scalar

and return it.
ndarray.tolist() Return the array as an a.ndim-levels deep nested list
of Python scalars.
ndarray.itemset(*args) Insert scalar into an array (scalar is cast to array’s dtype,
if possible)
ndarray.tostring([order]) Construct Python bytes containing the raw data bytes in
the array.
ndarray.tobytes([order]) Construct Python bytes containing the raw data bytes in
the array.
ndarray.tofile(fid[, sep, format]) Write array to a file as text or binary (default).
ndarray.dump(file) Dump a pickle of the array to the specified file.
ndarray.dumps() Returns the pickle of the array as a string.
ndarray.astype(dtype[, order, casting, . . . ]) Copy of the array, cast to a specified type.
ndarray.byteswap([inplace]) Swap the bytes of the array elements
ndarray.copy([order]) Return a copy of the array.
ndarray.view([dtype, type]) New view of array with the same data.
ndarray.getfield(dtype[, offset]) Returns a field of the given array as a certain type.
ndarray.setflags([write, align, uic]) Set array flags WRITEABLE, ALIGNED, (WRITE-
BACKIFCOPY and UPDATEIFCOPY), respectively.
ndarray.fill(value) Fill the array with a scalar value.

Shape manipulation

For reshape, resize, and transpose, the single tuple argument may be replaced with n integers which will be interpreted
as an n-tuple.

ndarray.reshape(shape[, order]) Returns an array containing the same data with a new
shape.
ndarray.resize(new_shape[, refcheck]) Change shape and size of array in-place.
ndarray.transpose(*axes) Returns a view of the array with axes transposed.
ndarray.swapaxes(axis1, axis2) Return a view of the array with axis1 and axis2 inter-
changed.
ndarray.flatten([order]) Return a copy of the array collapsed into one dimension.
ndarray.ravel([order]) Return a flattened array.
ndarray.squeeze([axis]) Remove single-dimensional entries from the shape of a.

Item selection and manipulation

For array methods that take an axis keyword, it defaults to None. If axis is None, then the array is treated as a 1-D
array. Any other value for axis represents the dimension along which the operation should proceed.

ndarray.take(indices[, axis, out, mode]) Return an array formed from the elements of a at the
given indices.
ndarray.put(indices, values[, mode]) Set a.flat[n] = values[n] for all n in indices.
ndarray.repeat(repeats[, axis]) Repeat elements of an array.
Continued on next page

1.1. The N-dimensional array (ndarray) 43

NumPy Reference, Release 1.18.1

Table 9 – continued from previous page

ndarray.choose(choices[, out, mode]) Use an index array to construct a new array from a set
of choices.
ndarray.sort([axis, kind, order]) Sort an array in-place.
ndarray.argsort([axis, kind, order]) Returns the indices that would sort this array.
ndarray.partition(kth[, axis, kind, order]) Rearranges the elements in the array in such a way that
the value of the element in kth position is in the position
it would be in a sorted array.
ndarray.argpartition(kth[, axis, kind, order]) Returns the indices that would partition this array.
ndarray.searchsorted(v[, side, sorter]) Find indices where elements of v should be inserted in
a to maintain order.
ndarray.nonzero() Return the indices of the elements that are non-zero.
ndarray.compress(condition[, axis, out]) Return selected slices of this array along given axis.
ndarray.diagonal([offset, axis1, axis2]) Return specified diagonals.

Calculation

Many of these methods take an argument named axis. In such cases,

• If axis is None (the default), the array is treated as a 1-D array and the operation is performed over the entire
array. This behavior is also the default if self is a 0-dimensional array or array scalar. (An array scalar is
an instance of the types/classes float32, float64, etc., whereas a 0-dimensional array is an ndarray instance
containing precisely one array scalar.)
• If axis is an integer, then the operation is done over the given axis (for each 1-D subarray that can be created
along the given axis).

Example of the axis argument

A 3-dimensional array of size 3 x 3 x 3, summed over each of its three axes

>>> x
array([[[ 0, 1, 2],
[ 3, 4, 5],
[ 6, 7, 8]],
[[ 9, 10, 11],
[12, 13, 14],
[15, 16, 17]],
[[18, 19, 20],
[21, 22, 23],
[24, 25, 26]]])
>>> x.sum(axis=0)
array([[27, 30, 33],
[36, 39, 42],
[45, 48, 51]])
>>> # for sum, axis is the first keyword, so we may omit it,
>>> # specifying only its value
>>> x.sum(0), x.sum(1), x.sum(2)
(array([[27, 30, 33],
[36, 39, 42],
[45, 48, 51]]),
array([[ 9, 12, 15],
[36, 39, 42],
[63, 66, 69]]),
array([[ 3, 12, 21],
(continues on next page)

44 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

(continued from previous page)

[30, 39, 48],
[57, 66, 75]]))

The parameter dtype specifies the data type over which a reduction operation (like summing) should take place. The
default reduce data type is the same as the data type of self. To avoid overflow, it can be useful to perform the reduction
using a larger data type.
For several methods, an optional out argument can also be provided and the result will be placed into the output array
given. The out argument must be an ndarray and have the same number of elements. It can have a different data
type in which case casting will be performed.

ndarray.max([axis, out, keepdims, initial, . . . ]) Return the maximum along a given axis.
ndarray.argmax([axis, out]) Return indices of the maximum values along the given
axis.
ndarray.min([axis, out, keepdims, initial, . . . ]) Return the minimum along a given axis.
ndarray.argmin([axis, out]) Return indices of the minimum values along the given
axis of a.
ndarray.ptp([axis, out, keepdims]) Peak to peak (maximum - minimum) value along a
given axis.
ndarray.clip([min, max, out]) Return an array whose values are limited to [min,
max].
ndarray.conj() Complex-conjugate all elements.
ndarray.round([decimals, out]) Return a with each element rounded to the given number
of decimals.
ndarray.trace([offset, axis1, axis2, dtype, out]) Return the sum along diagonals of the array.
ndarray.sum([axis, dtype, out, keepdims, . . . ]) Return the sum of the array elements over the given axis.
ndarray.cumsum([axis, dtype, out]) Return the cumulative sum of the elements along the
given axis.
ndarray.mean([axis, dtype, out, keepdims]) Returns the average of the array elements along given
axis.
ndarray.var([axis, dtype, out, ddof, keepdims]) Returns the variance of the array elements, along given
axis.
ndarray.std([axis, dtype, out, ddof, keepdims]) Returns the standard deviation of the array elements
along given axis.
ndarray.prod([axis, dtype, out, keepdims, . . . ]) Return the product of the array elements over the given
axis
ndarray.cumprod([axis, dtype, out]) Return the cumulative product of the elements along the
given axis.
ndarray.all([axis, out, keepdims]) Returns True if all elements evaluate to True.
ndarray.any([axis, out, keepdims]) Returns True if any of the elements of a evaluate to True.

1.1. The N-dimensional array (ndarray) 45

NumPy Reference, Release 1.18.1

1.1.6 Arithmetic, matrix multiplication, and comparison operations

Arithmetic and comparison operations on ndarrays are defined as element-wise operations, and generally yield
ndarray objects as results.
Each of the arithmetic operations (+, -, *, /, //, %, divmod(), ** or pow(), <<, >>, &, ^, |, ~) and the
comparisons (==, <, >, <=, >=, !=) is equivalent to the corresponding universal function (or ufunc for short) in
NumPy. For more information, see the section on Universal Functions.
Comparison operators:

ndarray.__lt__(self, value, /) Return self<value.

ndarray.__le__(self, value, /) Return self<=value.
ndarray.__gt__(self, value, /) Return self>value.
ndarray.__ge__(self, value, /) Return self>=value.
ndarray.__eq__(self, value, /) Return self==value.
ndarray.__ne__(self, value, /) Return self!=value.

method
ndarray.__lt__(self, value, / )
Return self<value.
method
ndarray.__le__(self, value, / )
Return self<=value.
method
ndarray.__gt__(self, value, / )
Return self>value.
method
ndarray.__ge__(self, value, / )
Return self>=value.
method
ndarray.__eq__(self, value, / )
Return self==value.
method
ndarray.__ne__(self, value, / )
Return self!=value.
Truth value of an array (bool):

ndarray.__bool__(self, /) self != 0

method
ndarray.__bool__(self, / )
self != 0

Note: Truth-value testing of an array invokes ndarray.__bool__, which raises an error if the number of elements
in the array is larger than 1, because the truth value of such arrays is ambiguous. Use .any() and .all() instead

46 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

to be clear about what is meant in such cases. (If the number of elements is 0, the array evaluates to False.)

Unary operations:

ndarray.__neg__(self, /) -self
ndarray.__pos__(self, /) +self
ndarray.__abs__(self)
ndarray.__invert__(self, /) ~self

method
ndarray.__neg__(self, / )
-self
method
ndarray.__pos__(self, / )
+self
method
ndarray.__abs__(self )
method
ndarray.__invert__(self, / )
~self
Arithmetic:

ndarray.__add__(self, value, /) Return self+value.

ndarray.__sub__(self, value, /) Return self-value.
ndarray.__mul__(self, value, /) Return self*value.
ndarray.__truediv__(self, value, /) Return self/value.
ndarray.__floordiv__(self, value, /) Return self//value.
ndarray.__mod__(self, value, /) Return self%value.
ndarray.__divmod__(self, value, /) Return divmod(self, value).
ndarray.__pow__(self, value[, mod]) Return pow(self, value, mod).
ndarray.__lshift__(self, value, /) Return self<<value.
ndarray.__rshift__(self, value, /) Return self>>value.
ndarray.__and__(self, value, /) Return self&value.
ndarray.__or__(self, value, /) Return self|value.
ndarray.__xor__(self, value, /) Return self^value.

method
ndarray.__add__(self, value, / )
Return self+value.
method
ndarray.__sub__(self, value, / )
Return self-value.
method
ndarray.__mul__(self, value, / )
Return self*value.

1.1. The N-dimensional array (ndarray) 47

NumPy Reference, Release 1.18.1

method
ndarray.__truediv__(self, value, / )
Return self/value.
method
ndarray.__floordiv__(self, value, / )
Return self//value.
method
ndarray.__mod__(self, value, / )
Return self%value.
method
ndarray.__divmod__(self, value, / )
Return divmod(self, value).
method
ndarray.__pow__(self, value, mod=None, / )
Return pow(self, value, mod).
method
ndarray.__lshift__(self, value, / )
Return self<<value.
method
ndarray.__rshift__(self, value, / )
Return self>>value.
method
ndarray.__and__(self, value, / )
Return self&value.
method
ndarray.__or__(self, value, / )
Return self|value.
method
ndarray.__xor__(self, value, / )
Return self^value.

Note:
• Any third argument to pow is silently ignored, as the underlying ufunc takes only two arguments.
• The three division operators are all defined; div is active by default, truediv is active when __future__
division is in effect.
• Because ndarray is a built-in type (written in C), the __r{op}__ special methods are not directly defined.
• The functions called to implement many arithmetic special methods for arrays can be modified using
__array_ufunc__.

Arithmetic, in-place:

48 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

ndarray.__iadd__(self, value, /) Return self+=value.

ndarray.__isub__(self, value, /) Return self-=value.
ndarray.__imul__(self, value, /) Return self*=value.
ndarray.__itruediv__(self, value, /) Return self/=value.
ndarray.__ifloordiv__(self, value, /) Return self//=value.
ndarray.__imod__(self, value, /) Return self%=value.
ndarray.__ipow__(self, value, /) Return self**=value.
ndarray.__ilshift__(self, value, /) Return self<<=value.
ndarray.__irshift__(self, value, /) Return self>>=value.
ndarray.__iand__(self, value, /) Return self&=value.
ndarray.__ior__(self, value, /) Return self|=value.
ndarray.__ixor__(self, value, /) Return self^=value.

method
ndarray.__iadd__(self, value, / )
Return self+=value.
method
ndarray.__isub__(self, value, / )
Return self-=value.
method
ndarray.__imul__(self, value, / )
Return self*=value.
method
ndarray.__itruediv__(self, value, / )
Return self/=value.
method
ndarray.__ifloordiv__(self, value, / )
Return self//=value.
method
ndarray.__imod__(self, value, / )
Return self%=value.
method
ndarray.__ipow__(self, value, / )
Return self**=value.
method
ndarray.__ilshift__(self, value, / )
Return self<<=value.
method
ndarray.__irshift__(self, value, / )
Return self>>=value.
method
ndarray.__iand__(self, value, / )
Return self&=value.

1.1. The N-dimensional array (ndarray) 49

NumPy Reference, Release 1.18.1

method
ndarray.__ior__(self, value, / )
Return self|=value.
method
ndarray.__ixor__(self, value, / )
Return self^=value.

Warning: In place operations will perform the calculation using the precision decided by the data type of the
two operands, but will silently downcast the result (if necessary) so it can fit back into the array. Therefore, for
mixed precision calculations, A {op}= B can be different than A = A {op} B. For example, suppose a =
ones((3,3)). Then, a += 3j is different than a = a + 3j: while they both perform the same computa-
tion, a += 3 casts the result to fit back in a, whereas a = a + 3j re-binds the name a to the result.

Matrix Multiplication:

ndarray.__matmul__(self, value, /) Return self@value.

method
ndarray.__matmul__(self, value, / )
Return self@value.

Note: Matrix operators @ and @= were introduced in Python 3.5 following PEP465. NumPy 1.10.0 has a preliminary
implementation of @ for testing purposes. Further documentation can be found in the matmul documentation.

1.1.7 Special methods

For standard library functions:

ndarray.__copy__() Used if copy.copy is called on an array.

ndarray.__deepcopy__() Used if copy.deepcopy is called on an array.
ndarray.__reduce__() For pickling.
ndarray.__setstate__(state, /) For unpickling.

method
ndarray.__copy__()
Used if copy.copy is called on an array. Returns a copy of the array.
Equivalent to a.copy(order='K').
method
ndarray.__deepcopy__()
Used if copy.deepcopy is called on an array.
method
ndarray.__reduce__()
For pickling.
method

50 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

ndarray.__setstate__(state, / )
For unpickling.
The state argument must be a sequence that contains the following elements:
Parameters
version [int] optional pickle version. If omitted defaults to 0.
shape [tuple]
dtype [data-type]
isFortran [bool]
rawdata [string or list] a binary string with the data (or a list if ‘a’ is an object array)
Basic customization:

ndarray.__new__(\*args, \*\*kwargs) Create and return a new object.

ndarray.__array__() Returns either a new reference to self if dtype is not
given or a new array of provided data type if dtype is
different from the current dtype of the array.
ndarray.__array_wrap__()

method
ndarray.__new__(*args, **kwargs)
Create and return a new object. See help(type) for accurate signature.
method
ndarray.__array__()
Returns either a new reference to self if dtype is not given or a new array of provided data type if dtype is
different from the current dtype of the array.
method
ndarray.__array_wrap__()
Container customization: (see Indexing)

ndarray.__len__(self, /) Return len(self).

ndarray.__getitem__(self, key, /) Return self[key].
ndarray.__setitem__(self, key, value, /) Set self[key] to value.
ndarray.__contains__(self, key, /) Return key in self.

method
ndarray.__len__(self, / )
Return len(self).
method
ndarray.__getitem__(self, key, / )
Return self[key].
method
ndarray.__setitem__(self, key, value, / )
Set self[key] to value.
method

1.1. The N-dimensional array (ndarray) 51

NumPy Reference, Release 1.18.1

ndarray.__contains__(self, key, / )
Return key in self.
Conversion; the operations int, float and complex. . They work only on arrays that have one element in them
and return the appropriate scalar.

ndarray.__int__(self)
ndarray.__float__(self)
ndarray.__complex__()

method
ndarray.__int__(self )
method
ndarray.__float__(self )
method
ndarray.__complex__()
String representations:

ndarray.__str__(self, /) Return str(self).

ndarray.__repr__(self, /) Return repr(self).

method
ndarray.__str__(self, / )
Return str(self).
method
ndarray.__repr__(self, / )
Return repr(self).

1.2 Scalars

Python defines only one type of a particular data class (there is only one integer type, one floating-point type, etc.).
This can be convenient in applications that don’t need to be concerned with all the ways data can be represented in a
computer. For scientific computing, however, more control is often needed.
In NumPy, there are 24 new fundamental Python types to describe different types of scalars. These type descriptors
are mostly based on the types available in the C language that CPython is written in, with several additional types
compatible with Python’s types.
Array scalars have the same attributes and methods as ndarrays.1 This allows one to treat items of an array partly
on the same footing as arrays, smoothing out rough edges that result when mixing scalar and array operations.
Array scalars live in a hierarchy (see the Figure below) of data types. They can be detected using the hierarchy:
For example, isinstance(val, np.generic) will return True if val is an array scalar object. Alternatively,
what kind of array scalar is present can be determined using other members of the data type hierarchy. Thus, for
example isinstance(val, np.complexfloating) will return True if val is a complex valued type, while
isinstance(val, np.flexible) will return true if val is one of the flexible itemsize array types (string,
unicode, void).
1 However, array scalars are immutable, so none of the array scalar attributes are settable.

52 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Fig. 2: Figure: Hierarchy of type objects representing the array data types. Not shown are the two integer types intp
and uintp which just point to the integer type that holds a pointer for the platform. All the number types can be
obtained using bit-width names as well.

1.2. Scalars 53
NumPy Reference, Release 1.18.1

1.2.1 Built-in scalar types

The built-in scalar types are shown below. Along with their (mostly) C-derived names, the integer, float, and complex
data-types are also available using a bit-width convention so that an array of the right size can always be ensured (e.g.
int8, float64, complex128). Two aliases (intp and uintp) pointing to the integer type that is sufficiently
large to hold a C pointer are also provided. The C-like names are associated with character codes, which are shown in
the table. Use of the character codes, however, is discouraged.
Some of the scalar types are essentially equivalent to fundamental Python types and therefore inherit from them as
well as from the generic array scalar type:

Array scalar type Related Python type

int_ IntType (Python 2 only)
float_ FloatType
complex_ ComplexType
bytes_ BytesType
unicode_ UnicodeType

The bool_ data type is very similar to the Python BooleanType but does not inherit from it because Python’s
BooleanType does not allow itself to be inherited from, and on the C-level the size of the actual bool data is not the
same as a Python Boolean scalar.

Warning: The bool_ type is not a subclass of the int_ type (the bool_ is not even a number type). This is
different than Python’s default implementation of bool as a sub-class of int.

Warning: The int_ type does not inherit from the int built-in under Python 3, because type int is no longer
a fixed-width integer type.

Tip: The default data type in NumPy is float_.

In the tables below, platform? means that the type may not be available on all platforms. Compatibility with
different C or Python types is indicated: two types are compatible if their data is of the same size and interpreted in
the same way.
Booleans:

Type Remarks Character code

bool_ compatible: Python bool '?'
bool8 8 bits

Integers:

54 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

byte compatible: C char 'b'

short compatible: C short 'h'
intc compatible: C int 'i'
int_ compatible: Python int 'l'
longlong compatible: C long long 'q'
intp large enough to fit a pointer 'p'
int8 8 bits
int16 16 bits
int32 32 bits
int64 64 bits

Unsigned integers:

ubyte compatible: C unsigned char 'B'

ushort compatible: C unsigned short 'H'
uintc compatible: C unsigned int 'I'
uint compatible: Python int 'L'
ulonglong compatible: C long long 'Q'
uintp large enough to fit a pointer 'P'
uint8 8 bits
uint16 16 bits
uint32 32 bits
uint64 64 bits

Floating-point numbers:

half 'e'
single compatible: C float 'f'
double compatible: C double
float_ compatible: Python float 'd'
longfloat compatible: C long float 'g'
float16 16 bits
float32 32 bits
float64 64 bits
float96 96 bits, platform?
float128 128 bits, platform?

Complex floating-point numbers:

csingle 'F'
complex_ compatible: Python complex 'D'
clongfloat 'G'
complex64 two 32-bit floats
complex128 two 64-bit floats
complex192 two 96-bit floats, platform?
complex256 two 128-bit floats, platform?

Any Python object:

object_ any Python object 'O'

1.2. Scalars 55
NumPy Reference, Release 1.18.1

Note: The data actually stored in object arrays (i.e., arrays having dtype object_) are references to Python objects,
not the objects themselves. Hence, object arrays behave more like usual Python lists, in the sense that their contents
need not be of the same Python type.
The object type is also special because an array containing object_ items does not return an object_ object on
item access, but instead returns the actual object that the array item refers to.

The following data types are flexible: they have no predefined size and the data they describe can be of different length
in different arrays. (In the character codes # is an integer denoting how many elements the data type consists of.)

bytes_ compatible: Python bytes 'S#'

unicode_ compatible: Python unicode/str 'U#'
void 'V#'

Warning: See Note on string types.

Numeric Compatibility: If you used old typecode characters in your Numeric code (which was never recom-
mended), you will need to change some of them to the new characters. In particular, the needed changes are c
-> S1, b -> B, 1 -> b, s -> h, w -> H, and u -> I. These changes make the type character convention
more consistent with other Python modules such as the struct module.

1.2.2 Attributes

The array scalar objects have an array priority of NPY_SCALAR_PRIORITY (-1,000,000.0). They also do
not (yet) have a ctypes attribute. Otherwise, they share the same attributes as arrays:

generic.flags integer value of flags

generic.shape tuple of array dimensions
generic.strides tuple of bytes steps in each dimension
generic.ndim number of array dimensions
generic.data pointer to start of data
generic.size number of elements in the gentype
generic.itemsize length of one element in bytes
generic.base base object
generic.dtype get array data-descriptor
generic.real real part of scalar
generic.imag imaginary part of scalar
generic.flat a 1-d view of scalar
generic.T transpose
generic.__array_interface__ Array protocol: Python side
generic.__array_struct__ Array protocol: struct
generic.__array_priority__ Array priority.
generic.__array_wrap__() sc.__array_wrap__(obj) return scalar from array

attribute
generic.flags
integer value of flags
attribute

56 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

generic.shape
tuple of array dimensions
attribute
generic.strides
tuple of bytes steps in each dimension
attribute
generic.ndim
number of array dimensions
attribute
generic.data
pointer to start of data
attribute
generic.size
number of elements in the gentype
attribute
generic.itemsize
length of one element in bytes
attribute
generic.base
base object
attribute
generic.dtype
get array data-descriptor
attribute
generic.real
real part of scalar
attribute
generic.imag
imaginary part of scalar
attribute
generic.flat
a 1-d view of scalar
attribute
generic.T
transpose
attribute
generic.__array_interface__
Array protocol: Python side
attribute
generic.__array_struct__
Array protocol: struct

1.2. Scalars 57
NumPy Reference, Release 1.18.1

attribute
generic.__array_priority__
Array priority.
method
generic.__array_wrap__()
sc.__array_wrap__(obj) return scalar from array

1.2.3 Indexing

See also:
Indexing, Data type objects (dtype)
Array scalars can be indexed like 0-dimensional arrays: if x is an array scalar,
• x[()] returns a copy of array scalar
• x[...] returns a 0-dimensional ndarray
• x['field-name'] returns the array scalar in the field field-name. (x can have fields, for example, when it
corresponds to a structured data type.)

1.2.4 Methods

Array scalars have exactly the same methods as arrays. The default behavior of these methods is to internally convert
the scalar to an equivalent 0-dimensional array and to call the corresponding array method. In addition, math operations
on array scalars are defined so that the same hardware flags are set and used to interpret the results as for ufunc, so that
the error state used for ufuncs also carries over to the math on array scalars.
The exceptions to the above rules are given below:

generic Base class for numpy scalar types.

generic.__array__() sc.__array__(dtype) return 0-dim array from scalar with
specified dtype
generic.__array_wrap__() sc.__array_wrap__(obj) return scalar from array
generic.squeeze() Not implemented (virtual attribute)
generic.byteswap() Not implemented (virtual attribute)
generic.__reduce__() Helper for pickle.
generic.__setstate__()
generic.setflags() Not implemented (virtual attribute)

class numpy.generic
Base class for numpy scalar types.
Class from which most (all?) numpy scalar types are derived. For consistency, exposes the same API as
ndarray, despite many consequent attributes being either “get-only,” or completely irrelevant. This is the
class from which it is strongly suggested users should derive custom scalar types.
Attributes
T transpose
base base object
data pointer to start of data

58 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

dtype get array data-descriptor

flags integer value of flags
flat a 1-d view of scalar
imag imaginary part of scalar
itemsize length of one element in bytes
nbytes length of item in bytes
ndim number of array dimensions
real real part of scalar
shape tuple of array dimensions
size number of elements in the gentype
strides tuple of bytes steps in each dimension

Methods

all() Not implemented (virtual attribute)

any() Not implemented (virtual attribute)
argmax() Not implemented (virtual attribute)
argmin() Not implemented (virtual attribute)
argsort() Not implemented (virtual attribute)
astype() Not implemented (virtual attribute)
byteswap() Not implemented (virtual attribute)
choose() Not implemented (virtual attribute)
clip() Not implemented (virtual attribute)
compress() Not implemented (virtual attribute)
conjugate() Not implemented (virtual attribute)
copy() Not implemented (virtual attribute)
cumprod() Not implemented (virtual attribute)
cumsum() Not implemented (virtual attribute)
diagonal() Not implemented (virtual attribute)
dump() Not implemented (virtual attribute)
dumps() Not implemented (virtual attribute)
fill() Not implemented (virtual attribute)
flatten() Not implemented (virtual attribute)
getfield() Not implemented (virtual attribute)
item() Not implemented (virtual attribute)
itemset() Not implemented (virtual attribute)
max() Not implemented (virtual attribute)
mean() Not implemented (virtual attribute)
min() Not implemented (virtual attribute)
newbyteorder([new_order]) Return a new dtype with a different byte order.
nonzero() Not implemented (virtual attribute)
prod() Not implemented (virtual attribute)
ptp() Not implemented (virtual attribute)
put() Not implemented (virtual attribute)
ravel() Not implemented (virtual attribute)
Continued on next page

1.2. Scalars 59
NumPy Reference, Release 1.18.1

Table 24 – continued from previous page

repeat() Not implemented (virtual attribute)
reshape() Not implemented (virtual attribute)
resize() Not implemented (virtual attribute)
round() Not implemented (virtual attribute)
searchsorted() Not implemented (virtual attribute)
setfield() Not implemented (virtual attribute)
setflags() Not implemented (virtual attribute)
sort() Not implemented (virtual attribute)
squeeze() Not implemented (virtual attribute)
std() Not implemented (virtual attribute)
sum() Not implemented (virtual attribute)
swapaxes() Not implemented (virtual attribute)
take() Not implemented (virtual attribute)
tofile() Not implemented (virtual attribute)
tolist() Not implemented (virtual attribute)
tostring() Not implemented (virtual attribute)
trace() Not implemented (virtual attribute)
transpose() Not implemented (virtual attribute)
var() Not implemented (virtual attribute)
view() Not implemented (virtual attribute)

method
generic.all()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.any()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.argmax()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.argmin()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.

60 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

method
generic.argsort()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.astype()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.byteswap()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.choose()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.clip()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.compress()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.conjugate()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.

1.2. Scalars 61
NumPy Reference, Release 1.18.1

See also the corresponding attribute of the derived class of interest.

method
generic.copy()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.cumprod()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.cumsum()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.diagonal()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.dump()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.dumps()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.fill()
Not implemented (virtual attribute)

62 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.flatten()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.getfield()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.item()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.itemset()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.max()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.mean()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method

1.2. Scalars 63
NumPy Reference, Release 1.18.1

generic.min()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.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.
The new_order code can be any from the following:
• ‘S’ - swap dtype from current to opposite endian
• {‘<’, ‘L’} - little endian
• {‘>’, ‘B’} - big endian
• {‘=’, ‘N’} - native order
• {‘|’, ‘I’} - ignore (no change to byte order)

Parameters
new_order [str, optional] Byte order to force; a value from the byte order specifications
above. The default value (‘S’) results in swapping the current byte order. The code does
a case-insensitive check on the first letter of new_order for the alternatives above. For
example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns
new_dtype [dtype] New dtype object with the given change to the byte order.

method
generic.nonzero()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.prod()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.ptp()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.

64 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

See also the corresponding attribute of the derived class of interest.

method
generic.put()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.ravel()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.repeat()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.reshape()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.resize()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.round()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.searchsorted()
Not implemented (virtual attribute)

1.2. Scalars 65
NumPy Reference, Release 1.18.1

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.setfield()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.setflags()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.sort()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.squeeze()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.std()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.sum()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method

66 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

generic.swapaxes()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.take()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.tofile()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.tolist()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.tostring()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.trace()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.transpose()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.

1.2. Scalars 67
NumPy Reference, Release 1.18.1

method
generic.var()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
generic.view()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.

conj
tobytes

method
generic.__array__()
sc.__array__(dtype) return 0-dim array from scalar with specified dtype
method
generic.__reduce__()
Helper for pickle.
method
generic.__setstate__()

1.2.5 Defining new types

There are two ways to effectively define a new array scalar type (apart from composing structured types dtypes from
the built-in scalar types): One way is to simply subclass the ndarray and overwrite the methods of interest. This
will work to a degree, but internally certain behaviors are fixed by the data type of the array. To fully customize the
data type of an array you need to define a new data-type, and register it with NumPy. Such new types can only be
defined in C, using the NumPy C-API.

1.3 Data type objects (dtype)

A data type object (an instance of numpy.dtype class) describes how the bytes in the fixed-size block of memory
corresponding to an array item should be interpreted. It describes the following aspects of the data:
1. Type of the data (integer, float, Python object, etc.)
2. Size of the data (how many bytes is in e.g. the integer)
3. Byte order of the data (little-endian or big-endian)
4. If the data type is structured data type, an aggregate of other data types, (e.g., describing an array item consisting
of an integer and a float),

68 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

1. what are the names of the “fields” of the structure, by which they can be accessed,
2. what is the data-type of each field, and
3. which part of the memory block each field takes.
5. If the data type is a sub-array, what is its shape and data type.
To describe the type of scalar data, there are several built-in scalar types in NumPy for various precision of integers,
floating-point numbers, etc. An item extracted from an array, e.g., by indexing, will be a Python object whose type is
the scalar type associated with the data type of the array.
Note that the scalar types are not dtype objects, even though they can be used in place of one whenever a data type
specification is needed in NumPy.
Structured data types are formed by creating a data type whose field contain other data types. Each field has a name by
which it can be accessed. The parent data type should be of sufficient size to contain all its fields; the parent is nearly
always based on the void type which allows an arbitrary item size. Structured data types may also contain nested
structured sub-array data types in their fields.
Finally, a data type can describe items that are themselves arrays of items of another data type. These sub-arrays must,
however, be of a fixed size.
If an array is created using a data-type describing a sub-array, the dimensions of the sub-array are appended to the
shape of the array when the array is created. Sub-arrays in a field of a structured type behave differently, see Field
Access.
Sub-arrays always have a C-contiguous memory layout.

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

>>> dt = np.dtype('>i4')
>>> dt.byteorder
'>'
>>> dt.itemsize
4
>>> dt.name
'int32'
>>> dt.type is np.int32
True

The corresponding array scalar type is int32.

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 an array scalar type that also has two fields:

1.3. Data type objects (dtype) 69

NumPy Reference, Release 1.18.1

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

1.3.1 Specifying and constructing data types

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

dtype(obj[, align, copy]) Create a data type object.

class numpy.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')])])

70 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Structured type, two fields: the first field contains an unsigned int, the second an int32:

>>> np.dtype([('f1', np.uint64), ('f2', np.int32)])

dtype([('f1', '<u8'), ('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.int64,3)),('world',np.void,10)])
dtype([('hello', '<i8', (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((numpy.int16, [('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')])

Attributes
alignment The required alignment (bytes) of this data-type according to the compiler.
base Returns dtype for the base element of the subarrays, regardless of their dimension or
shape.
byteorder A character indicating the byte-order of this data-type object.
char A unique character code for each of the 21 different built-in types.
descr __array_interface__ description of the data-type.
fields Dictionary of named fields defined for this data type, or None.
flags Bit-flags describing how this data type is to be interpreted.
hasobject Boolean indicating whether this dtype contains any reference-counted objects in
any fields or sub-dtypes.
isalignedstruct Boolean indicating whether the dtype is a struct which maintains field
alignment.
isbuiltin Integer indicating how this dtype relates to the built-in dtypes.
isnative Boolean indicating whether the byte order of this dtype is native to the platform.

1.3. Data type objects (dtype) 71

NumPy Reference, Release 1.18.1

itemsize The element size of this data-type object.

kind A character code (one of ‘biufcmMOSUV’) identifying the general kind of data.
metadata
name A bit-width name for this data-type.
names Ordered list of field names, or None if there are no fields.
ndim Number of dimensions of the sub-array if this data type describes a sub-array, and 0
otherwise.
num A unique number for each of the 21 different built-in types.
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.
type The type object used to instantiate a scalar of this data-type.

Methods

newbyteorder([new_order]) Return a new dtype with a different byte order.

method
dtype.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 alterna-
tives. 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.

72 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

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

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-in array 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 a type-object: for example, flexible
data-types have a default itemsize of 0, and require an explicitly given size to be useful.

Example

>>> dt = np.dtype(np.int32) # 32-bit integer

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

Generic types

1.3. Data type objects (dtype) 73

NumPy Reference, Release 1.18.1

The generic hierarchical type objects convert to corresponding type 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 corresponding array scalar when used to generate a dtype object:

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

Note that str refers to either null terminated bytes or unicode strings depending on the Python version.
In code targeting both Python 2 and 3 np.unicode_ should be used as a dtype for strings. See Note 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 a dtype attribute: The attribute will be accessed and used directly. The attribute
must return something that is convertible into a dtype object.
Several kinds of strings can be converted. Recognized strings can be prepended with '>' (big-endian), '<' (little-
endian), or '=' (hardware-native, the default), to specify 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 (see The Array Interface)

74 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

The first character specifies the kind of data and the remaining characters specify the number of bytes
per item, except for Unicode, where it is interpreted as the number of characters. The item size must
correspond to an existing type, or an error will be raised. The supported 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 the S and a typestrings remain zero-terminated bytes and np.
string_ continues to map to np.bytes_. To use actual strings in Python 3 use U or np.unicode_.
For signed bytes that do not need zero-termination b or i1 can be used.

String with comma-separated fields

A short-hand notation for specifying the format of a structured data type is a comma-separated string of
basic formats.
A basic format in this context is an optional shape specifier followed by an array-protocol type string.
Parenthesis are required on the shape if it has more than one dimension. NumPy allows a modification
on the format in that any string that can uniquely identify the type 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 basic formats in the string. If the optional shape specifier is provided, then
the data-type for the corresponding field describes a sub-array.

Example
• field named f0 containing a 32-bit integer
• field named f1 containing a 2 x 3 sub-array of 64-bit floating-point numbers
• field named f2 containing a 32-bit floating-point number

1.3. Data type objects (dtype) 75

NumPy Reference, Release 1.18.1

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

• field named f0 containing a 3-character string

• field named f1 containing a sub-array of shape (3,) containing 64-bit unsigned integers
• field named f2 containing a 3 x 4 sub-array containing 10-character strings

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

Type strings
Any string in numpy.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 a zero-sized flexible data-type object, the second
argument is an 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 a fixed-size data-type object. The second
argument is the desired shape of this type. If the shape parameter is 1, then the data-type object is
equivalent to fixed dtype. If shape is a tuple, 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 a tuple of length 2 or 3. (Equivalent to the
descr 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 as-
signed). The field name may also be a 2-tuple of strings where the first string is either a “title” (which
may be any string or unicode string) or meta-data for the field which can be any object, and the second
string is the “name” which must be a valid Python identifier.
The second element, field_dtype, can be anything that can be interpreted as a data-type.

76 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

The optional third element field_shape contains the shape if this field represents an array of the data-type
in the second element. Note that a 3-tuple with a third argument equal to 1 is equivalent to a 2-tuple.
This style does not accept align in the dtype constructor as it is assumed that all of the memory is
accounted for by the array interface description.

Example
Data-type with fields big (big-endian 32-bit integer) and little (little-endian 32-bit integer):

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

Data-type with fields R, G, B, A, each being an unsigned 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. The names and formats keys are required. Their
respective values are equal-length lists with the field names and the field formats. The field names must
be strings and the field formats can be any object accepted by dtype constructor.
When the optional keys offsets and titles are provided, their values must each be lists of the same length
as the names and formats lists. The offsets value is a list of byte offsets (limited to ctypes.c_int)
for each field, while the titles value is a list of titles for each field (None can be used if no title is desired
for that field). The titles can be any string or unicode object and will add another entry to the
fields dictionary keyed by the title and referencing the same field tuple which will contain the title as an
additional tuple member.
The itemsize key allows the total size of the dtype to be set, and must be an integer large enough so all the
fields are within the dtype. If the dtype being constructed is aligned, the itemsize must also be divisible
by the struct alignment. Total dtype itemsize is limited to ctypes.c_int.

Example
Data type with fields r, g, b, a, each being an 8-bit unsigned integer:

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

... 'formats': [uint8, uint8, uint8, uint8]})

Data type with fields r and b (with the given titles), both being 8-bit unsigned integers, the first at byte
position 0 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 the other dict-based construction method. If you
have a field called ‘names’ and a field called ‘formats’ there will be a conflict.
This style allows passing in the fields attribute of a data-type object.
obj should contain string or unicode keys that refer to (data-type, offset) or (data-type,
offset, title) tuples.

1.3. Data type objects (dtype) 77

NumPy Reference, Release 1.18.1

Example
Data type containing field col1 (10-character string at byte position 0), col2 (32-bit float at byte posi-
tion 10), and col3 (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 allows base_dtype to be interpreted as a structured dtype. Arrays
created with this dtype will have underlying dtype base_dtype but will have fields and flags taken from
new_dtype. This is useful for creating custom structured dtypes, as done in record arrays.
This form also makes it possible to specify struct dtypes with overlapping fields, 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 total size.

Example
32-bit integer, whose first two bytes are interpreted as an integer via field real, and the following two
bytes via field imag.

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

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

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

32-bit integer, containing fields r, g, b, a that interpret the 4 bytes in the integer as four unsigned integers:

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

1.3.2 dtype

NumPy data type descriptions are instances of the dtype class.

Attributes

The type of the data is described by the following dtype attributes:

dtype.type The type object used to instantiate a scalar of this data-

type.
dtype.kind A character code (one of ‘biufcmMOSUV’) identifying
the general kind of data.
dtype.char A unique character code for each of the 21 different
built-in types.
dtype.num A unique number for each of the 21 different built-in
types.
dtype.str The array-protocol typestring of this data-type object.

78 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

attribute
dtype.type
The type object used to instantiate a scalar of this data-type.
attribute
dtype.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

Examples

>>> dt = np.dtype('i4')
>>> dt.kind
'i'
>>> dt = np.dtype('f8')
>>> dt.kind
'f'
>>> dt = np.dtype([('field1', 'f8')])
>>> dt.kind
'V'

attribute
dtype.char
A unique character code for each of the 21 different built-in types.

Examples

>>> x = np.dtype(float)
>>> x.char
'd'

attribute
dtype.num
A unique number for each of the 21 different built-in types.
These are roughly ordered from least-to-most precision.

1.3. Data type objects (dtype) 79

NumPy Reference, Release 1.18.1

Examples

>>> dt = np.dtype(str)
>>> dt.num
19

>>> dt = np.dtype(float)
>>> dt.num
12

attribute
dtype.str
The array-protocol typestring of this data-type object.
Size of the data is in turn described by:

dtype.name A bit-width name for this data-type.

dtype.itemsize The element size of this data-type object.

attribute
dtype.name
A bit-width name for this data-type.
Un-sized flexible data-type objects do not have this attribute.

Examples

>>> x = np.dtype(float)
>>> x.name
'float64'
>>> x = np.dtype([('a', np.int32, 8), ('b', np.float64, 6)])
>>> x.name
'void640'

attribute
dtype.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.

Examples

>>> arr = np.array([[1, 2], [3, 4]])

>>> arr.dtype
dtype('int64')
>>> arr.itemsize
8

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

>>> dt.itemsize
80

80 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Endianness of this data:

dtype.byteorder A character indicating the byte-order of this data-type

object.

attribute
dtype.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

Information about sub-data-types in a structured data type:

dtype.fields Dictionary of named fields defined for this data type, or

None.
dtype.names Ordered list of field names, or None if there are no
fields.

attribute
dtype.fields

1.3. Data type objects (dtype) 81

NumPy Reference, Release 1.18.1

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

Offset is limited to C int, which is signed and usually 32 bits. 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)}

attribute
dtype.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')

For data types that describe sub-arrays:

dtype.subdtype Tuple (item_dtype, shape) if this dtype de-

scribes a sub-array, and None otherwise.
dtype.shape Shape tuple of the sub-array if this data type describes a
sub-array, and () otherwise.

attribute
dtype.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.
See also:
dtype.base

82 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = numpy.dtype('8f')
>>> x.subdtype
(dtype('float32'), (8,))

>>> x = numpy.dtype('i2')
>>> x.subdtype
>>>

attribute
dtype.shape
Shape tuple of the sub-array if this data type describes a sub-array, and () otherwise.

Examples

>>> dt = np.dtype(('i4', 4))

>>> dt.shape
(4,)

>>> dt = np.dtype(('i4', (2, 3)))

>>> dt.shape
(2, 3)

Attributes providing additional information:

dtype.hasobject Boolean indicating whether this dtype contains any

reference-counted objects in any fields or sub-dtypes.
dtype.flags Bit-flags describing how this data type is to be inter-
preted.
dtype.isbuiltin Integer indicating how this dtype relates to the built-in
dtypes.
dtype.isnative Boolean indicating whether the byte order of this dtype
is native to the platform.
dtype.descr __array_interface__ description of the data-type.
dtype.alignment The required alignment (bytes) of this data-type accord-
ing to the compiler.
dtype.base Returns dtype for the base element of the subarrays, re-
gardless of their dimension or shape.

attribute
dtype.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.
attribute
dtype.flags
Bit-flags describing how this data type is to be interpreted.

1.3. Data type objects (dtype) 83

NumPy Reference, Release 1.18.1

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.
The following example demonstrates that operations on this particular dtype requires Python C-API.

Examples

>>> x = np.dtype([('a', np.int32, 8), ('b', np.float64, 6)])

>>> x.flags
16
>>> np.core.multiarray.NEEDS_PYAPI
16

attribute
dtype.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 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

attribute
dtype.isnative
Boolean indicating whether the byte order of this dtype is native to the platform.
attribute
dtype.descr
__array_interface__ description of the data-type.
The format is that required by the ‘descr’ key in the __array_interface__ attribute.
Warning: This attribute exists specifically for __array_interface__, and passing it directly to np.dtype will not
accurately reconstruct some dtypes (e.g., scalar and subarray dtypes).

84 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = np.dtype(float)
>>> x.descr
[('', '<f8')]

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

>>> dt.descr
[('name', '<U16'), ('grades', '<f8', (2,))]

attribute
dtype.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.

Examples

>>> x = np.dtype('i4')
>>> x.alignment
4

>>> x = np.dtype(float)
>>> x.alignment
8

attribute
dtype.base
Returns dtype for the base element of the subarrays, regardless of their dimension or shape.
See also:
dtype.subdtype

Examples

>>> x = numpy.dtype('8f')
>>> x.base
dtype('float32')

>>> x = numpy.dtype('i2')
>>> x.base
dtype('int16')

1.3. Data type objects (dtype) 85

NumPy Reference, Release 1.18.1

Methods

Data types have the following method for changing the byte order:

dtype.newbyteorder([new_order]) Return a new dtype with a different byte order.

The following methods implement the pickle protocol:

dtype.__reduce__() Helper for pickle.

dtype.__setstate__()

method
dtype.__reduce__()
Helper for pickle.
method
dtype.__setstate__()

1.4 Indexing

See also:
Indexing basics
ndarrays can be indexed using the standard Python x[obj] syntax, where x is the array and obj the selection.
There are three kinds of indexing available: field access, basic slicing, advanced indexing. Which one occurs depends
on obj.

Note: In Python, x[(exp1, exp2, ..., expN)] is equivalent to x[exp1, exp2, ..., expN]; the
latter is just syntactic sugar for the former.

1.4.1 Basic Slicing and Indexing

Basic slicing extends Python’s basic concept of slicing to N dimensions. Basic slicing occurs when obj is a slice
object (constructed by start:stop:step notation inside of brackets), an integer, or a tuple of slice objects and
integers. Ellipsis and newaxis objects can be interspersed with these as well.
Deprecated since version 1.15.0: In order to remain backward compatible with a common usage in Numeric, basic
slicing is also initiated if the selection object is any non-ndarray and non-tuple sequence (such as a list) contain-
ing slice objects, the Ellipsis object, or the newaxis object, but not for integer arrays or other embedded
sequences.
The simplest case of indexing with N integers returns an array scalar representing the corresponding item. As in
Python, all indices are zero-based: for the i-th index 𝑛𝑖 , the valid range is 0 ≤ 𝑛𝑖 < 𝑑𝑖 where 𝑑𝑖 is the i-th element of
the shape of the array. Negative indices are interpreted as counting from the end of the array (i.e., if 𝑛𝑖 < 0, it means
𝑛𝑖 + 𝑑𝑖 ).
All arrays generated by basic slicing are always views of the original array.

86 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Note: NumPy slicing creates a view instead of a copy as in the case of builtin Python sequences such as string,
tuple and list. Care must be taken when extracting a small portion from a large array which becomes useless after the
extraction, because the small portion extracted contains a reference to the large original array whose memory will not
be released until all arrays derived from it are garbage-collected. In such cases an explicit copy() is recommended.

The standard rules of sequence slicing apply to basic slicing on a per-dimension basis (including using a step index).
Some useful concepts to remember include:
• The basic slice syntax is i:j:k where i is the starting index, j is the stopping index, and k is the step (𝑘 ̸= 0).
This selects the m elements (in the corresponding dimension) with index values i, i + k, . . . , i + (m - 1) k where
𝑚 = 𝑞 + (𝑟 ̸= 0) and q and r are the quotient and remainder obtained by dividing j - i by k: j - i = q k + r, so
that i + (m - 1) k < j.

Example
>>> x = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> x[1:7:2]
array([1, 3, 5])

• Negative i and j are interpreted as n + i and n + j where n is the number of elements in the corresponding
dimension. Negative k makes stepping go towards smaller indices.

Example
>>> x[-2:10]
array([8, 9])
>>> x[-3:3:-1]
array([7, 6, 5, 4])

• Assume n is the number of elements in the dimension being sliced. Then, if i is not given it defaults to 0 for k >
0 and n - 1 for k < 0 . If j is not given it defaults to n for k > 0 and -n-1 for k < 0 . If k is not given it defaults to
1. Note that :: is the same as : and means select all indices along this axis.

Example
>>> x[5:]
array([5, 6, 7, 8, 9])

• If the number of objects in the selection tuple is less than N , then : is assumed for any subsequent dimensions.

Example
>>> x = np.array([[[1],[2],[3]], [[4],[5],[6]]])
>>> x.shape
(2, 3, 1)
>>> x[1:2]
array([[[4],
[5],
[6]]])

1.4. Indexing 87
NumPy Reference, Release 1.18.1

• Ellipsis expands to the number of : objects needed for the selection tuple to index all dimensions. In most
cases, this means that length of the expanded selection tuple is x.ndim. There may only be a single ellipsis
present.

Example

>>> x[...,0]
array([[1, 2, 3],
[4, 5, 6]])

• Each newaxis object in the selection tuple serves to expand the dimensions of the resulting selection by one
unit-length dimension. The added dimension is the position of the newaxis object in the selection tuple.

Example

>>> x[:,np.newaxis,:,:].shape
(2, 1, 3, 1)

• An integer, i, returns the same values as i:i+1 except the dimensionality of the returned object is reduced by 1.
In particular, a selection tuple with the p-th element an integer (and all other entries :) returns the corresponding
sub-array with dimension N - 1. If N = 1 then the returned object is an array scalar. These objects are explained
in Scalars.
• If the selection tuple has all entries : except the p-th entry which is a slice object i:j:k, then the returned
array has dimension N formed by concatenating the sub-arrays returned by integer indexing of elements i, i+k,
. . . , i + (m - 1) k < j,
• Basic slicing with more than one non-: entry in the slicing tuple, acts like repeated application of slicing using
a single non-: entry, where the non-: entries are successively taken (with all other non-: entries replaced by
:). Thus, x[ind1,...,ind2,:] acts like x[ind1][...,ind2,:] under basic slicing.

Warning: The above is not true for advanced indexing.

• You may use slicing to set values in the array, but (unlike lists) you can never grow the array. The size of the
value to be set in x[obj] = value must be (broadcastable) to the same shape as x[obj].

Note: Remember that a slicing tuple can always be constructed as obj and used in the x[obj] notation. Slice objects
can be used in the construction in place of the [start:stop:step] notation. For example, x[1:10:5,::-1]
can also be implemented as obj = (slice(1,10,5), slice(None,None,-1)); x[obj] . This can be
useful for constructing generic code that works on arrays of arbitrary dimension.

numpy.newaxis
The newaxis object can be used in all slicing operations to create an axis of length one. newaxis is an alias
for ‘None’, and ‘None’ can be used in place of this with the same result.

88 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

1.4.2 Advanced Indexing

Advanced indexing is triggered when the selection object, obj, is a non-tuple sequence object, an ndarray (of data
type integer or bool), or a tuple with at least one sequence object or ndarray (of data type integer or bool). There are
two types of advanced indexing: integer and Boolean.
Advanced indexing always returns a copy of the data (contrast with basic slicing that returns a view).

Warning: The definition of advanced indexing means that x[(1,2,3),] is fundamentally different than
x[(1,2,3)]. The latter is equivalent to x[1,2,3] which will trigger basic selection while the former will
trigger advanced indexing. Be sure to understand why this occurs.
Also recognize that x[[1,2,3]] will trigger advanced indexing, whereas due to the deprecated Numeric com-
patibility mentioned above, x[[1,2,slice(None)]] will trigger basic slicing.

Integer array indexing

Integer array indexing allows selection of arbitrary items in the array based on their N-dimensional index. Each integer
array represents a number of indexes into that dimension.

Purely integer array indexing

When the index consists of as many integer arrays as the array being indexed has dimensions, the indexing is straight
forward, but different from slicing.
Advanced indexes always are broadcast and iterated as one:

result[i_1, ..., i_M] == x[ind_1[i_1, ..., i_M], ind_2[i_1, ..., i_M],

..., ind_N[i_1, ..., i_M]]

Note that the result shape is identical to the (broadcast) indexing array shapes ind_1, ..., ind_N.

Example
From each row, a specific element should be selected. The row index is just [0, 1, 2] and the column index
specifies the element to choose for the corresponding row, here [0, 1, 0]. Using both together the task can be
solved using advanced indexing:

>>> x = np.array([[1, 2], [3, 4], [5, 6]])

>>> x[[0, 1, 2], [0, 1, 0]]
array([1, 4, 5])

To achieve a behaviour similar to the basic slicing above, broadcasting can be used. The function ix_ can help with
this broadcasting. This is best understood with an example.

Example
From a 4x3 array the corner elements should be selected using advanced indexing. Thus all elements for which the
column is one of [0, 2] and the row is one of [0, 3] need to be selected. To use advanced indexing one needs to
select all elements explicitly. Using the method explained previously one could write:

1.4. Indexing 89
NumPy Reference, Release 1.18.1

>>> x = array([[ 0, 1, 2],

... [ 3, 4, 5],
... [ 6, 7, 8],
... [ 9, 10, 11]])
>>> rows = np.array([[0, 0],
... [3, 3]], dtype=np.intp)
>>> columns = np.array([[0, 2],
... [0, 2]], dtype=np.intp)
>>> x[rows, columns]
array([[ 0, 2],
[ 9, 11]])

However, since the indexing arrays above just repeat themselves, broadcasting can be used (compare operations such
as rows[:, np.newaxis] + columns) to simplify this:

>>> rows = np.array([0, 3], dtype=np.intp)

>>> columns = np.array([0, 2], dtype=np.intp)
>>> rows[:, np.newaxis]
array([[0],
[3]])
>>> x[rows[:, np.newaxis], columns]
array([[ 0, 2],
[ 9, 11]])

This broadcasting can also be achieved using the function ix_:

>>> x[np.ix_(rows, columns)]

array([[ 0, 2],
[ 9, 11]])

Note that without the np.ix_ call, only the diagonal elements would be selected, as was used in the previous example.
This difference is the most important thing to remember about indexing with multiple advanced indexes.

Combining advanced and basic indexing

When there is at least one slice (:), ellipsis (...) or newaxis in the index (or the array has more dimensions than
there are advanced indexes), then the behaviour can be more complicated. It is like concatenating the indexing result
for each advanced index element
In the simplest case, there is only a single advanced index. A single advanced index can for example replace a slice and
the result array will be the same, however, it is a copy and may have a different memory layout. A slice is preferable
when it is possible.

Example

>>> x[1:2, 1:3]

array([[4, 5]])
>>> x[1:2, [1, 2]]
array([[4, 5]])

The easiest way to understand the situation may be to think in terms of the result shape. There are two parts to
the indexing operation, the subspace defined by the basic indexing (excluding integers) and the subspace from the
advanced indexing part. Two cases of index combination need to be distinguished:

90 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

• The advanced indexes are separated by a slice, Ellipsis or newaxis. For example x[arr1, :,
arr2].
• The advanced indexes are all next to each other. For example x[..., arr1, arr2, :] but not x[arr1,
:, 1] since 1 is an advanced index in this regard.
In the first case, the dimensions resulting from the advanced indexing operation come first in the result array, and the
subspace dimensions after that. In the second case, the dimensions from the advanced indexing operations are inserted
into the result array at the same spot as they were in the initial array (the latter logic is what makes simple advanced
indexing behave just like slicing).

Example
Suppose x.shape is (10,20,30) and ind is a (2,3,4)-shaped indexing intp array, then result = x[...,ind,
:] has shape (10,2,3,4,30) because the (20,)-shaped subspace has been replaced with a (2,3,4)-shaped broadcasted
indexing subspace. If we let i, j, k loop over the (2,3,4)-shaped subspace then result[...,i,j,k,:] = x[.
..,ind[i,j,k],:]. This example produces the same result as x.take(ind, axis=-2).

Example
Let x.shape be (10,20,30,40,50) and suppose ind_1 and ind_2 can be broadcast to the shape (2,3,4). Then x[:,
ind_1,ind_2] has shape (10,2,3,4,40,50) because the (20,30)-shaped subspace from X has been replaced with the
(2,3,4) subspace from the indices. However, x[:,ind_1,:,ind_2] has shape (2,3,4,10,30,50) because there is no
unambiguous place to drop in the indexing subspace, thus it is tacked-on to the beginning. It is always possible to use
.transpose() to move the subspace anywhere desired. Note that this example cannot be replicated using take.

Boolean array indexing

This advanced indexing occurs when obj is an array object of Boolean type, such as may be returned from comparison
operators. A single boolean index array is practically identical to x[obj.nonzero()] where, as described above,
obj.nonzero() returns a tuple (of length obj.ndim) of integer index arrays showing the True elements of obj.
However, it is faster when obj.shape == x.shape.
If obj.ndim == x.ndim, x[obj] returns a 1-dimensional array filled with the elements of x corresponding to
the True values of obj. The search order will be row-major, C-style. If obj has True values at entries that are outside
of the bounds of x, then an index error will be raised. If obj is smaller than x it is identical to filling it with False.

Example
A common use case for this is filtering for desired element values. For example one may wish to select all entries from
an array which are not NaN:

>>> x = np.array([[1., 2.], [np.nan, 3.], [np.nan, np.nan]])

>>> x[~np.isnan(x)]
array([ 1., 2., 3.])

Or wish to add a constant to all negative elements:

>>> x = np.array([1., -1., -2., 3])

>>> x[x < 0] += 20
>>> x
array([ 1., 19., 18., 3.])

1.4. Indexing 91
NumPy Reference, Release 1.18.1

In general if an index includes a Boolean array, the result will be identical to inserting obj.nonzero() into the
same position and using the integer array indexing mechanism described above. x[ind_1, boolean_array,
ind_2] is equivalent to x[(ind_1,) + boolean_array.nonzero() + (ind_2,)].
If there is only one Boolean array and no integer indexing array present, this is straight forward. Care must only be
taken to make sure that the boolean index has exactly as many dimensions as it is supposed to work with.

Example
From an array, select all rows which sum up to less or equal two:

>>> x = np.array([[0, 1], [1, 1], [2, 2]])

>>> rowsum = x.sum(-1)
>>> x[rowsum <= 2, :]
array([[0, 1],
[1, 1]])

But if rowsum would have two dimensions as well:

>>> rowsum = x.sum(-1, keepdims=True)

>>> rowsum.shape
(3, 1)
>>> x[rowsum <= 2, :] # fails
IndexError: too many indices
>>> x[rowsum <= 2]
array([0, 1])

The last one giving only the first elements because of the extra dimension. Compare rowsum.nonzero() to
understand this example.

Combining multiple Boolean indexing arrays or a Boolean with an integer indexing array can best be understood with
the obj.nonzero() analogy. The function ix_ also supports boolean arrays and will work without any surprises.

Example
Use boolean indexing to select all rows adding up to an even number. At the same time columns 0 and 2 should be
selected with an advanced integer index. Using the ix_ function this can be done with:

>>> x = array([[ 0, 1, 2],

... [ 3, 4, 5],
... [ 6, 7, 8],
... [ 9, 10, 11]])
>>> rows = (x.sum(-1) % 2) == 0
>>> rows
array([False, True, False, True])
>>> columns = [0, 2]
>>> x[np.ix_(rows, columns)]
array([[ 3, 5],
[ 9, 11]])

Without the np.ix_ call or only the diagonal elements would be selected.
Or without np.ix_ (compare the integer array examples):

92 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> rows = rows.nonzero()[0]

>>> x[rows[:, np.newaxis], columns]
array([[ 3, 5],
[ 9, 11]])

1.4.3 Detailed notes

These are some detailed notes, which are not of importance for day to day indexing (in no particular order):
• The native NumPy indexing type is intp and may differ from the default integer array type. intp is the
smallest data type sufficient to safely index any array; for advanced indexing it may be faster than other types.
• For advanced assignments, there is in general no guarantee for the iteration order. This means that if an element
is set more than once, it is not possible to predict the final result.
• An empty (tuple) index is a full scalar index into a zero dimensional array. x[()] returns a scalar if x is zero
dimensional and a view otherwise. On the other hand x[...] always returns a view.
• If a zero dimensional array is present in the index and it is a full integer index the result will be a scalar and not
a zero dimensional array. (Advanced indexing is not triggered.)
• When an ellipsis (...) is present but has no size (i.e. replaces zero :) the result will still always be an array. A
view if no advanced index is present, otherwise a copy.
• the nonzero equivalence for Boolean arrays does not hold for zero dimensional boolean arrays.
• When the result of an advanced indexing operation has no elements but an individual index is out of bounds,
whether or not an IndexError is raised is undefined (e.g. x[[], [123]] with 123 being out of bounds).
• When a casting error occurs during assignment (for example updating a numerical array using a sequence of
strings), the array being assigned to may end up in an unpredictable partially updated state. However, if any
other error (such as an out of bounds index) occurs, the array will remain unchanged.
• The memory layout of an advanced indexing result is optimized for each indexing operation and no particular
memory order can be assumed.
• When using a subclass (especially one which manipulates its shape), the default ndarray.__setitem__
behaviour will call __getitem__ for basic indexing but not for advanced indexing. For such a subclass it
may be preferable to call ndarray.__setitem__ with a base class ndarray view on the data. This must be
done if the subclasses __getitem__ does not return views.

1.4.4 Field Access

See also:
Data type objects (dtype), Scalars
If the ndarray object is a structured array the fields of the array can be accessed by indexing the array with strings,
dictionary-like.
Indexing x['field-name'] returns a new view to the array, which is of the same shape as x (except when the field
is a sub-array) but of data type x.dtype['field-name'] and contains only the part of the data in the specified
field. Also record array scalars can be “indexed” this way.
Indexing into a structured array can also be done with a list of field names, e.g. x[['field-name1',
'field-name2']]. As of NumPy 1.16 this returns a view containing only those fields. In older versions of
numpy it returned a copy. See the user guide section on structured_arrays for more information on multifield indexing.

1.4. Indexing 93
NumPy Reference, Release 1.18.1

If the accessed field is a sub-array, the dimensions of the sub-array are appended to the shape of the result.

Example

>>> x = np.zeros((2,2), dtype=[('a', np.int32), ('b', np.float64, (3,3))])

>>> x['a'].shape
(2, 2)
>>> x['a'].dtype
dtype('int32')
>>> x['b'].shape
(2, 2, 3, 3)
>>> x['b'].dtype
dtype('float64')

1.4.5 Flat Iterator indexing

x.flat returns an iterator that will iterate over the entire array (in C-contiguous style with the last index varying
the fastest). This iterator object can also be indexed using basic slicing or advanced indexing as long as the selection
object is not a tuple. This should be clear from the fact that x.flat is a 1-dimensional view. It can be used for integer
indexing with 1-dimensional C-style-flat indices. The shape of any returned array is therefore the shape of the integer
indexing object.

1.5 Iterating Over Arrays

The iterator object nditer, introduced in NumPy 1.6, provides many flexible ways to visit all the elements of one
or more arrays in a systematic fashion. This page introduces some basic ways to use the object for computations on
arrays in Python, then concludes with how one can accelerate the inner loop in Cython. Since the Python exposure of
nditer is a relatively straightforward mapping of the C array iterator API, these ideas will also provide help working
with array iteration from C or C++.

1.5.1 Single Array Iteration

The most basic task that can be done with the nditer is to visit every element of an array. Each element is provided
one by one using the standard Python iterator interface.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a):
... print(x, end=' ')
...
0 1 2 3 4 5

An important thing to be aware of for this iteration is that the order is chosen to match the memory layout of the array
instead of using a standard C or Fortran ordering. This is done for access efficiency, reflecting the idea that by default
one simply wants to visit each element without concern for a particular ordering. We can see this by iterating over the
transpose of our previous array, compared to taking a copy of that transpose in C order.

94 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a.T):
... print(x, end=' ')
...
0 1 2 3 4 5

>>> for x in np.nditer(a.T.copy(order='C')):

... print(x, end=' ')
...
0 3 1 4 2 5

The elements of both a and a.T get traversed in the same order, namely the order they are stored in memory, whereas
the elements of a.T.copy(order=’C’) get visited in a different order because they have been put into a different memory
layout.

Controlling Iteration Order

There are times when it is important to visit the elements of an array in a specific order, irrespective of the layout of the
elements in memory. The nditer object provides an order parameter to control this aspect of iteration. The default,
having the behavior described above, is order=’K’ to keep the existing order. This can be overridden with order=’C’
for C order and order=’F’ for Fortran order.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, order='F'):
... print(x, end=' ')
...
0 3 1 4 2 5
>>> for x in np.nditer(a.T, order='C'):
... print(x, end=' ')
...
0 3 1 4 2 5

Modifying Array Values

By default, the nditer treats the input operand as a read-only object. To be able to modify the array elements, you
must specify either read-write or write-only mode using the ‘readwrite’ or ‘writeonly’ per-operand flags.
The nditer will then yield writeable buffer arrays which you may modify. However, because the nditer must copy this
buffer data back to the original array once iteration is finished, you must signal when the iteration is ended, by one of
two methods. You may either:
• used the nditer as a context manager using the with statement, and the temporary data will be written back when
the context is exited.
• call the iterator’s close method once finished iterating, which will trigger the write-back.
The nditer can no longer be iterated once either close is called or its context is exited.

1.5. Iterating Over Arrays 95

NumPy Reference, Release 1.18.1

Example

>>> a = np.arange(6).reshape(2,3)
>>> a
array([[0, 1, 2],
[3, 4, 5]])
>>> with np.nditer(a, op_flags=['readwrite']) as it:
... for x in it:
... x[...] = 2 * x
...
>>> a
array([[ 0, 2, 4],
[ 6, 8, 10]])

If you are writing code that needs to support older versions of numpy, note that prior to 1.15, nditer was not a
context manager and did not have a close method. Instead it relied on the destructor to initiate the writeback of the
buffer.

Using an External Loop

In all the examples so far, the elements of a are provided by the iterator one at a time, because all the looping logic is
internal to the iterator. While this is simple and convenient, it is not very efficient. A better approach is to move the
one-dimensional innermost loop into your code, external to the iterator. This way, NumPy’s vectorized operations can
be used on larger chunks of the elements being visited.
The nditer will try to provide chunks that are as large as possible to the inner loop. By forcing ‘C’ and ‘F’ order,
we get different external loop sizes. This mode is enabled by specifying an iterator flag.
Observe that with the default of keeping native memory order, the iterator is able to provide a single one-dimensional
chunk, whereas when forcing Fortran order, it has to provide three chunks of two elements each.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, flags=['external_loop']):
... print(x, end=' ')
...
[0 1 2 3 4 5]

>>> for x in np.nditer(a, flags=['external_loop'], order='F'):

... print(x, end=' ')
...
[0 3] [1 4] [2 5]

96 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Tracking an Index or Multi-Index

During iteration, you may want to use the index of the current element in a computation. For example, you may want
to visit the elements of an array in memory order, but use a C-order, Fortran-order, or multidimensional index to look
up values in a different array.
The index is tracked by the iterator object itself, and accessible through the index or multi_index properties, depending
on what was requested. The examples below show printouts demonstrating the progression of the index:

Example

>>> a = np.arange(6).reshape(2,3)
>>> it = np.nditer(a, flags=['f_index'])
>>> for x in it:
... print("%d <%d>" % (x, it.index), end=' ')
...
0 <0> 1 <2> 2 <4> 3 <1> 4 <3> 5 <5>

>>> it = np.nditer(a, flags=['multi_index'])

>>> for x in it:
... print("%d <%s>" % (x, it.multi_index), end=' ')
...
0 <(0, 0)> 1 <(0, 1)> 2 <(0, 2)> 3 <(1, 0)> 4 <(1, 1)> 5 <(1, 2)>

>>> with np.nditer(a, flags=['multi_index'], op_flags=['writeonly']) as it:

... for x in it:
... x[...] = it.multi_index[1] - it.multi_index[0]
...
>>> a
array([[ 0, 1, 2],
[-1, 0, 1]])

Tracking an index or multi-index is incompatible with using an external loop, because it requires a different index
value per element. If you try to combine these flags, the nditer object will raise an exception.

Example

>>> a = np.zeros((2,3))
>>> it = np.nditer(a, flags=['c_index', 'external_loop'])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Iterator flag EXTERNAL_LOOP cannot be used if an index or multi-index is
˓→being tracked

1.5. Iterating Over Arrays 97

NumPy Reference, Release 1.18.1

Alternative Looping and Element Access

To make its properties more readily accessible during iteration, nditer has an alternative syntax for iterating, which
works explicitly with the iterator object itself. With this looping construct, the current value is accessible by indexing
into the iterator. Other properties, such as tracked indices remain as before. The examples below produce identical
results to the ones in the previous section.

Example

>>> a = np.arange(6).reshape(2,3)
>>> it = np.nditer(a, flags=['f_index'])
>>> while not it.finished:
... print("%d <%d>" % (it[0], it.index), end=' ')
... it.iternext()
...
0 <0> 1 <2> 2 <4> 3 <1> 4 <3> 5 <5>

>>> it = np.nditer(a, flags=['multi_index'])

>>> while not it.finished:
... print("%d <%s>" % (it[0], it.multi_index), end=' ')
... it.iternext()
...
0 <(0, 0)> 1 <(0, 1)> 2 <(0, 2)> 3 <(1, 0)> 4 <(1, 1)> 5 <(1, 2)>

>>> with np.nditer(a, flags=['multi_index'], op_flags=['writeonly']) as it:

... while not it.finished:
... it[0] = it.multi_index[1] - it.multi_index[0]
... it.iternext()
...
>>> a
array([[ 0, 1, 2],
[-1, 0, 1]])

Buffering the Array Elements

When forcing an iteration order, we observed that the external loop option may provide the elements in smaller chunks
because the elements can’t be visited in the appropriate order with a constant stride. When writing C code, this is
generally fine, however in pure Python code this can cause a significant reduction in performance.
By enabling buffering mode, the chunks provided by the iterator to the inner loop can be made larger, significantly
reducing the overhead of the Python interpreter. In the example forcing Fortran iteration order, the inner loop gets to
see all the elements in one go when buffering is enabled.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, flags=['external_loop'], order='F'):
... print(x, end=' ')
...
[0 3] [1 4] [2 5]

98 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> for x in np.nditer(a, flags=['external_loop','buffered'], order='F'):

... print(x, end=' ')
...
[0 3 1 4 2 5]

Iterating as a Specific Data Type

There are times when it is necessary to treat an array as a different data type than it is stored as. For instance, one
may want to do all computations on 64-bit floats, even if the arrays being manipulated are 32-bit floats. Except when
writing low-level C code, it’s generally better to let the iterator handle the copying or buffering instead of casting the
data type yourself in the inner loop.
There are two mechanisms which allow this to be done, temporary copies and buffering mode. With temporary copies,
a copy of the entire array is made with the new data type, then iteration is done in the copy. Write access is permitted
through a mode which updates the original array after all the iteration is complete. The major drawback of temporary
copies is that the temporary copy may consume a large amount of memory, particularly if the iteration data type has a
larger itemsize than the original one.
Buffering mode mitigates the memory usage issue and is more cache-friendly than making temporary copies. Except
for special cases, where the whole array is needed at once outside the iterator, buffering is recommended over tem-
porary copying. Within NumPy, buffering is used by the ufuncs and other functions to support flexible inputs with
minimal memory overhead.
In our examples, we will treat the input array with a complex data type, so that we can take square roots of negative
numbers. Without enabling copies or buffering mode, the iterator will raise an exception if the data type doesn’t match
precisely.

Example
>>> a = np.arange(6).reshape(2,3) - 3
>>> for x in np.nditer(a, op_dtypes=['complex128']):
... print(np.sqrt(x), end=' ')
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Iterator operand required copying or buffering, but neither copying nor
˓→buffering was enabled

In copying mode, ‘copy’ is specified as a per-operand flag. This is done to provide control in a per-operand fashion.
Buffering mode is specified as an iterator flag.

Example
>>> a = np.arange(6).reshape(2,3) - 3
>>> for x in np.nditer(a, op_flags=['readonly','copy'],
... op_dtypes=['complex128']):
... print(np.sqrt(x), end=' ')
...
1.73205080757j 1.41421356237j 1j 0j (1+0j) (1.41421356237+0j)

>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['complex128']):

... print(np.sqrt(x), end=' ')
(continues on next page)

1.5. Iterating Over Arrays 99

NumPy Reference, Release 1.18.1

(continued from previous page)

...
1.73205080757j 1.41421356237j 1j 0j (1+0j) (1.41421356237+0j)

The iterator uses NumPy’s casting rules to determine whether a specific conversion is permitted. By default, it enforces
‘safe’ casting. This means, for example, that it will raise an exception if you try to treat a 64-bit float array as a 32-bit
float array. In many cases, the rule ‘same_kind’ is the most reasonable rule to use, since it will allow conversion from
64 to 32-bit float, but not from float to int or from complex to float.

Example

>>> a = np.arange(6.)
>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['float32']):
... print(x, end=' ')
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Iterator operand 0 dtype could not be cast from dtype('float64') to dtype(
˓→'float32') according to the rule 'safe'

>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['float32'],

... casting='same_kind'):
... print(x, end=' ')
...
0.0 1.0 2.0 3.0 4.0 5.0

>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['int32'], casting='same_kind

˓→'):

... print(x, end=' ')

...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Iterator operand 0 dtype could not be cast from dtype('float64') to dtype(
˓→'int32') according to the rule 'same_kind'

One thing to watch out for is conversions back to the original data type when using a read-write or write-only operand.
A common case is to implement the inner loop in terms of 64-bit floats, and use ‘same_kind’ casting to allow the other
floating-point types to be processed as well. While in read-only mode, an integer array could be provided, read-write
mode will raise an exception because conversion back to the array would violate the casting rule.

Example

>>> a = np.arange(6)
>>> for x in np.nditer(a, flags=['buffered'], op_flags=['readwrite'],
... op_dtypes=['float64'], casting='same_kind'):
... x[...] = x / 2.0
...
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
TypeError: Iterator requested dtype could not be cast from dtype('float64') to dtype(
˓→'int64'), the operand 0 dtype, according to the rule 'same_kind'

100 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

1.5.2 Broadcasting Array Iteration

NumPy has a set of rules for dealing with arrays that have differing shapes which are applied whenever functions take
multiple operands which combine element-wise. This is called broadcasting. The nditer object can apply these
rules for you when you need to write such a function.
As an example, we print out the result of broadcasting a one and a two dimensional array together.

Example

>>> a = np.arange(3)
>>> b = np.arange(6).reshape(2,3)
>>> for x, y in np.nditer([a,b]):
... print("%d:%d" % (x,y), end=' ')
...
0:0 1:1 2:2 0:3 1:4 2:5

When a broadcasting error occurs, the iterator raises an exception which includes the input shapes to help diagnose
the problem.

Example

>>> a = np.arange(2)
>>> b = np.arange(6).reshape(2,3)
>>> for x, y in np.nditer([a,b]):
... print("%d:%d" % (x,y), end=' ')
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: operands could not be broadcast together with shapes (2) (2,3)

Iterator-Allocated Output Arrays

A common case in NumPy functions is to have outputs allocated based on the broadcasting of the input, and addition-
ally have an optional parameter called ‘out’ where the result will be placed when it is provided. The nditer object
provides a convenient idiom that makes it very easy to support this mechanism.
We’ll show how this works by creating a function square which squares its input. Let’s start with a minimal function
definition excluding ‘out’ parameter support.

Example

>>> def square(a):

... with np.nditer([a, None]) as it:
... for x, y in it:
... y[...] = x*x
... return it.operands[1]
...
>>> square([1,2,3])
array([1, 4, 9])

1.5. Iterating Over Arrays 101

NumPy Reference, Release 1.18.1

By default, the nditer uses the flags ‘allocate’ and ‘writeonly’ for operands that are passed in as None. This means
we were able to provide just the two operands to the iterator, and it handled the rest.
When adding the ‘out’ parameter, we have to explicitly provide those flags, because if someone passes in an array as
‘out’, the iterator will default to ‘readonly’, and our inner loop would fail. The reason ‘readonly’ is the default for input
arrays is to prevent confusion about unintentionally triggering a reduction operation. If the default were ‘readwrite’,
any broadcasting operation would also trigger a reduction, a topic which is covered later in this document.
While we’re at it, let’s also introduce the ‘no_broadcast’ flag, which will prevent the output from being broadcast.
This is important, because we only want one input value for each output. Aggregating more than one input value
is a reduction operation which requires special handling. It would already raise an error because reductions must
be explicitly enabled in an iterator flag, but the error message that results from disabling broadcasting is much more
understandable for end-users. To see how to generalize the square function to a reduction, look at the sum of squares
function in the section about Cython.
For completeness, we’ll also add the ‘external_loop’ and ‘buffered’ flags, as these are what you will typically want for
performance reasons.

Example

>>> def square(a, out=None):

... it = np.nditer([a, out],
... flags = ['external_loop', 'buffered'],
... op_flags = [['readonly'],
... ['writeonly', 'allocate', 'no_broadcast']])
... with it:
... for x, y in it:
... y[...] = x*x
... return it.operands[1]
...

>>> square([1,2,3])
array([1, 4, 9])

>>> b = np.zeros((3,))
>>> square([1,2,3], out=b)
array([ 1., 4., 9.])
>>> b
array([ 1., 4., 9.])

>>> square(np.arange(6).reshape(2,3), out=b)

Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 4, in square
ValueError: non-broadcastable output operand with shape (3) doesn't match the
˓→broadcast shape (2,3)

102 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Outer Product Iteration

Any binary operation can be extended to an array operation in an outer product fashion like in outer, and the
nditer object provides a way to accomplish this by explicitly mapping the axes of the operands. It is also possible to
do this with newaxis indexing, but we will show you how to directly use the nditer op_axes parameter to accomplish
this with no intermediate views.
We’ll do a simple outer product, placing the dimensions of the first operand before the dimensions of the second
operand. The op_axes parameter needs one list of axes for each operand, and provides a mapping from the iterator’s
axes to the axes of the operand.
Suppose the first operand is one dimensional and the second operand is two dimensional. The iterator will have three
dimensions, so op_axes will have two 3-element lists. The first list picks out the one axis of the first operand, and is
-1 for the rest of the iterator axes, with a final result of [0, -1, -1]. The second list picks out the two axes of the second
operand, but shouldn’t overlap with the axes picked out in the first operand. Its list is [-1, 0, 1]. The output operand
maps onto the iterator axes in the standard manner, so we can provide None instead of constructing another list.
The operation in the inner loop is a straightforward multiplication. Everything to do with the outer product is handled
by the iterator setup.

Example

>>> a = np.arange(3)
>>> b = np.arange(8).reshape(2,4)
>>> it = np.nditer([a, b, None], flags=['external_loop'],
... op_axes=[[0, -1, -1], [-1, 0, 1], None])
>>> with it:
... for x, y, z in it:
... z[...] = x*y
... result = it.operands[2] # same as z
...
>>> result
array([[[ 0, 0, 0, 0],
[ 0, 0, 0, 0]],
[[ 0, 1, 2, 3],
[ 4, 5, 6, 7]],
[[ 0, 2, 4, 6],
[ 8, 10, 12, 14]]])

Note that once the iterator is closed we can not access operands and must use a reference created inside the context
manager.

Reduction Iteration

Whenever a writeable operand has fewer elements than the full iteration space, that operand is undergoing a reduction.
The nditer object requires that any reduction operand be flagged as read-write, and only allows reductions when
‘reduce_ok’ is provided as an iterator flag.
For a simple example, consider taking the sum of all elements in an array.

Example

>>> a = np.arange(24).reshape(2,3,4)
>>> b = np.array(0)
(continues on next page)

1.5. Iterating Over Arrays 103

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> with np.nditer([a, b], flags=['reduce_ok', 'external_loop'],
... op_flags=[['readonly'], ['readwrite']]) as it:
... for x,y in it:
... y[...] += x
...
>>> b
array(276)
>>> np.sum(a)
276

Things are a little bit more tricky when combining reduction and allocated operands. Before iteration is started, any
reduction operand must be initialized to its starting values. Here’s how we can do this, taking sums along the last axis
of a.

Example
>>> a = np.arange(24).reshape(2,3,4)
>>> it = np.nditer([a, None], flags=['reduce_ok', 'external_loop'],
... op_flags=[['readonly'], ['readwrite', 'allocate']],
... op_axes=[None, [0,1,-1]])
>>> with it:
... it.operands[1][...] = 0
... for x, y in it:
... y[...] += x
... result = it.operands[1]
...
>>> result
array([[ 6, 22, 38],
[54, 70, 86]])
>>> np.sum(a, axis=2)
array([[ 6, 22, 38],
[54, 70, 86]])

To do buffered reduction requires yet another adjustment during the setup. Normally the iterator construction involves
copying the first buffer of data from the readable arrays into the buffer. Any reduction operand is readable, so it may
be read into a buffer. Unfortunately, initialization of the operand after this buffering operation is complete will not be
reflected in the buffer that the iteration starts with, and garbage results will be produced.
The iterator flag “delay_bufalloc” is there to allow iterator-allocated reduction operands to exist together with buffer-
ing. When this flag is set, the iterator will leave its buffers uninitialized until it receives a reset, after which it will be
ready for regular iteration. Here’s how the previous example looks if we also enable buffering.

Example
>>> a = np.arange(24).reshape(2,3,4)
>>> it = np.nditer([a, None], flags=['reduce_ok', 'external_loop',
... 'buffered', 'delay_bufalloc'],
... op_flags=[['readonly'], ['readwrite', 'allocate']],
... op_axes=[None, [0,1,-1]])
>>> with it:
... it.operands[1][...] = 0
... it.reset()
... for x, y in it:
(continues on next page)

104 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

(continued from previous page)

... y[...] += x
... result = it.operands[1]
...
>>> result
array([[ 6, 22, 38],
[54, 70, 86]])

1.5.3 Putting the Inner Loop in Cython

Those who want really good performance out of their low level operations should strongly consider directly using the
iteration API provided in C, but for those who are not comfortable with C or C++, Cython is a good middle ground with
reasonable performance tradeoffs. For the nditer object, this means letting the iterator take care of broadcasting,
dtype conversion, and buffering, while giving the inner loop to Cython.
For our example, we’ll create a sum of squares function. To start, let’s implement this function in straightforward
Python. We want to support an ‘axis’ parameter similar to the numpy sum function, so we will need to construct a list
for the op_axes parameter. Here’s how this looks.

Example

>>> def axis_to_axeslist(axis, ndim):

... if axis is None:
... return [-1] * ndim
... else:
... if type(axis) is not tuple:
... axis = (axis,)
... axeslist = [1] * ndim
... for i in axis:
... axeslist[i] = -1
... ax = 0
... for i in range(ndim):
... if axeslist[i] != -1:
... axeslist[i] = ax
... ax += 1
... return axeslist
...
>>> def sum_squares_py(arr, axis=None, out=None):
... axeslist = axis_to_axeslist(axis, arr.ndim)
... it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop',
... 'buffered', 'delay_bufalloc'],
... op_flags=[['readonly'], ['readwrite', 'allocate']],
... op_axes=[None, axeslist],
... op_dtypes=['float64', 'float64'])
... with it:
... it.operands[1][...] = 0
... it.reset()
... for x, y in it:
... y[...] += x*x
... return it.operands[1]
...
>>> a = np.arange(6).reshape(2,3)
>>> sum_squares_py(a)
array(55.0)
(continues on next page)

1.5. Iterating Over Arrays 105

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> sum_squares_py(a, axis=-1)
array([ 5., 50.])

To Cython-ize this function, we replace the inner loop (y[. . . ] += x*x) with Cython code that’s specialized for
the float64 dtype. With the ‘external_loop’ flag enabled, the arrays provided to the inner loop will always be one-
dimensional, so very little checking needs to be done.
Here’s the listing of sum_squares.pyx:

import numpy as np
cimport numpy as np
cimport cython

def axis_to_axeslist(axis, ndim):

if axis is None:
return [-1] * ndim
else:
if type(axis) is not tuple:
axis = (axis,)
axeslist = [1] * ndim
for i in axis:
axeslist[i] = -1
ax = 0
for i in range(ndim):
if axeslist[i] != -1:
axeslist[i] = ax
ax += 1
return axeslist

@cython.boundscheck(False)
def sum_squares_cy(arr, axis=None, out=None):
cdef np.ndarray[double] x
cdef np.ndarray[double] y
cdef int size
cdef double value

axeslist = axis_to_axeslist(axis, arr.ndim)

it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop',
'buffered', 'delay_bufalloc'],
op_flags=[['readonly'], ['readwrite', 'allocate']],
op_axes=[None, axeslist],
op_dtypes=['float64', 'float64'])
with it:
it.operands[1][...] = 0
it.reset()
for xarr, yarr in it:
x = xarr
y = yarr
size = x.shape[0]
for i in range(size):
value = x[i]
y[i] = y[i] + value * value
return it.operands[1]

On this machine, building the .pyx file into a module looked like the following, but you may have to find some Cython
tutorials to tell you the specifics for your system configuration.:

106 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

$ cython sum_squares.pyx
$ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -I/usr/include/python2.7 -fno-strict-
˓→aliasing -o sum_squares.so sum_squares.c

Running this from the Python interpreter produces the same answers as our native Python/NumPy code did.

Example

>>> from sum_squares import sum_squares_cy

>>> a = np.arange(6).reshape(2,3)
>>> sum_squares_cy(a)
array(55.0)
>>> sum_squares_cy(a, axis=-1)
array([ 5., 50.])

Doing a little timing in IPython shows that the reduced overhead and memory allocation of the Cython inner loop is
providing a very nice speedup over both the straightforward Python code and an expression using NumPy’s built-in
sum function.:

>>> a = np.random.rand(1000,1000)

>>> timeit sum_squares_py(a, axis=-1)

10 loops, best of 3: 37.1 ms per loop

>>> timeit np.sum(a*a, axis=-1)

10 loops, best of 3: 20.9 ms per loop

>>> timeit sum_squares_cy(a, axis=-1)

100 loops, best of 3: 11.8 ms per loop

>>> np.all(sum_squares_cy(a, axis=-1) == np.sum(a*a, axis=-1))

True

>>> np.all(sum_squares_py(a, axis=-1) == np.sum(a*a, axis=-1))

True

1.6 Standard array subclasses

Note: Subclassing a numpy.ndarray is possible but if your goal is to create an array with modified behavior, as
do dask arrays for distributed computation and cupy arrays for GPU-based computation, subclassing is discouraged.
Instead, using numpy’s dispatch mechanism is recommended.

The ndarray can be inherited from (in Python or in C) if desired. Therefore, it can form a foundation for many
useful classes. Often whether to sub-class the array object or to simply use the core array component as an internal
part of a new class is a difficult decision, and can be simply a matter of choice. NumPy has several tools for simplifying
how your new object interacts with other array objects, and so the choice may not be significant in the end. One way
to simplify the question is by asking yourself if the object you are interested in can be replaced as a single array or
does it really require two or more arrays at its core.
Note that asarray always returns the base-class ndarray. If you are confident that your use of the array object can
handle any subclass of an ndarray, then asanyarray can be used to allow subclasses to propagate more cleanly

1.6. Standard array subclasses 107

NumPy Reference, Release 1.18.1

through your subroutine. In principal a subclass could redefine any aspect of the array and therefore, under strict
guidelines, asanyarray would rarely be useful. However, most subclasses of the array object will not redefine
certain aspects of the array object such as the buffer interface, or the attributes of the array. One important example,
however, of why your subroutine may not be able to handle an arbitrary subclass of an array is that matrices redefine
the “*” operator to be matrix-multiplication, rather than element-by-element multiplication.

1.6.1 Special attributes and methods

See also:
Subclassing ndarray
NumPy provides several hooks that classes can customize:
class.__array_ufunc__(ufunc, method, *inputs, **kwargs)
New in version 1.13.
Any class, ndarray subclass or not, can define this method or set it to None in order to override the behavior of
NumPy’s ufuncs. This works quite similarly to Python’s __mul__ and other binary operation routines.
• ufunc is the ufunc object that was called.
• method is a string indicating which Ufunc method was called (one of "__call__", "reduce",
"reduceat", "accumulate", "outer", "inner").
• inputs is a tuple of the input arguments to the ufunc.
• kwargs is a dictionary containing the optional input arguments of the ufunc. If given, any out arguments,
both positional and keyword, are passed as a tuple in kwargs. See the discussion in Universal functions
(ufunc) for details.
The method should return either the result of the operation, or NotImplemented if the operation requested
is not implemented.
If one of the input or output arguments has a __array_ufunc__ method, it is executed instead of the
ufunc. If more than one of the arguments implements __array_ufunc__, they are tried in the order: sub-
classes before superclasses, inputs before outputs, otherwise left to right. The first routine returning something
other than NotImplemented determines the result. If all of the __array_ufunc__ operations return
NotImplemented, a TypeError is raised.

Note: We intend to re-implement numpy functions as (generalized) Ufunc, in which case it will become
possible for them to be overridden by the __array_ufunc__ method. A prime candidate is matmul, which
currently is not a Ufunc, but could be relatively easily be rewritten as a (set of) generalized Ufuncs. The same
may happen with functions such as median, amin, and argsort.

Like with some other special methods in python, such as __hash__ and __iter__, it is possible to indi-
cate that your class does not support ufuncs by setting __array_ufunc__ = None. Ufuncs always raise
TypeError when called on an object that sets __array_ufunc__ = None.
The presence of __array_ufunc__ also influences how ndarray handles binary operations like arr +
obj and arr < obj when arr is an ndarray and obj is an instance of a custom class. There are two
possibilities. If obj.__array_ufunc__ is present and not None, then ndarray.__add__ and friends
will delegate to the ufunc machinery, meaning that arr + obj becomes np.add(arr, obj), and then
add invokes obj.__array_ufunc__. This is useful if you want to define an object that acts like an array.
Alternatively, if obj.__array_ufunc__ is set to None, then as a special case, special methods like
ndarray.__add__ will notice this and unconditionally raise TypeError. This is useful if you want to
create objects that interact with arrays via binary operations, but are not themselves arrays. For example, a units

108 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

handling system might have an object m representing the “meters” unit, and want to support the syntax arr * m
to represent that the array has units of “meters”, but not want to otherwise interact with arrays via ufuncs or oth-
erwise. This can be done by setting __array_ufunc__ = None and defining __mul__ and __rmul__
methods. (Note that this means that writing an __array_ufunc__ that always returns NotImplemented
is not quite the same as setting __array_ufunc__ = None: in the former case, arr + obj will raise
TypeError, while in the latter case it is possible to define a __radd__ method to prevent this.)
The above does not hold for in-place operators, for which ndarray never returns NotImplemented. Hence,
arr += obj would always lead to a TypeError. This is because for arrays in-place operations cannot
generically be replaced by a simple reverse operation. (For instance, by default, arr += obj would be
translated to arr = arr + obj, i.e., arr would be replaced, contrary to what is expected for in-place array
operations.)

Note: If you define __array_ufunc__:

• If you are not a subclass of ndarray, we recommend your class define special methods like __add__
and __lt__ that delegate to ufuncs just like ndarray does. An easy way to do this is to subclass from
NDArrayOperatorsMixin.
• If you subclass ndarray, we recommend that you put all your override logic in __array_ufunc__
and not also override special methods. This ensures the class hierarchy is determined in only one place
rather than separately by the ufunc machinery and by the binary operation rules (which gives preference
to special methods of subclasses; the alternative way to enforce a one-place only hierarchy, of setting
__array_ufunc__ to None, would seem very unexpected and thus confusing, as then the subclass
would not work at all with ufuncs).
• ndarray defines its own __array_ufunc__, which, evaluates the ufunc if no arguments have
overrides, and returns NotImplemented otherwise. This may be useful for subclasses for which
__array_ufunc__ converts any instances of its own class to ndarray: it can then pass these on to
its superclass using super().__array_ufunc__(*inputs, **kwargs), and finally return the
results after possible back-conversion. The advantage of this practice is that it ensures that it is possible to
have a hierarchy of subclasses that extend the behaviour. See Subclassing ndarray for details.

Note: If a class defines the __array_ufunc__ method, this disables the __array_wrap__,
__array_prepare__, __array_priority__ mechanism described below for ufuncs (which may even-
tually be deprecated).

class.__array_function__(func, types, args, kwargs)

New in version 1.16.

Note:
• In NumPy 1.17, the protocol is enabled by default, but can be disabled with
NUMPY_EXPERIMENTAL_ARRAY_FUNCTION=0.
• In NumPy 1.16, you need to set the environment variable NUMPY_EXPERIMENTAL_ARRAY_FUNCTION=1
before importing NumPy to use NumPy function overrides.
• Eventually, expect to __array_function__ to always be enabled.

• func is an arbitrary callable exposed by NumPy’s public API, which was called in the form
func(*args, **kwargs).

1.6. Standard array subclasses 109

NumPy Reference, Release 1.18.1

• types is a collection of unique argument types from the original NumPy function call that implement
__array_function__.
• The tuple args and dict kwargs are directly passed on from the original call.

As a convenience for __array_function__ implementors, types provides all argument types with an
'__array_function__' attribute. This allows implementors to quickly identify cases where they should
defer to __array_function__ implementations on other arguments. Implementations should not rely on
the iteration order of types.
Most implementations of __array_function__ will start with two checks:
1. Is the given function something that we know how to overload?
2. Are all arguments of a type that we know how to handle?
If these conditions hold, __array_function__ should return the result from calling its implementation for
func(*args, **kwargs). Otherwise, it should return the sentinel value NotImplemented, indicating
that the function is not implemented by these types.
There are no general requirements on the return value from __array_function__, although most sensible
implementations should probably return array(s) with the same type as one of the function’s arguments.
It may also be convenient to define a custom decorators (implements below) for registering
__array_function__ implementations.

HANDLED_FUNCTIONS = {}

class MyArray:
def __array_function__(self, func, types, args, kwargs):
if func not in HANDLED_FUNCTIONS:
return NotImplemented
# Note: this allows subclasses that don't override
# __array_function__ to handle MyArray objects
if not all(issubclass(t, MyArray) for t in types):
return NotImplemented
return HANDLED_FUNCTIONS[func](*args, **kwargs)

def implements(numpy_function):
"""Register an __array_function__ implementation for MyArray objects."""
def decorator(func):
HANDLED_FUNCTIONS[numpy_function] = func
return func
return decorator

@implements(np.concatenate)
def concatenate(arrays, axis=0, out=None):
... # implementation of concatenate for MyArray objects

@implements(np.broadcast_to)
def broadcast_to(array, shape):
... # implementation of broadcast_to for MyArray objects

Note that it is not required for __array_function__ implementations to include all of the corresponding
NumPy function’s optional arguments (e.g., broadcast_to above omits the irrelevant subok argument).
Optional arguments are only passed in to __array_function__ if they were explicitly used in the NumPy
function call.
Just like the case for builtin special methods like __add__, properly written __array_function__ meth-
ods should always return NotImplemented when an unknown type is encountered. Otherwise, it will be

110 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

impossible to correctly override NumPy functions from another object if the operation also includes one of your
objects.
For the most part, the rules for dispatch with __array_function__ match those for __array_ufunc__.
In particular:
• NumPy will gather implementations of __array_function__ from all specified inputs and call them
in order: subclasses before superclasses, and otherwise left to right. Note that in some edge cases involving
subclasses, this differs slightly from the current behavior of Python.
• Implementations of __array_function__ indicate that they can handle the operation by returning
any value other than NotImplemented.
• If all __array_function__ methods return NotImplemented, NumPy will raise TypeError.
If no __array_function__ methods exists, NumPy will default to calling its own implementation,
intended for use on NumPy arrays. This case arises, for example, when all array-like arguments are
Python numbers or lists. (NumPy arrays do have a __array_function__ method, given below, but
it always returns NotImplemented if any argument other than a NumPy array subclass implements
__array_function__.)
One deviation from the current behavior of __array_ufunc__ is that NumPy will only call
__array_function__ on the first argument of each unique type. This matches Python’s rule for calling
reflected methods, and this ensures that checking overloads has acceptable performance even when there are a
large number of overloaded arguments.
class.__array_finalize__(obj)
This method is called whenever the system internally allocates a new array from obj, where obj is a subclass
(subtype) of the ndarray. It can be used to change attributes of self after construction (so as to ensure a 2-d
matrix for example), or to update meta-information from the “parent.” Subclasses inherit a default implementa-
tion of this method that does nothing.
class.__array_prepare__(array, context=None)
At the beginning of every ufunc, this method is called on the input object with the highest array priority, or the
output object if one was specified. The output array is passed in and whatever is returned is passed to the ufunc.
Subclasses inherit a default implementation of this method which simply returns the output array unmodified.
Subclasses may opt to use this method to transform the output array into an instance of the subclass and update
metadata before returning the array to the ufunc for computation.

Note: For ufuncs, it is hoped to eventually deprecate this method in favour of __array_ufunc__.

class.__array_wrap__(array, context=None)
At the end of every ufunc, this method is called on the input object with the highest array priority, or the output
object if one was specified. The ufunc-computed array is passed in and whatever is returned is passed to the
user. Subclasses inherit a default implementation of this method, which transforms the array into a new instance
of the object’s class. Subclasses may opt to use this method to transform the output array into an instance of the
subclass and update metadata before returning the array to the user.

Note: For ufuncs, it is hoped to eventually deprecate this method in favour of __array_ufunc__.

class.__array_priority__
The value of this attribute is used to determine what type of object to return in situations where there is more
than one possibility for the Python type of the returned object. Subclasses inherit a default value of 0.0 for this
attribute.

1.6. Standard array subclasses 111

NumPy Reference, Release 1.18.1

Note: For ufuncs, it is hoped to eventually deprecate this method in favour of __array_ufunc__.

class.__array__([dtype ])
If a class (ndarray subclass or not) having the __array__ method is used as the output object of an ufunc,
results will be written to the object returned by __array__. Similar conversion is done on input arrays.

1.6.2 Matrix objects

Note: It is strongly advised not to use the matrix subclass. As described below, it makes writing functions that
deal consistently with matrices and regular arrays very difficult. Currently, they are mainly used for interacting with
scipy.sparse. We hope to provide an alternative for this use, however, and eventually remove the matrix
subclass.

matrix objects inherit from the ndarray and therefore, they have the same attributes and methods of ndarrays. There
are six important differences of matrix objects, however, that may lead to unexpected results when you use matrices
but expect them to act like arrays:
1. Matrix objects can be created using a string notation to allow Matlab-style syntax where spaces separate columns
and semicolons (‘;’) separate rows.
2. Matrix objects are always two-dimensional. This has far-reaching implications, in that m.ravel() is still two-
dimensional (with a 1 in the first dimension) and item selection returns two-dimensional objects so that sequence
behavior is fundamentally different than arrays.
3. Matrix objects over-ride multiplication to be matrix-multiplication. Make sure you understand this for func-
tions that you may want to receive matrices. Especially in light of the fact that asanyarray(m) returns a
matrix when m is a matrix.
4. Matrix objects over-ride power to be matrix raised to a power. The same warning about using power inside a
function that uses asanyarray(. . . ) to get an array object holds for this fact.
5. The default __array_priority__ of matrix objects is 10.0, and therefore mixed operations with ndarrays always
produce matrices.
6. Matrices have special attributes which make calculations easier. These are

matrix.T Returns the transpose of the matrix.

matrix.H Returns the (complex) conjugate transpose of self.
matrix.I Returns the (multiplicative) inverse of invertible self.
matrix.A Return self as an ndarray object.

property
property matrix.T
Returns the transpose of the matrix.
Does not conjugate! For the complex conjugate transpose, use .H.
Parameters
None
Returns
ret [matrix object] The (non-conjugated) transpose of the matrix.

112 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

See also:
transpose, getH

Examples

>>> m = np.matrix('[1, 2; 3, 4]')

>>> m
matrix([[1, 2],
[3, 4]])
>>> m.getT()
matrix([[1, 3],
[2, 4]])

property
property matrix.H
Returns the (complex) conjugate transpose of self.
Equivalent to np.transpose(self) if self is real-valued.
Parameters
None
Returns
ret [matrix object] complex conjugate transpose of self

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4)))
>>> z = x - 1j*x; z
matrix([[ 0. +0.j, 1. -1.j, 2. -2.j, 3. -3.j],
[ 4. -4.j, 5. -5.j, 6. -6.j, 7. -7.j],
[ 8. -8.j, 9. -9.j, 10.-10.j, 11.-11.j]])
>>> z.getH()
matrix([[ 0. -0.j, 4. +4.j, 8. +8.j],
[ 1. +1.j, 5. +5.j, 9. +9.j],
[ 2. +2.j, 6. +6.j, 10.+10.j],
[ 3. +3.j, 7. +7.j, 11.+11.j]])

property
property matrix.I
Returns the (multiplicative) inverse of invertible self.
Parameters
None
Returns
ret [matrix object] If self is non-singular, ret is such that ret * self == self * ret
== np.matrix(np.eye(self[0,:].size) all return True.
Raises
numpy.linalg.LinAlgError: Singular matrix If self is singular.

1.6. Standard array subclasses 113

NumPy Reference, Release 1.18.1

See also:
linalg.inv

Examples

>>> m = np.matrix('[1, 2; 3, 4]'); m

matrix([[1, 2],
[3, 4]])
>>> m.getI()
matrix([[-2. , 1. ],
[ 1.5, -0.5]])
>>> m.getI() * m
matrix([[ 1., 0.], # may vary
[ 0., 1.]])

property
property matrix.A
Return self as an ndarray object.
Equivalent to np.asarray(self).
Parameters
None
Returns
ret [ndarray] self as an ndarray

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.getA()
array([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])

Warning: Matrix objects over-ride multiplication, ‘*’, and power, ‘**’, to be matrix-multiplication and matrix
power, respectively. If your subroutine can accept sub-classes and you do not convert to base- class arrays, then
you must use the ufuncs multiply and power to be sure that you are performing the correct operation for all inputs.

The matrix class is a Python subclass of the ndarray and can be used as a reference for how to construct your own
subclass of the ndarray. Matrices can be created from other matrices, strings, and anything else that can be converted
to an ndarray . The name “mat “is an alias for “matrix “in NumPy.

114 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

matrix(data[, dtype, copy])

Note: It is no longer recommended to use this class,

even for linear

asmatrix(data[, dtype]) Interpret the input as a matrix.

bmat(obj[, ldict, gdict]) Build a matrix object from a string, nested sequence, or
array.

class numpy.matrix(data, dtype=None, copy=True)

Note: It is no longer recommended to use this class, even for linear algebra. Instead use regular arrays. The
class may be removed in the future.

Returns a matrix from an array-like object, or from a string of data. A matrix is a specialized 2-D array that
retains its 2-D nature through operations. It has certain special operators, such as * (matrix multiplication) and
** (matrix power).
Parameters
data [array_like or string] If data is a string, it is interpreted as a matrix with commas or
spaces separating columns, and semicolons separating rows.
dtype [data-type] Data-type of the output matrix.
copy [bool] If data is already an ndarray, then this flag determines whether the data is
copied (the default), or whether a view is constructed.
See also:
array

Examples

>>> a = np.matrix('1 2; 3 4')

>>> a
matrix([[1, 2],
[3, 4]])

>>> np.matrix([[1, 2], [3, 4]])

matrix([[1, 2],
[3, 4]])

Attributes
A Return self as an ndarray object.
A1 Return self as a flattened ndarray.
H Returns the (complex) conjugate transpose of self.
I Returns the (multiplicative) inverse of invertible self.
T Returns the transpose of the matrix.

1.6. Standard array subclasses 115

NumPy Reference, Release 1.18.1

base Base object if memory is from some other object.

ctypes An object to simplify the interaction of the array with the ctypes module.
data Python buffer object pointing to the start of the array’s data.
dtype Data-type of the array’s elements.
flags Information about the memory layout of the array.
flat A 1-D iterator over the array.
imag The imaginary part of the array.
itemsize Length of one array element in bytes.
nbytes Total bytes consumed by the elements of the array.
ndim Number of array dimensions.
real The real part of the array.
shape Tuple of array dimensions.
size Number of elements in the array.
strides Tuple of bytes to step in each dimension when traversing an array.

Methods

all(self[, axis, out]) Test whether all matrix elements along a given axis
evaluate to True.
any(self[, axis, out]) Test whether any array element along a given axis
evaluates to True.
argmax(self[, axis, out]) Indexes of the maximum values along an axis.
argmin(self[, axis, out]) Indexes of the minimum values along an axis.
argpartition(kth[, axis, kind, order]) Returns the indices that would partition this array.
argsort([axis, kind, order]) Returns the indices that would sort this array.
astype(dtype[, order, casting, subok, copy]) Copy of the array, cast to a specified type.
byteswap([inplace]) Swap the bytes of the array elements
choose(choices[, out, mode]) Use an index array to construct a new array from a
set of choices.
clip([min, max, out]) Return an array whose values are limited to [min,
max].
compress(condition[, axis, out]) Return selected slices of this array along given axis.
conj() Complex-conjugate all elements.
conjugate() Return the complex conjugate, element-wise.
copy([order]) Return a copy of the array.
cumprod([axis, dtype, out]) Return the cumulative product of the elements along
the given axis.
cumsum([axis, dtype, out]) Return the cumulative sum of the elements along the
given axis.
diagonal([offset, axis1, axis2]) Return specified diagonals.
dot(b[, out]) Dot product of two arrays.
dump(file) Dump a pickle of the array to the specified file.
dumps() Returns the pickle of the array as a string.
fill(value) Fill the array with a scalar value.
Continued on next page

116 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Table 37 – continued from previous page

flatten(self[, order]) Return a flattened copy of the matrix.
getA(self) Return self as an ndarray object.
getA1(self) Return self as a flattened ndarray.
getH(self) Returns the (complex) conjugate transpose of self.
getI(self) Returns the (multiplicative) inverse of invertible self.
getT(self) Returns the transpose of the matrix.
getfield(dtype[, offset]) Returns a field of the given array as a certain type.
item(*args) Copy an element of an array to a standard Python
scalar and return it.
itemset(*args) Insert scalar into an array (scalar is cast to array’s
dtype, if possible)
max(self[, axis, out]) Return the maximum value along an axis.
mean(self[, axis, dtype, out]) Returns the average of the matrix elements along the
given axis.
min(self[, axis, out]) Return the minimum value along an axis.
newbyteorder([new_order]) Return the array with the same data viewed with a
different byte order.
nonzero() Return the indices of the elements that are non-zero.
partition(kth[, axis, kind, order]) Rearranges the elements in the array in such a way
that the value of the element in kth position is in the
position it would be in a sorted array.
prod(self[, axis, dtype, out]) Return the product of the array elements over the
given axis.
ptp(self[, axis, out]) Peak-to-peak (maximum - minimum) value along the
given axis.
put(indices, values[, mode]) Set a.flat[n] = values[n] for all n in in-
dices.
ravel(self[, order]) Return a flattened matrix.
repeat(repeats[, axis]) Repeat elements of an array.
reshape(shape[, order]) Returns an array containing the same data with a new
shape.
resize(new_shape[, refcheck]) Change shape and size of array in-place.
round([decimals, out]) Return a with each element rounded to the given
number of decimals.
searchsorted(v[, side, sorter]) Find indices where elements of v should be inserted
in a to maintain order.
setfield(val, dtype[, offset]) Put a value into a specified place in a field defined by
a data-type.
setflags([write, align, uic]) Set array flags WRITEABLE, ALIGNED, (WRITE-
BACKIFCOPY and UPDATEIFCOPY), respec-
tively.
sort([axis, kind, order]) Sort an array in-place.
squeeze(self[, axis]) Return a possibly reshaped matrix.
std(self[, axis, dtype, out, ddof]) Return the standard deviation of the array elements
along the given axis.
sum(self[, axis, dtype, out]) Returns the sum of the matrix elements, along the
given axis.
swapaxes(axis1, axis2) Return a view of the array with axis1 and axis2 in-
terchanged.
take(indices[, axis, out, mode]) Return an array formed from the elements of a at the
given indices.
Continued on next page

1.6. Standard array subclasses 117

NumPy Reference, Release 1.18.1

Table 37 – continued from previous page

tobytes([order]) Construct Python bytes containing the raw data bytes
in the array.
tofile(fid[, sep, format]) Write array to a file as text or binary (default).
tolist(self) Return the matrix as a (possibly nested) list.
tostring([order]) Construct Python bytes containing the raw data bytes
in the array.
trace([offset, axis1, axis2, dtype, out]) Return the sum along diagonals of the array.
transpose(*axes) Returns a view of the array with axes transposed.
var(self[, axis, dtype, out, ddof]) Returns the variance of the matrix elements, along
the given axis.
view([dtype, type]) New view of array with the same data.

method
matrix.all(self, axis=None, out=None)
Test whether all matrix elements along a given axis evaluate to True.
Parameters
See `numpy.all` for complete descriptions
See also:
numpy.all

Notes

This is the same as ndarray.all, but it returns a matrix object.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> y = x[0]; y
matrix([[0, 1, 2, 3]])
>>> (x == y)
matrix([[ True, True, True, True],
[False, False, False, False],
[False, False, False, False]])
>>> (x == y).all()
False
>>> (x == y).all(0)
matrix([[False, False, False, False]])
>>> (x == y).all(1)
matrix([[ True],
[False],
[False]])

method
matrix.any(self, axis=None, out=None)
Test whether any array element along a given axis evaluates to True.
Refer to numpy.any for full documentation.

118 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Parameters
axis [int, optional] Axis along which logical OR is performed
out [ndarray, optional] Output to existing array instead of creating new one, must have same
shape as expected output
Returns
any [bool, ndarray] Returns a single bool if axis is None; otherwise, returns ndarray
method
matrix.argmax(self, axis=None, out=None)
Indexes of the maximum values along an axis.
Return the indexes of the first occurrences of the maximum values along the specified axis. If axis is None,
the index is for the flattened matrix.
Parameters
See `numpy.argmax` for complete descriptions
See also:
numpy.argmax

Notes

This is the same as ndarray.argmax, but returns a matrix object where ndarray.argmax would
return an ndarray.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.argmax()
11
>>> x.argmax(0)
matrix([[2, 2, 2, 2]])
>>> x.argmax(1)
matrix([[3],
[3],
[3]])

method
matrix.argmin(self, axis=None, out=None)
Indexes of the minimum values along an axis.
Return the indexes of the first occurrences of the minimum values along the specified axis. If axis is None,
the index is for the flattened matrix.
Parameters
See `numpy.argmin` for complete descriptions.
See also:
numpy.argmin

1.6. Standard array subclasses 119

NumPy Reference, Release 1.18.1

Notes

This is the same as ndarray.argmin, but returns a matrix object where ndarray.argmin would
return an ndarray.

Examples

>>> x = -np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, -1, -2, -3],
[ -4, -5, -6, -7],
[ -8, -9, -10, -11]])
>>> x.argmin()
11
>>> x.argmin(0)
matrix([[2, 2, 2, 2]])
>>> x.argmin(1)
matrix([[3],
[3],
[3]])

method
matrix.argpartition(kth, axis=-1, kind='introselect', order=None)
Returns the indices that would partition this array.
Refer to numpy.argpartition for full documentation.
New in version 1.8.0.
See also:

numpy.argpartition equivalent function

method
matrix.argsort(axis=-1, kind=None, order=None)
Returns the indices that would sort this array.
Refer to numpy.argsort for full documentation.
See also:

numpy.argsort equivalent function

method
matrix.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
Copy of the array, cast to a specified type.
Parameters
dtype [str or dtype] Typecode or data-type to which the array is cast.
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout order of the result. ‘C’
means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran
contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements
appear in memory as possible. Default is ‘K’.
casting [{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional] Controls what kind of data
casting may occur. Defaults to ‘unsafe’ for backwards compatibility.

120 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

• ‘no’ means the data types should not be cast at all.

• ‘equiv’ means only byte-order changes are allowed.
• ‘safe’ means only casts which can preserve values are allowed.
• ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are
allowed.
• ‘unsafe’ means any data conversions may be done.
subok [bool, optional] If True, then sub-classes will be passed-through (default), otherwise
the returned array will be forced to be a base-class array.
copy [bool, optional] By default, astype always returns a newly allocated array. If this is
set to false, and the dtype, order, and subok requirements are satisfied, the input array is
returned instead of a copy.
Returns
arr_t [ndarray] Unless copy is False and the other conditions for returning the input array
are satisfied (see description for copy input parameter), arr_t is a new array of the same
shape as the input array, with dtype, order given by dtype, order.
Raises
ComplexWarning When casting from complex to float or int. To avoid this, one should use
a.real.astype(t).

Notes

Changed in version 1.17.0: Casting between a simple data type and a structured one is possible only for
“unsafe” casting. Casting to multiple fields is allowed, but casting from multiple fields is not.
Changed in version 1.9.0: Casting from numeric to string types in ‘safe’ casting mode requires that the
string dtype length is long enough to store the max integer/float value converted.

Examples

>>> x = np.array([1, 2, 2.5])

>>> x
array([1. , 2. , 2.5])

>>> x.astype(int)
array([1, 2, 2])

method
matrix.byteswap(inplace=False)
Swap the bytes of the array elements
Toggle between low-endian and big-endian data representation by returning a byteswapped array, option-
ally swapped in-place. Arrays of byte-strings are not swapped. The real and imaginary parts of a complex
number are swapped individually.
Parameters
inplace [bool, optional] If True, swap bytes in-place, default is False.
Returns

1.6. Standard array subclasses 121

NumPy Reference, Release 1.18.1

out [ndarray] The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)

>>> list(map(hex, A))
['0x1', '0x100', '0x2233']
>>> A.byteswap(inplace=True)
array([ 256, 1, 13090], dtype=int16)
>>> list(map(hex, A))
['0x100', '0x1', '0x3322']

Arrays of byte-strings are not swapped

>>> A = np.array([b'ceg', b'fac'])

>>> A.byteswap()
array([b'ceg', b'fac'], dtype='|S3')

A.newbyteorder().byteswap() produces an array with the same values but different repre-
sentation in memory

>>> A = np.array([1, 2, 3])

>>> A.view(np.uint8)
array([1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0,
0, 0], dtype=uint8)
>>> A.newbyteorder().byteswap(inplace=True)
array([1, 2, 3])
>>> A.view(np.uint8)
array([0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0,
0, 3], dtype=uint8)

method
matrix.choose(choices, out=None, mode='raise')
Use an index array to construct a new array from a set of choices.
Refer to numpy.choose for full documentation.
See also:

numpy.choose equivalent function

method
matrix.clip(min=None, max=None, out=None, **kwargs)
Return an array whose values are limited to [min, max]. One of max or min must be given.
Refer to numpy.clip for full documentation.
See also:

numpy.clip equivalent function

method
matrix.compress(condition, axis=None, out=None)
Return selected slices of this array along given axis.

122 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Refer to numpy.compress for full documentation.

See also:

numpy.compress equivalent function

method
matrix.conj()
Complex-conjugate all elements.
Refer to numpy.conjugate for full documentation.
See also:

numpy.conjugate equivalent function

method
matrix.conjugate()
Return the complex conjugate, element-wise.
Refer to numpy.conjugate for full documentation.
See also:

numpy.conjugate equivalent function

method
matrix.copy(order='C')
Return a copy of the array.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout of the copy. ‘C’ means
C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’
means match the layout of a as closely as possible. (Note that this function and numpy.
copy are very similar, but have different default values for their order= arguments.)
See also:
numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
[0, 0, 0]])

1.6. Standard array subclasses 123

NumPy Reference, Release 1.18.1

>>> y
array([[1, 2, 3],
[4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True

method
matrix.cumprod(axis=None, dtype=None, out=None)
Return the cumulative product of the elements along the given axis.
Refer to numpy.cumprod for full documentation.
See also:

numpy.cumprod equivalent function

method
matrix.cumsum(axis=None, dtype=None, out=None)
Return the cumulative sum of the elements along the given axis.
Refer to numpy.cumsum for full documentation.
See also:

numpy.cumsum equivalent function

method
matrix.diagonal(offset=0, axis1=0, axis2=1)
Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in
previous NumPy versions. In a future version the read-only restriction will be removed.
Refer to numpy.diagonal for full documentation.
See also:

numpy.diagonal equivalent function

method
matrix.dot(b, out=None)
Dot product of two arrays.
Refer to numpy.dot for full documentation.
See also:

numpy.dot equivalent function

124 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[2., 2.],
[2., 2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[8., 8.],
[8., 8.]])

method
matrix.dump(file)
Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.
Parameters
file [str or Path] A string naming the dump file.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
method
matrix.dumps()
Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an
array.
Parameters
None
method
matrix.fill(value)
Fill the array with a scalar value.
Parameters
value [scalar] All elements of a will be assigned this value.

Examples

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

>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([1., 1.])

method
matrix.flatten(self, order='C')
Return a flattened copy of the matrix.
All N elements of the matrix are placed into a single row.

1.6. Standard array subclasses 125

NumPy Reference, Release 1.18.1

Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] ‘C’ means to flatten in row-major (C-style) order. ‘F’
means to flatten in column-major (Fortran-style) order. ‘A’ means to flatten in column-
major order if m is Fortran contiguous in memory, row-major order otherwise. ‘K’ means
to flatten m in the order the elements occur in memory. The default is ‘C’.
Returns
y [matrix] A copy of the matrix, flattened to a (1, N) matrix where N is the number of
elements in the original matrix.
See also:

ravel Return a flattened array.

flat A 1-D flat iterator over the matrix.

Examples

>>> m = np.matrix([[1,2], [3,4]])

>>> m.flatten()
matrix([[1, 2, 3, 4]])
>>> m.flatten('F')
matrix([[1, 3, 2, 4]])

method
matrix.getA(self )
Return self as an ndarray object.
Equivalent to np.asarray(self).
Parameters
None
Returns
ret [ndarray] self as an ndarray

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.getA()
array([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])

method
matrix.getA1(self )
Return self as a flattened ndarray.
Equivalent to np.asarray(x).ravel()
Parameters

126 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

None
Returns
ret [ndarray] self, 1-D, as an ndarray

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.getA1()
array([ 0, 1, 2, ..., 9, 10, 11])

method
matrix.getH(self )
Returns the (complex) conjugate transpose of self.
Equivalent to np.transpose(self) if self is real-valued.
Parameters
None
Returns
ret [matrix object] complex conjugate transpose of self

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4)))
>>> z = x - 1j*x; z
matrix([[ 0. +0.j, 1. -1.j, 2. -2.j, 3. -3.j],
[ 4. -4.j, 5. -5.j, 6. -6.j, 7. -7.j],
[ 8. -8.j, 9. -9.j, 10.-10.j, 11.-11.j]])
>>> z.getH()
matrix([[ 0. -0.j, 4. +4.j, 8. +8.j],
[ 1. +1.j, 5. +5.j, 9. +9.j],
[ 2. +2.j, 6. +6.j, 10.+10.j],
[ 3. +3.j, 7. +7.j, 11.+11.j]])

method
matrix.getI(self )
Returns the (multiplicative) inverse of invertible self.
Parameters
None
Returns
ret [matrix object] If self is non-singular, ret is such that ret * self == self * ret
== np.matrix(np.eye(self[0,:].size) all return True.
Raises
numpy.linalg.LinAlgError: Singular matrix If self is singular.

1.6. Standard array subclasses 127

NumPy Reference, Release 1.18.1

See also:
linalg.inv

Examples

>>> m = np.matrix('[1, 2; 3, 4]'); m

matrix([[1, 2],
[3, 4]])
>>> m.getI()
matrix([[-2. , 1. ],
[ 1.5, -0.5]])
>>> m.getI() * m
matrix([[ 1., 0.], # may vary
[ 0., 1.]])

method
matrix.getT(self )
Returns the transpose of the matrix.
Does not conjugate! For the complex conjugate transpose, use .H.
Parameters
None
Returns
ret [matrix object] The (non-conjugated) transpose of the matrix.
See also:
transpose, getH

Examples

>>> m = np.matrix('[1, 2; 3, 4]')

>>> m
matrix([[1, 2],
[3, 4]])
>>> m.getT()
matrix([[1, 3],
[2, 4]])

method
matrix.getfield(dtype, offset=0)
Returns a field of the given array as a certain type.
A field is a view of the array data with a given data-type. The values in the view are determined by the
given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits
in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with
a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.
Parameters
dtype [str or dtype] The data type of the view. The dtype size of the view can not be larger
than that of the array itself.

128 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

offset [int] Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[1.+1.j, 0.+0.j],
[0.+0.j, 2.+4.j]])
>>> x.getfield(np.float64)
array([[1., 0.],
[0., 2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)

array([[1., 0.],
[0., 4.]])

method
matrix.item(*args)
Copy an element of an array to a standard Python scalar and return it.
Parameters
*args [Arguments (variable number and type)]
• none: in this case, the method only works for arrays with one element (a.size == 1),
which element is copied into a standard Python scalar object and returned.
• int_type: this argument is interpreted as a flat index into the array, specifying which
element to copy and return.
• tuple of int_types: functions as does a single int_type argument, except that the argu-
ment is interpreted as an nd-index into the array.
Returns
z [Standard Python scalar object] A copy of the specified element of the array as a suitable
Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is
no available Python scalar that would not lose information. Void arrays return a buffer object for item(),
unless fields are defined, in which case a tuple is returned.
item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned.
This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the
array using Python’s optimized math.

1.6. Standard array subclasses 129

NumPy Reference, Release 1.18.1

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

method
matrix.itemset(*args)
Insert scalar into an array (scalar is cast to array’s dtype, if possible)
There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is
equivalent to but faster than a[args] = item. The item should be a scalar value and args must select
a single item in the array a.
Parameters
*args [Arguments] If one argument: a scalar, only used in case a is of size 1. If two ar-
guments: the last argument is the value to be set and must be a scalar, the first argument
specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular
location in an ndarray, if you must do this. However, generally this is discouraged: among other
problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a
loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[2, 2, 6],
[1, 0, 6],
[1, 0, 9]])

method

130 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

matrix.max(self, axis=None, out=None)

Return the maximum value along an axis.
Parameters
See `amax` for complete descriptions
See also:
amax, ndarray.max

Notes

This is the same as ndarray.max, but returns a matrix object where ndarray.max would return
an ndarray.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.max()
11
>>> x.max(0)
matrix([[ 8, 9, 10, 11]])
>>> x.max(1)
matrix([[ 3],
[ 7],
[11]])

method
matrix.mean(self, axis=None, dtype=None, out=None)
Returns the average of the matrix elements along the given axis.
Refer to numpy.mean for full documentation.
See also:
numpy.mean

Notes

Same as ndarray.mean except that, where that returns an ndarray, this returns a matrix object.

Examples

>>> x = np.matrix(np.arange(12).reshape((3, 4)))

>>> x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.mean()
5.5
(continues on next page)

1.6. Standard array subclasses 131

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> x.mean(0)
matrix([[4., 5., 6., 7.]])
>>> x.mean(1)
matrix([[ 1.5],
[ 5.5],
[ 9.5]])

method
matrix.min(self, axis=None, out=None)
Return the minimum value along an axis.
Parameters
See `amin` for complete descriptions.
See also:
amin, ndarray.min

Notes

This is the same as ndarray.min, but returns a matrix object where ndarray.min would return an
ndarray.

Examples

>>> x = -np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, -1, -2, -3],
[ -4, -5, -6, -7],
[ -8, -9, -10, -11]])
>>> x.min()
-11
>>> x.min(0)
matrix([[ -8, -9, -10, -11]])
>>> x.min(1)
matrix([[ -3],
[ -7],
[-11]])

method
matrix.newbyteorder(new_order='S')
Return the array with the same data viewed with a different byte order.
Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.
Parameters
new_order [string, optional] Byte order to force; a value from the byte order specifications
below. new_order codes can be any of:
• ‘S’ - swap dtype from current to opposite endian

132 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

• {‘<’, ‘L’} - little endian

• {‘>’, ‘B’} - big endian
• {‘=’, ‘N’} - native order
• {‘|’, ‘I’} - ignore (no change to byte order)
The default value (‘S’) results in swapping the current byte order. The code does a case-
insensitive check on the first letter of new_order for the alternatives above. For example,
any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns
new_arr [array] New array object with the dtype reflecting given change to the byte order.
method
matrix.nonzero()
Return the indices of the elements that are non-zero.
Refer to numpy.nonzero for full documentation.
See also:

numpy.nonzero equivalent function

method
matrix.partition(kth, axis=-1, kind='introselect', order=None)
Rearranges the elements in the array in such a way that the value of the element in kth position is in the
position it would be in a sorted array. All elements smaller than the kth element are moved before this
element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is
undefined.
New in version 1.8.0.
Parameters
kth [int or sequence of ints] Element index to partition by. The kth element value will be
in its final sorted position and all smaller elements will be moved before it and all equal
or greater elements behind it. The order of all elements in the partitions is undefined. If
provided with a sequence of kth it will partition all elements indexed by kth of them into
their sorted position at once.
axis [int, optional] Axis along which to sort. Default is -1, which means sort along the last
axis.
kind [{‘introselect’}, optional] Selection algorithm. Default is ‘introselect’.
order [str or list of str, optional] When a is an array with fields defined, this argument
specifies which fields to compare first, second, etc. A single field can be specified as a
string, and not all fields need to be specified, but unspecified fields will still be used, in the
order in which they come up in the dtype, to break ties.
See also:

numpy.partition Return a parititioned copy of an array.

argpartition Indirect partition.
sort Full sort.

1.6. Standard array subclasses 133

NumPy Reference, Release 1.18.1

Notes

See np.partition for notes on the different algorithms.

Examples

>>> a = np.array([3, 4, 2, 1])

>>> a.partition(3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))

>>> a
array([1, 2, 3, 4])

method
matrix.prod(self, axis=None, dtype=None, out=None)
Return the product of the array elements over the given axis.
Refer to prod for full documentation.
See also:
prod, ndarray.prod

Notes

Same as ndarray.prod, except, where that returns an ndarray, this returns a matrix object instead.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.prod()
0
>>> x.prod(0)
matrix([[ 0, 45, 120, 231]])
>>> x.prod(1)
matrix([[ 0],
[ 840],
[7920]])

method
matrix.ptp(self, axis=None, out=None)
Peak-to-peak (maximum - minimum) value along the given axis.
Refer to numpy.ptp for full documentation.
See also:
numpy.ptp

134 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

Same as ndarray.ptp, except, where that would return an ndarray object, this returns a matrix
object.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.ptp()
11
>>> x.ptp(0)
matrix([[8, 8, 8, 8]])
>>> x.ptp(1)
matrix([[3],
[3],
[3]])

method
matrix.put(indices, values, mode='raise')
Set a.flat[n] = values[n] for all n in indices.
Refer to numpy.put for full documentation.
See also:

numpy.put equivalent function

method
matrix.ravel(self, order='C')
Return a flattened matrix.
Refer to numpy.ravel for more documentation.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] The elements of m are read using this index order. ‘C’
means to index the elements in C-like order, with the last axis index changing fastest, back
to the first axis index changing slowest. ‘F’ means to index the elements in Fortran-like
index order, with the first index changing fastest, and the last index changing slowest. Note
that the ‘C’ and ‘F’ options take no account of the memory layout of the underlying array,
and only refer to the order of axis indexing. ‘A’ means to read the elements in Fortran-like
index order if m is Fortran contiguous in memory, C-like order otherwise. ‘K’ means to
read the elements in the order they occur in memory, except for reversing the data when
strides are negative. By default, ‘C’ index order is used.
Returns
ret [matrix] Return the matrix flattened to shape (1, N) where N is the number of elements
in the original matrix. A copy is made only if necessary.
See also:

matrix.flatten returns a similar output matrix but always a copy

1.6. Standard array subclasses 135

NumPy Reference, Release 1.18.1

matrix.flat a flat iterator on the array.

numpy.ravel related function which returns an ndarray

method
matrix.repeat(repeats, axis=None)
Repeat elements of an array.
Refer to numpy.repeat for full documentation.
See also:

numpy.repeat equivalent function

method
matrix.reshape(shape, order='C')
Returns an array containing the same data with a new shape.
Refer to numpy.reshape for full documentation.
See also:

numpy.reshape equivalent function

Notes

Unlike the free function numpy.reshape, this method on ndarray allows the elements of the shape
parameter to be passed in as separate arguments. For example, a.reshape(10, 11) is equivalent to
a.reshape((10, 11)).
method
matrix.resize(new_shape, refcheck=True)
Change shape and size of array in-place.
Parameters
new_shape [tuple of ints, or n ints] Shape of resized array.
refcheck [bool, optional] If False, reference count will not be checked. Default is True.
Returns
None
Raises
ValueError If a does not own its own data or references or views to it exist, and the data
memory must be changed. PyPy only: will always raise if the data memory must be
changed, since there is no reliable way to determine if references or views to it exist.
SystemError If the order keyword argument is specified. This behaviour is a bug in NumPy.
See also:

resize Return a new array with the specified shape.

136 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.
The purpose of the reference count check is to make sure you do not use this array as a buffer for another
Python object and then reallocate the memory. However, reference counts can increase in other ways so if
you are sure that you have not shared the memory for this array with another Python object, then you may
safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and re-
shaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')

>>> a.resize((2, 1))
>>> a
array([[0],
[1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')

>>> a.resize((2, 1))
>>> a
array([[0],
[2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])

>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
[3, 0, 0]])

Referencing an array prevents resizing. . .

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that references or is referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)

>>> a
array([[0]])
>>> c
array([[0]])

method
matrix.round(decimals=0, out=None)
Return a with each element rounded to the given number of decimals.
Refer to numpy.around for full documentation.

1.6. Standard array subclasses 137

NumPy Reference, Release 1.18.1

See also:

numpy.around equivalent function

method
matrix.searchsorted(v, side='left', sorter=None)
Find indices where elements of v should be inserted in a to maintain order.
For full documentation, see numpy.searchsorted
See also:

numpy.searchsorted equivalent function

method
matrix.setfield(val, dtype, offset=0)
Put a value into a specified place in a field defined by a data-type.
Place val into a’s field defined by dtype and beginning offset bytes into the field.
Parameters
val [object] Value to be placed in field.
dtype [dtype object] Data-type of the field in which to place val.
offset [int, optional] The number of bytes into the field at which to place val.
Returns
None
See also:
getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
[3, 3, 3],
[3, 3, 3]], dtype=int32)
>>> x
array([[1.0e+000, 1.5e-323, 1.5e-323],
[1.5e-323, 1.0e+000, 1.5e-323],
[1.5e-323, 1.5e-323, 1.0e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])

method

138 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

matrix.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, (WRITEBACKIFCOPY and UPDATEIFCOPY), respectively.
These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The
ALIGNED flag can only be set to True if the data is actually aligned according to the type. The WRITE-
BACKIFCOPY and (deprecated) UPDATEIFCOPY flags can never be set to True. The flag WRITEABLE
can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a
writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done
without copying memory.)
Parameters
write [bool, optional] Describes whether or not a can be written to.
align [bool, optional] Describes whether or not a is aligned properly for its type.
uic [bool, optional] Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There
are 7 Boolean flags in use, only four of which can be changed by the user: WRITEBACKIFCOPY, UP-
DATEIFCOPY, WRITEABLE, and ALIGNED.
WRITEABLE (W) the data area can be written to;
ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the com-
piler);
UPDATEIFCOPY (U) (deprecated), replaced by WRITEBACKIFCOPY;
WRITEBACKIFCOPY (X) this array is a copy of some other array (referenced by .base). When the C-API
function PyArray_ResolveWritebackIfCopy is called, the base array will be updated with the contents of
this array.
All flags can be accessed using the single (upper case) letter as well as the full name.

Examples

>>> y = np.array([[3, 1, 7],

... [2, 0, 0],
... [8, 5, 9]])
>>> y
array([[3, 1, 7],
[2, 0, 0],
[8, 5, 9]])
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
OWNDATA : True
WRITEABLE : True
ALIGNED : True
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
(continues on next page)

1.6. Standard array subclasses 139

NumPy Reference, Release 1.18.1

(continued from previous page)

OWNDATA : True
WRITEABLE : False
ALIGNED : False
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: cannot set WRITEBACKIFCOPY flag to True

method
matrix.sort(axis=-1, kind=None, order=None)
Sort an array in-place. Refer to numpy.sort for full documentation.
Parameters
axis [int, optional] Axis along which to sort. Default is -1, which means sort along the last
axis.
kind [{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] Sorting algorithm. The de-
fault is ‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers
and, in general, the actual implementation will vary with datatype. The ‘mergesort’ option
is retained for backwards compatibility.
Changed in version 1.15.0.: The ‘stable’ option was added.
order [str or list of str, optional] When a is an array with fields defined, this argument
specifies which fields to compare first, second, etc. A single field can be specified as a
string, and not all fields need be specified, but unspecified fields will still be used, in the
order in which they come up in the dtype, to break ties.
See also:

numpy.sort Return a sorted copy of an array.

numpy.argsort Indirect sort.
numpy.lexsort Indirect stable sort on multiple keys.
numpy.searchsorted Find elements in sorted array.
numpy.partition Partial sort.

Notes

See numpy.sort for notes on the different sorting algorithms.

140 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> a = np.array([[1,4], [3,1]])

>>> a.sort(axis=1)
>>> a
array([[1, 4],
[1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
[1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:
>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
>>> a.sort(order='y')
>>> a
array([(b'c', 1), (b'a', 2)],
dtype=[('x', 'S1'), ('y', '<i8')])

method
matrix.squeeze(self, axis=None)
Return a possibly reshaped matrix.
Refer to numpy.squeeze for more documentation.
Parameters
axis [None or int or tuple of ints, optional] Selects a subset of the single-dimensional entries
in the shape. If an axis is selected with shape entry greater than one, an error is raised.
Returns
squeezed [matrix] The matrix, but as a (1, N) matrix if it had shape (N, 1).
See also:

numpy.squeeze related function

Notes

If m has a single column then that column is returned as the single row of a matrix. Otherwise m is returned.
The returned matrix is always either m itself or a view into m. Supplying an axis keyword argument will
not affect the returned matrix but it may cause an error to be raised.

Examples

>>> c = np.matrix([[1], [2]])

>>> c
matrix([[1],
[2]])
>>> c.squeeze()
matrix([[1, 2]])
>>> r = c.T
>>> r
matrix([[1, 2]])
(continues on next page)

1.6. Standard array subclasses 141

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> r.squeeze()
matrix([[1, 2]])
>>> m = np.matrix([[1, 2], [3, 4]])
>>> m.squeeze()
matrix([[1, 2],
[3, 4]])

method
matrix.std(self, axis=None, dtype=None, out=None, ddof=0)
Return the standard deviation of the array elements along the given axis.
Refer to numpy.std for full documentation.
See also:
numpy.std

Notes

This is the same as ndarray.std, except that where an ndarray would be returned, a matrix object
is returned instead.

Examples

>>> x = np.matrix(np.arange(12).reshape((3, 4)))

>>> x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.std()
3.4520525295346629 # may vary
>>> x.std(0)
matrix([[ 3.26598632, 3.26598632, 3.26598632, 3.26598632]]) # may vary
>>> x.std(1)
matrix([[ 1.11803399],
[ 1.11803399],
[ 1.11803399]])

method
matrix.sum(self, axis=None, dtype=None, out=None)
Returns the sum of the matrix elements, along the given axis.
Refer to numpy.sum for full documentation.
See also:
numpy.sum

142 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

This is the same as ndarray.sum, except that where an ndarray would be returned, a matrix object
is returned instead.

Examples

>>> x = np.matrix([[1, 2], [4, 3]])

>>> x.sum()
10
>>> x.sum(axis=1)
matrix([[3],
[7]])
>>> x.sum(axis=1, dtype='float')
matrix([[3.],
[7.]])
>>> out = np.zeros((2, 1), dtype='float')
>>> x.sum(axis=1, dtype='float', out=np.asmatrix(out))
matrix([[3.],
[7.]])

method
matrix.swapaxes(axis1, axis2)
Return a view of the array with axis1 and axis2 interchanged.
Refer to numpy.swapaxes for full documentation.
See also:

numpy.swapaxes equivalent function

method
matrix.take(indices, axis=None, out=None, mode='raise')
Return an array formed from the elements of a at the given indices.
Refer to numpy.take for full documentation.
See also:

numpy.take equivalent function

method
matrix.tobytes(order='C')
Construct Python bytes containing the raw data bytes in the array.
Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be
produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order
unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.
New in version 1.9.0.
Parameters
order [{‘C’, ‘F’, None}, optional] Order of the data for multidimensional arrays: C, Fortran,
or the same as for the original array.
Returns

1.6. Standard array subclasses 143

NumPy Reference, Release 1.18.1

s [bytes] Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')

>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

method
matrix.tofile(fid, sep="", format="%s")
Write array to a file as text or binary (default).
Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can
be recovered using the function fromfile().
Parameters
fid [file or str or Path] An open file object, or a string containing a filename.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
sep [str] Separator between array items for text output. If “” (empty), a binary file is written,
equivalent to file.write(a.tobytes()).
format [str] Format string for text file output. Each entry in the array is formatted to text by
first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision
is lost, so this method is not a good choice for files intended to archive data or transport data between
machines with different endianness. Some of these problems can be overcome by outputting the data as
text files, at the expense of speed and file size.
When fid is a file object, array contents are directly written to the file, bypassing the file object’s write
method. As a result, tofile cannot be used with files objects supporting compression (e.g., GzipFile) or
file-like objects that do not support fileno() (e.g., BytesIO).
method
matrix.tolist(self )
Return the matrix as a (possibly nested) list.
See ndarray.tolist for full documentation.
See also:
ndarray.tolist

144 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.tolist()
[[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11]]

method
matrix.tostring(order='C')
Construct Python bytes containing the raw data bytes in the array.
Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be
produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order
unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.
This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.
Parameters
order [{‘C’, ‘F’, None}, optional] Order of the data for multidimensional arrays: C, Fortran,
or the same as for the original array.
Returns
s [bytes] Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')

>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

method
matrix.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)
Return the sum along diagonals of the array.
Refer to numpy.trace for full documentation.
See also:

numpy.trace equivalent function

method
matrix.transpose(*axes)
Returns a view of the array with axes transposed.
For a 1-D array this has no effect, as a transposed vector is simply the same vector. To convert a 1-
D array into a 2D column vector, an additional dimension must be added. np.atleast2d(a).T achieves
this, as does a[:, np.newaxis]. For a 2-D array, this is a standard matrix transpose. For an n-D array, if
axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided

1.6. Standard array subclasses 145

NumPy Reference, Release 1.18.1

and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape =

(i[n-1], i[n-2], ... i[1], i[0]).
Parameters
axes [None, tuple of ints, or n ints]
• None or no argument: reverses the order of the axes.
• tuple of ints: i in the j-th place in the tuple means a’s i-th axis becomes a.transpose()’s
j-th axis.
• n ints: same as an n-tuple of the same ints (this form is intended simply as a “conve-
nience” alternative to the tuple form)
Returns
out [ndarray] View of a, with axes suitably permuted.
See also:

ndarray.T Array property returning the array transposed.

ndarray.reshape Give a new shape to an array without changing its data.

Examples

>>> a = np.array([[1, 2], [3, 4]])

>>> a
array([[1, 2],
[3, 4]])
>>> a.transpose()
array([[1, 3],
[2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
[2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
[2, 4]])

method
matrix.var(self, axis=None, dtype=None, out=None, ddof=0)
Returns the variance of the matrix elements, along the given axis.
Refer to numpy.var for full documentation.
See also:
numpy.var

146 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

This is the same as ndarray.var, except that where an ndarray would be returned, a matrix object
is returned instead.

Examples

>>> x = np.matrix(np.arange(12).reshape((3, 4)))

>>> x
matrix([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
>>> x.var()
11.916666666666666
>>> x.var(0)
matrix([[ 10.66666667, 10.66666667, 10.66666667, 10.66666667]]) # may vary
>>> x.var(1)
matrix([[1.25],
[1.25],
[1.25]])

method
matrix.view(dtype=None, type=None)
New view of array with the same data.
Parameters
dtype [data-type or ndarray sub-class, optional] Data-type descriptor of the returned view,
e.g., float32 or int16. The default, None, results in the view having the same data-type as
a. This argument can also be specified as an ndarray sub-class, which then specifies the
type of the returned object (this is equivalent to setting the type parameter).
type [Python type, optional] Type of the returned view, e.g., ndarray or matrix. Again, the
default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory
with a different data-type. This can cause a reinterpretation of the bytes of memory.
a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance
of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinter-
pretation of the memory.
For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the pre-
vious dtype (for example, converting a regular array to a structured array), then the behavior of the view
cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on
exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a
slice or transpose, etc., the view may give different results.

1.6. Standard array subclasses 147

NumPy Reference, Release 1.18.1

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)

>>> y
matrix([[513]], dtype=int16)
>>> print(type(y))
<class 'numpy.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])

>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
[3, 4]], dtype=int8)
>>> xv.mean(0)
array([2., 3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> x
array([(1, 20), (3, 4)], dtype=[('a', 'i1'), ('b', 'i1')])

Using a view to convert an array to a recarray:

>>> z = x.view(np.recarray)
>>> z.a
array([1, 3], dtype=int8)

Views share data:

>>> x[0] = (9, 10)

>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices,
transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)

>>> y = x[:, 0:2]
>>> y
array([[1, 2],
[4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
...
ValueError: To change to a dtype of a different size, the array must be C-
˓→contiguous

>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
[(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])

148 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

numpy.asmatrix(data, dtype=None)
Interpret the input as a matrix.
Unlike matrix, asmatrix does not make a copy if the input is already a matrix or an ndarray. Equivalent to
matrix(data, copy=False).
Parameters
data [array_like] Input data.
dtype [data-type] Data-type of the output matrix.
Returns
mat [matrix] data interpreted as a matrix.

Examples

>>> x = np.array([[1, 2], [3, 4]])

>>> m = np.asmatrix(x)

>>> x[0,0] = 5

>>> m
matrix([[5, 2],
[3, 4]])

numpy.bmat(obj, ldict=None, gdict=None)

Build a matrix object from a string, nested sequence, or array.
Parameters
obj [str or array_like] Input data. If a string, variables in the current scope may be referenced
by name.
ldict [dict, optional] A dictionary that replaces local operands in current frame. Ignored if obj
is not a string or gdict is None.
gdict [dict, optional] A dictionary that replaces global operands in current frame. Ignored if obj
is not a string.
Returns
out [matrix] Returns a matrix object, which is a specialized 2-D array.
See also:

block A generalization of this function for N-d arrays, that returns normal ndarrays.

1.6. Standard array subclasses 149

NumPy Reference, Release 1.18.1

Examples

>>> A = np.mat('1 1; 1 1')

>>> B = np.mat('2 2; 2 2')
>>> C = np.mat('3 4; 5 6')
>>> D = np.mat('7 8; 9 0')

All the following expressions construct the same block matrix:

>>> np.bmat([[A, B], [C, D]])

matrix([[1, 1, 2, 2],
[1, 1, 2, 2],
[3, 4, 7, 8],
[5, 6, 9, 0]])
>>> np.bmat(np.r_[np.c_[A, B], np.c_[C, D]])
matrix([[1, 1, 2, 2],
[1, 1, 2, 2],
[3, 4, 7, 8],
[5, 6, 9, 0]])
>>> np.bmat('A,B; C,D')
matrix([[1, 1, 2, 2],
[1, 1, 2, 2],
[3, 4, 7, 8],
[5, 6, 9, 0]])

Example 1: Matrix creation from a string

>>> a=mat('1 2 3; 4 5 3')

>>> print (a*a.T).I
[[ 0.2924 -0.1345]
[-0.1345 0.0819]]

Example 2: Matrix creation from nested sequence

>>> mat([[1,5,10],[1.0,3,4j]])
matrix([[ 1.+0.j, 5.+0.j, 10.+0.j],
[ 1.+0.j, 3.+0.j, 0.+4.j]])

Example 3: Matrix creation from an array

>>> mat(random.rand(3,3)).T
matrix([[ 0.7699, 0.7922, 0.3294],
[ 0.2792, 0.0101, 0.9219],
[ 0.3398, 0.7571, 0.8197]])

1.6.3 Memory-mapped file arrays

Memory-mapped files are useful for reading and/or modifying small segments of a large file with regular layout,
without reading the entire file into memory. A simple subclass of the ndarray uses a memory-mapped file for the data
buffer of the array. For small files, the over-head of reading the entire file into memory is typically not significant,
however for large files using memory mapping can save considerable resources.
Memory-mapped-file arrays have one additional method (besides those they inherit from the ndarray): .flush()
which must be called manually by the user to ensure that any changes to the array actually get written to disk.

150 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

memmap Create a memory-map to an array stored in a binary file

on disk.
memmap.flush(self) Write any changes in the array to the file on disk.

class numpy.memmap
Create a memory-map to an array stored in a binary file on disk.
Memory-mapped files are used for accessing small segments of large files on disk, without reading the entire
file into memory. NumPy’s memmap’s are array-like objects. This differs from Python’s mmap module, which
uses file-like objects.
This subclass of ndarray has some unpleasant interactions with some operations, because it doesn’t quite fit
properly as a subclass. An alternative to using this subclass is to create the mmap object yourself, then create an
ndarray with ndarray.__new__ directly, passing the object created in its ‘buffer=’ parameter.
This class may at some point be turned into a factory function which returns a view into an mmap buffer.
Delete the memmap instance to close the memmap file.
Parameters
filename [str, file-like object, or pathlib.Path instance] The file name or file object to be used as
the array data buffer.
dtype [data-type, optional] The data-type used to interpret the file contents. Default is uint8.
mode [{‘r+’, ‘r’, ‘w+’, ‘c’}, optional] The file is opened in this mode:

‘r’ Open existing file for reading only.

‘r+’ Open existing file for reading and writing.
‘w+’ Create or overwrite existing file for reading and writing.
‘c’ Copy-on-write: assignments affect data in memory, but changes are not saved to
disk. The file on disk is read-only.

Default is ‘r+’.
offset [int, optional] In the file, array data starts at this offset. Since offset is measured in bytes,
it should normally be a multiple of the byte-size of dtype. When mode != 'r', even
positive offsets beyond end of file are valid; The file will be extended to accommodate
the additional data. By default, memmap will start at the beginning of the file, even if
filename is a file pointer fp and fp.tell() != 0.
shape [tuple, optional] The desired shape of the array. If mode == 'r' and the number of
remaining bytes after offset is not a multiple of the byte-size of dtype, you must specify
shape. By default, the returned array will be 1-D with the number of elements determined
by file size and data-type.
order [{‘C’, ‘F’}, optional] Specify the order of the ndarray memory layout: row-major, C-
style or column-major, Fortran-style. This only has an effect if the shape is greater than
1-D. The default order is ‘C’.
See also:

lib.format.open_memmap Create or load a memory-mapped .npy file.

1.6. Standard array subclasses 151

NumPy Reference, Release 1.18.1

Notes

The memmap object can be used anywhere an ndarray is accepted. Given a memmap fp, isinstance(fp,
numpy.ndarray) returns True.
Memory-mapped files cannot be larger than 2GB on 32-bit systems.
When a memmap causes a file to be created or extended beyond its current size in the filesystem, the contents
of the new part are unspecified. On systems with POSIX filesystem semantics, the extended part will be filled
with zero bytes.

Examples

>>> data = np.arange(12, dtype='float32')

>>> data.resize((3,4))

This example uses a temporary file so that doctest doesn’t write files to your directory. You would use a ‘normal’
filename.

>>> from tempfile import mkdtemp

>>> import os.path as path
>>> filename = path.join(mkdtemp(), 'newfile.dat')

Create a memmap with dtype and shape that matches our data:

>>> fp = np.memmap(filename, dtype='float32', mode='w+', shape=(3,4))

>>> fp
memmap([[0., 0., 0., 0.],
[0., 0., 0., 0.],
[0., 0., 0., 0.]], dtype=float32)

Write data to memmap array:

>>> fp[:] = data[:]

>>> fp
memmap([[ 0., 1., 2., 3.],
[ 4., 5., 6., 7.],
[ 8., 9., 10., 11.]], dtype=float32)

>>> fp.filename == path.abspath(filename)

True

Deletion flushes memory changes to disk before removing the object:

>>> del fp

Load the memmap and verify data was stored:

>>> newfp = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))

>>> newfp
memmap([[ 0., 1., 2., 3.],
[ 4., 5., 6., 7.],
[ 8., 9., 10., 11.]], dtype=float32)

Read-only memmap:

152 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> fpr = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))

>>> fpr.flags.writeable
False

Copy-on-write memmap:

>>> fpc = np.memmap(filename, dtype='float32', mode='c', shape=(3,4))

>>> fpc.flags.writeable
True

It’s possible to assign to copy-on-write array, but values are only written into the memory copy of the array, and
not written to disk:

>>> fpc
memmap([[ 0., 1., 2., 3.],
[ 4., 5., 6., 7.],
[ 8., 9., 10., 11.]], dtype=float32)
>>> fpc[0,:] = 0
>>> fpc
memmap([[ 0., 0., 0., 0.],
[ 4., 5., 6., 7.],
[ 8., 9., 10., 11.]], dtype=float32)

File on disk is unchanged:

>>> fpr
memmap([[ 0., 1., 2., 3.],
[ 4., 5., 6., 7.],
[ 8., 9., 10., 11.]], dtype=float32)

Offset into a memmap:

>>> fpo = np.memmap(filename, dtype='float32', mode='r', offset=16)

>>> fpo
memmap([ 4., 5., 6., 7., 8., 9., 10., 11.], dtype=float32)

Attributes
filename [str or pathlib.Path instance] Path to the mapped file.
offset [int] Offset position in the file.
mode [str] File mode.

Methods

flush(self) Write any changes in the array to the file on disk.

method
memmap.flush(self )
Write any changes in the array to the file on disk.
For further information, see memmap.
Parameters

1.6. Standard array subclasses 153

NumPy Reference, Release 1.18.1

None
See also:
memmap
Example:

>>> a = memmap('newfile.dat', dtype=float, mode='w+', shape=1000)

>>> a[10] = 10.0
>>> a[30] = 30.0
>>> del a
>>> b = fromfile('newfile.dat', dtype=float)
>>> print b[10], b[30]
10.0 30.0
>>> a = memmap('newfile.dat', dtype=float)
>>> print a[10], a[30]
10.0 30.0

1.6.4 Character arrays (numpy.char)

See also:
Creating character arrays (numpy.char)

Note: The chararray class exists for backwards compatibility with Numarray, it is not recommended for new
development. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of dtype
object_, string_ or unicode_, and use the free functions in the numpy.char module for fast vectorized
string operations.

These are enhanced arrays of either string_ type or unicode_ type. These arrays inherit from the ndarray,
but specially-define the operations +, *, and % on a (broadcasting) element-by-element basis. These operations are
not available on the standard ndarray of character type. In addition, the chararray has all of the standard
string (and unicode) methods, executing them on an element-by-element basis. Perhaps the easiest way to create
a chararray is to use self.view(chararray) where self is an ndarray of str or unicode data-type. However, a
chararray can also be created using the numpy.chararray constructor, or via the numpy.char.array function:

chararray(shape[, itemsize, unicode, . . . ]) Provides a convenient view on arrays of string and uni-
code values.
core.defchararray.array(obj[, itemsize, . . . ]) Create a chararray.

class numpy.chararray(shape, itemsize=1, unicode=False, buffer=None, offset=0, strides=None, or-

der=None)
Provides a convenient view on arrays of string and unicode values.

Note: The chararray class exists for backwards compatibility with Numarray, it is not recommended for
new development. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of
dtype object_, string_ or unicode_, and use the free functions in the numpy.char module for fast
vectorized string operations.

Versus a regular NumPy array of type str or unicode, this class adds the following functionality:
1) values automatically have whitespace removed from the end when indexed

154 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

2) comparison operators automatically remove whitespace from the end when comparing values
3) vectorized string operations are provided as methods (e.g. endswith) and infix operators (e.g. "+",
"*", "%")
chararrays should be created using numpy.char.array or numpy.char.asarray, rather than this con-
structor directly.
This constructor creates the array, using buffer (with offset and strides) if it is not None. If buffer is None,
then constructs a new array with strides in “C order”, unless both len(shape) >= 2 and order='F',
in which case strides is in “Fortran order”.
Parameters
shape [tuple] Shape of the array.
itemsize [int, optional] Length of each array element, in number of characters. Default is 1.
unicode [bool, optional] Are the array elements of type unicode (True) or string (False). Default
is False.
buffer [int, optional] Memory address of the start of the array data. Default is None, in which
case a new array is created.
offset [int, optional] Fixed stride displacement from the beginning of an axis? Default is 0.
Needs to be >=0.
strides [array_like of ints, optional] Strides for the array (see ndarray.strides for full
description). Default is None.
order [{‘C’, ‘F’}, optional] The order in which the array data is stored in memory: ‘C’ -> “row
major” order (the default), ‘F’ -> “column major” (Fortran) order.

Examples

>>> charar = np.chararray((3, 3))

>>> charar[:] = 'a'
>>> charar
chararray([[b'a', b'a', b'a'],
[b'a', b'a', b'a'],
[b'a', b'a', b'a']], dtype='|S1')

>>> charar = np.chararray(charar.shape, itemsize=5)

>>> charar[:] = 'abc'
>>> charar
chararray([[b'abc', b'abc', b'abc'],
[b'abc', b'abc', b'abc'],
[b'abc', b'abc', b'abc']], dtype='|S5')

Attributes
T The transposed array.
base Base object if memory is from some other object.
ctypes An object to simplify the interaction of the array with the ctypes module.
data Python buffer object pointing to the start of the array’s data.
dtype Data-type of the array’s elements.
flags Information about the memory layout of the array.

1.6. Standard array subclasses 155

NumPy Reference, Release 1.18.1

flat A 1-D iterator over the array.

imag The imaginary part of the array.
itemsize Length of one array element in bytes.
nbytes Total bytes consumed by the elements of the array.
ndim Number of array dimensions.
real The real part of the array.
shape Tuple of array dimensions.
size Number of elements in the array.
strides Tuple of bytes to step in each dimension when traversing an array.

Methods

astype(dtype[, order, casting, subok, copy]) Copy of the array, cast to a specified type.
argsort([axis, kind, order]) Returns the indices that would sort this array.
copy([order]) Return a copy of the array.
count(self, sub[, start, end]) Returns an array with the number of non-overlapping
occurrences of substring sub in the range [start, end].
decode(self[, encoding, errors]) Calls str.decode element-wise.
dump(file) Dump a pickle of the array to the specified file.
dumps() Returns the pickle of the array as a string.
encode(self[, encoding, errors]) Calls str.encode element-wise.
endswith(self, suffix[, start, end]) Returns a boolean array which is True where the
string element in self ends with suffix, otherwise
False.
expandtabs(self[, tabsize]) Return a copy of each string element where all tab
characters are replaced by one or more spaces.
fill(value) Fill the array with a scalar value.
find(self, sub[, start, end]) For each element, return the lowest index in the
string where substring sub is found.
flatten([order]) Return a copy of the array collapsed into one dimen-
sion.
getfield(dtype[, offset]) Returns a field of the given array as a certain type.
index(self, sub[, start, end]) Like find, but raises ValueError when the substring
is not found.
isalnum(self) Returns true for each element if all characters in the
string are alphanumeric and there is at least one char-
acter, false otherwise.
isalpha(self) Returns true for each element if all characters in the
string are alphabetic and there is at least one charac-
ter, false otherwise.
isdecimal(self) For each element in self, return True if there are only
decimal characters in the element.
isdigit(self) Returns true for each element if all characters in the
string are digits and there is at least one character,
false otherwise.
Continued on next page

156 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Table 41 – continued from previous page

islower(self) Returns true for each element if all cased characters
in the string are lowercase and there is at least one
cased character, false otherwise.
isnumeric(self) For each element in self, return True if there are only
numeric characters in the element.
isspace(self) Returns true for each element if there are only
whitespace characters in the string and there is at
least one character, false otherwise.
istitle(self) Returns true for each element if the element is a title-
cased string and there is at least one character, false
otherwise.
isupper(self) Returns true for each element if all cased characters
in the string are uppercase and there is at least one
character, false otherwise.
item(*args) Copy an element of an array to a standard Python
scalar and return it.
join(self, seq) Return a string which is the concatenation of the
strings in the sequence seq.
ljust(self, width[, fillchar]) Return an array with the elements of self left-
justified in a string of length width.
lower(self) Return an array with the elements of self converted
to lowercase.
lstrip(self[, chars]) For each element in self, return a copy with the lead-
ing characters removed.
nonzero() Return the indices of the elements that are non-zero.
put(indices, values[, mode]) Set a.flat[n] = values[n] for all n in in-
dices.
ravel([order]) Return a flattened array.
repeat(repeats[, axis]) Repeat elements of an array.
replace(self, old, new[, count]) For each element in self, return a copy of the string
with all occurrences of substring old replaced by
new.
reshape(shape[, order]) Returns an array containing the same data with a new
shape.
resize(new_shape[, refcheck]) Change shape and size of array in-place.
rfind(self, sub[, start, end]) For each element in self, return the highest index in
the string where substring sub is found, such that sub
is contained within [start, end].
rindex(self, sub[, start, end]) Like rfind, but raises ValueError when the sub-
string sub is not found.
rjust(self, width[, fillchar]) Return an array with the elements of self right-
justified in a string of length width.
rsplit(self[, sep, maxsplit]) For each element in self, return a list of the words in
the string, using sep as the delimiter string.
rstrip(self[, chars]) For each element in self, return a copy with the trail-
ing characters removed.
searchsorted(v[, side, sorter]) Find indices where elements of v should be inserted
in a to maintain order.
setfield(val, dtype[, offset]) Put a value into a specified place in a field defined by
a data-type.
Continued on next page

1.6. Standard array subclasses 157

NumPy Reference, Release 1.18.1

Table 41 – continued from previous page

setflags([write, align, uic]) Set array flags WRITEABLE, ALIGNED, (WRITE-
BACKIFCOPY and UPDATEIFCOPY), respec-
tively.
sort([axis, kind, order]) Sort an array in-place.
split(self[, sep, maxsplit]) For each element in self, return a list of the words in
the string, using sep as the delimiter string.
splitlines(self[, keepends]) For each element in self, return a list of the lines in
the element, breaking at line boundaries.
squeeze([axis]) Remove single-dimensional entries from the shape
of a.
startswith(self, prefix[, start, end]) Returns a boolean array which is True where the
string element in self starts with prefix, otherwise
False.
strip(self[, chars]) For each element in self, return a copy with the lead-
ing and trailing characters removed.
swapaxes(axis1, axis2) Return a view of the array with axis1 and axis2 in-
terchanged.
swapcase(self) For each element in self, return a copy of the string
with uppercase characters converted to lowercase
and vice versa.
take(indices[, axis, out, mode]) Return an array formed from the elements of a at the
given indices.
title(self) For each element in self, return a titlecased version
of the string: words start with uppercase characters,
all remaining cased characters are lowercase.
tofile(fid[, sep, format]) Write array to a file as text or binary (default).
tolist() Return the array as an a.ndim-levels deep nested
list of Python scalars.
tostring([order]) Construct Python bytes containing the raw data bytes
in the array.
translate(self, table[, deletechars]) For each element in self, return a copy of the string
where all characters occurring in the optional ar-
gument deletechars are removed, and the remain-
ing characters have been mapped through the given
translation table.
transpose(*axes) Returns a view of the array with axes transposed.
upper(self) Return an array with the elements of self converted
to uppercase.
view([dtype, type]) New view of array with the same data.
zfill(self, width) Return the numeric string left-filled with zeros in a
string of length width.

method
chararray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
Copy of the array, cast to a specified type.
Parameters
dtype [str or dtype] Typecode or data-type to which the array is cast.
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout order of the result. ‘C’
means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran
contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements

158 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

appear in memory as possible. Default is ‘K’.

casting [{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional] Controls what kind of data
casting may occur. Defaults to ‘unsafe’ for backwards compatibility.
• ‘no’ means the data types should not be cast at all.
• ‘equiv’ means only byte-order changes are allowed.
• ‘safe’ means only casts which can preserve values are allowed.
• ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are
allowed.
• ‘unsafe’ means any data conversions may be done.
subok [bool, optional] If True, then sub-classes will be passed-through (default), otherwise
the returned array will be forced to be a base-class array.
copy [bool, optional] By default, astype always returns a newly allocated array. If this is
set to false, and the dtype, order, and subok requirements are satisfied, the input array is
returned instead of a copy.
Returns
arr_t [ndarray] Unless copy is False and the other conditions for returning the input array
are satisfied (see description for copy input parameter), arr_t is a new array of the same
shape as the input array, with dtype, order given by dtype, order.
Raises
ComplexWarning When casting from complex to float or int. To avoid this, one should use
a.real.astype(t).

Notes

Changed in version 1.17.0: Casting between a simple data type and a structured one is possible only for
“unsafe” casting. Casting to multiple fields is allowed, but casting from multiple fields is not.
Changed in version 1.9.0: Casting from numeric to string types in ‘safe’ casting mode requires that the
string dtype length is long enough to store the max integer/float value converted.

Examples

>>> x = np.array([1, 2, 2.5])

>>> x
array([1. , 2. , 2.5])

>>> x.astype(int)
array([1, 2, 2])

method
chararray.argsort(axis=-1, kind=None, order=None)
Returns the indices that would sort this array.
Refer to numpy.argsort for full documentation.
See also:

1.6. Standard array subclasses 159

NumPy Reference, Release 1.18.1

numpy.argsort equivalent function

method
chararray.copy(order='C')
Return a copy of the array.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout of the copy. ‘C’ means
C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’
means match the layout of a as closely as possible. (Note that this function and numpy.
copy are very similar, but have different default values for their order= arguments.)
See also:
numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
[0, 0, 0]])

>>> y
array([[1, 2, 3],
[4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True

method
chararray.count(self, sub, start=0, end=None)
Returns an array with the number of non-overlapping occurrences of substring sub in the range [start, end].
See also:
char.count
method
chararray.decode(self, encoding=None, errors=None)
Calls str.decode element-wise.
See also:
char.decode
method
chararray.dump(file)
Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

160 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Parameters
file [str or Path] A string naming the dump file.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
method
chararray.dumps()
Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an
array.
Parameters
None
method
chararray.encode(self, encoding=None, errors=None)
Calls str.encode element-wise.
See also:
char.encode
method
chararray.endswith(self, suffix, start=0, end=None)
Returns a boolean array which is True where the string element in self ends with suffix, otherwise False.
See also:
char.endswith
method
chararray.expandtabs(self, tabsize=8)
Return a copy of each string element where all tab characters are replaced by one or more spaces.
See also:
char.expandtabs
method
chararray.fill(value)
Fill the array with a scalar value.
Parameters
value [scalar] All elements of a will be assigned this value.

Examples

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

>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([1., 1.])

method

1.6. Standard array subclasses 161

NumPy Reference, Release 1.18.1

chararray.find(self, sub, start=0, end=None)

For each element, return the lowest index in the string where substring sub is found.
See also:
char.find
method
chararray.flatten(order='C')
Return a copy of the array collapsed into one dimension.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] ‘C’ means to flatten in row-major (C-style) order. ‘F’
means to flatten in column-major (Fortran- style) order. ‘A’ means to flatten in column-
major order if a is Fortran contiguous in memory, row-major order otherwise. ‘K’ means
to flatten a in the order the elements occur in memory. The default is ‘C’.
Returns
y [ndarray] A copy of the input array, flattened to one dimension.
See also:

ravel Return a flattened array.

flat A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])

>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])

method
chararray.getfield(dtype, offset=0)
Returns a field of the given array as a certain type.
A field is a view of the array data with a given data-type. The values in the view are determined by the
given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits
in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with
a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.
Parameters
dtype [str or dtype] The data type of the view. The dtype size of the view can not be larger
than that of the array itself.
offset [int] Number of bytes to skip before beginning the element view.

162 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[1.+1.j, 0.+0.j],
[0.+0.j, 2.+4.j]])
>>> x.getfield(np.float64)
array([[1., 0.],
[0., 2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)

array([[1., 0.],
[0., 4.]])

method
chararray.index(self, sub, start=0, end=None)
Like find, but raises ValueError when the substring is not found.
See also:
char.index
method
chararray.isalnum(self )
Returns true for each element if all characters in the string are alphanumeric and there is at least one
character, false otherwise.
See also:
char.isalnum
method
chararray.isalpha(self )
Returns true for each element if all characters in the string are alphabetic and there is at least one character,
false otherwise.
See also:
char.isalpha
method
chararray.isdecimal(self )
For each element in self, return True if there are only decimal characters in the element.
See also:
char.isdecimal
method
chararray.isdigit(self )
Returns true for each element if all characters in the string are digits and there is at least one character,
false otherwise.
See also:
char.isdigit

1.6. Standard array subclasses 163

NumPy Reference, Release 1.18.1

method
chararray.islower(self )
Returns true for each element if all cased characters in the string are lowercase and there is at least one
cased character, false otherwise.
See also:
char.islower
method
chararray.isnumeric(self )
For each element in self, return True if there are only numeric characters in the element.
See also:
char.isnumeric
method
chararray.isspace(self )
Returns true for each element if there are only whitespace characters in the string and there is at least one
character, false otherwise.
See also:
char.isspace
method
chararray.istitle(self )
Returns true for each element if the element is a titlecased string and there is at least one character, false
otherwise.
See also:
char.istitle
method
chararray.isupper(self )
Returns true for each element if all cased characters in the string are uppercase and there is at least one
character, false otherwise.
See also:
char.isupper
method
chararray.item(*args)
Copy an element of an array to a standard Python scalar and return it.
Parameters
*args [Arguments (variable number and type)]
• none: in this case, the method only works for arrays with one element (a.size == 1),
which element is copied into a standard Python scalar object and returned.
• int_type: this argument is interpreted as a flat index into the array, specifying which
element to copy and return.
• tuple of int_types: functions as does a single int_type argument, except that the argu-
ment is interpreted as an nd-index into the array.

164 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Returns
z [Standard Python scalar object] A copy of the specified element of the array as a suitable
Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is
no available Python scalar that would not lose information. Void arrays return a buffer object for item(),
unless fields are defined, in which case a tuple is returned.
item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned.
This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the
array using Python’s optimized math.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

method
chararray.join(self, seq)
Return a string which is the concatenation of the strings in the sequence seq.
See also:
char.join
method
chararray.ljust(self, width, fillchar=' ')
Return an array with the elements of self left-justified in a string of length width.
See also:
char.ljust
method
chararray.lower(self )
Return an array with the elements of self converted to lowercase.
See also:
char.lower
method

1.6. Standard array subclasses 165

NumPy Reference, Release 1.18.1

chararray.lstrip(self, chars=None)
For each element in self, return a copy with the leading characters removed.
See also:
char.lstrip
method
chararray.nonzero()
Return the indices of the elements that are non-zero.
Refer to numpy.nonzero for full documentation.
See also:

numpy.nonzero equivalent function

method
chararray.put(indices, values, mode='raise')
Set a.flat[n] = values[n] for all n in indices.
Refer to numpy.put for full documentation.
See also:

numpy.put equivalent function

method
chararray.ravel([order ])
Return a flattened array.
Refer to numpy.ravel for full documentation.
See also:

numpy.ravel equivalent function

ndarray.flat a flat iterator on the array.

method
chararray.repeat(repeats, axis=None)
Repeat elements of an array.
Refer to numpy.repeat for full documentation.
See also:

numpy.repeat equivalent function

method
chararray.replace(self, old, new, count=None)
For each element in self, return a copy of the string with all occurrences of substring old replaced by new.
See also:
char.replace
method

166 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

chararray.reshape(shape, order='C')
Returns an array containing the same data with a new shape.
Refer to numpy.reshape for full documentation.
See also:

numpy.reshape equivalent function

Notes

Unlike the free function numpy.reshape, this method on ndarray allows the elements of the shape
parameter to be passed in as separate arguments. For example, a.reshape(10, 11) is equivalent to
a.reshape((10, 11)).
method
chararray.resize(new_shape, refcheck=True)
Change shape and size of array in-place.
Parameters
new_shape [tuple of ints, or n ints] Shape of resized array.
refcheck [bool, optional] If False, reference count will not be checked. Default is True.
Returns
None
Raises
ValueError If a does not own its own data or references or views to it exist, and the data
memory must be changed. PyPy only: will always raise if the data memory must be
changed, since there is no reliable way to determine if references or views to it exist.
SystemError If the order keyword argument is specified. This behaviour is a bug in NumPy.
See also:

resize Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.
The purpose of the reference count check is to make sure you do not use this array as a buffer for another
Python object and then reallocate the memory. However, reference counts can increase in other ways so if
you are sure that you have not shared the memory for this array with another Python object, then you may
safely set refcheck to False.

1.6. Standard array subclasses 167

NumPy Reference, Release 1.18.1

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and re-
shaped:
>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
[1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')

>>> a.resize((2, 1))
>>> a
array([[0],
[2]])

Enlarging an array: as above, but missing entries are filled with zeros:
>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
[3, 0, 0]])

Referencing an array prevents resizing. . .

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that references or is referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])

method
chararray.rfind(self, sub, start=0, end=None)
For each element in self, return the highest index in the string where substring sub is found, such that sub
is contained within [start, end].
See also:
char.rfind
method
chararray.rindex(self, sub, start=0, end=None)
Like rfind, but raises ValueError when the substring sub is not found.
See also:
char.rindex
method

168 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

chararray.rjust(self, width, fillchar=' ')

Return an array with the elements of self right-justified in a string of length width.
See also:
char.rjust
method
chararray.rsplit(self, sep=None, maxsplit=None)
For each element in self, return a list of the words in the string, using sep as the delimiter string.
See also:
char.rsplit
method
chararray.rstrip(self, chars=None)
For each element in self, return a copy with the trailing characters removed.
See also:
char.rstrip
method
chararray.searchsorted(v, side='left', sorter=None)
Find indices where elements of v should be inserted in a to maintain order.
For full documentation, see numpy.searchsorted
See also:

numpy.searchsorted equivalent function

method
chararray.setfield(val, dtype, offset=0)
Put a value into a specified place in a field defined by a data-type.
Place val into a’s field defined by dtype and beginning offset bytes into the field.
Parameters
val [object] Value to be placed in field.
dtype [dtype object] Data-type of the field in which to place val.
offset [int, optional] The number of bytes into the field at which to place val.
Returns
None
See also:
getfield

1.6. Standard array subclasses 169

NumPy Reference, Release 1.18.1

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
[3, 3, 3],
[3, 3, 3]], dtype=int32)
>>> x
array([[1.0e+000, 1.5e-323, 1.5e-323],
[1.5e-323, 1.0e+000, 1.5e-323],
[1.5e-323, 1.5e-323, 1.0e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])

method
chararray.setflags(write=None, align=None, uic=None)
Set array flags WRITEABLE, ALIGNED, (WRITEBACKIFCOPY and UPDATEIFCOPY), respectively.
These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The
ALIGNED flag can only be set to True if the data is actually aligned according to the type. The WRITE-
BACKIFCOPY and (deprecated) UPDATEIFCOPY flags can never be set to True. The flag WRITEABLE
can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a
writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done
without copying memory.)
Parameters
write [bool, optional] Describes whether or not a can be written to.
align [bool, optional] Describes whether or not a is aligned properly for its type.
uic [bool, optional] Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There
are 7 Boolean flags in use, only four of which can be changed by the user: WRITEBACKIFCOPY, UP-
DATEIFCOPY, WRITEABLE, and ALIGNED.
WRITEABLE (W) the data area can be written to;
ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the com-
piler);
UPDATEIFCOPY (U) (deprecated), replaced by WRITEBACKIFCOPY;
WRITEBACKIFCOPY (X) this array is a copy of some other array (referenced by .base). When the C-API
function PyArray_ResolveWritebackIfCopy is called, the base array will be updated with the contents of
this array.
All flags can be accessed using the single (upper case) letter as well as the full name.

170 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> y = np.array([[3, 1, 7],

... [2, 0, 0],
... [8, 5, 9]])
>>> y
array([[3, 1, 7],
[2, 0, 0],
[8, 5, 9]])
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
OWNDATA : True
WRITEABLE : True
ALIGNED : True
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
OWNDATA : True
WRITEABLE : False
ALIGNED : False
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: cannot set WRITEBACKIFCOPY flag to True

method
chararray.sort(axis=-1, kind=None, order=None)
Sort an array in-place. Refer to numpy.sort for full documentation.
Parameters
axis [int, optional] Axis along which to sort. Default is -1, which means sort along the last
axis.
kind [{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] Sorting algorithm. The de-
fault is ‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers
and, in general, the actual implementation will vary with datatype. The ‘mergesort’ option
is retained for backwards compatibility.
Changed in version 1.15.0.: The ‘stable’ option was added.
order [str or list of str, optional] When a is an array with fields defined, this argument
specifies which fields to compare first, second, etc. A single field can be specified as a
string, and not all fields need be specified, but unspecified fields will still be used, in the
order in which they come up in the dtype, to break ties.
See also:

numpy.sort Return a sorted copy of an array.

numpy.argsort Indirect sort.
numpy.lexsort Indirect stable sort on multiple keys.

1.6. Standard array subclasses 171

NumPy Reference, Release 1.18.1

numpy.searchsorted Find elements in sorted array.

numpy.partition Partial sort.

Notes

See numpy.sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])

>>> a.sort(axis=1)
>>> a
array([[1, 4],
[1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
[1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])

>>> a.sort(order='y')
>>> a
array([(b'c', 1), (b'a', 2)],
dtype=[('x', 'S1'), ('y', '<i8')])

method
chararray.split(self, sep=None, maxsplit=None)
For each element in self, return a list of the words in the string, using sep as the delimiter string.
See also:
char.split
method
chararray.splitlines(self, keepends=None)
For each element in self, return a list of the lines in the element, breaking at line boundaries.
See also:
char.splitlines
method
chararray.squeeze(axis=None)
Remove single-dimensional entries from the shape of a.
Refer to numpy.squeeze for full documentation.
See also:

numpy.squeeze equivalent function

method

172 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

chararray.startswith(self, prefix, start=0, end=None)

Returns a boolean array which is True where the string element in self starts with prefix, otherwise False.
See also:
char.startswith
method
chararray.strip(self, chars=None)
For each element in self, return a copy with the leading and trailing characters removed.
See also:
char.strip
method
chararray.swapaxes(axis1, axis2)
Return a view of the array with axis1 and axis2 interchanged.
Refer to numpy.swapaxes for full documentation.
See also:

numpy.swapaxes equivalent function

method
chararray.swapcase(self )
For each element in self, return a copy of the string with uppercase characters converted to lowercase and
vice versa.
See also:
char.swapcase
method
chararray.take(indices, axis=None, out=None, mode='raise')
Return an array formed from the elements of a at the given indices.
Refer to numpy.take for full documentation.
See also:

numpy.take equivalent function

method
chararray.title(self )
For each element in self, return a titlecased version of the string: words start with uppercase characters, all
remaining cased characters are lowercase.
See also:
char.title
method
chararray.tofile(fid, sep="", format="%s")
Write array to a file as text or binary (default).
Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can
be recovered using the function fromfile().

1.6. Standard array subclasses 173

NumPy Reference, Release 1.18.1

Parameters
fid [file or str or Path] An open file object, or a string containing a filename.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
sep [str] Separator between array items for text output. If “” (empty), a binary file is written,
equivalent to file.write(a.tobytes()).
format [str] Format string for text file output. Each entry in the array is formatted to text by
first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision
is lost, so this method is not a good choice for files intended to archive data or transport data between
machines with different endianness. Some of these problems can be overcome by outputting the data as
text files, at the expense of speed and file size.
When fid is a file object, array contents are directly written to the file, bypassing the file object’s write
method. As a result, tofile cannot be used with files objects supporting compression (e.g., GzipFile) or
file-like objects that do not support fileno() (e.g., BytesIO).
method
chararray.tolist()
Return the array as an a.ndim-levels deep nested list of Python scalars.
Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible
builtin Python type, via the item function.
If a.ndim is 0, then since the depth of the nested list is 0, it will not be a list at all, but a simple Python
scalar.
Parameters
none
Returns
y [object, or list of object, or list of list of object, or . . . ] The possibly nested list of array
elements.

Notes

The array may be recreated via a = np.array(a.tolist()), although this may sometimes lose
precision.

Examples

For a 1D array, a.tolist() is almost the same as list(a), except that tolist changes numpy
scalars to Python scalars:

>>> a = np.uint32([1, 2])

>>> a_list = list(a)
>>> a_list
[1, 2]
>>> type(a_list[0])
(continues on next page)

174 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

(continued from previous page)

<class 'numpy.uint32'>
>>> a_tolist = a.tolist()
>>> a_tolist
[1, 2]
>>> type(a_tolist[0])
<class 'int'>

Additionally, for a 2D array, tolist applies recursively:

>>> a = np.array([[1, 2], [3, 4]])

>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]

The base case for this recursion is a 0D array:

>>> a = np.array(1)
>>> list(a)
Traceback (most recent call last):
...
TypeError: iteration over a 0-d array
>>> a.tolist()
1

method
chararray.tostring(order='C')
Construct Python bytes containing the raw data bytes in the array.
Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be
produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order
unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.
This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.
Parameters
order [{‘C’, ‘F’, None}, optional] Order of the data for multidimensional arrays: C, Fortran,
or the same as for the original array.
Returns
s [bytes] Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')

>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

method

1.6. Standard array subclasses 175

NumPy Reference, Release 1.18.1

chararray.translate(self, table, deletechars=None)

For each element in self, return a copy of the string where all characters occurring in the optional argument
deletechars are removed, and the remaining characters have been mapped through the given translation
table.
See also:
char.translate
method
chararray.transpose(*axes)
Returns a view of the array with axes transposed.
For a 1-D array this has no effect, as a transposed vector is simply the same vector. To convert a 1-
D array into a 2D column vector, an additional dimension must be added. np.atleast2d(a).T achieves
this, as does a[:, np.newaxis]. For a 2-D array, this is a standard matrix transpose. For an n-D array, if
axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided
and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape =
(i[n-1], i[n-2], ... i[1], i[0]).
Parameters
axes [None, tuple of ints, or n ints]
• None or no argument: reverses the order of the axes.
• tuple of ints: i in the j-th place in the tuple means a’s i-th axis becomes a.transpose()’s
j-th axis.
• n ints: same as an n-tuple of the same ints (this form is intended simply as a “conve-
nience” alternative to the tuple form)
Returns
out [ndarray] View of a, with axes suitably permuted.
See also:

ndarray.T Array property returning the array transposed.

ndarray.reshape Give a new shape to an array without changing its data.

Examples

>>> a = np.array([[1, 2], [3, 4]])

>>> a
array([[1, 2],
[3, 4]])
>>> a.transpose()
array([[1, 3],
[2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
[2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
[2, 4]])

method

176 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

chararray.upper(self )
Return an array with the elements of self converted to uppercase.
See also:
char.upper
method
chararray.view(dtype=None, type=None)
New view of array with the same data.
Parameters
dtype [data-type or ndarray sub-class, optional] Data-type descriptor of the returned view,
e.g., float32 or int16. The default, None, results in the view having the same data-type as
a. This argument can also be specified as an ndarray sub-class, which then specifies the
type of the returned object (this is equivalent to setting the type parameter).
type [Python type, optional] Type of the returned view, e.g., ndarray or matrix. Again, the
default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory
with a different data-type. This can cause a reinterpretation of the bytes of memory.
a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance
of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinter-
pretation of the memory.
For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the pre-
vious dtype (for example, converting a regular array to a structured array), then the behavior of the view
cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on
exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a
slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print(type(y))
<class 'numpy.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
[3, 4]], dtype=int8)
(continues on next page)

1.6. Standard array subclasses 177

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> xv.mean(0)
array([2., 3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> x
array([(1, 20), (3, 4)], dtype=[('a', 'i1'), ('b', 'i1')])

Using a view to convert an array to a recarray:

>>> z = x.view(np.recarray)
>>> z.a
array([1, 3], dtype=int8)

Views share data:

>>> x[0] = (9, 10)

>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices,
transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)

>>> y = x[:, 0:2]
>>> y
array([[1, 2],
[4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
...
ValueError: To change to a dtype of a different size, the array must be C-
˓→contiguous

>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
[(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])

method
chararray.zfill(self, width)
Return the numeric string left-filled with zeros in a string of length width.
See also:
char.zfill
numpy.core.defchararray.array(obj, itemsize=None, copy=True, unicode=None, order=None)
Create a chararray.

Note: This class is provided for numarray backward-compatibility. New code (not concerned with numarray
compatibility) should use arrays of type string_ or unicode_ and use the free functions in numpy.char
for fast vectorized string operations instead.

Versus a regular NumPy array of type str or unicode, this class adds the following functionality:

178 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

1) values automatically have whitespace removed from the end when indexed
2) comparison operators automatically remove whitespace from the end when comparing values
3) vectorized string operations are provided as methods (e.g. str.endswith) and infix operators (e.g. +, *,
%)

Parameters
obj [array of str or unicode-like]
itemsize [int, optional] itemsize is the number of characters per scalar in the resulting array. If
itemsize is None, and obj is an object array or a Python list, the itemsize will be automatically
determined. If itemsize is provided and obj is of type str or unicode, then the obj string will
be chunked into itemsize pieces.
copy [bool, optional] If true (default), then the object is copied. Otherwise, a copy will only
be made if __array__ returns a copy, if obj is a nested sequence, or if a copy is needed to
satisfy any of the other requirements (itemsize, unicode, order, etc.).
unicode [bool, optional] When true, the resulting chararray can contain Unicode characters,
when false only 8-bit characters. If unicode is None and obj is one of the following:
• a chararray,
• an ndarray of type str or unicode
• a Python str or unicode object,
then the unicode setting of the output array will be automatically determined.
order [{‘C’, ‘F’, ‘A’}, optional] Specify the order of the array. If order is ‘C’ (default), then the
array will be in C-contiguous order (last-index varies the fastest). If order is ‘F’, then the
returned array will be in Fortran-contiguous order (first-index varies the fastest). If order
is ‘A’, then the returned array may be in any order (either C-, Fortran-contiguous, or even
discontiguous).

Another difference with the standard ndarray of str data-type is that the chararray inherits the feature introduced by
Numarray that white-space at the end of any element in the array will be ignored on item retrieval and comparison
operations.

1.6.5 Record arrays (numpy.rec)

See also:
Creating record arrays (numpy.rec), Data type routines, Data type objects (dtype).
NumPy provides the recarray class which allows accessing the fields of a structured array as attributes, and a
corresponding scalar data type object record.

recarray Construct an ndarray that allows field access using at-

tributes.
record A data-type scalar that allows field access as attribute
lookup.

class numpy.recarray
Construct an ndarray that allows field access using attributes.
Arrays may have a data-types containing fields, analogous to columns in a spread sheet. An example is [(x,

1.6. Standard array subclasses 179

NumPy Reference, Release 1.18.1

int), (y, float)], where each entry in the array is a pair of (int, float). Normally, these attributes
are accessed using dictionary lookups such as arr['x'] and arr['y']. Record arrays allow the fields to be
accessed as members of the array, using arr.x and arr.y.
Parameters
shape [tuple] Shape of output array.
dtype [data-type, optional] The desired data-type. By default, the data-type is determined from
formats, names, titles, aligned and byteorder.
formats [list of data-types, optional] A list containing the data-types for the different columns,
e.g. ['i4', 'f8', 'i4']. formats does not support the new convention of using types
directly, i.e. (int, float, int). Note that formats must be a list, not a tuple. Given
that formats is somewhat limited, we recommend specifying dtype instead.
names [tuple of str, optional] The name of each column, e.g. ('x', 'y', 'z').
buf [buffer, optional] By default, a new array is created of the given shape and data-type. If
buf is specified and is an object exposing the buffer interface, the array will use the memory
from the existing buffer. In this case, the offset and strides keywords are available.
Returns
rec [recarray] Empty array of the given shape and type.
Other Parameters
titles [tuple of str, optional] Aliases for column names. For example, if names
were ('x', 'y', 'z') and titles is ('x_coordinate', 'y_coordinate',
'z_coordinate'), then arr['x'] is equivalent to both arr.x and arr.
x_coordinate.
byteorder [{‘<’, ‘>’, ‘=’}, optional] Byte-order for all fields.
aligned [bool, optional] Align the fields in memory as the C-compiler would.
strides [tuple of ints, optional] Buffer (buf ) is interpreted according to these strides (strides
define how many bytes each array element, row, column, etc. occupy in memory).
offset [int, optional] Start reading buffer (buf ) from this offset onwards.
order [{‘C’, ‘F’}, optional] Row-major (C-style) or column-major (Fortran-style) order.
See also:

rec.fromrecords Construct a record array from data.

record fundamental data-type for recarray.
format_parser determine a data-type from formats, names, titles.

Notes

This constructor can be compared to empty: it creates a new record array but does not fill it with data. To create
a record array from data, use one of the following methods:
1. Create a standard ndarray and convert it to a record array, using arr.view(np.recarray)
2. Use the buf keyword.
3. Use np.rec.fromrecords.

180 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

Create an array with two fields, x and y:

>>> x = np.array([(1.0, 2), (3.0, 4)], dtype=[('x', '<f8'), ('y', '<i8')])

>>> x
array([(1., 2), (3., 4)], dtype=[('x', '<f8'), ('y', '<i8')])

>>> x['x']
array([1., 3.])

View the array as a record array:

>>> x = x.view(np.recarray)

>>> x.x
array([1., 3.])

>>> x.y
array([2, 4])

Create a new, empty record array:

>>> np.recarray((2,),
... dtype=[('x', int), ('y', float), ('z', int)])
rec.array([(-1073741821, 1.2249118382103472e-301, 24547520),
(3471280, 1.2134086255804012e-316, 0)],
dtype=[('x', '<i4'), ('y', '<f8'), ('z', '<i4')])

Attributes
T The transposed array.
base Base object if memory is from some other object.
ctypes An object to simplify the interaction of the array with the ctypes module.
data Python buffer object pointing to the start of the array’s data.
dtype Data-type of the array’s elements.
flags Information about the memory layout of the array.
flat A 1-D iterator over the array.
imag The imaginary part of the array.
itemsize Length of one array element in bytes.
nbytes Total bytes consumed by the elements of the array.
ndim Number of array dimensions.
real The real part of the array.
shape Tuple of array dimensions.
size Number of elements in the array.
strides Tuple of bytes to step in each dimension when traversing an array.

1.6. Standard array subclasses 181

NumPy Reference, Release 1.18.1

Methods

all([axis, out, keepdims]) Returns True if all elements evaluate to True.

any([axis, out, keepdims]) Returns True if any of the elements of a evaluate to
True.
argmax([axis, out]) Return indices of the maximum values along the
given axis.
argmin([axis, out]) Return indices of the minimum values along the
given axis of a.
argpartition(kth[, axis, kind, order]) Returns the indices that would partition this array.
argsort([axis, kind, order]) Returns the indices that would sort this array.
astype(dtype[, order, casting, subok, copy]) Copy of the array, cast to a specified type.
byteswap([inplace]) Swap the bytes of the array elements
choose(choices[, out, mode]) Use an index array to construct a new array from a
set of choices.
clip([min, max, out]) Return an array whose values are limited to [min,
max].
compress(condition[, axis, out]) Return selected slices of this array along given axis.
conj() Complex-conjugate all elements.
conjugate() Return the complex conjugate, element-wise.
copy([order]) Return a copy of the array.
cumprod([axis, dtype, out]) Return the cumulative product of the elements along
the given axis.
cumsum([axis, dtype, out]) Return the cumulative sum of the elements along the
given axis.
diagonal([offset, axis1, axis2]) Return specified diagonals.
dot(b[, out]) Dot product of two arrays.
dump(file) Dump a pickle of the array to the specified file.
dumps() Returns the pickle of the array as a string.
fill(value) Fill the array with a scalar value.
flatten([order]) Return a copy of the array collapsed into one dimen-
sion.
getfield(dtype[, offset]) Returns a field of the given array as a certain type.
item(*args) Copy an element of an array to a standard Python
scalar and return it.
itemset(*args) Insert scalar into an array (scalar is cast to array’s
dtype, if possible)
max([axis, out, keepdims, initial, where]) Return the maximum along a given axis.
mean([axis, dtype, out, keepdims]) Returns the average of the array elements along
given axis.
min([axis, out, keepdims, initial, where]) Return the minimum along a given axis.
newbyteorder([new_order]) Return the array with the same data viewed with a
different byte order.
nonzero() Return the indices of the elements that are non-zero.
partition(kth[, axis, kind, order]) Rearranges the elements in the array in such a way
that the value of the element in kth position is in the
position it would be in a sorted array.
prod([axis, dtype, out, keepdims, initial, . . . ]) Return the product of the array elements over the
given axis
ptp([axis, out, keepdims]) Peak to peak (maximum - minimum) value along a
given axis.
Continued on next page

182 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Table 43 – continued from previous page

put(indices, values[, mode]) Set a.flat[n] = values[n] for all n in in-
dices.
ravel([order]) Return a flattened array.
repeat(repeats[, axis]) Repeat elements of an array.
reshape(shape[, order]) Returns an array containing the same data with a new
shape.
resize(new_shape[, refcheck]) Change shape and size of array in-place.
round([decimals, out]) Return a with each element rounded to the given
number of decimals.
searchsorted(v[, side, sorter]) Find indices where elements of v should be inserted
in a to maintain order.
setfield(val, dtype[, offset]) Put a value into a specified place in a field defined by
a data-type.
setflags([write, align, uic]) Set array flags WRITEABLE, ALIGNED, (WRITE-
BACKIFCOPY and UPDATEIFCOPY), respec-
tively.
sort([axis, kind, order]) Sort an array in-place.
squeeze([axis]) Remove single-dimensional entries from the shape
of a.
std([axis, dtype, out, ddof, keepdims]) Returns the standard deviation of the array elements
along given axis.
sum([axis, dtype, out, keepdims, initial, where]) Return the sum of the array elements over the given
axis.
swapaxes(axis1, axis2) Return a view of the array with axis1 and axis2 in-
terchanged.
take(indices[, axis, out, mode]) Return an array formed from the elements of a at the
given indices.
tobytes([order]) Construct Python bytes containing the raw data bytes
in the array.
tofile(fid[, sep, format]) Write array to a file as text or binary (default).
tolist() Return the array as an a.ndim-levels deep nested
list of Python scalars.
tostring([order]) Construct Python bytes containing the raw data bytes
in the array.
trace([offset, axis1, axis2, dtype, out]) Return the sum along diagonals of the array.
transpose(*axes) Returns a view of the array with axes transposed.
var([axis, dtype, out, ddof, keepdims]) Returns the variance of the array elements, along
given axis.
view([dtype, type]) New view of array with the same data.

method
recarray.all(axis=None, out=None, keepdims=False)
Returns True if all elements evaluate to True.
Refer to numpy.all for full documentation.
See also:

numpy.all equivalent function

method

1.6. Standard array subclasses 183

NumPy Reference, Release 1.18.1

recarray.any(axis=None, out=None, keepdims=False)

Returns True if any of the elements of a evaluate to True.
Refer to numpy.any for full documentation.
See also:

numpy.any equivalent function

method
recarray.argmax(axis=None, out=None)
Return indices of the maximum values along the given axis.
Refer to numpy.argmax for full documentation.
See also:

numpy.argmax equivalent function

method
recarray.argmin(axis=None, out=None)
Return indices of the minimum values along the given axis of a.
Refer to numpy.argmin for detailed documentation.
See also:

numpy.argmin equivalent function

method
recarray.argpartition(kth, axis=-1, kind='introselect', order=None)
Returns the indices that would partition this array.
Refer to numpy.argpartition for full documentation.
New in version 1.8.0.
See also:

numpy.argpartition equivalent function

method
recarray.argsort(axis=-1, kind=None, order=None)
Returns the indices that would sort this array.
Refer to numpy.argsort for full documentation.
See also:

numpy.argsort equivalent function

method
recarray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
Copy of the array, cast to a specified type.
Parameters
dtype [str or dtype] Typecode or data-type to which the array is cast.

184 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout order of the result. ‘C’
means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran
contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements
appear in memory as possible. Default is ‘K’.
casting [{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional] Controls what kind of data
casting may occur. Defaults to ‘unsafe’ for backwards compatibility.
• ‘no’ means the data types should not be cast at all.
• ‘equiv’ means only byte-order changes are allowed.
• ‘safe’ means only casts which can preserve values are allowed.
• ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are
allowed.
• ‘unsafe’ means any data conversions may be done.
subok [bool, optional] If True, then sub-classes will be passed-through (default), otherwise
the returned array will be forced to be a base-class array.
copy [bool, optional] By default, astype always returns a newly allocated array. If this is
set to false, and the dtype, order, and subok requirements are satisfied, the input array is
returned instead of a copy.
Returns
arr_t [ndarray] Unless copy is False and the other conditions for returning the input array
are satisfied (see description for copy input parameter), arr_t is a new array of the same
shape as the input array, with dtype, order given by dtype, order.
Raises
ComplexWarning When casting from complex to float or int. To avoid this, one should use
a.real.astype(t).

Notes

Changed in version 1.17.0: Casting between a simple data type and a structured one is possible only for
“unsafe” casting. Casting to multiple fields is allowed, but casting from multiple fields is not.
Changed in version 1.9.0: Casting from numeric to string types in ‘safe’ casting mode requires that the
string dtype length is long enough to store the max integer/float value converted.

Examples

>>> x = np.array([1, 2, 2.5])

>>> x
array([1. , 2. , 2.5])

>>> x.astype(int)
array([1, 2, 2])

method
recarray.byteswap(inplace=False)
Swap the bytes of the array elements

1.6. Standard array subclasses 185

NumPy Reference, Release 1.18.1

Toggle between low-endian and big-endian data representation by returning a byteswapped array, option-
ally swapped in-place. Arrays of byte-strings are not swapped. The real and imaginary parts of a complex
number are swapped individually.
Parameters
inplace [bool, optional] If True, swap bytes in-place, default is False.
Returns
out [ndarray] The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)

>>> list(map(hex, A))
['0x1', '0x100', '0x2233']
>>> A.byteswap(inplace=True)
array([ 256, 1, 13090], dtype=int16)
>>> list(map(hex, A))
['0x100', '0x1', '0x3322']

Arrays of byte-strings are not swapped

>>> A = np.array([b'ceg', b'fac'])

>>> A.byteswap()
array([b'ceg', b'fac'], dtype='|S3')

A.newbyteorder().byteswap() produces an array with the same values but different repre-
sentation in memory

>>> A = np.array([1, 2, 3])

>>> A.view(np.uint8)
array([1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0,
0, 0], dtype=uint8)
>>> A.newbyteorder().byteswap(inplace=True)
array([1, 2, 3])
>>> A.view(np.uint8)
array([0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0,
0, 3], dtype=uint8)

method
recarray.choose(choices, out=None, mode='raise')
Use an index array to construct a new array from a set of choices.
Refer to numpy.choose for full documentation.
See also:

numpy.choose equivalent function

method
recarray.clip(min=None, max=None, out=None, **kwargs)
Return an array whose values are limited to [min, max]. One of max or min must be given.
Refer to numpy.clip for full documentation.

186 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

See also:

numpy.clip equivalent function

method
recarray.compress(condition, axis=None, out=None)
Return selected slices of this array along given axis.
Refer to numpy.compress for full documentation.
See also:

numpy.compress equivalent function

method
recarray.conj()
Complex-conjugate all elements.
Refer to numpy.conjugate for full documentation.
See also:

numpy.conjugate equivalent function

method
recarray.conjugate()
Return the complex conjugate, element-wise.
Refer to numpy.conjugate for full documentation.
See also:

numpy.conjugate equivalent function

method
recarray.copy(order='C')
Return a copy of the array.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout of the copy. ‘C’ means
C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’
means match the layout of a as closely as possible. (Note that this function and numpy.
copy are very similar, but have different default values for their order= arguments.)
See also:
numpy.copy, numpy.copyto

1.6. Standard array subclasses 187

NumPy Reference, Release 1.18.1

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
[0, 0, 0]])

>>> y
array([[1, 2, 3],
[4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True

method
recarray.cumprod(axis=None, dtype=None, out=None)
Return the cumulative product of the elements along the given axis.
Refer to numpy.cumprod for full documentation.
See also:

numpy.cumprod equivalent function

method
recarray.cumsum(axis=None, dtype=None, out=None)
Return the cumulative sum of the elements along the given axis.
Refer to numpy.cumsum for full documentation.
See also:

numpy.cumsum equivalent function

method
recarray.diagonal(offset=0, axis1=0, axis2=1)
Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in
previous NumPy versions. In a future version the read-only restriction will be removed.
Refer to numpy.diagonal for full documentation.
See also:

numpy.diagonal equivalent function

method
recarray.dot(b, out=None)
Dot product of two arrays.
Refer to numpy.dot for full documentation.

188 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

See also:

numpy.dot equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[2., 2.],
[2., 2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[8., 8.],
[8., 8.]])

method
recarray.dump(file)
Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.
Parameters
file [str or Path] A string naming the dump file.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
method
recarray.dumps()
Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an
array.
Parameters
None
method
recarray.fill(value)
Fill the array with a scalar value.
Parameters
value [scalar] All elements of a will be assigned this value.

Examples

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

>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([1., 1.])

1.6. Standard array subclasses 189

NumPy Reference, Release 1.18.1

method
recarray.flatten(order='C')
Return a copy of the array collapsed into one dimension.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] ‘C’ means to flatten in row-major (C-style) order. ‘F’
means to flatten in column-major (Fortran- style) order. ‘A’ means to flatten in column-
major order if a is Fortran contiguous in memory, row-major order otherwise. ‘K’ means
to flatten a in the order the elements occur in memory. The default is ‘C’.
Returns
y [ndarray] A copy of the input array, flattened to one dimension.
See also:

ravel Return a flattened array.

flat A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])

>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])

method
recarray.getfield(dtype, offset=0)
Returns a field of the given array as a certain type.
A field is a view of the array data with a given data-type. The values in the view are determined by the
given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits
in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with
a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.
Parameters
dtype [str or dtype] The data type of the view. The dtype size of the view can not be larger
than that of the array itself.
offset [int] Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[1.+1.j, 0.+0.j],
[0.+0.j, 2.+4.j]])
>>> x.getfield(np.float64)
array([[1., 0.],
[0., 2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

190 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> x.getfield(np.float64, offset=8)

array([[1., 0.],
[0., 4.]])

method
recarray.item(*args)
Copy an element of an array to a standard Python scalar and return it.
Parameters
*args [Arguments (variable number and type)]
• none: in this case, the method only works for arrays with one element (a.size == 1),
which element is copied into a standard Python scalar object and returned.
• int_type: this argument is interpreted as a flat index into the array, specifying which
element to copy and return.
• tuple of int_types: functions as does a single int_type argument, except that the argu-
ment is interpreted as an nd-index into the array.
Returns
z [Standard Python scalar object] A copy of the specified element of the array as a suitable
Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is
no available Python scalar that would not lose information. Void arrays return a buffer object for item(),
unless fields are defined, in which case a tuple is returned.
item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned.
This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the
array using Python’s optimized math.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

method
recarray.itemset(*args)
Insert scalar into an array (scalar is cast to array’s dtype, if possible)

1.6. Standard array subclasses 191

NumPy Reference, Release 1.18.1

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is
equivalent to but faster than a[args] = item. The item should be a scalar value and args must select
a single item in the array a.
Parameters
*args [Arguments] If one argument: a scalar, only used in case a is of size 1. If two ar-
guments: the last argument is the value to be set and must be a scalar, the first argument
specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular
location in an ndarray, if you must do this. However, generally this is discouraged: among other
problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a
loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[2, 2, 6],
[1, 0, 6],
[1, 0, 9]])

method
recarray.max(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
Return the maximum along a given axis.
Refer to numpy.amax for full documentation.
See also:

numpy.amax equivalent function

method
recarray.mean(axis=None, dtype=None, out=None, keepdims=False)
Returns the average of the array elements along given axis.
Refer to numpy.mean for full documentation.
See also:

numpy.mean equivalent function

method

192 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

recarray.min(axis=None, out=None, keepdims=False, initial=<no value>, where=True)

Return the minimum along a given axis.
Refer to numpy.amin for full documentation.
See also:

numpy.amin equivalent function

method
recarray.newbyteorder(new_order='S')
Return the array with the same data viewed with a different byte order.
Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.
Parameters
new_order [string, optional] Byte order to force; a value from the byte order specifications
below. 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 default value (‘S’) results in swapping the current byte order. The code does a case-
insensitive check on the first letter of new_order for the alternatives above. For example,
any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns
new_arr [array] New array object with the dtype reflecting given change to the byte order.
method
recarray.nonzero()
Return the indices of the elements that are non-zero.
Refer to numpy.nonzero for full documentation.
See also:

numpy.nonzero equivalent function

method
recarray.partition(kth, axis=-1, kind='introselect', order=None)
Rearranges the elements in the array in such a way that the value of the element in kth position is in the
position it would be in a sorted array. All elements smaller than the kth element are moved before this
element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is
undefined.
New in version 1.8.0.
Parameters

1.6. Standard array subclasses 193

NumPy Reference, Release 1.18.1

kth [int or sequence of ints] Element index to partition by. The kth element value will be
in its final sorted position and all smaller elements will be moved before it and all equal
or greater elements behind it. The order of all elements in the partitions is undefined. If
provided with a sequence of kth it will partition all elements indexed by kth of them into
their sorted position at once.
axis [int, optional] Axis along which to sort. Default is -1, which means sort along the last
axis.
kind [{‘introselect’}, optional] Selection algorithm. Default is ‘introselect’.
order [str or list of str, optional] When a is an array with fields defined, this argument
specifies which fields to compare first, second, etc. A single field can be specified as a
string, and not all fields need to be specified, but unspecified fields will still be used, in the
order in which they come up in the dtype, to break ties.
See also:

numpy.partition Return a parititioned copy of an array.

argpartition Indirect partition.
sort Full sort.

Notes

See np.partition for notes on the different algorithms.

Examples

>>> a = np.array([3, 4, 2, 1])

>>> a.partition(3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))

>>> a
array([1, 2, 3, 4])

method
recarray.prod(axis=None, dtype=None, out=None, keepdims=False, initial=1, where=True)
Return the product of the array elements over the given axis
Refer to numpy.prod for full documentation.
See also:

numpy.prod equivalent function

method
recarray.ptp(axis=None, out=None, keepdims=False)
Peak to peak (maximum - minimum) value along a given axis.
Refer to numpy.ptp for full documentation.
See also:

194 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

numpy.ptp equivalent function

method
recarray.put(indices, values, mode='raise')
Set a.flat[n] = values[n] for all n in indices.
Refer to numpy.put for full documentation.
See also:

numpy.put equivalent function

method
recarray.ravel([order ])
Return a flattened array.
Refer to numpy.ravel for full documentation.
See also:

numpy.ravel equivalent function

ndarray.flat a flat iterator on the array.

method
recarray.repeat(repeats, axis=None)
Repeat elements of an array.
Refer to numpy.repeat for full documentation.
See also:

numpy.repeat equivalent function

method
recarray.reshape(shape, order='C')
Returns an array containing the same data with a new shape.
Refer to numpy.reshape for full documentation.
See also:

numpy.reshape equivalent function

Notes

Unlike the free function numpy.reshape, this method on ndarray allows the elements of the shape
parameter to be passed in as separate arguments. For example, a.reshape(10, 11) is equivalent to
a.reshape((10, 11)).
method
recarray.resize(new_shape, refcheck=True)
Change shape and size of array in-place.
Parameters
new_shape [tuple of ints, or n ints] Shape of resized array.

1.6. Standard array subclasses 195

NumPy Reference, Release 1.18.1

refcheck [bool, optional] If False, reference count will not be checked. Default is True.
Returns
None
Raises
ValueError If a does not own its own data or references or views to it exist, and the data
memory must be changed. PyPy only: will always raise if the data memory must be
changed, since there is no reliable way to determine if references or views to it exist.
SystemError If the order keyword argument is specified. This behaviour is a bug in NumPy.
See also:

resize Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.
The purpose of the reference count check is to make sure you do not use this array as a buffer for another
Python object and then reallocate the memory. However, reference counts can increase in other ways so if
you are sure that you have not shared the memory for this array with another Python object, then you may
safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and re-
shaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')

>>> a.resize((2, 1))
>>> a
array([[0],
[1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')

>>> a.resize((2, 1))
>>> a
array([[0],
[2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])

>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
[3, 0, 0]])

Referencing an array prevents resizing. . .

196 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that references or is referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)

>>> a
array([[0]])
>>> c
array([[0]])

method
recarray.round(decimals=0, out=None)
Return a with each element rounded to the given number of decimals.
Refer to numpy.around for full documentation.
See also:

numpy.around equivalent function

method
recarray.searchsorted(v, side='left', sorter=None)
Find indices where elements of v should be inserted in a to maintain order.
For full documentation, see numpy.searchsorted
See also:

numpy.searchsorted equivalent function

method
recarray.setfield(val, dtype, offset=0)
Put a value into a specified place in a field defined by a data-type.
Place val into a’s field defined by dtype and beginning offset bytes into the field.
Parameters
val [object] Value to be placed in field.
dtype [dtype object] Data-type of the field in which to place val.
offset [int, optional] The number of bytes into the field at which to place val.
Returns
None
See also:
getfield

1.6. Standard array subclasses 197

NumPy Reference, Release 1.18.1

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
[3, 3, 3],
[3, 3, 3]], dtype=int32)
>>> x
array([[1.0e+000, 1.5e-323, 1.5e-323],
[1.5e-323, 1.0e+000, 1.5e-323],
[1.5e-323, 1.5e-323, 1.0e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]])

method
recarray.setflags(write=None, align=None, uic=None)
Set array flags WRITEABLE, ALIGNED, (WRITEBACKIFCOPY and UPDATEIFCOPY), respectively.
These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The
ALIGNED flag can only be set to True if the data is actually aligned according to the type. The WRITE-
BACKIFCOPY and (deprecated) UPDATEIFCOPY flags can never be set to True. The flag WRITEABLE
can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a
writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done
without copying memory.)
Parameters
write [bool, optional] Describes whether or not a can be written to.
align [bool, optional] Describes whether or not a is aligned properly for its type.
uic [bool, optional] Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There
are 7 Boolean flags in use, only four of which can be changed by the user: WRITEBACKIFCOPY, UP-
DATEIFCOPY, WRITEABLE, and ALIGNED.
WRITEABLE (W) the data area can be written to;
ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the com-
piler);
UPDATEIFCOPY (U) (deprecated), replaced by WRITEBACKIFCOPY;
WRITEBACKIFCOPY (X) this array is a copy of some other array (referenced by .base). When the C-API
function PyArray_ResolveWritebackIfCopy is called, the base array will be updated with the contents of
this array.
All flags can be accessed using the single (upper case) letter as well as the full name.

198 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> y = np.array([[3, 1, 7],

... [2, 0, 0],
... [8, 5, 9]])
>>> y
array([[3, 1, 7],
[2, 0, 0],
[8, 5, 9]])
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
OWNDATA : True
WRITEABLE : True
ALIGNED : True
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
C_CONTIGUOUS : True
F_CONTIGUOUS : False
OWNDATA : True
WRITEABLE : False
ALIGNED : False
WRITEBACKIFCOPY : False
UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: cannot set WRITEBACKIFCOPY flag to True

method
recarray.sort(axis=-1, kind=None, order=None)
Sort an array in-place. Refer to numpy.sort for full documentation.
Parameters
axis [int, optional] Axis along which to sort. Default is -1, which means sort along the last
axis.
kind [{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] Sorting algorithm. The de-
fault is ‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers
and, in general, the actual implementation will vary with datatype. The ‘mergesort’ option
is retained for backwards compatibility.
Changed in version 1.15.0.: The ‘stable’ option was added.
order [str or list of str, optional] When a is an array with fields defined, this argument
specifies which fields to compare first, second, etc. A single field can be specified as a
string, and not all fields need be specified, but unspecified fields will still be used, in the
order in which they come up in the dtype, to break ties.
See also:

numpy.sort Return a sorted copy of an array.

numpy.argsort Indirect sort.
numpy.lexsort Indirect stable sort on multiple keys.

1.6. Standard array subclasses 199

NumPy Reference, Release 1.18.1

numpy.searchsorted Find elements in sorted array.

numpy.partition Partial sort.

Notes

See numpy.sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])

>>> a.sort(axis=1)
>>> a
array([[1, 4],
[1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
[1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])

>>> a.sort(order='y')
>>> a
array([(b'c', 1), (b'a', 2)],
dtype=[('x', 'S1'), ('y', '<i8')])

method
recarray.squeeze(axis=None)
Remove single-dimensional entries from the shape of a.
Refer to numpy.squeeze for full documentation.
See also:

numpy.squeeze equivalent function

method
recarray.std(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
Returns the standard deviation of the array elements along given axis.
Refer to numpy.std for full documentation.
See also:

numpy.std equivalent function

method
recarray.sum(axis=None, dtype=None, out=None, keepdims=False, initial=0, where=True)
Return the sum of the array elements over the given axis.
Refer to numpy.sum for full documentation.
See also:

200 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

numpy.sum equivalent function

method
recarray.swapaxes(axis1, axis2)
Return a view of the array with axis1 and axis2 interchanged.
Refer to numpy.swapaxes for full documentation.
See also:

numpy.swapaxes equivalent function

method
recarray.take(indices, axis=None, out=None, mode='raise')
Return an array formed from the elements of a at the given indices.
Refer to numpy.take for full documentation.
See also:

numpy.take equivalent function

method
recarray.tobytes(order='C')
Construct Python bytes containing the raw data bytes in the array.
Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be
produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order
unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.
New in version 1.9.0.
Parameters
order [{‘C’, ‘F’, None}, optional] Order of the data for multidimensional arrays: C, Fortran,
or the same as for the original array.
Returns
s [bytes] Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')

>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

method
recarray.tofile(fid, sep="", format="%s")
Write array to a file as text or binary (default).
Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can
be recovered using the function fromfile().

1.6. Standard array subclasses 201

NumPy Reference, Release 1.18.1

Parameters
fid [file or str or Path] An open file object, or a string containing a filename.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
sep [str] Separator between array items for text output. If “” (empty), a binary file is written,
equivalent to file.write(a.tobytes()).
format [str] Format string for text file output. Each entry in the array is formatted to text by
first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision
is lost, so this method is not a good choice for files intended to archive data or transport data between
machines with different endianness. Some of these problems can be overcome by outputting the data as
text files, at the expense of speed and file size.
When fid is a file object, array contents are directly written to the file, bypassing the file object’s write
method. As a result, tofile cannot be used with files objects supporting compression (e.g., GzipFile) or
file-like objects that do not support fileno() (e.g., BytesIO).
method
recarray.tolist()
Return the array as an a.ndim-levels deep nested list of Python scalars.
Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible
builtin Python type, via the item function.
If a.ndim is 0, then since the depth of the nested list is 0, it will not be a list at all, but a simple Python
scalar.
Parameters
none
Returns
y [object, or list of object, or list of list of object, or . . . ] The possibly nested list of array
elements.

Notes

The array may be recreated via a = np.array(a.tolist()), although this may sometimes lose
precision.

Examples

For a 1D array, a.tolist() is almost the same as list(a), except that tolist changes numpy
scalars to Python scalars:

>>> a = np.uint32([1, 2])

>>> a_list = list(a)
>>> a_list
[1, 2]
>>> type(a_list[0])
(continues on next page)

202 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

(continued from previous page)

<class 'numpy.uint32'>
>>> a_tolist = a.tolist()
>>> a_tolist
[1, 2]
>>> type(a_tolist[0])
<class 'int'>

Additionally, for a 2D array, tolist applies recursively:

>>> a = np.array([[1, 2], [3, 4]])

>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]

The base case for this recursion is a 0D array:

>>> a = np.array(1)
>>> list(a)
Traceback (most recent call last):
...
TypeError: iteration over a 0-d array
>>> a.tolist()
1

method
recarray.tostring(order='C')
Construct Python bytes containing the raw data bytes in the array.
Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be
produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order
unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.
This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.
Parameters
order [{‘C’, ‘F’, None}, optional] Order of the data for multidimensional arrays: C, Fortran,
or the same as for the original array.
Returns
s [bytes] Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')

>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

method

1.6. Standard array subclasses 203

NumPy Reference, Release 1.18.1

recarray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.
Refer to numpy.trace for full documentation.
See also:

numpy.trace equivalent function

method
recarray.transpose(*axes)
Returns a view of the array with axes transposed.
For a 1-D array this has no effect, as a transposed vector is simply the same vector. To convert a 1-
D array into a 2D column vector, an additional dimension must be added. np.atleast2d(a).T achieves
this, as does a[:, np.newaxis]. For a 2-D array, this is a standard matrix transpose. For an n-D array, if
axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided
and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape =
(i[n-1], i[n-2], ... i[1], i[0]).
Parameters
axes [None, tuple of ints, or n ints]
• None or no argument: reverses the order of the axes.
• tuple of ints: i in the j-th place in the tuple means a’s i-th axis becomes a.transpose()’s
j-th axis.
• n ints: same as an n-tuple of the same ints (this form is intended simply as a “conve-
nience” alternative to the tuple form)
Returns
out [ndarray] View of a, with axes suitably permuted.
See also:

ndarray.T Array property returning the array transposed.

ndarray.reshape Give a new shape to an array without changing its data.

Examples

>>> a = np.array([[1, 2], [3, 4]])

>>> a
array([[1, 2],
[3, 4]])
>>> a.transpose()
array([[1, 3],
[2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
[2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
[2, 4]])

method

204 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

recarray.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False)

Returns the variance of the array elements, along given axis.
Refer to numpy.var for full documentation.
See also:

numpy.var equivalent function

method
recarray.view(dtype=None, type=None)
New view of array with the same data.
Parameters
dtype [data-type or ndarray sub-class, optional] Data-type descriptor of the returned view,
e.g., float32 or int16. The default, None, results in the view having the same data-type as
a. This argument can also be specified as an ndarray sub-class, which then specifies the
type of the returned object (this is equivalent to setting the type parameter).
type [Python type, optional] Type of the returned view, e.g., ndarray or matrix. Again, the
default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory
with a different data-type. This can cause a reinterpretation of the bytes of memory.
a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance
of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinter-
pretation of the memory.
For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the pre-
vious dtype (for example, converting a regular array to a structured array), then the behavior of the view
cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on
exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a
slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)

>>> y
matrix([[513]], dtype=int16)
>>> print(type(y))
<class 'numpy.matrix'>

Creating a view on a structured array so it can be used in calculations

1.6. Standard array subclasses 205

NumPy Reference, Release 1.18.1

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])

>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
[3, 4]], dtype=int8)
>>> xv.mean(0)
array([2., 3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> x
array([(1, 20), (3, 4)], dtype=[('a', 'i1'), ('b', 'i1')])

Using a view to convert an array to a recarray:

>>> z = x.view(np.recarray)
>>> z.a
array([1, 3], dtype=int8)

Views share data:

>>> x[0] = (9, 10)

>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices,
transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)

>>> y = x[:, 0:2]
>>> y
array([[1, 2],
[4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
...
ValueError: To change to a dtype of a different size, the array must be C-
˓→contiguous

>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
[(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])

field

class numpy.record
A data-type scalar that allows field access as attribute lookup.
Attributes
T transpose
base base object
data pointer to start of data
dtype dtype object

206 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

flags integer value of flags

flat a 1-d view of scalar
imag imaginary part of scalar
itemsize length of one element in bytes
nbytes length of item in bytes
ndim number of array dimensions
real real part of scalar
shape tuple of array dimensions
size number of elements in the gentype
strides tuple of bytes steps in each dimension

Methods

all() Not implemented (virtual attribute)

any() Not implemented (virtual attribute)
argmax() Not implemented (virtual attribute)
argmin() Not implemented (virtual attribute)
argsort() Not implemented (virtual attribute)
astype() Not implemented (virtual attribute)
byteswap() Not implemented (virtual attribute)
choose() Not implemented (virtual attribute)
clip() Not implemented (virtual attribute)
compress() Not implemented (virtual attribute)
conjugate() Not implemented (virtual attribute)
copy() Not implemented (virtual attribute)
cumprod() Not implemented (virtual attribute)
cumsum() Not implemented (virtual attribute)
diagonal() Not implemented (virtual attribute)
dump() Not implemented (virtual attribute)
dumps() Not implemented (virtual attribute)
fill() Not implemented (virtual attribute)
flatten() Not implemented (virtual attribute)
getfield() Not implemented (virtual attribute)
item() Not implemented (virtual attribute)
itemset() Not implemented (virtual attribute)
max() Not implemented (virtual attribute)
mean() Not implemented (virtual attribute)
min() Not implemented (virtual attribute)
newbyteorder([new_order]) Return a new dtype with a different byte order.
nonzero() Not implemented (virtual attribute)
pprint(self) Pretty-print all fields.
prod() Not implemented (virtual attribute)
ptp() Not implemented (virtual attribute)
put() Not implemented (virtual attribute)
ravel() Not implemented (virtual attribute)
repeat() Not implemented (virtual attribute)
Continued on next page

1.6. Standard array subclasses 207

NumPy Reference, Release 1.18.1

Table 44 – continued from previous page

reshape() Not implemented (virtual attribute)
resize() Not implemented (virtual attribute)
round() Not implemented (virtual attribute)
searchsorted() Not implemented (virtual attribute)
setfield() Not implemented (virtual attribute)
setflags() Not implemented (virtual attribute)
sort() Not implemented (virtual attribute)
squeeze() Not implemented (virtual attribute)
std() Not implemented (virtual attribute)
sum() Not implemented (virtual attribute)
swapaxes() Not implemented (virtual attribute)
take() Not implemented (virtual attribute)
tofile() Not implemented (virtual attribute)
tolist() Not implemented (virtual attribute)
tostring() Not implemented (virtual attribute)
trace() Not implemented (virtual attribute)
transpose() Not implemented (virtual attribute)
var() Not implemented (virtual attribute)
view() Not implemented (virtual attribute)

method
record.all()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.any()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.argmax()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.argmin()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.

208 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

method
record.argsort()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.astype()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.byteswap()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.choose()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.clip()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.compress()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.conjugate()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.

1.6. Standard array subclasses 209

NumPy Reference, Release 1.18.1

See also the corresponding attribute of the derived class of interest.

method
record.copy()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.cumprod()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.cumsum()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.diagonal()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.dump()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.dumps()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.fill()
Not implemented (virtual attribute)

210 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.flatten()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.getfield()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.item()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.itemset()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.max()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.mean()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method

1.6. Standard array subclasses 211

NumPy Reference, Release 1.18.1

record.min()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.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.
The new_order code can be any from the following:
• ‘S’ - swap dtype from current to opposite endian
• {‘<’, ‘L’} - little endian
• {‘>’, ‘B’} - big endian
• {‘=’, ‘N’} - native order
• {‘|’, ‘I’} - ignore (no change to byte order)

Parameters
new_order [str, optional] Byte order to force; a value from the byte order specifications
above. The default value (‘S’) results in swapping the current byte order. The code does
a case-insensitive check on the first letter of new_order for the alternatives above. For
example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns
new_dtype [dtype] New dtype object with the given change to the byte order.

method
record.nonzero()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.pprint(self )
Pretty-print all fields.
method
record.prod()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method

212 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

record.ptp()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.put()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.ravel()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.repeat()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.reshape()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.resize()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.round()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.

1.6. Standard array subclasses 213

NumPy Reference, Release 1.18.1

method
record.searchsorted()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.setfield()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.setflags()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.sort()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.squeeze()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.std()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.sum()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.

214 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

See also the corresponding attribute of the derived class of interest.

method
record.swapaxes()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.take()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.tofile()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.tolist()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.tostring()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.trace()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.transpose()
Not implemented (virtual attribute)

1.6. Standard array subclasses 215

NumPy Reference, Release 1.18.1

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.var()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.
method
record.view()
Not implemented (virtual attribute)
Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the
attributes of the ndarray class so as to provide a uniform API.
See also the corresponding attribute of the derived class of interest.

conj
tobytes

1.6.6 Masked arrays (numpy.ma)

See also:
Masked arrays

1.6.7 Standard container class

For backward compatibility and as a standard “container “class, the UserArray from Numeric has been brought over to
NumPy and named numpy.lib.user_array.container The container class is a Python class whose self.array
attribute is an ndarray. Multiple inheritance is probably easier with numpy.lib.user_array.container than with the
ndarray itself and so it is included by default. It is not documented here beyond mentioning its existence because you
are encouraged to use the ndarray class directly if you can.

numpy.lib.user_array.container(data[, Standard container-class for easy multiple-inheritance.

. . . ])

class numpy.lib.user_array.container(data, dtype=None, copy=True)

Standard container-class for easy multiple-inheritance.

216 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Methods

copy
tostring
byteswap
astype

1.6.8 Array Iterators

Iterators are a powerful concept for array processing. Essentially, iterators implement a generalized for-loop. If myiter
is an iterator object, then the Python code:

for val in myiter:

...
some code involving val
...

calls val = next(myiter) repeatedly until StopIteration is raised by the iterator. There are several ways
to iterate over an array that may be useful: default iteration, flat iteration, and 𝑁 -dimensional enumeration.

Default iteration

The default iterator of an ndarray object is the default Python iterator of a sequence type. Thus, when the array object
itself is used as an iterator. The default behavior is equivalent to:

for i in range(arr.shape[0]):
val = arr[i]

This default iterator selects a sub-array of dimension 𝑁 − 1 from the array. This can be a useful construct for defining
recursive algorithms. To loop over the entire array requires 𝑁 for-loops.

>>> a = arange(24).reshape(3,2,4)+10
>>> for val in a:
... print 'item:', val
item: [[10 11 12 13]
[14 15 16 17]]
item: [[18 19 20 21]
[22 23 24 25]]
item: [[26 27 28 29]
[30 31 32 33]]

Flat iteration

ndarray.flat A 1-D iterator over the array.

As mentioned previously, the flat attribute of ndarray objects returns an iterator that will cycle over the entire array in
C-style contiguous order.
>>> for i, val in enumerate(a.flat):
... if i%5 == 0: print i, val
(continues on next page)

1.6. Standard array subclasses 217

NumPy Reference, Release 1.18.1

(continued from previous page)

0 10
5 15
10 20
15 25
20 30

Here, I’ve used the built-in enumerate iterator to return the iterator index as well as the value.

N-dimensional enumeration

ndenumerate(arr) Multidimensional index iterator.

class numpy.ndenumerate(arr)
Multidimensional index iterator.
Return an iterator yielding pairs of array coordinates and values.
Parameters
arr [ndarray] Input array.
See also:
ndindex, flatiter

Examples

>>> a = np.array([[1, 2], [3, 4]])

>>> for index, x in np.ndenumerate(a):
... print(index, x)
(0, 0) 1
(0, 1) 2
(1, 0) 3
(1, 1) 4

Methods

next(self) Standard iterator method, returns the index tuple and

array value.

method
ndenumerate.next(self )
Standard iterator method, returns the index tuple and array value.
Returns
coords [tuple of ints] The indices of the current iteration.
val [scalar] The array element of the current iteration.
Sometimes it may be useful to get the N-dimensional index while iterating. The ndenumerate iterator can achieve this.

218 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> for i, val in ndenumerate(a):

... if sum(i)%5 == 0: print i, val
(0, 0, 0) 10
(1, 1, 3) 25
(2, 0, 3) 29
(2, 1, 2) 32

Iterator for broadcasting

broadcast Produce an object that mimics broadcasting.

class numpy.broadcast
Produce an object that mimics broadcasting.
Parameters
in1, in2, . . . [array_like] Input parameters.
Returns
b [broadcast object] Broadcast the input parameters against one another, and return an object
that encapsulates the result. Amongst others, it has shape and nd properties, and may be
used as an iterator.
See also:
broadcast_arrays, broadcast_to

Examples

Manually adding two vectors, using broadcasting:

>>> x = np.array([[1], [2], [3]])

>>> y = np.array([4, 5, 6])
>>> b = np.broadcast(x, y)

>>> out = np.empty(b.shape)

>>> out.flat = [u+v for (u,v) in b]
>>> out
array([[5., 6., 7.],
[6., 7., 8.],
[7., 8., 9.]])

Compare against built-in broadcasting:

>>> x + y
array([[5, 6, 7],
[6, 7, 8],
[7, 8, 9]])

Attributes
index current index in broadcasted result
iters tuple of iterators along self’s “components.”

1.6. Standard array subclasses 219

NumPy Reference, Release 1.18.1

nd Number of dimensions of broadcasted result.

ndim Number of dimensions of broadcasted result.
numiter Number of iterators possessed by the broadcasted result.
shape Shape of broadcasted result.
size Total size of broadcasted result.

Methods

reset() Reset the broadcasted result’s iterator(s).

method
broadcast.reset()
Reset the broadcasted result’s iterator(s).
Parameters
None
Returns
None

Examples

>>> x = np.array([1, 2, 3])

>>> y = np.array([[4], [5], [6]])
>>> b = np.broadcast(x, y)
>>> b.index
0
>>> next(b), next(b), next(b)
((1, 4), (2, 4), (3, 4))
>>> b.index
3
>>> b.reset()
>>> b.index
0

The general concept of broadcasting is also available from Python using the broadcast iterator. This object takes
𝑁 objects as inputs and returns an iterator that returns tuples providing each of the input sequence elements in the
broadcasted result.

>>> for val in broadcast([[1,0],[2,3]],[0,1]):

... print val
(1, 0)
(0, 1)
(2, 0)
(3, 1)

220 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

1.7 Masked arrays

Masked arrays are arrays that may have missing or invalid entries. The numpy.ma module provides a nearly work-
alike replacement for numpy that supports data arrays with masks.

1.7.1 The numpy.ma module

Rationale

Masked arrays are arrays that may have missing or invalid entries. The numpy.ma module provides a nearly work-
alike replacement for numpy that supports data arrays with masks.

What is a masked array?

In many circumstances, datasets can be incomplete or tainted by the presence of invalid data. For example, a sensor
may have failed to record a data, or recorded an invalid value. The numpy.ma module provides a convenient way to
address this issue, by introducing masked arrays.
A masked array is the combination of a standard numpy.ndarray and a mask. A mask is either nomask, indicating
that no value of the associated array is invalid, or an array of booleans that determines for each element of the associated
array whether the value is valid or not. When an element of the mask is False, the corresponding element of the
associated array is valid and is said to be unmasked. When an element of the mask is True, the corresponding element
of the associated array is said to be masked (invalid).
The package ensures that masked entries are not used in computations.
As an illustration, let’s consider the following dataset:

>>> import numpy as np

>>> import numpy.ma as ma
>>> x = np.array([1, 2, 3, -1, 5])

We wish to mark the fourth entry as invalid. The easiest is to create a masked array:

>>> mx = ma.masked_array(x, mask=[0, 0, 0, 1, 0])

We can now compute the mean of the dataset, without taking the invalid data into account:

>>> mx.mean()
2.75

The numpy.ma module

The main feature of the numpy.ma module is the MaskedArray class, which is a subclass of numpy.ndarray.
The class, its attributes and methods are described in more details in the MaskedArray class section.
The numpy.ma module can be used as an addition to numpy:

>>> import numpy as np

>>> import numpy.ma as ma

To create an array with the second element invalid, we would do:

1.7. Masked arrays 221

NumPy Reference, Release 1.18.1

>>> y = ma.array([1, 2, 3], mask = [0, 1, 0])

To create a masked array where all values close to 1.e20 are invalid, we would do:

>>> z = ma.masked_values([1.0, 1.e20, 3.0, 4.0], 1.e20)

For a complete discussion of creation methods for masked arrays please see section Constructing masked arrays.

1.7.2 Using numpy.ma

Constructing masked arrays

There are several ways to construct a masked array.

• A first possibility is to directly invoke the MaskedArray class.
• A second possibility is to use the two masked array constructors, array and masked_array.

array(data[, dtype, copy, order, mask, . . . ]) An array class with possibly masked values.
masked_array alias of numpy.ma.core.MaskedArray

numpy.ma.array(data, dtype=None, copy=False, order=None, mask=False, fill_value=None,

keep_mask=True, hard_mask=False, shrink=True, subok=True, ndmin=0)
An array class with possibly masked values.
Masked values of True exclude the corresponding element from any computation.
Construction:

x = MaskedArray(data, mask=nomask, dtype=None, copy=False, subok=True,

ndmin=0, fill_value=None, keep_mask=True, hard_mask=None,
shrink=True, order=None)

Parameters
data [array_like] Input data.
mask [sequence, optional] Mask. Must be convertible to an array of booleans with the same
shape as data. True indicates a masked (i.e. invalid) data.
dtype [dtype, optional] Data type of the output. If dtype is None, the type of the data argu-
ment (data.dtype) is used. If dtype is not None and different from data.dtype, a
copy is performed.
copy [bool, optional] Whether to copy the input data (True), or to use a reference instead.
Default is False.
subok [bool, optional] Whether to return a subclass of MaskedArray if possible (True)
or a plain MaskedArray. Default is True.
ndmin [int, optional] Minimum number of dimensions. Default is 0.
fill_value [scalar, optional] Value used to fill in the masked values when necessary. If None,
a default based on the data-type is used.
keep_mask [bool, optional] Whether to combine mask with the mask of the input data, if
any (True), or to use only mask for the output (False). Default is True.

222 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

hard_mask [bool, optional] Whether to use a hard mask or not. With a hard mask, masked
values cannot be unmasked. Default is False.
shrink [bool, optional] Whether to force compression of an empty mask. Default is True.
order [{‘C’, ‘F’, ‘A’}, optional] Specify the order of the array. If order is ‘C’, then the
array will be in C-contiguous order (last-index varies the fastest). If order is ‘F’, then the
returned array will be in Fortran-contiguous order (first-index varies the fastest). If order
is ‘A’ (default), then the returned array may be in any order (either C-, Fortran-contiguous,
or even discontiguous), unless a copy is required, in which case it will be C-contiguous.

numpy.ma.masked_array
alias of numpy.ma.core.MaskedArray
• A third option is to take the view of an existing array. In that case, the mask of the view is set to nomask if the
array has no named fields, or an array of boolean with the same structure as the array otherwise.

>>> x = np.array([1, 2, 3])

>>> x.view(ma.MaskedArray)
masked_array(data=[1, 2, 3],
mask=False,
fill_value=999999)
>>> x = np.array([(1, 1.), (2, 2.)], dtype=[('a',int), ('b', float)])
>>> x.view(ma.MaskedArray)
masked_array(data=[(1, 1.0), (2, 2.0)],
mask=[(False, False), (False, False)],
fill_value=(999999, 1.e+20),
dtype=[('a', '<i8'), ('b', '<f8')])

• Yet another possibility is to use any of the following functions:

asarray(a[, dtype, order]) Convert the input to a masked array of the given data-
type.
asanyarray(a[, dtype]) Convert the input to a masked array, conserving sub-
classes.
fix_invalid(a[, mask, copy, fill_value]) Return input with invalid data masked and replaced
by a fill value.
masked_equal(x, value[, copy]) Mask an array where equal to a given value.
masked_greater(x, value[, copy]) Mask an array where greater than a given value.
masked_greater_equal(x, value[, copy]) Mask an array where greater than or equal to a given
value.
masked_inside(x, v1, v2[, copy]) Mask an array inside a given interval.
masked_invalid(a[, copy]) Mask an array where invalid values occur (NaNs or
infs).
masked_less(x, value[, copy]) Mask an array where less than a given value.
masked_less_equal(x, value[, copy]) Mask an array where less than or equal to a given
value.
masked_not_equal(x, value[, copy]) Mask an array where not equal to a given value.
masked_object(x, value[, copy, shrink]) Mask the array x where the data are exactly equal to
value.
masked_outside(x, v1, v2[, copy]) Mask an array outside a given interval.
masked_values(x, value[, rtol, atol, copy, . . . ]) Mask using floating point equality.
masked_where(condition, a[, copy]) Mask an array where a condition is met.

numpy.ma.asarray(a, dtype=None, order=None)

1.7. Masked arrays 223

NumPy Reference, Release 1.18.1

Convert the input to a masked array of the given data-type.

No copy is performed if the input is already an ndarray. If a is a subclass of MaskedArray, a base class
MaskedArray is returned.
Parameters
a [array_like] Input data, in any form that can be converted to a masked array. This includes
lists, lists of tuples, tuples, tuples of tuples, tuples of lists, ndarrays and masked arrays.
dtype [dtype, optional] By default, the data-type is inferred from the input data.
order [{‘C’, ‘F’}, optional] Whether to use row-major (‘C’) or column-major (‘FOR-
TRAN’) memory representation. Default is ‘C’.
Returns
out [MaskedArray] Masked array interpretation of a.
See also:

asanyarray Similar to asarray, but conserves subclasses.

Examples

>>> x = np.arange(10.).reshape(2, 5)
>>> x
array([[0., 1., 2., 3., 4.],
[5., 6., 7., 8., 9.]])
>>> np.ma.asarray(x)
masked_array(
data=[[0., 1., 2., 3., 4.],
[5., 6., 7., 8., 9.]],
mask=False,
fill_value=1e+20)
>>> type(np.ma.asarray(x))
<class 'numpy.ma.core.MaskedArray'>

numpy.ma.asanyarray(a, dtype=None)
Convert the input to a masked array, conserving subclasses.
If a is a subclass of MaskedArray, its class is conserved. No copy is performed if the input is already
an ndarray.
Parameters
a [array_like] Input data, in any form that can be converted to an array.
dtype [dtype, optional] By default, the data-type is inferred from the input data.
order [{‘C’, ‘F’}, optional] Whether to use row-major (‘C’) or column-major (‘FOR-
TRAN’) memory representation. Default is ‘C’.
Returns
out [MaskedArray] MaskedArray interpretation of a.
See also:

asarray Similar to asanyarray, but does not conserve subclass.

224 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = np.arange(10.).reshape(2, 5)
>>> x
array([[0., 1., 2., 3., 4.],
[5., 6., 7., 8., 9.]])
>>> np.ma.asanyarray(x)
masked_array(
data=[[0., 1., 2., 3., 4.],
[5., 6., 7., 8., 9.]],
mask=False,
fill_value=1e+20)
>>> type(np.ma.asanyarray(x))
<class 'numpy.ma.core.MaskedArray'>

numpy.ma.fix_invalid(a, mask=False, copy=True, fill_value=None)

Return input with invalid data masked and replaced by a fill value.
Invalid data means values of nan, inf, etc.
Parameters
a [array_like] Input array, a (subclass of) ndarray.
mask [sequence, optional] Mask. Must be convertible to an array of booleans with the same
shape as data. True indicates a masked (i.e. invalid) data.
copy [bool, optional] Whether to use a copy of a (True) or to fix a in place (False). Default
is True.
fill_value [scalar, optional] Value used for fixing invalid data. Default is None, in which
case the a.fill_value is used.
Returns
b [MaskedArray] The input array with invalid entries fixed.

Notes

A copy is performed by default.

Examples

>>> x = np.ma.array([1., -1, np.nan, np.inf], mask=[1] + [0]*3)

>>> x
masked_array(data=[--, -1.0, nan, inf],
mask=[ True, False, False, False],
fill_value=1e+20)
>>> np.ma.fix_invalid(x)
masked_array(data=[--, -1.0, --, --],
mask=[ True, False, True, True],
fill_value=1e+20)

>>> fixed = np.ma.fix_invalid(x)

>>> fixed.data
array([ 1.e+00, -1.e+00, 1.e+20, 1.e+20])
(continues on next page)

1.7. Masked arrays 225

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> x.data
array([ 1., -1., nan, inf])

numpy.ma.masked_equal(x, value, copy=True)

Mask an array where equal to a given value.
This function is a shortcut to masked_where, with condition = (x == value). For floating point arrays,
consider using masked_values(x, value).
See also:

masked_where Mask where a condition is met.

masked_values Mask using floating point equality.

Examples

>>> import numpy.ma as ma

>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_equal(a, 2)
masked_array(data=[0, 1, --, 3],
mask=[False, False, True, False],
fill_value=2)

numpy.ma.masked_greater(x, value, copy=True)

Mask an array where greater than a given value.
This function is a shortcut to masked_where, with condition = (x > value).
See also:

masked_where Mask where a condition is met.

Examples

>>> import numpy.ma as ma

>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_greater(a, 2)
masked_array(data=[0, 1, 2, --],
mask=[False, False, False, True],
fill_value=999999)

numpy.ma.masked_greater_equal(x, value, copy=True)

Mask an array where greater than or equal to a given value.
This function is a shortcut to masked_where, with condition = (x >= value).
See also:

masked_where Mask where a condition is met.

226 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> import numpy.ma as ma

>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_greater_equal(a, 2)
masked_array(data=[0, 1, --, --],
mask=[False, False, True, True],
fill_value=999999)

numpy.ma.masked_inside(x, v1, v2, copy=True)

Mask an array inside a given interval.
Shortcut to masked_where, where condition is True for x inside the interval [v1,v2] (v1 <= x <= v2).
The boundaries v1 and v2 can be given in either order.
See also:

masked_where Mask where a condition is met.

Notes

The array x is prefilled with its filling value.

Examples

>>> import numpy.ma as ma

>>> x = [0.31, 1.2, 0.01, 0.2, -0.4, -1.1]
>>> ma.masked_inside(x, -0.3, 0.3)
masked_array(data=[0.31, 1.2, --, --, -0.4, -1.1],
mask=[False, False, True, True, False, False],
fill_value=1e+20)

The order of v1 and v2 doesn’t matter.

>>> ma.masked_inside(x, 0.3, -0.3)

masked_array(data=[0.31, 1.2, --, --, -0.4, -1.1],
mask=[False, False, True, True, False, False],
fill_value=1e+20)

numpy.ma.masked_invalid(a, copy=True)
Mask an array where invalid values occur (NaNs or infs).
This function is a shortcut to masked_where, with condition = ~(np.isfinite(a)). Any pre-existing mask
is conserved. Only applies to arrays with a dtype where NaNs or infs make sense (i.e. floating point types),
but accepts any array_like object.
See also:

masked_where Mask where a condition is met.

1.7. Masked arrays 227

NumPy Reference, Release 1.18.1

Examples

>>> import numpy.ma as ma

>>> a = np.arange(5, dtype=float)
>>> a[2] = np.NaN
>>> a[3] = np.PINF
>>> a
array([ 0., 1., nan, inf, 4.])
>>> ma.masked_invalid(a)
masked_array(data=[0.0, 1.0, --, --, 4.0],
mask=[False, False, True, True, False],
fill_value=1e+20)

numpy.ma.masked_less(x, value, copy=True)

Mask an array where less than a given value.
This function is a shortcut to masked_where, with condition = (x < value).
See also:

masked_where Mask where a condition is met.

Examples

>>> import numpy.ma as ma

>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_less(a, 2)
masked_array(data=[--, --, 2, 3],
mask=[ True, True, False, False],
fill_value=999999)

numpy.ma.masked_less_equal(x, value, copy=True)

Mask an array where less than or equal to a given value.
This function is a shortcut to masked_where, with condition = (x <= value).
See also:

masked_where Mask where a condition is met.

Examples

>>> import numpy.ma as ma

>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_less_equal(a, 2)
masked_array(data=[--, --, --, 3],
mask=[ True, True, True, False],
fill_value=999999)

numpy.ma.masked_not_equal(x, value, copy=True)

Mask an array where not equal to a given value.

228 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

This function is a shortcut to masked_where, with condition = (x != value).

See also:

masked_where Mask where a condition is met.

Examples

>>> import numpy.ma as ma

>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_not_equal(a, 2)
masked_array(data=[--, --, 2, --],
mask=[ True, True, False, True],
fill_value=999999)

numpy.ma.masked_object(x, value, copy=True, shrink=True)

Mask the array x where the data are exactly equal to value.
This function is similar to masked_values, but only suitable for object arrays: for floating point, use
masked_values instead.
Parameters
x [array_like] Array to mask
value [object] Comparison value
copy [{True, False}, optional] Whether to return a copy of x.
shrink [{True, False}, optional] Whether to collapse a mask full of False to nomask
Returns
result [MaskedArray] The result of masking x where equal to value.
See also:

masked_where Mask where a condition is met.

masked_equal Mask where equal to a given value (integers).
masked_values Mask using floating point equality.

Examples

>>> import numpy.ma as ma

>>> food = np.array(['green_eggs', 'ham'], dtype=object)
>>> # don't eat spoiled food
>>> eat = ma.masked_object(food, 'green_eggs')
>>> eat
masked_array(data=[--, 'ham'],
mask=[ True, False],
fill_value='green_eggs',
dtype=object)
>>> # plain ol` ham is boring
>>> fresh_food = np.array(['cheese', 'ham', 'pineapple'], dtype=object)
>>> eat = ma.masked_object(fresh_food, 'green_eggs')
(continues on next page)

1.7. Masked arrays 229

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> eat
masked_array(data=['cheese', 'ham', 'pineapple'],
mask=False,
fill_value='green_eggs',
dtype=object)

Note that mask is set to nomask if possible.

>>> eat
masked_array(data=['cheese', 'ham', 'pineapple'],
mask=False,
fill_value='green_eggs',
dtype=object)

numpy.ma.masked_outside(x, v1, v2, copy=True)

Mask an array outside a given interval.
Shortcut to masked_where, where condition is True for x outside the interval [v1,v2] (x < v1)|(x > v2).
The boundaries v1 and v2 can be given in either order.
See also:

masked_where Mask where a condition is met.

Notes

The array x is prefilled with its filling value.

Examples

>>> import numpy.ma as ma

>>> x = [0.31, 1.2, 0.01, 0.2, -0.4, -1.1]
>>> ma.masked_outside(x, -0.3, 0.3)
masked_array(data=[--, --, 0.01, 0.2, --, --],
mask=[ True, True, False, False, True, True],
fill_value=1e+20)

The order of v1 and v2 doesn’t matter.

>>> ma.masked_outside(x, 0.3, -0.3)
masked_array(data=[--, --, 0.01, 0.2, --, --],
mask=[ True, True, False, False, True, True],
fill_value=1e+20)

numpy.ma.masked_values(x, value, rtol=1e-05, atol=1e-08, copy=True, shrink=True)

Mask using floating point equality.
Return a MaskedArray, masked where the data in array x are approximately equal to value, determined
using isclose. The default tolerances for masked_values are the same as those for isclose.
For integer types, exact equality is used, in the same way as masked_equal.
The fill_value is set to value and the mask is set to nomask if possible.
Parameters
x [array_like] Array to mask.

230 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

value [float] Masking value.

rtol, atol [float, optional] Tolerance parameters passed on to isclose
copy [bool, optional] Whether to return a copy of x.
shrink [bool, optional] Whether to collapse a mask full of False to nomask.
Returns
result [MaskedArray] The result of masking x where approximately equal to value.
See also:

masked_where Mask where a condition is met.

masked_equal Mask where equal to a given value (integers).

Examples

>>> import numpy.ma as ma

>>> x = np.array([1, 1.1, 2, 1.1, 3])
>>> ma.masked_values(x, 1.1)
masked_array(data=[1.0, --, 2.0, --, 3.0],
mask=[False, True, False, True, False],
fill_value=1.1)

Note that mask is set to nomask if possible.

>>> ma.masked_values(x, 1.5)

masked_array(data=[1. , 1.1, 2. , 1.1, 3. ],
mask=False,
fill_value=1.5)

For integers, the fill value will be different in general to the result of masked_equal.

>>> x = np.arange(5)
>>> x
array([0, 1, 2, 3, 4])
>>> ma.masked_values(x, 2)
masked_array(data=[0, 1, --, 3, 4],
mask=[False, False, True, False, False],
fill_value=2)
>>> ma.masked_equal(x, 2)
masked_array(data=[0, 1, --, 3, 4],
mask=[False, False, True, False, False],
fill_value=2)

numpy.ma.masked_where(condition, a, copy=True)
Mask an array where a condition is met.
Return a as an array masked where condition is True. Any masked values of a or condition are also masked
in the output.
Parameters
condition [array_like] Masking condition. When condition tests floating point values for
equality, consider using masked_values instead.
a [array_like] Array to mask.

1.7. Masked arrays 231

NumPy Reference, Release 1.18.1

copy [bool] If True (default) make a copy of a in the result. If False modify a in place and
return a view.
Returns
result [MaskedArray] The result of masking a where condition is True.
See also:

masked_values Mask using floating point equality.

masked_equal Mask where equal to a given value.
masked_not_equal Mask where not equal to a given value.
masked_less_equal Mask where less than or equal to a given value.
masked_greater_equal Mask where greater than or equal to a given value.
masked_less Mask where less than a given value.
masked_greater Mask where greater than a given value.
masked_inside Mask inside a given interval.
masked_outside Mask outside a given interval.
masked_invalid Mask invalid values (NaNs or infs).

Examples

>>> import numpy.ma as ma

>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_where(a <= 2, a)
masked_array(data=[--, --, --, 3],
mask=[ True, True, True, False],
fill_value=999999)

Mask array b conditional on a.

>>> b = ['a', 'b', 'c', 'd']

>>> ma.masked_where(a == 2, b)
masked_array(data=['a', 'b', --, 'd'],
mask=[False, False, True, False],
fill_value='N/A',
dtype='<U1')

Effect of the copy argument.

>>> c = ma.masked_where(a <= 2, a)

>>> c
masked_array(data=[--, --, --, 3],
mask=[ True, True, True, False],
fill_value=999999)
>>> c[0] = 99
>>> c
masked_array(data=[99, --, --, 3],
mask=[False, True, True, False],
(continues on next page)

232 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

(continued from previous page)

fill_value=999999)
>>> a
array([0, 1, 2, 3])
>>> c = ma.masked_where(a <= 2, a, copy=False)
>>> c[0] = 99
>>> c
masked_array(data=[99, --, --, 3],
mask=[False, True, True, False],
fill_value=999999)
>>> a
array([99, 1, 2, 3])

When condition or a contain masked values.

>>> a = np.arange(4)
>>> a = ma.masked_where(a == 2, a)
>>> a
masked_array(data=[0, 1, --, 3],
mask=[False, False, True, False],
fill_value=999999)
>>> b = np.arange(4)
>>> b = ma.masked_where(b == 0, b)
>>> b
masked_array(data=[--, 1, 2, 3],
mask=[ True, False, False, False],
fill_value=999999)
>>> ma.masked_where(a == 3, b)
masked_array(data=[--, 1, --, --],
mask=[ True, False, True, True],
fill_value=999999)

Accessing the data

The underlying data of a masked array can be accessed in several ways:

• through the data attribute. The output is a view of the array as a numpy.ndarray or one of its subclasses,
depending on the type of the underlying data at the masked array creation.
• through the __array__ method. The output is then a numpy.ndarray.
• by directly taking a view of the masked array as a numpy.ndarray or one of its subclass (which is actually
what using the data attribute does).
• by using the getdata function.
None of these methods is completely satisfactory if some entries have been marked as invalid. As a general rule,
where a representation of the array is required without any masked entries, it is recommended to fill the array with the
filled method.

1.7. Masked arrays 233

NumPy Reference, Release 1.18.1

Accessing the mask

The mask of a masked array is accessible through its mask attribute. We must keep in mind that a True entry in the
mask indicates an invalid data.
Another possibility is to use the getmask and getmaskarray functions. getmask(x) outputs the mask of x if
x is a masked array, and the special value nomask otherwise. getmaskarray(x) outputs the mask of x if x is a
masked array. If x has no invalid entry or is not a masked array, the function outputs a boolean array of False with
as many elements as x.

Accessing only the valid entries

To retrieve only the valid entries, we can use the inverse of the mask as an index. The inverse of the mask can be
calculated with the numpy.logical_not function or simply with the ~ operator:
>>> x = ma.array([[1, 2], [3, 4]], mask=[[0, 1], [1, 0]])
>>> x[~x.mask]
masked_array(data=[1, 4],
mask=[False, False],
fill_value=999999)

Another way to retrieve the valid data is to use the compressed method, which returns a one-dimensional ndarray
(or one of its subclasses, depending on the value of the baseclass attribute):
>>> x.compressed()
array([1, 4])

Note that the output of compressed is always 1D.

Modifying the mask

Masking an entry

The recommended way to mark one or several specific entries of a masked array as invalid is to assign the special
value masked to them:
>>> x = ma.array([1, 2, 3])
>>> x[0] = ma.masked
>>> x
masked_array(data=[--, 2, 3],
mask=[ True, False, False],
fill_value=999999)
>>> y = ma.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> y[(0, 1, 2), (1, 2, 0)] = ma.masked
>>> y
masked_array(
data=[[1, --, 3],
[4, 5, --],
[--, 8, 9]],
mask=[[False, True, False],
[False, False, True],
[ True, False, False]],
fill_value=999999)
>>> z = ma.array([1, 2, 3, 4])
>>> z[:-2] = ma.masked
(continues on next page)

234 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

(continued from previous page)

>>> z
masked_array(data=[--, --, 3, 4],
mask=[ True, True, False, False],
fill_value=999999)

A second possibility is to modify the mask directly, but this usage is discouraged.

Note: When creating a new masked array with a simple, non-structured datatype, the mask is initially set to the
special value nomask, that corresponds roughly to the boolean False. Trying to set an element of nomask will fail
with a TypeError exception, as a boolean does not support item assignment.

All the entries of an array can be masked at once by assigning True to the mask:
>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x.mask = True
>>> x
masked_array(data=[--, --, --],
mask=[ True, True, True],
fill_value=999999,
dtype=int64)

Finally, specific entries can be masked and/or unmasked by assigning to the mask a sequence of booleans:
>>> x = ma.array([1, 2, 3])
>>> x.mask = [0, 1, 0]
>>> x
masked_array(data=[1, --, 3],
mask=[False, True, False],
fill_value=999999)

Unmasking an entry

To unmask one or several specific entries, we can just assign one or several new valid values to them:
>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x[-1] = 5
>>> x
masked_array(data=[1, 2, 5],
mask=[False, False, False],
fill_value=999999)

Note: Unmasking an entry by direct assignment will silently fail if the masked array has a hard mask, as shown by
the hardmask attribute. This feature was introduced to prevent overwriting the mask. To force the unmasking of an
entry where the array has a hard mask, the mask must first to be softened using the soften_mask method before
the allocation. It can be re-hardened with harden_mask:
>>> x = ma.array([1, 2, 3], mask=[0, 0, 1], hard_mask=True)
>>> x
(continues on next page)

1.7. Masked arrays 235

NumPy Reference, Release 1.18.1

(continued from previous page)

masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x[-1] = 5
>>> x
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x.soften_mask()
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x[-1] = 5
>>> x
masked_array(data=[1, 2, 5],
mask=[False, False, False],
fill_value=999999)
>>> x.harden_mask()
masked_array(data=[1, 2, 5],
mask=[False, False, False],
fill_value=999999)

To unmask all masked entries of a masked array (provided the mask isn’t a hard mask), the simplest solution is to
assign the constant nomask to the mask:

>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])

>>> x
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x.mask = ma.nomask
>>> x
masked_array(data=[1, 2, 3],
mask=[False, False, False],
fill_value=999999)

Indexing and slicing

As a MaskedArray is a subclass of numpy.ndarray, it inherits its mechanisms for indexing and slicing.
When accessing a single entry of a masked array with no named fields, the output is either a scalar (if the corresponding
entry of the mask is False) or the special value masked (if the corresponding entry of the mask is True):

>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])

>>> x[0]
1
>>> x[-1]
masked
>>> x[-1] is ma.masked
True

If the masked array has named fields, accessing a single entry returns a numpy.void object if none of the fields are
masked, or a 0d masked array with the same dtype as the initial array if at least one of the fields is masked.

236 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

>>> y = ma.masked_array([(1,2), (3, 4)],

... mask=[(0, 0), (0, 1)],
... dtype=[('a', int), ('b', int)])
>>> y[0]
(1, 2)
>>> y[-1]
(3, --)

When accessing a slice, the output is a masked array whose data attribute is a view of the original data, and whose
mask is either nomask (if there was no invalid entries in the original array) or a view of the corresponding slice of
the original mask. The view is required to ensure propagation of any modification of the mask to the original.

>>> x = ma.array([1, 2, 3, 4, 5], mask=[0, 1, 0, 0, 1])

>>> mx = x[:3]
>>> mx
masked_array(data=[1, --, 3],
mask=[False, True, False],
fill_value=999999)
>>> mx[1] = -1
>>> mx
masked_array(data=[1, -1, 3],
mask=[False, False, False],
fill_value=999999)
>>> x.mask
array([False, False, False, False, True])
>>> x.data
array([ 1, -1, 3, 4, 5])

Accessing a field of a masked array with structured datatype returns a MaskedArray.

Operations on masked arrays

Arithmetic and comparison operations are supported by masked arrays. As much as possible, invalid entries of a
masked array are not processed, meaning that the corresponding data entries should be the same before and after the
operation.

Warning: We need to stress that this behavior may not be systematic, that masked data may be affected by the
operation in some cases and therefore users should not rely on this data remaining unchanged.

The numpy.ma module comes with a specific implementation of most ufuncs. Unary and binary functions that have a
validity domain (such as log or divide) return the masked constant whenever the input is masked or falls outside
the validity domain:

>>> ma.log([-1, 0, 1, 2])

masked_array(data=[--, --, 0.0, 0.6931471805599453],
mask=[ True, True, False, False],
fill_value=1e+20)

Masked arrays also support standard numpy ufuncs. The output is then a masked array. The result of a unary ufunc is
masked wherever the input is masked. The result of a binary ufunc is masked wherever any of the input is masked. If
the ufunc also returns the optional context output (a 3-element tuple containing the name of the ufunc, its arguments
and its domain), the context is processed and entries of the output masked array are masked wherever the corresponding
input fall outside the validity domain:

1.7. Masked arrays 237

NumPy Reference, Release 1.18.1

>>> x = ma.array([-1, 1, 0, 2, 3], mask=[0, 0, 0, 0, 1])

>>> np.log(x)
masked_array(data=[--, 0.0, --, 0.6931471805599453, --],
mask=[ True, False, True, False, True],
fill_value=1e+20)

1.7.3 Examples

Data with a given value representing missing data

Let’s consider a list of elements, x, where values of -9999. represent missing data. We wish to compute the average
value of the data and the vector of anomalies (deviations from the average):

>>> import numpy.ma as ma

>>> x = [0.,1.,-9999.,3.,4.]
>>> mx = ma.masked_values (x, -9999.)
>>> print(mx.mean())
2.0
>>> print(mx - mx.mean())
[-2.0 -1.0 -- 1.0 2.0]
>>> print(mx.anom())
[-2.0 -1.0 -- 1.0 2.0]

Filling in the missing data

Suppose now that we wish to print that same data, but with the missing values replaced by the average value.

>>> print(mx.filled(mx.mean()))
[ 0. 1. 2. 3. 4.]

Numerical operations

Numerical operations can be easily performed without worrying about missing values, dividing by zero, square roots
of negative numbers, etc.:

>>> import numpy.ma as ma

>>> x = ma.array([1., -1., 3., 4., 5., 6.], mask=[0,0,0,0,1,0])
>>> y = ma.array([1., 2., 0., 4., 5., 6.], mask=[0,0,0,0,0,1])
>>> print(ma.sqrt(x/y))
[1.0 -- -- 1.0 -- --]

Four values of the output are invalid: the first one comes from taking the square root of a negative number, the second
from the division by zero, and the last two where the inputs were masked.

238 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Ignoring extreme values

Let’s consider an array d of floats between 0 and 1. We wish to compute the average of the values of d while ignoring
any data outside the range [0.2, 0.9]:

>>> d = np.linspace(0, 1, 20)

>>> print(d.mean() - ma.masked_outside(d, 0.2, 0.9).mean())
-0.05263157894736836

1.7.4 Constants of the numpy.ma module

In addition to the MaskedArray class, the numpy.ma module defines several constants.
numpy.ma.masked
The masked constant is a special case of MaskedArray, with a float datatype and a null shape. It is used to
test whether a specific entry of a masked array is masked, or to mask one or several entries of a masked array:

>>> x = ma.array([1, 2, 3], mask=[0, 1, 0])

>>> x[1] is ma.masked
True
>>> x[-1] = ma.masked
>>> x
masked_array(data = [1 -- --],
mask = [False True True],
fill_value = 999999)

numpy.ma.nomask
Value indicating that a masked array has no invalid entry. nomask is used internally to speed up computations
when the mask is not needed.
numpy.ma.masked_print_options
String used in lieu of missing data when a masked array is printed. By default, this string is '--'.

1.7.5 The MaskedArray class

class numpy.ma.MaskedArray
A subclass of ndarray designed to manipulate numerical arrays with missing data.
An instance of MaskedArray can be thought as the combination of several elements:
• The data, as a regular numpy.ndarray of any shape or datatype (the data).
• A boolean mask with the same shape as the data, where a True value indicates that the corresponding element
of the data is invalid. The special value nomask is also acceptable for arrays without named fields, and indicates
that no data is invalid.
• A fill_value, a value that may be used to replace the invalid entries in order to return a standard numpy.
ndarray.

1.7. Masked arrays 239

NumPy Reference, Release 1.18.1

Attributes and properties of masked arrays

See also:
Array Attributes
MaskedArray.data
Returns the underlying data, as a view of the masked array.
If the underlying data is a subclass of numpy.ndarray, it is returned as such.

>>> x = np.ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])

>>> x.data
matrix([[1, 2],
[3, 4]])

The type of the data can be accessed through the baseclass attribute.
MaskedArray.mask
Current mask.
MaskedArray.recordmask
Get or set the mask of the array if it has no named fields. For structured arrays, returns a ndarray of booleans
where entries are True if all the fields are masked, False otherwise:

>>> x = np.ma.array([(1, 1), (2, 2), (3, 3), (4, 4), (5, 5)],
... mask=[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
... dtype=[('a', int), ('b', int)])
>>> x.recordmask
array([False, False, True, False, False])

MaskedArray.fill_value
The filling value of the masked array is a scalar. When setting, None will set to a default based on the data type.

Examples

>>> for dt in [np.int32, np.int64, np.float64, np.complex128]:

... np.ma.array([0, 1], dtype=dt).get_fill_value()
...
999999
999999
1e+20
(1e+20+0j)

>>> x = np.ma.array([0, 1.], fill_value=-np.inf)

>>> x.fill_value
-inf
>>> x.fill_value = np.pi
>>> x.fill_value
3.1415926535897931 # may vary

Reset to default:

>>> x.fill_value = None

>>> x.fill_value
1e+20

240 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

MaskedArray.baseclass
Class of the underlying data (read-only).
MaskedArray.sharedmask
Share status of the mask (read-only).
MaskedArray.hardmask
Hardness of the mask
As MaskedArray is a subclass of ndarray, a masked array also inherits all the attributes and properties of a
ndarray instance.

MaskedArray.base Base object if memory is from some other object.

MaskedArray.ctypes An object to simplify the interaction of the array with
the ctypes module.
MaskedArray.dtype Data-type of the array’s elements.
MaskedArray.flags Information about the memory layout of the array.
MaskedArray.itemsize Length of one array element in bytes.
MaskedArray.nbytes Total bytes consumed by the elements of the array.
MaskedArray.ndim Number of array dimensions.
MaskedArray.shape Tuple of array dimensions.
MaskedArray.size Number of elements in the array.
MaskedArray.strides Tuple of bytes to step in each dimension when travers-
ing an array.
MaskedArray.imag The imaginary part of the masked array.
MaskedArray.real The real part of the masked array.
MaskedArray.flat Return a flat iterator, or set a flattened version of self to
value.
MaskedArray.__array_priority__

attribute
MaskedArray.base
Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True

attribute
MaskedArray.ctypes
An object to simplify the interaction of the array with the ctypes module.
This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes
module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which

1.7. Masked arrays 241

NumPy Reference, Release 1.18.1

themselves return ctypes objects that can be used as arguments to a shared library.
Parameters
None
Returns
c [Python object] Possessing attributes data, shape, strides, etc.
See also:
numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted
undocumented public attributes, as well as documented private attributes):
_ctypes.data
A pointer to the memory area of the array as a Python integer. This memory area may contain data that
is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags
and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid
trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as
self._array_interface_['data'][0].
Note that unlike data_as, a reference will not be kept to the array: code like ctypes.c_void_p((a
+ b).ctypes.data) will result in a pointer to a deallocated array, and should be spelt (a + b).
ctypes.data_as(ctypes.c_void_p)
_ctypes.shape
(c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding
to dtype('p') on this platform. This base-type could be ctypes.c_int, ctypes.c_long, or
ctypes.c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.
ctypeslib. The ctypes array contains the shape of the underlying array.
_ctypes.strides
(c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape
attribute. This ctypes array contains the strides information from the underlying array. This strides in-
formation is important for showing how many bytes must be jumped to get to the next element in the
array.
_ctypes.data_as(self, obj)
Return the data pointer cast to a particular c-types object. For example, calling self.
_as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want
to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.
POINTER(ctypes.c_double)).
The returned pointer will keep a reference to the array.
_ctypes.shape_as(self, obj)
Return the shape tuple as an array of some other c-types type. For example: self.
shape_as(ctypes.c_short).
_ctypes.strides_as(self, obj)
Return the strides tuple as an array of some other c-types type. For example: self.
strides_as(ctypes.c_longlong).
If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful,
but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the
as_parameter attribute which will return an integer equal to the data attribute.

242 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> import ctypes

>>> x
array([[0, 1],
[2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>

property
property MaskedArray.dtype
Data-type of the array’s elements.
Parameters
None
Returns
d [numpy dtype object]
See also:
numpy.dtype

Examples

>>> x
array([[0, 1],
[2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>

attribute
MaskedArray.flags
Information about the memory layout of the array.

1.7. Masked arrays 243

NumPy Reference, Release 1.18.1

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased
attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.
Only the WRITEBACKIFCOPY, UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by
the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.
The array flags cannot be set arbitrarily:
• UPDATEIFCOPY can only be set False.
• WRITEBACKIFCOPY can only be set False.
• ALIGNED can only be set True if the data is truly aligned.
• WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory
exposes a writeable buffer interface or is a string.
Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays,
but can also be true for higher dimensional arrays.
Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.
shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1]
== self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for
Fortran-style contiguous arrays is true.
Attributes
C_CONTIGUOUS (C) The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) The data area can be written to. Setting this to False locks the data, making
it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time,
but a view of a writeable array may be subsequently locked while the base array remains
writeable. (The opposite is not true, in that a view of a locked array may not be made
writeable. However, currently, locking a base object does not lock any views that already
reference it, so under that circumstance it is possible to alter the contents of a locked array
via a previously created writeable view onto it.) Attempting to change a non-writeable array
raises a RuntimeError exception.
ALIGNED (A) The data and all elements are aligned appropriately for the hardware.
WRITEBACKIFCOPY (X) This array is a copy of some other array. The C-API function
PyArray_ResolveWritebackIfCopy must be called before deallocating to the base array will
be updated with the contents of this array.
UPDATEIFCOPY (U) (Deprecated, use WRITEBACKIFCOPY) This array is a copy of some
other array. When this array is deallocated, the base array will be updated with the contents
of this array.
FNC F_CONTIGUOUS and not C_CONTIGUOUS.
FORC F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) ALIGNED and WRITEABLE.
CARRAY (CA) BEHAVED and C_CONTIGUOUS.
FARRAY (FA) BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.
attribute

244 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

MaskedArray.itemsize
Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)

>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16

attribute
MaskedArray.nbytes
Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)

>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480

attribute
MaskedArray.ndim
Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])

>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3

property
property MaskedArray.shape
Tuple of array dimensions.
The shape property is usually used to get the current shape of an array, but may also be used to reshape the
array in-place by assigning a tuple of array dimensions to it. As with numpy.reshape, one of the new shape
dimensions can be -1, in which case its value is inferred from the size of the array and the remaining dimensions.
Reshaping an array in-place will fail if a copy is required.
See also:

1.7. Masked arrays 245

NumPy Reference, Release 1.18.1

numpy.reshape similar function

ndarray.reshape similar method

Examples

>>> x = np.array([1, 2, 3, 4])

>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
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.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged
>>> np.zeros((4,2))[::2].shape = (-1,)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: incompatible shape for a non-contiguous array

attribute
MaskedArray.size
Number of elements in the array.
Equal to np.prod(a.shape), i.e., the product of the array’s dimensions.

Notes

a.size returns a standard arbitrary precision Python integer. This may not be the case with other methods of
obtaining the same value (like the suggested np.prod(a.shape), which returns an instance of np.int_),
and may be relevant if the value is used further in calculations that may overflow a fixed size integer type.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)

>>> x.size
30
>>> np.prod(x.shape)
30

attribute
MaskedArray.strides
Tuple of bytes to step in each dimension when traversing an array.
The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

246 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.
See also:
numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
[5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The
strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain
axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get
to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))

>>> y
array([[[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]],
[[12, 13, 14, 15],
[16, 17, 18, 19],
[20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)

>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813

property
property MaskedArray.imag
The imaginary part of the masked array.
This property is a view on the imaginary part of this MaskedArray.
See also:
real

1.7. Masked arrays 247

NumPy Reference, Release 1.18.1

Examples

>>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])

>>> x.imag
masked_array(data=[1.0, --, 1.6],
mask=[False, True, False],
fill_value=1e+20)

property
property MaskedArray.real
The real part of the masked array.
This property is a view on the real part of this MaskedArray.
See also:
imag

Examples

>>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])

>>> x.real
masked_array(data=[1.0, --, 3.45],
mask=[False, True, False],
fill_value=1e+20)

property
property MaskedArray.flat
Return a flat iterator, or set a flattened version of self to value.
attribute
MaskedArray.__array_priority__ = 15

1.7.6 MaskedArray methods

See also:
Array methods

Conversion

MaskedArray.__float__(self) Convert to float.

MaskedArray.__int__(self) Convert to int.
MaskedArray.__long__(self) Convert to long.
MaskedArray.view(self[, dtype, type, fill_value]) Return a view of the MaskedArray data.
MaskedArray.astype(dtype[, order, casting, . . . ]) Copy of the array, cast to a specified type.
MaskedArray.byteswap([inplace]) Swap the bytes of the array elements
MaskedArray.compressed(self) Return all the non-masked data as a 1-D array.
MaskedArray.filled(self[, fill_value]) Return a copy of self, with masked values filled with a
given value.
MaskedArray.tofile(self, fid[, sep, format]) Save a masked array to a file in binary format.
Continued on next page

248 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Table 54 – continued from previous page

MaskedArray.toflex(self) Transforms a masked array into a flexible-type array.
MaskedArray.tolist(self[, fill_value]) Return the data portion of the masked array as a hierar-
chical Python list.
MaskedArray.torecords(self) Transforms a masked array into a flexible-type array.
MaskedArray.tostring(self[, fill_value, order]) This function is a compatibility alias for tobytes.
MaskedArray.tobytes(self[, fill_value, order]) Return the array data as a string containing the raw bytes
in the array.

method
MaskedArray.__float__(self )
Convert to float.
method
MaskedArray.__int__(self )
Convert to int.
method
MaskedArray.__long__(self )
Convert to long.
method
MaskedArray.view(self, dtype=None, type=None, fill_value=None)
Return a view of the MaskedArray data.
Parameters
dtype [data-type or ndarray sub-class, optional] Data-type descriptor of the returned view, e.g.,
float32 or int16. The default, None, results in the view having the same data-type as a.
As with ndarray.view, dtype can also be specified as an ndarray sub-class, which then
specifies the type of the returned object (this is equivalent to setting the type parameter).
type [Python type, optional] Type of the returned view, either ndarray or a subclass. The default
None results in type preservation.
fill_value [scalar, optional] The value to use for invalid entries (None by default). If None, then
this argument is inferred from the passed dtype, or in its absence the original array, as
discussed in the notes below.
See also:

numpy.ndarray.view Equivalent method on ndarray object.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with
a different data-type. This can cause a reinterpretation of the bytes of memory.
a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of
ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation
of the memory.
If fill_value is not specified, but dtype is specified (and is not an ndarray sub-class), the fill_value
of the MaskedArray will be reset. If neither fill_value nor dtype are specified (or if dtype is an ndarray

1.7. Masked arrays 249

NumPy Reference, Release 1.18.1

sub-class), then the fill value is preserved. Finally, if fill_value is specified, but dtype is not, the fill value
is set to the specified value.
For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous
dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be
predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a
is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose,
etc., the view may give different results.
method
MaskedArray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
Copy of the array, cast to a specified type.
Parameters
dtype [str or dtype] Typecode or data-type to which the array is cast.
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout order of the result. ‘C’ means
C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contigu-
ous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in
memory as possible. Default is ‘K’.
casting [{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional] Controls what kind of data
casting may occur. Defaults to ‘unsafe’ for backwards compatibility.
• ‘no’ means the data types should not be cast at all.
• ‘equiv’ means only byte-order changes are allowed.
• ‘safe’ means only casts which can preserve values are allowed.
• ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are
allowed.
• ‘unsafe’ means any data conversions may be done.
subok [bool, optional] If True, then sub-classes will be passed-through (default), otherwise the
returned array will be forced to be a base-class array.
copy [bool, optional] By default, astype always returns a newly allocated array. If this is set to
false, and the dtype, order, and subok requirements are satisfied, the input array is returned
instead of a copy.
Returns
arr_t [ndarray] Unless copy is False and the other conditions for returning the input array are
satisfied (see description for copy input parameter), arr_t is a new array of the same shape
as the input array, with dtype, order given by dtype, order.
Raises
ComplexWarning When casting from complex to float or int. To avoid this, one should use
a.real.astype(t).

250 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

Changed in version 1.17.0: Casting between a simple data type and a structured one is possible only for “unsafe”
casting. Casting to multiple fields is allowed, but casting from multiple fields is not.
Changed in version 1.9.0: Casting from numeric to string types in ‘safe’ casting mode requires that the string
dtype length is long enough to store the max integer/float value converted.

Examples

>>> x = np.array([1, 2, 2.5])

>>> x
array([1. , 2. , 2.5])

>>> x.astype(int)
array([1, 2, 2])

method
MaskedArray.byteswap(inplace=False)
Swap the bytes of the array elements
Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally
swapped in-place. Arrays of byte-strings are not swapped. The real and imaginary parts of a complex number
are swapped individually.
Parameters
inplace [bool, optional] If True, swap bytes in-place, default is False.
Returns
out [ndarray] The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)

>>> list(map(hex, A))
['0x1', '0x100', '0x2233']
>>> A.byteswap(inplace=True)
array([ 256, 1, 13090], dtype=int16)
>>> list(map(hex, A))
['0x100', '0x1', '0x3322']

Arrays of byte-strings are not swapped

>>> A = np.array([b'ceg', b'fac'])

>>> A.byteswap()
array([b'ceg', b'fac'], dtype='|S3')

A.newbyteorder().byteswap() produces an array with the same values but different representa-
tion in memory

1.7. Masked arrays 251

NumPy Reference, Release 1.18.1

>>> A = np.array([1, 2, 3])

>>> A.view(np.uint8)
array([1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0,
0, 0], dtype=uint8)
>>> A.newbyteorder().byteswap(inplace=True)
array([1, 2, 3])
>>> A.view(np.uint8)
array([0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0,
0, 3], dtype=uint8)

method
MaskedArray.compressed(self )
Return all the non-masked data as a 1-D array.
Returns
data [ndarray] A new ndarray holding the non-masked data is returned.

Notes

The result is not a MaskedArray!

Examples

>>> x = np.ma.array(np.arange(5), mask=[0]*2 + [1]*3)

>>> x.compressed()
array([0, 1])
>>> type(x.compressed())
<class 'numpy.ndarray'>

method
MaskedArray.filled(self, fill_value=None)
Return a copy of self, with masked values filled with a given value. However, if there are no masked values to
fill, self will be returned instead as an ndarray.
Parameters
fill_value [array_like, optional] The value to use for invalid entries. Can be scalar or non-scalar.
If non-scalar, the resulting ndarray must be broadcastable over input array. Default is None,
in which case, the fill_value attribute of the array is used instead.
Returns
filled_array [ndarray] A copy of self with invalid entries replaced by fill_value (be it the
function argument or the attribute of self), or self itself as an ndarray if there are no
invalid entries to be replaced.

252 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

The result is not a MaskedArray!

Examples

>>> x = np.ma.array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)

>>> x.filled()
array([ 1, 2, -999, 4, -999])
>>> x.filled(fill_value=1000)
array([ 1, 2, 1000, 4, 1000])
>>> type(x.filled())
<class 'numpy.ndarray'>

Subclassing is preserved. This means that if, e.g., the data part of the masked array is a recarray, filled
returns a recarray:

>>> x = np.array([(-1, 2), (-3, 4)], dtype='i8,i8').view(np.recarray)

>>> m = np.ma.array(x, mask=[(True, False), (False, True)])
>>> m.filled()
rec.array([(999999, 2), ( -3, 999999)],
dtype=[('f0', '<i8'), ('f1', '<i8')])

method
MaskedArray.tofile(self, fid, sep='', format='%s')
Save a masked array to a file in binary format.

Warning: This function is not implemented yet.

Raises
NotImplementedError When tofile is called.

method
MaskedArray.toflex(self )
Transforms a masked array into a flexible-type array.
The flexible type array that is returned will have two fields:
• the _data field stores the _data part of the array.
• the _mask field stores the _mask part of the array.

Parameters
None
Returns
record [ndarray] A new flexible-type ndarray with two fields: the first element containing a
value, the second element containing the corresponding mask boolean. The returned record
shape matches self.shape.

1.7. Masked arrays 253

NumPy Reference, Release 1.18.1

Notes

A side-effect of transforming a masked array into a flexible ndarray is that meta information (fill_value,
. . . ) will be lost.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)

>>> x
masked_array(
data=[[1, --, 3],
[--, 5, --],
[7, --, 9]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)
>>> x.toflex()
array([[(1, False), (2, True), (3, False)],
[(4, True), (5, False), (6, True)],
[(7, False), (8, True), (9, False)]],
dtype=[('_data', '<i8'), ('_mask', '?')])

method
MaskedArray.tolist(self, fill_value=None)
Return the data portion of the masked array as a hierarchical Python list.
Data items are converted to the nearest compatible Python type. Masked values are converted to fill_value.
If fill_value is None, the corresponding entries in the output list will be None.
Parameters
fill_value [scalar, optional] The value to use for invalid entries. Default is None.
Returns
result [list] The Python list representation of the masked array.

Examples

>>> x = np.ma.array([[1,2,3], [4,5,6], [7,8,9]], mask=[0] + [1,0]*4)

>>> x.tolist()
[[1, None, 3], [None, 5, None], [7, None, 9]]
>>> x.tolist(-999)
[[1, -999, 3], [-999, 5, -999], [7, -999, 9]]

method
MaskedArray.torecords(self )
Transforms a masked array into a flexible-type array.
The flexible type array that is returned will have two fields:
• the _data field stores the _data part of the array.
• the _mask field stores the _mask part of the array.

Parameters

254 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

None
Returns
record [ndarray] A new flexible-type ndarray with two fields: the first element containing a
value, the second element containing the corresponding mask boolean. The returned record
shape matches self.shape.

Notes

A side-effect of transforming a masked array into a flexible ndarray is that meta information (fill_value,
. . . ) will be lost.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)

>>> x
masked_array(
data=[[1, --, 3],
[--, 5, --],
[7, --, 9]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)
>>> x.toflex()
array([[(1, False), (2, True), (3, False)],
[(4, True), (5, False), (6, True)],
[(7, False), (8, True), (9, False)]],
dtype=[('_data', '<i8'), ('_mask', '?')])

method
MaskedArray.tostring(self, fill_value=None, order='C')
This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.
method
MaskedArray.tobytes(self, fill_value=None, order='C')
Return the array data as a string containing the raw bytes in the array.
The array is filled with a fill value before the string conversion.
New in version 1.9.0.
Parameters
fill_value [scalar, optional] Value used to fill in the masked values. Default is None, in which
case MaskedArray.fill_value is used.
order [{‘C’,’F’,’A’}, optional] Order of the data item in the copy. Default is ‘C’.
• ‘C’ – C order (row major).
• ‘F’ – Fortran order (column major).
• ‘A’ – Any, current order of array.
• None – Same as ‘A’.

1.7. Masked arrays 255

NumPy Reference, Release 1.18.1

See also:
numpy.ndarray.tobytes, tolist, tofile

Notes

As for ndarray.tobytes, information about the shape, dtype, etc., but also about fill_value, will be lost.

Examples

>>> x = np.ma.array(np.array([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])

>>> x.tobytes()
b'\x01\x00\x00\x00\x00\x00\x00\x00?B\x0f\x00\x00\x00\x00\x00?B\x0f\x00\x00\x00\
˓→x00\x00\x04\x00\x00\x00\x00\x00\x00\x00'

Shape manipulation

For reshape, resize, and transpose, the single tuple argument may be replaced with n integers which will be interpreted
as an n-tuple.

MaskedArray.flatten([order]) Return a copy of the array collapsed into one dimension.

MaskedArray.ravel(self[, order]) Returns a 1D version of self, as a view.
MaskedArray.reshape(self, \*s, \*\*kwargs) Give a new shape to the array without changing its data.
MaskedArray.resize(self, newshape[, . . . ])
MaskedArray.squeeze([axis]) Remove single-dimensional entries from the shape of a.
MaskedArray.swapaxes(axis1, axis2) Return a view of the array with axis1 and axis2 inter-
changed.
MaskedArray.transpose(*axes) Returns a view of the array with axes transposed.
MaskedArray.T

method
MaskedArray.flatten(order='C')
Return a copy of the array collapsed into one dimension.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] ‘C’ means to flatten in row-major (C-style) order. ‘F’
means to flatten in column-major (Fortran- style) order. ‘A’ means to flatten in column-
major order if a is Fortran contiguous in memory, row-major order otherwise. ‘K’ means to
flatten a in the order the elements occur in memory. The default is ‘C’.
Returns
y [ndarray] A copy of the input array, flattened to one dimension.
See also:

ravel Return a flattened array.

flat A 1-D flat iterator over the array.

256 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> a = np.array([[1,2], [3,4]])

>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])

method
MaskedArray.ravel(self, order='C')
Returns a 1D version of self, as a view.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] The elements of a are read using this index order. ‘C’
means to index the elements in C-like order, with the last axis index changing fastest, back
to the first axis index changing slowest. ‘F’ means to index the elements in Fortran-like
index order, with the first index changing fastest, and the last index changing slowest. Note
that the ‘C’ and ‘F’ options take no account of the memory layout of the underlying array,
and only refer to the order of axis indexing. ‘A’ means to read the elements in Fortran-like
index order if m is Fortran contiguous in memory, C-like order otherwise. ‘K’ means to read
the elements in the order they occur in memory, except for reversing the data when strides
are negative. By default, ‘C’ index order is used.
Returns
MaskedArray Output view is of shape (self.size,) (or (np.ma.product(self.
shape),)).

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)

>>> x
masked_array(
data=[[1, --, 3],
[--, 5, --],
[7, --, 9]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)
>>> x.ravel()
masked_array(data=[1, --, 3, --, 5, --, 7, --, 9],
mask=[False, True, False, True, False, True, False, True,
False],
fill_value=999999)

method
MaskedArray.reshape(self, *s, **kwargs)
Give a new shape to the array without changing its data.
Returns a masked array containing the same data, but with a new shape. The result is a view on the original
array; if this is not possible, a ValueError is raised.
Parameters

1.7. Masked arrays 257

NumPy Reference, Release 1.18.1

shape [int or tuple of ints] The new shape should be compatible with the original shape. If an
integer is supplied, then the result will be a 1-D array of that length.
order [{‘C’, ‘F’}, optional] Determines whether the array data should be viewed as in C (row-
major) or FORTRAN (column-major) order.
Returns
reshaped_array [array] A new view on the array.
See also:

reshape Equivalent function in the masked array module.

numpy.ndarray.reshape Equivalent method on ndarray object.
numpy.reshape Equivalent function in the NumPy module.

Notes

The reshaping operation cannot guarantee that a copy will not be made, to modify the shape in place, use
a.shape = s

Examples

>>> x = np.ma.array([[1,2],[3,4]], mask=[1,0,0,1])

>>> x
masked_array(
data=[[--, 2],
[3, --]],
mask=[[ True, False],
[False, True]],
fill_value=999999)
>>> x = x.reshape((4,1))
>>> x
masked_array(
data=[[--],
[2],
[3],
[--]],
mask=[[ True],
[False],
[False],
[ True]],
fill_value=999999)

method
MaskedArray.resize(self, newshape, refcheck=True, order=False)

Warning: This method does nothing, except raise a ValueError exception. A masked array does not own
its data and therefore cannot safely be resized in place. Use the numpy.ma.resize function instead.

This method is difficult to implement safely and may be deprecated in future releases of NumPy.
method

258 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

MaskedArray.squeeze(axis=None)
Remove single-dimensional entries from the shape of a.
Refer to numpy.squeeze for full documentation.
See also:

numpy.squeeze equivalent function

method
MaskedArray.swapaxes(axis1, axis2)
Return a view of the array with axis1 and axis2 interchanged.
Refer to numpy.swapaxes for full documentation.
See also:

numpy.swapaxes equivalent function

method
MaskedArray.transpose(*axes)
Returns a view of the array with axes transposed.
For a 1-D array this has no effect, as a transposed vector is simply the same vector. To convert a 1-D array
into a 2D column vector, an additional dimension must be added. np.atleast2d(a).T achieves this, as does
a[:, np.newaxis]. For a 2-D array, this is a standard matrix transpose. For an n-D array, if axes are given,
their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape =
(i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2],
... i[1], i[0]).
Parameters
axes [None, tuple of ints, or n ints]
• None or no argument: reverses the order of the axes.
• tuple of ints: i in the j-th place in the tuple means a’s i-th axis becomes a.transpose()’s
j-th axis.
• n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience”
alternative to the tuple form)
Returns
out [ndarray] View of a, with axes suitably permuted.
See also:

ndarray.T Array property returning the array transposed.

ndarray.reshape Give a new shape to an array without changing its data.

1.7. Masked arrays 259

NumPy Reference, Release 1.18.1

Examples

>>> a = np.array([[1, 2], [3, 4]])

>>> a
array([[1, 2],
[3, 4]])
>>> a.transpose()
array([[1, 3],
[2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
[2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
[2, 4]])

property
property MaskedArray.T

Item selection and manipulation

For array methods that take an axis keyword, it defaults to None. If axis is None, then the array is treated as a 1-D
array. Any other value for axis represents the dimension along which the operation should proceed.

MaskedArray.argmax(self[, axis, fill_value, out]) Returns array of indices of the maximum values along
the given axis.
MaskedArray.argmin(self[, axis, fill_value, out]) Return array of indices to the minimum values along the
given axis.
MaskedArray.argsort(self[, axis, kind, . . . ]) Return an ndarray of indices that sort the array along the
specified axis.
MaskedArray.choose(choices[, out, mode]) Use an index array to construct a new array from a set
of choices.
MaskedArray.compress(self, condition[, . . . ]) Return a where condition is True.
MaskedArray.diagonal([offset, axis1, axis2]) Return specified diagonals.
MaskedArray.fill(value) Fill the array with a scalar value.
MaskedArray.item(*args) Copy an element of an array to a standard Python scalar
and return it.
MaskedArray.nonzero(self) Return the indices of unmasked elements that are not
zero.
MaskedArray.put(self, indices, values[, mode]) Set storage-indexed locations to corresponding values.
MaskedArray.repeat(repeats[, axis]) Repeat elements of an array.
MaskedArray.searchsorted(v[, side, sorter]) Find indices where elements of v should be inserted in
a to maintain order.
MaskedArray.sort(self[, axis, kind, order, . . . ]) Sort the array, in-place
MaskedArray.take(self, indices[, axis, out, . . . ])

method
MaskedArray.argmax(self, axis=None, fill_value=None, out=None)
Returns array of indices of the maximum values along the given axis. Masked values are treated as if they had
the value fill_value.
Parameters

260 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

axis [{None, integer}] If None, the index is into the flattened array, otherwise along the specified
axis
fill_value [{var}, optional] Value used to fill in the masked values. If None, the output of
maximum_fill_value(self._data) is used instead.
out [{None, array}, optional] Array into which the result can be placed. Its type is preserved
and it must be of the right shape to hold the output.
Returns
index_array [{integer_array}]

Examples

>>> a = np.arange(6).reshape(2,3)
>>> a.argmax()
5
>>> a.argmax(0)
array([1, 1, 1])
>>> a.argmax(1)
array([2, 2])

method
MaskedArray.argmin(self, axis=None, fill_value=None, out=None)
Return array of indices to the minimum values along the given axis.
Parameters
axis [{None, integer}] If None, the index is into the flattened array, otherwise along the specified
axis
fill_value [{var}, optional] Value used to fill in the masked values. If None, the output of
minimum_fill_value(self._data) is used instead.
out [{None, array}, optional] Array into which the result can be placed. Its type is preserved
and it must be of the right shape to hold the output.
Returns
ndarray or scalar If multi-dimension input, returns a new ndarray of indices to the minimum
values along the given axis. Otherwise, returns a scalar of index to the minimum values
along the given axis.

Examples

>>> x = np.ma.array(np.arange(4), mask=[1,1,0,0])

>>> x.shape = (2,2)
>>> x
masked_array(
data=[[--, --],
[2, 3]],
mask=[[ True, True],
[False, False]],
fill_value=999999)
>>> x.argmin(axis=0, fill_value=-1)
array([0, 0])
(continues on next page)

1.7. Masked arrays 261

NumPy Reference, Release 1.18.1

(continued from previous page)

>>> x.argmin(axis=0, fill_value=9)
array([1, 1])

method
MaskedArray.argsort(self, axis=<no value>, kind=None, order=None, endwith=True,
fill_value=None)
Return an ndarray of indices that sort the array along the specified axis. Masked values are filled beforehand to
fill_value.
Parameters
axis [int, optional] Axis along which to sort. If None, the default, the flattened array is used.
Changed in version 1.13.0: Previously, the default was documented to be -1, but that was in
error. At some future date, the default will change to -1, as originally intended. Until then,
the axis should be given explicitly when arr.ndim > 1, to avoid a FutureWarning.
kind [{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] The sorting algorithm used.
order [list, optional] When a is an array with fields defined, this argument specifies which fields
to compare first, second, etc. Not all fields need be specified.
endwith [{True, False}, optional] Whether missing values (if any) should be treated as the
largest values (True) or the smallest values (False) When the array contains unmasked values
at the same extremes of the datatype, the ordering of these values and the masked values is
undefined.
fill_value [{var}, optional] Value used internally for the masked values. If fill_value is
not None, it supersedes endwith.
Returns
index_array [ndarray, int] Array of indices that sort a along the specified axis. In other words,
a[index_array] yields a sorted a.
See also:

MaskedArray.sort Describes sorting algorithms used.

lexsort Indirect stable sort with multiple keys.
numpy.ndarray.sort Inplace sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.ma.array([3,2,1], mask=[False, False, True])

>>> a
masked_array(data=[3, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> a.argsort()
array([1, 0, 2])

262 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

method
MaskedArray.choose(choices, out=None, mode='raise')
Use an index array to construct a new array from a set of choices.
Refer to numpy.choose for full documentation.
See also:

numpy.choose equivalent function

method
MaskedArray.compress(self, condition, axis=None, out=None)
Return a where condition is True.
If condition is a MaskedArray, missing values are considered as False.
Parameters
condition [var] Boolean 1-d array selecting which entries to return. If len(condition) is less
than the size of a along the axis, then output is truncated to length of condition array.
axis [{None, int}, optional] Axis along which the operation must be performed.
out [{None, ndarray}, optional] Alternative output array in which to place the result. It must
have the same shape as the expected output but the type will be cast if necessary.
Returns
result [MaskedArray] A MaskedArray object.

Notes

Please note the difference with compressed ! The output of compress has a mask, the output of
compressed does not.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)

>>> x
masked_array(
data=[[1, --, 3],
[--, 5, --],
[7, --, 9]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)
>>> x.compress([1, 0, 1])
masked_array(data=[1, 3],
mask=[False, False],
fill_value=999999)

>>> x.compress([1, 0, 1], axis=1)

masked_array(
data=[[1, 3],
[--, --],
(continues on next page)

1.7. Masked arrays 263

NumPy Reference, Release 1.18.1

(continued from previous page)

[7, 9]],
mask=[[False, False],
[ True, True],
[False, False]],
fill_value=999999)

method
MaskedArray.diagonal(offset=0, axis1=0, axis2=1)
Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous
NumPy versions. In a future version the read-only restriction will be removed.
Refer to numpy.diagonal for full documentation.
See also:

numpy.diagonal equivalent function

method
MaskedArray.fill(value)
Fill the array with a scalar value.
Parameters
value [scalar] All elements of a will be assigned this value.

Examples

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

>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([1., 1.])

method
MaskedArray.item(*args)
Copy an element of an array to a standard Python scalar and return it.
Parameters
*args [Arguments (variable number and type)]
• none: in this case, the method only works for arrays with one element (a.size == 1),
which element is copied into a standard Python scalar object and returned.
• int_type: this argument is interpreted as a flat index into the array, specifying which
element to copy and return.
• tuple of int_types: functions as does a single int_type argument, except that the argument
is interpreted as an nd-index into the array.
Returns
z [Standard Python scalar object] A copy of the specified element of the array as a suitable
Python scalar

264 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no
available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless
fields are defined, in which case a tuple is returned.
item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can
be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using
Python’s optimized math.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
[1, 3, 6],
[1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

method
MaskedArray.nonzero(self )
Return the indices of unmasked elements that are not zero.
Returns a tuple of arrays, one for each dimension, containing the indices of the non-zero elements in that
dimension. The corresponding non-zero values can be obtained with:

a[a.nonzero()]

To group the indices by element, rather than dimension, use instead:

np.transpose(a.nonzero())

The result of this is always a 2d array, with a row for each non-zero element.
Parameters
None
Returns
tuple_of_arrays [tuple] Indices of elements that are non-zero.
See also:

numpy.nonzero Function operating on ndarrays.

flatnonzero Return indices that are non-zero in the flattened version of the input array.
numpy.ndarray.nonzero Equivalent ndarray method.
count_nonzero Counts the number of non-zero elements in the input array.

1.7. Masked arrays 265

NumPy Reference, Release 1.18.1

Examples

>>> import numpy.ma as ma

>>> x = ma.array(np.eye(3))
>>> x
masked_array(
data=[[1., 0., 0.],
[0., 1., 0.],
[0., 0., 1.]],
mask=False,
fill_value=1e+20)
>>> x.nonzero()
(array([0, 1, 2]), array([0, 1, 2]))

Masked elements are ignored.

>>> x[1, 1] = ma.masked

>>> x
masked_array(
data=[[1.0, 0.0, 0.0],
[0.0, --, 0.0],
[0.0, 0.0, 1.0]],
mask=[[False, False, False],
[False, True, False],
[False, False, False]],
fill_value=1e+20)
>>> x.nonzero()
(array([0, 2]), array([0, 2]))

Indices can also be grouped by element.

>>> np.transpose(x.nonzero())
array([[0, 0],
[2, 2]])

A common use for nonzero is to find the indices of an array, where a condition is True. Given an array a, the
condition a > 3 is a boolean array and since False is interpreted as 0, ma.nonzero(a > 3) yields the indices of the
a where the condition is true.

>>> a = ma.array([[1,2,3],[4,5,6],[7,8,9]])
>>> a > 3
masked_array(
data=[[False, False, False],
[ True, True, True],
[ True, True, True]],
mask=False,
fill_value=True)
>>> ma.nonzero(a > 3)
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

The nonzero method of the condition array can also be called.

>>> (a > 3).nonzero()

(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

method

266 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

MaskedArray.put(self, indices, values, mode='raise')

Set storage-indexed locations to corresponding values.
Sets self._data.flat[n] = values[n] for each n in indices. If values is shorter than indices then it will repeat. If
values has some masked values, the initial mask is updated in consequence, else the corresponding values are
unmasked.
Parameters
indices [1-D array_like] Target indices, interpreted as integers.
values [array_like] Values to place in self._data copy at target indices.
mode [{‘raise’, ‘wrap’, ‘clip’}, optional] Specifies how out-of-bounds indices will behave.
‘raise’ : raise an error. ‘wrap’ : wrap around. ‘clip’ : clip to the range.

Notes

values can be a scalar or length 1 array.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)

>>> x
masked_array(
data=[[1, --, 3],
[--, 5, --],
[7, --, 9]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)
>>> x.put([0,4,8],[10,20,30])
>>> x
masked_array(
data=[[10, --, 3],
[--, 20, --],
[7, --, 30]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)

>>> x.put(4,999)
>>> x
masked_array(
data=[[10, --, 3],
[--, 999, --],
[7, --, 30]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)

method
MaskedArray.repeat(repeats, axis=None)
Repeat elements of an array.

1.7. Masked arrays 267

NumPy Reference, Release 1.18.1

Refer to numpy.repeat for full documentation.

See also:

numpy.repeat equivalent function

method
MaskedArray.searchsorted(v, side='left', sorter=None)
Find indices where elements of v should be inserted in a to maintain order.
For full documentation, see numpy.searchsorted
See also:

numpy.searchsorted equivalent function

method
MaskedArray.sort(self, axis=-1, kind=None, order=None, endwith=True, fill_value=None)
Sort the array, in-place
Parameters
a [array_like] Array to be sorted.
axis [int, optional] Axis along which to sort. If None, the array is flattened before sorting. The
default is -1, which sorts along the last axis.
kind [{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] The sorting algorithm used.
order [list, optional] When a is a structured array, this argument specifies which fields to com-
pare first, second, and so on. This list does not need to include all of the fields.
endwith [{True, False}, optional] Whether missing values (if any) should be treated as the
largest values (True) or the smallest values (False) When the array contains unmasked values
sorting at the same extremes of the datatype, the ordering of these values and the masked
values is undefined.
fill_value [{var}, optional] Value used internally for the masked values. If fill_value is
not None, it supersedes endwith.
Returns
sorted_array [ndarray] Array of the same type and shape as a.
See also:

numpy.ndarray.sort Method to sort an array in-place.

argsort Indirect sort.
lexsort Indirect stable sort on multiple keys.
searchsorted Find elements in a sorted array.

268 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])

>>> # Default
>>> a.sort()
>>> a
masked_array(data=[1, 3, 5, --, --],
mask=[False, False, False, True, True],
fill_value=999999)

>>> a = np.ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])

>>> # Put missing values in the front
>>> a.sort(endwith=False)
>>> a
masked_array(data=[--, --, 1, 3, 5],
mask=[ True, True, False, False, False],
fill_value=999999)

>>> a = np.ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])

>>> # fill_value takes over endwith
>>> a.sort(endwith=False, fill_value=3)
>>> a
masked_array(data=[1, --, --, 3, 5],
mask=[False, True, True, False, False],
fill_value=999999)

method
MaskedArray.take(self, indices, axis=None, out=None, mode='raise')

Pickling and copy

MaskedArray.copy([order]) Return a copy of the array.

MaskedArray.dump(file) Dump a pickle of the array to the specified file.
MaskedArray.dumps() Returns the pickle of the array as a string.

method
MaskedArray.copy(order='C')
Return a copy of the array.
Parameters
order [{‘C’, ‘F’, ‘A’, ‘K’}, optional] Controls the memory layout of the copy. ‘C’ means C-
order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means
match the layout of a as closely as possible. (Note that this function and numpy.copy are
very similar, but have different default values for their order= arguments.)
See also:
numpy.copy, numpy.copyto

1.7. Masked arrays 269

NumPy Reference, Release 1.18.1

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
[0, 0, 0]])

>>> y
array([[1, 2, 3],
[4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True

method
MaskedArray.dump(file)
Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.
Parameters
file [str or Path] A string naming the dump file.
Changed in version 1.17.0: pathlib.Path objects are now accepted.
method
MaskedArray.dumps()
Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.
Parameters
None

Calculations

MaskedArray.all(self[, axis, out, keepdims]) Returns True if all elements evaluate to True.
MaskedArray.anom(self[, axis, dtype]) Compute the anomalies (deviations from the arithmetic
mean) along the given axis.
MaskedArray.any(self[, axis, out, keepdims]) Returns True if any of the elements of a evaluate to True.
MaskedArray.clip([min, max, out]) Return an array whose values are limited to [min,
max].
MaskedArray.conj() Complex-conjugate all elements.
MaskedArray.conjugate() Return the complex conjugate, element-wise.
MaskedArray.cumprod(self[, axis, dtype, out]) Return the cumulative product of the array elements
over the given axis.
MaskedArray.cumsum(self[, axis, dtype, out]) Return the cumulative sum of the array elements over
the given axis.
MaskedArray.max(self[, axis, out, . . . ]) Return the maximum along a given axis.
Continued on next page

270 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Table 58 – continued from previous page

MaskedArray.mean(self[, axis, dtype, out, . . . ]) Returns the average of the array elements along given
axis.
MaskedArray.min(self[, axis, out, . . . ]) Return the minimum along a given axis.
MaskedArray.prod(self[, axis, dtype, out, . . . ]) Return the product of the array elements over the given
axis.
MaskedArray.product(self[, axis, dtype, . . . ]) Return the product of the array elements over the given
axis.
MaskedArray.ptp(self[, axis, out, . . . ]) Return (maximum - minimum) along the given dimen-
sion (i.e.
MaskedArray.round(self[, decimals, out]) Return each element rounded to the given number of
decimals.
MaskedArray.std(self[, axis, dtype, out, . . . ]) Returns the standard deviation of the array elements
along given axis.
MaskedArray.sum(self[, axis, dtype, out, . . . ]) Return the sum of the array elements over the given axis.
MaskedArray.trace([offset, axis1, axis2, . . . ]) Return the sum along diagonals of the array.
MaskedArray.var(self[, axis, dtype, out, . . . ]) Compute the variance along the specified axis.

method
MaskedArray.all(self, axis=None, out=None, keepdims=<no value>)
Returns True if all elements evaluate to True.
The output array is masked where all the values along the given axis are masked: if the output would have been
a scalar and that all the values are masked, then the output is masked.
Refer to numpy.all for full documentation.
See also:

numpy.ndarray.all corresponding function for ndarrays

numpy.all equivalent function

Examples

>>> np.ma.array([1,2,3]).all()
True
>>> a = np.ma.array([1,2,3], mask=True)
>>> (a.all() is np.ma.masked)
True

method
MaskedArray.anom(self, axis=None, dtype=None)
Compute the anomalies (deviations from the arithmetic mean) along the given axis.
Returns an array of anomalies, with the same shape as the input and where the arithmetic mean is computed
along the given axis.
Parameters
axis [int, optional] Axis over which the anomalies are taken. The default is to use the mean of
the flattened array as reference.
dtype [dtype, optional]

1.7. Masked arrays 271

NumPy Reference, Release 1.18.1

Type to use in computing the variance. For arrays of integer type the default is
float32; for arrays of float types it is the same as the array type.
See also:

mean Compute the mean of the array.

Examples

>>> a = np.ma.array([1,2,3])
>>> a.anom()
masked_array(data=[-1., 0., 1.],
mask=False,
fill_value=1e+20)

method
MaskedArray.any(self, axis=None, out=None, keepdims=<no value>)
Returns True if any of the elements of a evaluate to True.
Masked values are considered as False during computation.
Refer to numpy.any for full documentation.
See also:

numpy.ndarray.any corresponding function for ndarrays

numpy.any equivalent function

method
MaskedArray.clip(min=None, max=None, out=None, **kwargs)
Return an array whose values are limited to [min, max]. One of max or min must be given.
Refer to numpy.clip for full documentation.
See also:

numpy.clip equivalent function

method
MaskedArray.conj()
Complex-conjugate all elements.
Refer to numpy.conjugate for full documentation.
See also:

numpy.conjugate equivalent function

method
MaskedArray.conjugate()
Return the complex conjugate, element-wise.
Refer to numpy.conjugate for full documentation.
See also:

272 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

numpy.conjugate equivalent function

method
MaskedArray.cumprod(self, axis=None, dtype=None, out=None)
Return the cumulative product of the array elements over the given axis.
Masked values are set to 1 internally during the computation. However, their position is saved, and the result
will be masked at the same locations.
Refer to numpy.cumprod for full documentation.
See also:

numpy.ndarray.cumprod corresponding function for ndarrays

numpy.cumprod equivalent function

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.
method
MaskedArray.cumsum(self, axis=None, dtype=None, out=None)
Return the cumulative sum of the array elements over the given axis.
Masked values are set to 0 internally during the computation. However, their position is saved, and the result
will be masked at the same locations.
Refer to numpy.cumsum for full documentation.
See also:

numpy.ndarray.cumsum corresponding function for ndarrays

numpy.cumsum equivalent function

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> marr = np.ma.array(np.arange(10), mask=[0,0,0,1,1,1,0,0,0,0])

>>> marr.cumsum()
masked_array(data=[0, 1, 3, --, --, --, 9, 16, 24, 33],
mask=[False, False, False, True, True, True, False, False,
False, False],
fill_value=999999)

method
MaskedArray.max(self, axis=None, out=None, fill_value=None, keepdims=<no value>)
Return the maximum along a given axis.

1.7. Masked arrays 273

NumPy Reference, Release 1.18.1

Parameters
axis [{None, int}, optional] Axis along which to operate. By default, axis is None and the
flattened input is used.
out [array_like, optional] Alternative output array in which to place the result. Must be of the
same shape and buffer length as the expected output.
fill_value [{var}, optional] Value used to fill in the masked values. If None, use the output of
maximum_fill_value().
keepdims [bool, optional] If this is set to True, the axes which are reduced are left in the result
as dimensions with size one. With this option, the result will broadcast correctly against the
array.
Returns
amax [array_like] New array holding the result. If out was specified, out is returned.
See also:

maximum_fill_value Returns the maximum filling value for a given datatype.

method
MaskedArray.mean(self, axis=None, dtype=None, out=None, keepdims=<no value>)
Returns the average of the array elements along given axis.
Masked entries are ignored, and result elements which are not finite will be masked.
Refer to numpy.mean for full documentation.
See also:

numpy.ndarray.mean corresponding function for ndarrays

numpy.mean Equivalent function
numpy.ma.average Weighted average.

Examples

>>> a = np.ma.array([1,2,3], mask=[False, False, True])

>>> a
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> a.mean()
1.5

method
MaskedArray.min(self, axis=None, out=None, fill_value=None, keepdims=<no value>)
Return the minimum along a given axis.
Parameters
axis [{None, int}, optional] Axis along which to operate. By default, axis is None and the
flattened input is used.
out [array_like, optional] Alternative output array in which to place the result. Must be of the
same shape and buffer length as the expected output.

274 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

fill_value [{var}, optional] Value used to fill in the masked values. If None, use the output of
minimum_fill_value.
keepdims [bool, optional] If this is set to True, the axes which are reduced are left in the result
as dimensions with size one. With this option, the result will broadcast correctly against the
array.
Returns
amin [array_like] New array holding the result. If out was specified, out is returned.
See also:

minimum_fill_value Returns the minimum filling value for a given datatype.

method
MaskedArray.prod(self, axis=None, dtype=None, out=None, keepdims=<no value>)
Return the product of the array elements over the given axis.
Masked elements are set to 1 internally for computation.
Refer to numpy.prod for full documentation.
See also:

numpy.ndarray.prod corresponding function for ndarrays

numpy.prod equivalent function

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.
method
MaskedArray.product(self, axis=None, dtype=None, out=None, keepdims=<no value>)
Return the product of the array elements over the given axis.
Masked elements are set to 1 internally for computation.
Refer to numpy.prod for full documentation.
See also:

numpy.ndarray.prod corresponding function for ndarrays

numpy.prod equivalent function

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.
method
MaskedArray.ptp(self, axis=None, out=None, fill_value=None, keepdims=False)
Return (maximum - minimum) along the given dimension (i.e. peak-to-peak value).
Parameters
axis [{None, int}, optional] Axis along which to find the peaks. If None (default) the flattened
array is used.

1.7. Masked arrays 275

NumPy Reference, Release 1.18.1

out [{None, array_like}, optional] Alternative output array in which to place the result. It must
have the same shape and buffer length as the expected output but the type will be cast if
necessary.
fill_value [{var}, optional] Value used to fill in the masked values.
keepdims [bool, optional] If this is set to True, the axes which are reduced are left in the result
as dimensions with size one. With this option, the result will broadcast correctly against the
array.
Returns
ptp [ndarray.] A new array holding the result, unless out was specified, in which case a refer-
ence to out is returned.
method
MaskedArray.round(self, decimals=0, out=None)
Return each element rounded to the given number of decimals.
Refer to numpy.around for full documentation.
See also:

numpy.ndarray.around corresponding function for ndarrays

numpy.around equivalent function

method
MaskedArray.std(self, axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>)
Returns the standard deviation of the array elements along given axis.
Masked entries are ignored.
Refer to numpy.std for full documentation.
See also:

numpy.ndarray.std corresponding function for ndarrays

numpy.std Equivalent function

method
MaskedArray.sum(self, axis=None, dtype=None, out=None, keepdims=<no value>)
Return the sum of the array elements over the given axis.
Masked elements are set to 0 internally.
Refer to numpy.sum for full documentation.
See also:

numpy.ndarray.sum corresponding function for ndarrays

numpy.sum equivalent function

276 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)

>>> x
masked_array(
data=[[1, --, 3],
[--, 5, --],
[7, --, 9]],
mask=[[False, True, False],
[ True, False, True],
[False, True, False]],
fill_value=999999)
>>> x.sum()
25
>>> x.sum(axis=1)
masked_array(data=[4, 5, 16],
mask=[False, False, False],
fill_value=999999)
>>> x.sum(axis=0)
masked_array(data=[8, 5, 12],
mask=[False, False, False],
fill_value=999999)
>>> print(type(x.sum(axis=0, dtype=np.int64)[0]))
<class 'numpy.int64'>

method
MaskedArray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)
Return the sum along diagonals of the array.
Refer to numpy.trace for full documentation.
See also:

numpy.trace equivalent function

method
MaskedArray.var(self, axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>)
Compute the variance along the specified axis.
Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed
for the flattened array by default, otherwise over the specified axis.
Parameters
a [array_like] Array containing numbers whose variance is desired. If a is not an array, a con-
version is attempted.
axis [None or int or tuple of ints, optional] Axis or axes along which the variance is computed.
The default is to compute the variance of the flattened array.
New in version 1.7.0.
If this is a tuple of ints, a variance is performed over multiple axes, instead of a single axis
or all the axes as before.
dtype [data-type, optional] Type to use in computing the variance. For arrays of integer type
the default is float64; for arrays of float types it is the same as the array type.

1.7. Masked arrays 277

NumPy Reference, Release 1.18.1

out [ndarray, optional] Alternate output array in which to place the result. It must have the same
shape as the expected output, but the type is cast if necessary.
ddof [int, optional] “Delta Degrees of Freedom”: the divisor used in the calculation is N -
ddof, where N represents the number of elements. By default ddof is zero.
keepdims [bool, optional] If this is set to True, the axes which are reduced are left in the result
as dimensions with size one. With this option, the result will broadcast correctly against the
input array.
If the default value is passed, then keepdims will not be passed through to the var method
of sub-classes of ndarray, however any non-default value will be. If the sub-class’ method
does not implement keepdims any exceptions will be raised.
Returns
variance [ndarray, see dtype parameter above] If out=None, returns a new array containing
the variance; otherwise, a reference to the output array is returned.
See also:
std, mean, nanmean, nanstd, nanvar, ufuncs-output-type

Notes

The variance is the average of the squared deviations from the mean, i.e., var = mean(abs(x - x.
mean())**2).
The mean is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the
divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator
of the variance of a hypothetical infinite population. ddof=0 provides a maximum likelihood estimate of the
variance for normally distributed variables.
Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and
nonnegative.
For floating-point input, the variance is computed using the same precision the input has. Depending on the
input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a
higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, 2], [3, 4]])

>>> np.var(a)
1.25
>>> np.var(a, axis=0)
array([1., 1.])
>>> np.var(a, axis=1)
array([0.25, 0.25])

In single precision, var() can be inaccurate:

>>> a = np.zeros((2, 512*512), dtype=np.float32)

>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.var(a)
0.20250003

278 Chapter 1. Array objects

 NumPy Reference, Release 1.18.1

Computing the variance in float64 is more accurate:

>>> np.var(a, dtype=np.float64)

0.20249999932944759 # may vary
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2
0.2025

Arithmetic and comparison operations

Comparison operators:

MaskedArray.__lt__(self, value, /) Return self<value.

MaskedArray.__le__(self, value, /) Return self<=value.
MaskedArray.__gt__(self, value, /) Return self>value.
MaskedArray.__ge__(self, value, /) Return self>=value.
MaskedArray.__eq__(self, other) Check whether other equals self elementwise.
MaskedArray.__ne__(self, other) Check whether other does not equal self elementwise.

method
MaskedArray.__lt__(self, value, / )
Return self<value.
method
MaskedArray.__le__(self, value, / )
Return self<=value.
method
MaskedArray.__gt__(self, value, / )
Return self>value.
method
MaskedArray.__ge__(self, value, / )
Return self>=value.
method
MaskedArray.__eq__(self, other)
Check whether other equals self elementwise.
When either of the elements is masked, the result is masked as well, but the underlying boolean data are still set,
with self and other considered equal if both are masked, and unequal otherwise.
For structured arrays, all fields are combined, with masked values ignored. The result is masked if all fields
were masked, with self and other considered equal only if both were fully masked.
method
MaskedArray.__ne__(self, other)
Check whether other does not equal self elementwise.
When either of the elements is masked, the result is masked as well, but the underlying boolean data are still set,
with self and other considered equal if both are masked, and unequal otherwise.
For structured arrays, all fields are combined, with masked values ignored. The result is masked if all fields
were masked, with self and other considered equal only if both were fully masked.

1.7. Masked arrays 279

NumPy Reference, Release 1.18.1

Truth value of an array (bool):

MaskedArray.__bool__(self, /) self != 0

method
MaskedArray.__bool__(self, / )
self != 0

Arithmetic:

MaskedArray.__abs__(self)
MaskedArray.__add__(self, other) Add self to other, and return a new masked array.
MaskedArray.__radd__(self, other) Add other to self, and return a new masked array.
MaskedArray.__sub__(self, other) Subtract other from self, and return a new masked array.
MaskedArray.__rsub__(self, other) Subtract self from other, and return a new masked array.
MaskedArray.__mul__(self, other) Multiply self by other, and return a new masked array.
MaskedArray.__rmul__(self, other) Multiply other by self, and return a new masked array.
MaskedArray.__div__(self, other) Divide other into self, and return a new masked array.
MaskedArray.__truediv__(self, other) Divide other into self, and return a new masked array.
MaskedArray.__rtruediv__(self, other) Divide self into other, and return a new masked array.
MaskedArray.__floordiv__(self, other) Divide other into self, and return a new masked array.
MaskedArray.__rfloordiv__(self, other) Divide self into other, and return a new masked array.
MaskedArray.__mod__(self, value, /) Return self%value.
MaskedArray.__rmod__(self, value, /) Return value%self.
MaskedArray.__div