NumPy Reference

Release 1.20.0

Written by the NumPy community

January 31, 2021

 CONTENTS

1 Array objects 3
1.1 The N-dimensional array (ndarray) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
1.3 Data type objects (dtype) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
1.4 Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
1.5 Iterating Over Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
1.6 Standard array subclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
1.7 Masked arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
1.8 The Array Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
1.9 Datetimes and Timedeltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

2 Constants 433

3 Universal functions (ufunc) 441

3.1 Broadcasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
3.2 Output type determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
3.3 Use of internal buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
3.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
3.5 Casting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
3.6 Overriding Ufunc behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
3.7 ufunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
3.8 Available ufuncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

4 Routines 469
4.1 Array creation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
4.2 Array manipulation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
4.3 Binary operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
4.4 String operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
4.5 C-Types Foreign Function Interface (numpy.ctypeslib) . . . . . . . . . . . . . . . . . . . . . . 646
4.6 Datetime Support Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
4.7 Data type routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
4.8 Optionally SciPy-accelerated routines (numpy.dual) . . . . . . . . . . . . . . . . . . . . . . . . . 676
4.9 Mathematical functions with automatic domain (numpy.emath) . . . . . . . . . . . . . . . . . . . 677
4.10 Floating point error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
4.11 Discrete Fourier Transform (numpy.fft) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
4.12 Functional programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
4.13 NumPy-specific help functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
4.14 Indexing routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
4.15 Input and output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
4.16 Linear algebra (numpy.linalg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810

i
 4.17 Logic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
4.18 Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
4.19 Matrix library (numpy.matlib) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
4.20 Miscellaneous routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
4.21 Padding Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
4.22 Polynomials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
4.23 Random sampling (numpy.random) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1252
4.24 Set routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1513
4.25 Sorting, searching, and counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1519
4.26 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1539
4.27 Test Support (numpy.testing) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
4.28 Window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617

5 Typing (numpy.typing) 1631

5.1 Differences from the runtime NumPy API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631
5.2 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632

6 Global State 1635

6.1 Performance-Related Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635
6.2 Interoperability-Related Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635
6.3 Debugging-Related Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636

7 Packaging (numpy.distutils) 1637

7.1 Modules in numpy.distutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1637
7.2 Configuration class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1644
7.3 Building Installable C libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1653
7.4 Conversion of .src files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654

8 NumPy Distutils - Users Guide 1655

8.1 SciPy structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1655
8.2 Requirements for SciPy packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1655
8.3 The setup.py file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656
8.4 The __init__.py file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
8.5 Extra features in NumPy Distutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663

9 NumPy C-API 1665

9.1 Python Types and C-Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665
9.2 System configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
9.3 Data Type API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
9.4 Array API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1690
9.5 Array Iterator API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732
9.6 UFunc API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
9.7 Generalized Universal Function API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
9.8 NumPy core libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
9.9 C API Deprecations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1764

10 NumPy internals 1765

10.1 NumPy C Code Explanations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1765
10.2 Memory Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772
10.3 Internal organization of numpy arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1774
10.4 Multidimensional Array Indexing Order Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1774

11 SIMD Optimizations 1777

11.1 Build options for compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1777
11.2 Understanding CPU Dispatching, How the NumPy dispatcher works? . . . . . . . . . . . . . . . . . . 1781

ii
 11.3 Dive into the CPU dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787

12 NumPy and SWIG 1789

12.1 Testing the numpy.i Typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1805

13 Acknowledgements 1809

Bibliography 1811

Python Module Index 1823

Index 1825

iii
iv
 NumPy Reference, Release 1.20.0

Release
1.20
Date
January 31, 2021
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 the complete documentation.

CONTENTS 1
NumPy Reference, Release 1.20.0

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 homogeneous: 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.20.0

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

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, homoge-
neous 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 param-
eters 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.20.0

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:

1.1. The N-dimensional array (ndarray) 5

NumPy Reference, Release 1.20.0

>>> 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.
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 module.
base
[ndarray] Base object if memory is from some other object.

6 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Methods

all([axis, out, keepdims, where]) Returns True if all elements evaluate to True.
any([axis, out, keepdims, where]) 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.
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, where]) 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 dif-
ferent 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 posi-
tion 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

1.1. The N-dimensional array (ndarray) 7

NumPy Reference, Release 1.20.0

Table 2 – 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 num-
ber 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 axes of length one from a.
std([axis, dtype, out, ddof, keepdims, where]) 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 inter-
changed.
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]) A compatibility alias for tobytes, with exactly the
same behavior.
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, where]) 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, *, where=True)
Returns True if all elements evaluate to True.
Refer to numpy.all for full documentation.
See also:

numpy.all
equivalent function

method

8 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

ndarray.any(axis=None, out=None, keepdims=False, *, where=True)

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

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

1.1. The N-dimensional array (ndarray) 9

NumPy Reference, Release 1.20.0

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 re-
turned 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).

10 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.1. The N-dimensional array (ndarray) 11

NumPy Reference, Release 1.20.0

A.newbyteorder().byteswap() produces an array with the same values

but different representation 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
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:

12 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

numpy.conjugate
equivalent function

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

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

1.1. The N-dimensional array (ndarray) 13

NumPy Reference, Release 1.20.0

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

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

14 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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.
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.1. The N-dimensional array (ndarray) 15

NumPy Reference, Release 1.20.0

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.
offset
[int] Number of bytes to skip before beginning the element view.

16 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

NumPy Reference, Release 1.20.0

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

18 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
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, *, where=True)
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
• {‘<’, ‘little’} - little endian
• {‘>’, ‘big’} - big endian
• ‘=’ - native order, equivalent to sys.byteorder

1.1. The N-dimensional array (ndarray) 19

NumPy Reference, Release 1.20.0

• {‘|’, ‘I’} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order.

Returns

new_arr
[array] New array object with the dtype reflecting given change to the byte order.

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.

20 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.1. The N-dimensional array (ndarray) 21

NumPy Reference, Release 1.20.0

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

22 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

1.1. The N-dimensional array (ndarray) 23

NumPy Reference, Release 1.20.0

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

24 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.1. The N-dimensional array (ndarray) 25

NumPy Reference, Release 1.20.0

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, UPDATEIF-
COPY, 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 compiler);
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
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.

26 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 default is
‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers and, in gen-
eral, 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.

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

1.1. The N-dimensional array (ndarray) 27

NumPy Reference, Release 1.20.0

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 axes of length one from 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, *, where=True)
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:

numpy.swapaxes
equivalent function

method

28 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 is produced
in C-order by default. This behavior is controlled by the order parameter.
New in version 1.9.0.
Parameters

order
[{‘C’, ‘F’, ‘A’}, optional] Controls the memory layout of the bytes object. ‘C’ means C-order,
‘F’ means F-order, ‘A’ (short for Any) means ‘F’ if a is Fortran contiguous, ‘C’ otherwise.
Default is ‘C’.

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.

1.1. The N-dimensional array (ndarray) 29

NumPy Reference, Release 1.20.0

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
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 pre-
cision.

30 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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])]
>>> 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’)
A compatibility alias for tobytes, with exactly the same behavior.
Despite its name, it returns bytes not strs.
Deprecated since version 1.19.0.
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.

1.1. The N-dimensional array (ndarray) 31

NumPy Reference, Release 1.20.0

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 or-
der 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.

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, *, where=True)
Returns the variance of the array elements, along given axis.
Refer to numpy.var for full documentation.

32 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

See also:

numpy.var
equivalent function

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

Note: Passing None for dtype is different from omitting the parameter, since the former invokes
dtype(None) which is an alias for dtype('float_').

Parameters

dtype
[data-type or ndarray sub-class, optional] Data-type descriptor of the returned view, e.g.,
float32 or int16. Omitting it 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, omission
of the parameter 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 reinterpre-
tation of the memory.
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.

1.1. The N-dimensional array (ndarray) 33

NumPy Reference, Release 1.20.0

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

34 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 (n0 , n1 , ..., nN −1 ) corresponds to the offset (in bytes):

X
N −1
noffset = sk nk
k=0

from the beginning of the memory block associated with the array. Here, sk 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
(used in C) schemes are just specific kinds of strided scheme, and correspond to memory that can be addressed by the
strides:
Y
k−1 Y
N −1
scolumn
k = itemsize dj , srow
k = itemsize dj .
j=0 j=k+1

where dj = 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.

Note: Contiguous arrays and single-segment arrays are synonymous and are used interchangeably throughout the docu-
mentation.

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 nk = 0 and thus sk nk = 0 and the value of sk = 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) can currently be disabled by the compile time environmental variable
NPY_RELAXED_STRIDES_CHECKING=0, which was the default before NumPy 1.10. No users should have

1.1. The N-dimensional array (ndarray) 35

NumPy Reference, Release 1.20.0

to do this. NPY_RELAXED_STRIDES_DEBUG=1 can be used to help find errors when incorrectly relying on the
strides in C-extension code (see below warning).
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 en-
abled.

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

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

36 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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)

1.1. The N-dimensional array (ndarray) 37

NumPy Reference, Release 1.20.0

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

38 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: Incompatible shape for in-place modification. Use
`.reshape()` to make a copy with the desired shape.

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])
(continues on next page)

1.1. The N-dimensional array (ndarray) 39

NumPy Reference, Release 1.20.0

(continued from previous page)

>>> offset = sum(i * x.strides)
>>> 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 ob-
taining 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.

40 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

NumPy Reference, Release 1.20.0

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

42 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

See also:

transpose

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

1.1. The N-dimensional array (ndarray) 43

NumPy Reference, Release 1.20.0

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

44 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 at-
tribute. This ctypes array contains the strides information from the underlying array. This strides information
is important for showing how many bytes must be jumped to get to the next element in the array.
_ctypes.data_as(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(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(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) 45

NumPy Reference, Release 1.20.0

Examples

>>> import ctypes

>>> x = np.array([[0, 1], [2, 3]], dtype=np.int32)
>>> x
array([[0, 1],
[2, 3]], dtype=int32)
>>> x.ctypes.data
31962608 # may vary
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32))
<__main__.LP_c_uint object at 0x7ff2fc1fc200> # may vary
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32)).contents
c_uint(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint64)).contents
c_ulong(4294967296)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x7ff2fc1fce60> # may vary
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x7ff2fc1ff320> # may vary

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.

46 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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]) A compatibility alias for tobytes, with exactly the same
behavior.
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 axes of length one from 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) 47

NumPy Reference, Release 1.20.0

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 = np.arange(27).reshape((3,3,3))
>>> 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]]),
(continues on next page)

48 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

array([[ 3, 12, 21],
[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.
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, where]) Returns the average of the array elements along given
axis.
ndarray.var([axis, dtype, out, ddof, …]) Returns the variance of the array elements, along given
axis.
ndarray.std([axis, dtype, out, ddof, …]) 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, where]) Returns True if all elements evaluate to True.
ndarray.any([axis, out, keepdims, where]) Returns True if any of the elements of a evaluate to True.

1.1. The N-dimensional array (ndarray) 49

NumPy Reference, Release 1.20.0

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__(value, /) Return self<value.

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

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

ndarray.__bool__(/) self != 0

method
ndarray.__bool__(/ )
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 to

50 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
ndarray.__pos__(/) +self
ndarray.__abs__(self)
ndarray.__invert__(/) ~self

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

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

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

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

1.1. The N-dimensional array (ndarray) 51

NumPy Reference, Release 1.20.0

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

Note:
• Any third argument to pow is silently ignored, as the underlying ufunc takes only two arguments.
• 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:

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

ndarray.__isub__(value, /) Return self-=value.
Continued on next page

52 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Table 15 – continued from previous page

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

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

1.1. The N-dimensional array (ndarray) 53

NumPy Reference, Release 1.20.0

ndarray.__ior__(value, / )
Return self|=value.
method
ndarray.__ixor__(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 pre-
cision 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 computation, 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__(value, /) Return self@value.

method
ndarray.__matmul__(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__(memo, /) 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__(memo, / ) → Deep copy of array.
Used if copy.deepcopy is called on an array.
method
ndarray.__reduce__()
For pickling.
method

54 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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__([dtype], /) 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__(obj)

method
ndarray.__new__(*args, **kwargs)
Create and return a new object. See help(type) for accurate signature.
method
ndarray.__array__([dtype ], / ) → reference if type unchanged, copy otherwise.
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__(obj) → Object of same type as ndarray object a.
Container customization: (see Indexing)

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

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

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

1.1. The N-dimensional array (ndarray) 55

NumPy Reference, Release 1.20.0

method
ndarray.__getitem__(key, / )
Return self[key].
method
ndarray.__setitem__(key, value, / )
Set self[key] to value.
method
ndarray.__contains__(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__(/) Return str(self).

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

method
ndarray.__str__(/ )
Return str(self).
method
ndarray.__repr__(/ )
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.

56 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 ex-
ample 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 (str_,
bytes_, void).

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 However, array scalars are immutable, so none of the array scalar attributes are settable.

1.2. Scalars 57
NumPy Reference, Release 1.20.0

1.2.1 Built-in scalar types

The built-in scalar types are shown below. The C-like names are associated with character codes, which are shown in
their descriptions. 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 Inherits?

int_ int Python 2 only
float_ float yes
complex_ complex yes
bytes_ bytes yes
str_ str yes
bool_ bool no
datetime64 datetime.datetime no
timedelta64 datetime.timedelta no

The bool_ data type is very similar to the Python bool but does not inherit from it because Python’s bool 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 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_.

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.
class numpy.number
Abstract base class of all numeric scalar types.

Integer types

class numpy.integer
Abstract base class of all integer scalar types.

58 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Signed integer types

class numpy.signedinteger
Abstract base class of all signed integer scalar types.
class numpy.byte
Signed integer type, compatible with C char.
Character code
'b'
Alias on this platform
numpy.int8: 8-bit signed integer (-128 to 127).
class numpy.short
Signed integer type, compatible with C short.
Character code
'h'
Alias on this platform
numpy.int16: 16-bit signed integer (-32_768 to 32_767).
class numpy.intc
Signed integer type, compatible with C int.
Character code
'i'
Alias on this platform
numpy.int32: 32-bit signed integer (-2_147_483_648 to 2_147_483_647).
class numpy.int_
Signed integer type, compatible with Python int and C long.
Character code
'l'
Alias on this platform
numpy.int64: 64-bit signed integer (-9_223_372_036_854_775_808 to
9_223_372_036_854_775_807).
Alias on this platform
numpy.intp: Signed integer large enough to fit pointer, compatible with C intptr_t.
class numpy.longlong
Signed integer type, compatible with C long long.
Character code
'q'

1.2. Scalars 59
NumPy Reference, Release 1.20.0

Unsigned integer types

class numpy.unsignedinteger
Abstract base class of all unsigned integer scalar types.
class numpy.ubyte
Unsigned integer type, compatible with C unsigned char.
Character code
'B'
Alias on this platform
numpy.uint8: 8-bit unsigned integer (0 to 255).
class numpy.ushort
Unsigned integer type, compatible with C unsigned short.
Character code
'H'
Alias on this platform
numpy.uint16: 16-bit unsigned integer (0 to 65_535).
class numpy.uintc
Unsigned integer type, compatible with C unsigned int.
Character code
'I'
Alias on this platform
numpy.uint32: 32-bit unsigned integer (0 to 4_294_967_295).
class numpy.uint
Unsigned integer type, compatible with C unsigned long.
Character code
'L'
Alias on this platform
numpy.uint64: 64-bit unsigned integer (0 to 18_446_744_073_709_551_615).
Alias on this platform
numpy.uintp: Unsigned integer large enough to fit pointer, compatible with C uintptr_t.
class numpy.ulonglong
Signed integer type, compatible with C unsigned long long.
Character code
'Q'

60 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Inexact types

class numpy.inexact
Abstract base class of all numeric scalar types with a (potentially) inexact representation of the values in its range,
such as floating-point numbers.

Floating-point types
class numpy.floating
Abstract base class of all floating-point scalar types.
class numpy.half
Half-precision floating-point number type.
Character code
'e'
Alias on this platform
numpy.float16: 16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits
mantissa.
class numpy.single
Single-precision floating-point number type, compatible with C float.
Character code
'f'
Alias on this platform
numpy.float32: 32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits
mantissa.
class numpy.double
Double-precision floating-point number type, compatible with Python float and C double.
Character code
'd'
Alias
numpy.float_
Alias on this platform
numpy.float64: 64-bit precision floating-point number type: sign bit, 11 bits exponent, 52
bits mantissa.
class numpy.longdouble
Extended-precision floating-point number type, compatible with C long double but not necessarily with IEEE
754 quadruple-precision.
Character code
'g'
Alias
numpy.longfloat
Alias on this platform
numpy.float128: 128-bit extended-precision floating-point number type.

1.2. Scalars 61
NumPy Reference, Release 1.20.0

Complex floating-point types

class numpy.complexfloating
Abstract base class of all complex number scalar types that are made up of floating-point numbers.
class numpy.csingle
Complex number type composed of two single-precision floating-point numbers.
Character code
'F'
Alias
numpy.singlecomplex
Alias on this platform
numpy.complex64: Complex number type composed of 2 32-bit-precision floating-point num-
bers.
class numpy.cdouble
Complex number type composed of two double-precision floating-point numbers, compatible with Python
complex.
Character code
'D'
Alias
numpy.cfloat
Alias
numpy.complex_
Alias on this platform
numpy.complex128: Complex number type composed of 2 64-bit-precision floating-point
numbers.
class numpy.clongdouble
Complex number type composed of two extended-precision floating-point numbers.
Character code
'G'
Alias
numpy.clongfloat
Alias
numpy.longcomplex
Alias on this platform
numpy.complex256: Complex number type composed of 2 128-bit extended-precision
floating-point numbers.

62 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Other types

class numpy.bool_
Boolean type (True or False), stored as a byte.

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.

Character code
'?'
Alias
numpy.bool8

class numpy.datetime64
A datetime stored as a 64-bit integer, counting from 1970-01-01T00:00:00.

>>> np.datetime64(10, 'Y')

numpy.datetime64('1980')
>>> np.datetime64(10, 'D')
numpy.datetime64('1970-01-11')

See Datetimes and Timedeltas for more information.

Character code
'M'
class numpy.timedelta64
A timedelta stored as a 64-bit integer.
See Datetimes and Timedeltas for more information.
Character code
'm'
class numpy.object_
Any Python object.
Character code
'O'

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.)
class numpy.flexible
Abstract base class of all scalar types without predefined length. The actual size of these types depends on the
specific np.dtype instantiation.

1.2. Scalars 63
NumPy Reference, Release 1.20.0

class numpy.bytes_
A byte string.
When used in arrays, this type strips trailing null bytes.
Character code
'S'
Alias
numpy.string_
class numpy.str_
A unicode string.
When used in arrays, this type strips trailing null codepoints.
Unlike the builtin str, this supports the Buffer Protocol, exposing its contents as UCS4:

>>> m = memoryview(np.str_("abc"))
>>> m.format
'3w'
>>> m.tobytes()
b'a\x00\x00\x00b\x00\x00\x00c\x00\x00\x00'

Character code
'U'
Alias
numpy.unicode_

class numpy.void
Either an opaque sequence of bytes, or a structure.

>>> np.void(b'abcd')
void(b'\x61\x62\x63\x64')

Structured void scalars can only be constructed via extraction from structured_arrays:

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

>>> arr[()]
(1, 2) # looks like a tuple, but is `np.void`

Character code
'V'

Warning: See Note on string types.

Numeric Compatibility: If you used old typecode characters in your Numeric code (which was never recommended),
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.

64 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Sized aliases

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. Two aliases (numpy.intp and numpy.uintp)
pointing to the integer type that is sufficiently large to hold a C pointer are also provided.
numpy.bool8
alias of numpy.bool_
numpy.int8
numpy.int16
numpy.int32
numpy.int64
Aliases for the signed integer types (one of numpy.byte, numpy.short, numpy.intc, numpy.int_ and
numpy.longlong) with the specified number of bits.
Compatible with the C99 int8_t, int16_t, int32_t, and int64_t, respectively.
numpy.uint8
numpy.uint16
numpy.uint32
numpy.uint64
Alias for the unsigned integer types (one of numpy.byte, numpy.short, numpy.intc, numpy.int_ and
numpy.longlong) with the specified number of bits.
Compatible with the C99 uint8_t, uint16_t, uint32_t, and uint64_t, respectively.
numpy.intp
Alias for the signed integer type (one of numpy.byte, numpy.short, numpy.intc, numpy.int_ and
np.longlong) that is the same size as a pointer.
Compatible with the C intptr_t.
Character code
'p'
numpy.uintp
Alias for the unsigned integer type (one of numpy.byte, numpy.short, numpy.intc, numpy.int_ and
np.longlong) that is the same size as a pointer.
Compatible with the C uintptr_t.
Character code
'P'
numpy.float16
alias of numpy.half
numpy.float32
alias of numpy.single
numpy.float64
alias of numpy.double
numpy.float96
numpy.float128
Alias for numpy.longdouble, named after its size in bits. The existence of these aliases depends on the
platform.
numpy.complex64
alias of numpy.csingle

1.2. Scalars 65
NumPy Reference, Release 1.20.0

numpy.complex128
alias of numpy.cdouble
numpy.complex192
numpy.complex256
Alias for numpy.clongdouble, named after its size in bits. The existance of these aliases depends on the
platform.

Other aliases

The first two of these are conveniences which resemble the names of the builtin types, in the same style as bool_, int_,
str_, bytes_, and object_:
numpy.float_
alias of numpy.double
numpy.complex_
alias of numpy.cdouble
Some more use alternate naming conventions for extended-precision floats and complex numbers:
numpy.longfloat
alias of numpy.longdouble
numpy.singlecomplex
alias of numpy.csingle
numpy.cfloat
alias of numpy.cdouble
numpy.longcomplex
alias of numpy.clongdouble
numpy.clongfloat
alias of numpy.clongdouble
The following aliases originate from Python 2, and it is recommended that they not be used in new code.
numpy.string_
alias of numpy.bytes_
numpy.unicode_
alias of numpy.str_

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 The integer value of flags.

generic.shape Tuple of array dimensions.
generic.strides Tuple of bytes steps in each dimension.
generic.ndim The number of array dimensions.
generic.data Pointer to start of data.
generic.size The number of elements in the gentype.
generic.itemsize The length of one element in bytes.
Continued on next page

66 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Table 22 – continued from previous page

generic.base Scalar attribute identical to the corresponding array at-
tribute.
generic.dtype Get array data-descriptor.
generic.real The real part of the scalar.
generic.imag The imaginary part of the scalar.
generic.flat A 1-D view of the scalar.
generic.T Scalar attribute identical to the corresponding array at-
tribute.
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
The integer value of flags.
attribute
generic.shape
Tuple of array dimensions.
attribute
generic.strides
Tuple of bytes steps in each dimension.
attribute
generic.ndim
The number of array dimensions.
attribute
generic.data
Pointer to start of data.
attribute
generic.size
The number of elements in the gentype.
attribute
generic.itemsize
The length of one element in bytes.
attribute
generic.base
Scalar attribute identical to the corresponding array attribute.
Please see ndarray.base.
attribute
generic.dtype
Get array data-descriptor.
attribute

1.2. Scalars 67
NumPy Reference, Release 1.20.0

generic.real
The real part of the scalar.
attribute
generic.imag
The imaginary part of the scalar.
attribute
generic.flat
A 1-D view of the scalar.
attribute
generic.T
Scalar attribute identical to the corresponding array attribute.
Please see ndarray.T.
attribute
generic.__array_interface__
Array protocol: Python side
attribute
generic.__array_struct__
Array protocol: struct
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.)

68 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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.__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 Scalar method identical to the corresponding array at-
tribute.
generic.byteswap Scalar method identical to the corresponding array at-
tribute.
generic.__reduce__ Helper for pickle.
generic.__setstate__
generic.setflags Scalar method identical to the corresponding array at-
tribute.

method
generic.__array__()
sc.__array__(dtype) return 0-dim array from scalar with specified dtype
method
generic.squeeze()
Scalar method identical to the corresponding array attribute.
Please see ndarray.squeeze.
method
generic.byteswap()
Scalar method identical to the corresponding array attribute.
Please see ndarray.byteswap.
method
generic.__reduce__()
Helper for pickle.
method
generic.__setstate__()
method
generic.setflags()
Scalar method identical to the corresponding array attribute.
Please see ndarray.setflags.

1.2. Scalars 69
NumPy Reference, Release 1.20.0

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),
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
(continues on next page)

70 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

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(('<f8', (2,)))

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

>>> x = np.array([('Sarah', (8.0, 7.0)), ('John', (6.0, 7.0))], dtype=dt)

>>> x[1]
('John', [6., 7.])
>>> x[1]['grades']
array([6., 7.])
>>> type(x[1])
<class 'numpy.void'>
>>> type(x[1]['grades'])
<class '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
Attributes

class numpy.dtype
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

1.3. Data type objects (dtype) 71

NumPy Reference, Release 1.20.0

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.
itemsize
The element size of this data-type object.
kind
A character code (one of ‘biufcmMOSUV’) identifying the general kind of data.
metadata
Either None or a readonly dictionary of metadata (mappingproxy).
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.

72 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

subdtype
Tuple (item_dtype, shape) if this dtype describes a sub-array, and None otherwise.
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
• {‘<’, ‘little’} - little endian
• {‘>’, ‘big’} - big endian
• ‘=’ - native order
• {‘|’, ‘I’} - ignore (no change to byte order)

Returns

new_dtype
[dtype] New dtype object with the given change to the byte order.

Notes

Changes are also made in all fields and sub-arrays of the data type.

Examples

>>> import sys

>>> sys_is_le = sys.byteorder == 'little'
>>> native_code = sys_is_le and '<' or '>'
>>> swapped_code = sys_is_le and '>' or '<'
>>> native_dt = np.dtype(native_code+'i2')
>>> swapped_dt = np.dtype(swapped_code+'i2')
>>> native_dt.newbyteorder('S') == swapped_dt
True
>>> native_dt.newbyteorder() == swapped_dt
True
(continues on next page)

1.3. Data type objects (dtype) 73

NumPy Reference, Release 1.20.0

(continued from previous page)

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

Deprecated since version 1.19: This conversion of generic scalar types is deprecated. This is because it can be
unexpected in a context such as arr.astype(dtype=np.floating), which casts an array of float32
to an array of float64, even though float32 is a subdtype of np.floating.
Built-in Python types

74 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

Note: All other types map to object_ for convenience. Code should expect that such types may map to a
specific (new) dtype in the future.

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)

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

1.3. Data type objects (dtype) 75

NumPy Reference, Release 1.20.0

'?' 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 numpy.
string_ continues to alias numpy.bytes_. To use actual strings in Python 3 use U or numpy.str_. 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

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

76 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

• 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 used to be equivalent to fixed
dtype. This behaviour is deprecated since NumPy 1.17 and will raise an error in the future. 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(('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 assigned). 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.
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.

1.3. Data type objects (dtype) 77

NumPy Reference, Release 1.20.0

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 object, but when a str object 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': [np.uint8, np.uint8, np.uint8, np.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.

Example
Data type containing field col1 (10-character string at byte position 0), col2 (32-bit float at byte position 10),
and col3 (integers at byte position 14):

78 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

>>> dt = np.dtype({'col1': ('U10', 0), 'col2': (np.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
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.

attribute
dtype.type = None
attribute

1.3. Data type objects (dtype) 79

NumPy Reference, Release 1.20.0

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.

80 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.3. Data type objects (dtype) 81

NumPy Reference, Release 1.20.0

Endianness of this data:

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

ject.

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
Dictionary of named fields defined for this data type, or None.

82 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.3. Data type objects (dtype) 83

NumPy Reference, Release 1.20.0

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 interpreted.
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.
Bit-masks are in numpy.core.multiarray as the constants ITEM_HASOBJECT, LIST_PICKLE,

84 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.3. Data type objects (dtype) 85

NumPy Reference, Release 1.20.0

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

Metadata attached by the user:

dtype.metadata Either None or a readonly dictionary of metadata (map-

pingproxy).

attribute
dtype.metadata

86 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Either None or a readonly dictionary of metadata (mappingproxy).

The metadata field can be set using any dictionary at data-type creation. NumPy currently has no uniform approach
to propagating metadata; although some array operations preserve it, there is no guarantee that others will.

Warning: Although used in certain projects, this feature was long undocumented and is not well supported.
Some aspects of metadata propagation are expected to change in the future.

Examples

>>> dt = np.dtype(float, metadata={"key": "value"})

>>> dt.metadata["key"]
'value'
>>> arr = np.array([1, 2, 3], dtype=dt)
>>> arr.dtype.metadata
mappingproxy({'key': 'value'})

Adding arrays with identical datatypes currently preserves the metadata:

>>> (arr + arr).dtype.metadata

mappingproxy({'key': 'value'})

But if the arrays have different dtype metadata, the metadata may be dropped:

>>> dt2 = np.dtype(float, metadata={"key2": "value2"})

>>> arr2 = np.array([3, 2, 1], dtype=dt2)
>>> (arr + arr2).dtype.metadata is None
True # The metadata field is cleared so None is returned

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.3. Data type objects (dtype) 87

NumPy Reference, Release 1.20.0

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 lat-
ter 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) containing 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 ni , the valid range is 0 ≤ ni < di where di 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 ni < 0, it means ni + di ).
All arrays generated by basic slicing are always views of the original array.

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 (k ̸= 0).
This selects the m elements (in the corresponding dimension) with index values i, i + k, …, i + (m - 1) k where
m = q + (r ̸= 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

88 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

1.4. Indexing 89
NumPy Reference, Release 1.20.0

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

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 compat-
ibility 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.

90 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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:

>>> x = np.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_:

1.4. Indexing 91
NumPy Reference, Release 1.20.0

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

92 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

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 = np.array([[ 0, 1, 2],

... [ 3, 4, 5],
(continues on next page)

1.4. Indexing 93
NumPy Reference, Release 1.20.0

(continued from previous page)

... [ 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, only the diagonal elements would be selected.
Or without np.ix_ (compare the integer array examples):

>>> 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__ be-
haviour 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.

94 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

Note: Arrays support the iterator protocol and can be iterated over like Python lists. See the quickstart.indexing-slicing-
and-iterating section in the Quickstart guide for basic usage and examples. The remainder of this document presents the
nditer object and covers more advanced usage.

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. Iterating Over Arrays 95

NumPy Reference, Release 1.20.0

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.

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=' ')
(continues on next page)

96 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

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

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

1.5. Iterating Over Arrays 97

NumPy Reference, Release 1.20.0

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

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):
(continues on next page)

98 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

File "<stdin>", line 1, in <module>
ValueError: Iterator flag EXTERNAL_LOOP cannot be used if an index or multi-index is␣
,→being tracked

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=' ')
... is_not_finished = 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=' ')
... is_not_finished = 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]
... is_not_finished = 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

1.5. Iterating Over Arrays 99

NumPy Reference, Release 1.20.0

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

>>> 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 temporary
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']):
(continues on next page)

100 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

... print(np.sqrt(x), end=' ')
...
1.7320508075688772j 1.4142135623730951j 1j 0j (1+0j) (1.4142135623730951+0j)

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

... print(np.sqrt(x), end=' ')
...
1.7320508075688772j 1.4142135623730951j 1j 0j (1+0j) (1.4142135623730951+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
(continues on next page)

1.5. Iterating Over Arrays 101

NumPy Reference, Release 1.20.0

(continued from previous page)

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

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):
...
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 additionally
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

102 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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):
...
ValueError: non-broadcastable output operand with shape (3,) doesn't
match the broadcast shape (2,3)

1.5. Iterating Over Arrays 103

NumPy Reference, Release 1.20.0

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)

104 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

>>> with np.nditer([a, b], flags=['reduce_ok'],
... 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'],
... 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 buffering.
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',
... '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)

1.5. Iterating Over Arrays 105

NumPy Reference, Release 1.20.0

(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',
... '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)

106 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.5. Iterating Over Arrays 107

NumPy Reference, Release 1.20.0

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

108 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 109

NumPy Reference, Release 1.20.0

system might have an object m representing the “meters” unit, and want to support the syntax arr * m to rep-
resent that the array has units of “meters”, but not want to otherwise interact with arrays via ufuncs or otherwise.
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 gener-
ically 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).
• types is a collection collections.abc.Collection of unique argument types from the original
NumPy function call that implement __array_function__.

110 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

• 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). Op-
tional arguments are only passed in to __array_function__ if they were explicitly used in the NumPy func-
tion call.
Just like the case for builtin special methods like __add__, properly written __array_function__ methods
should always return NotImplemented when an unknown type is encountered. Otherwise, it will be impossible
to correctly override NumPy functions from another object if the operation also includes one of your objects.

1.6. Standard array subclasses 111

NumPy Reference, Release 1.20.0

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, in-
tended for use on NumPy arrays. This case arises, for example, when all array-like arguments are Python num-
bers 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 call-
ing 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 implementation 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.

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

112 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

will not be written to the object returned by __array__. This practice will return TypeError.

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

See also:

transpose, getH

1.6. Standard array subclasses 113

NumPy Reference, Release 1.20.0

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

114 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

numpy.linalg.LinAlgError: Singular matrix

If self is singular.

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.

1.6. Standard array subclasses 115

NumPy Reference, Release 1.20.0

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.

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

116 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 117

NumPy Reference, Release 1.20.0

size
Number of elements in the array.
strides
Tuple of bytes to step in each dimension when traversing an array.

Methods

all([axis, out]) Test whether all matrix elements along a given axis
evaluate to True.
any([axis, out]) Test whether any array element along a given axis eval-
uates to True.
argmax([axis, out]) Indexes of the maximum values along an axis.
argmin([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.
flatten([order]) Return a flattened copy of the matrix.
getA() Return self as an ndarray object.
getA1() Return self as a flattened ndarray.
getH() Returns the (complex) conjugate transpose of self.
getI() Returns the (multiplicative) inverse of invertible self.
getT() 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([axis, out]) Return the maximum value along an axis.
mean([axis, dtype, out]) Returns the average of the matrix elements along the
given axis.
min([axis, out]) Return the minimum value along an axis.
Continued on next page

118 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Table 37 – continued from previous page

newbyteorder([new_order]) Return the array with the same data viewed with a dif-
ferent 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 posi-
tion it would be in a sorted array.
prod([axis, dtype, out]) Return the product of the array elements over the given
axis.
ptp([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([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 num-
ber 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]) Return a possibly reshaped matrix.
std([axis, dtype, out, ddof]) Return the standard deviation of the array elements
along the given axis.
sum([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 inter-
changed.
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 matrix as a (possibly nested) list.
tostring([order]) A compatibility alias for tobytes, with exactly the
same behavior.
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]) 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(axis=None, out=None)
Test whether all matrix elements along a given axis evaluate to True.

1.6. Standard array subclasses 119

NumPy Reference, Release 1.20.0

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(axis=None, out=None)
Test whether any array element along a given axis evaluates to True.
Refer to numpy.any for full documentation.
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

120 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
matrix.argmax(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(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 121

NumPy Reference, Release 1.20.0

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.

122 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 re-
turned 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.

1.6. Standard array subclasses 123

NumPy Reference, Release 1.20.0

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, 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 representation 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)
(continues on next page)

124 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

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

1.6. Standard array subclasses 125

NumPy Reference, Release 1.20.0

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

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

126 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

1.6. Standard array subclasses 127

NumPy Reference, Release 1.20.0

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(order=’C’)
Return a flattened copy of the matrix.
All N elements of the matrix are placed into a single row.
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

128 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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()
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()
Return self as a flattened ndarray.
Equivalent to np.asarray(x).ravel()

1.6. Standard array subclasses 129

NumPy Reference, Release 1.20.0

Parameters

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()
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()
Returns the (multiplicative) inverse of invertible self.
Parameters

None

130 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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.

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

1.6. Standard array subclasses 131

NumPy Reference, Release 1.20.0

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

132 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

• 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 ele-
ment 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

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

1.6. Standard array subclasses 133

NumPy Reference, Release 1.20.0

[Arguments] If one argument: a scalar, only used in case a is of size 1. If two arguments:
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
matrix.max(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.

134 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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(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
>>> x.mean(0)
matrix([[4., 5., 6., 7.]])
>>> x.mean(1)
matrix([[ 1.5],
[ 5.5],
[ 9.5]])

method
matrix.min(axis=None, out=None)
Return the minimum value along an axis.
Parameters

See ‘amin‘ for complete descriptions.

See also:

1.6. Standard array subclasses 135

NumPy Reference, Release 1.20.0

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
• {‘<’, ‘little’} - little endian
• {‘>’, ‘big’} - big endian
• ‘=’ - native order, equivalent to sys.byteorder
• {‘|’, ‘I’} - ignore (no change to byte order)
The default value (‘S’) results in swapping the current byte order.

Returns

new_arr
[array] New array object with the dtype reflecting given change to the byte order.

method

136 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 137

NumPy Reference, Release 1.20.0

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

138 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 139

NumPy Reference, Release 1.20.0

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

140 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

1.6. Standard array subclasses 141

NumPy Reference, Release 1.20.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.
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.

142 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 143

NumPy Reference, Release 1.20.0

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, UPDATEIF-
COPY, 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 compiler);
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
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.

144 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

kind
[{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] Sorting algorithm. The default is
‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers and, in gen-
eral, 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.

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:

1.6. Standard array subclasses 145

NumPy Reference, Release 1.20.0

>>> 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(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 axes of length one 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]])
>>> r.squeeze()
matrix([[1, 2]])
>>> m = np.matrix([[1, 2], [3, 4]])
>>> m.squeeze()
matrix([[1, 2],
[3, 4]])

146 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
matrix.std(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(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

Notes

This is the same as ndarray.sum, except that where an ndarray would be returned, a matrix object
is returned instead.

1.6. Standard array subclasses 147

NumPy Reference, Release 1.20.0

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 is produced
in C-order by default. This behavior is controlled by the order parameter.
New in version 1.9.0.
Parameters

order
[{‘C’, ‘F’, ‘A’}, optional] Controls the memory layout of the bytes object. ‘C’ means C-order,
‘F’ means F-order, ‘A’ (short for Any) means ‘F’ if a is Fortran contiguous, ‘C’ otherwise.
Default is ‘C’.

Returns

148 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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()
Return the matrix as a (possibly nested) list.
See ndarray.tolist for full documentation.
See also:

1.6. Standard array subclasses 149

NumPy Reference, Release 1.20.0

ndarray.tolist

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’)
A compatibility alias for tobytes, with exactly the same behavior.
Despite its name, it returns bytes not strs.
Deprecated since version 1.19.0.
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 or-
der 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

150 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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
(continues on next page)

1.6. Standard array subclasses 151

NumPy Reference, Release 1.20.0

(continued from previous page)

>>> 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][, type])
New view of array with the same data.

Note: Passing None for dtype is different from omitting the parameter, since the former invokes
dtype(None) which is an alias for dtype('float_').

Parameters

dtype
[data-type or ndarray sub-class, optional] Data-type descriptor of the returned view, e.g.,
float32 or int16. Omitting it 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, omission
of the parameter 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 reinterpre-
tation of the memory.
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.

152 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 153

NumPy Reference, Release 1.20.0

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.

154 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

See also:

block
A generalization of this function for N-d arrays, that returns normal ndarrays.

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 = np.mat('1 2 3; 4 5 3')

>>> print((a*a.T).I)
[[ 0.29239766 -0.13450292]
[-0.13450292 0.08187135]]

Example 2: Matrix creation from nested sequence

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

>>> np.mat(np.random.rand(3,3)).T
matrix([[4.17022005e-01, 3.02332573e-01, 1.86260211e-01],
[7.20324493e-01, 1.46755891e-01, 3.45560727e-01],
[1.14374817e-04, 9.23385948e-02, 3.96767474e-01]])

1.6. Standard array subclasses 155

NumPy Reference, Release 1.20.0

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.

memmap Create a memory-map to an array stored in a binary file

on disk.
memmap.flush() 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.
Flush the memmap instance to write the changes to the file. Currently there is no API to close the underlying mmap.
It is tricky to ensure the resource is actually closed, since it may be shared between different memmap instances.
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

156 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 remain-
ing 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.

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:

1.6. Standard array subclasses 157

NumPy Reference, Release 1.20.0

>>> fp[:] = data[:]

>>> fp
memmap([[ 0., 1., 2., 3.],
[ 4., 5., 6., 7.],
[ 8., 9., 10., 11.]], dtype=float32)

>>> fp.filename == path.abspath(filename)

True

Flushes memory changes to disk in order to read them back

>>> fp.flush()

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:

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

158 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

>>> 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() Write any changes in the array to the file on disk.

method
memmap.flush()
Write any changes in the array to the file on disk.
For further information, see memmap.
Parameters

None

See also:

memmap

Example:

>>> a = np.memmap('newfile.dat', dtype=float, mode='w+', shape=1000)

>>> a[10] = 10.0
>>> a[30] = 30.0
>>> del a
>>> b = np.fromfile('newfile.dat', dtype=float)
>>> print(b[10], b[30])
10.0 30.0
>>> a = np.memmap('newfile.dat', dtype=float)
>>> print(a[10], a[30])
10.0 30.0

1.6. Standard array subclasses 159

NumPy Reference, Release 1.20.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 devel-
opment. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of dtype object_,
bytes_ or str_, and use the free functions in the numpy.char module for fast vectorized string operations.

These are enhanced arrays of either str_ type or bytes_ 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 str (and bytes)
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
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.

160 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

unicode
[bool, optional] Are the array elements of type unicode (True) or string (False). Default is
False.
buffer
[object exposing the buffer interface or str, 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 descrip-
tion). 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.

1.6. Standard array subclasses 161

NumPy Reference, Release 1.20.0

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

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(sub[, start, end]) Returns an array with the number of non-overlapping
occurrences of substring sub in the range [start, end].
decode([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([encoding, errors]) Calls str.encode element-wise.
endswith(suffix[, start, end]) Returns a boolean array which is True where the string
element in self ends with suffix, otherwise False.
expandtabs([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(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.
Continued on next page

162 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Table 41 – continued from previous page

getfield(dtype[, offset]) Returns a field of the given array as a certain type.
index(sub[, start, end]) Like find, but raises ValueError when the substring
is not found.
isalnum() Returns true for each element if all characters in the
string are alphanumeric and there is at least one char-
acter, false otherwise.
isalpha() Returns true for each element if all characters in the
string are alphabetic and there is at least one character,
false otherwise.
isdecimal() For each element in self, return True if there are only
decimal characters in the element.
isdigit() Returns true for each element if all characters in the
string are digits and there is at least one character, false
otherwise.
islower() 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() For each element in self, return True if there are only
numeric characters in the element.
isspace() Returns true for each element if there are only whites-
pace characters in the string and there is at least one
character, false otherwise.
istitle() Returns true for each element if the element is a title-
cased string and there is at least one character, false
otherwise.
isupper() Returns true for each element if all cased characters in
the string are uppercase and there is at least one char-
acter, false otherwise.
item(*args) Copy an element of an array to a standard Python
scalar and return it.
join(seq) Return a string which is the concatenation of the
strings in the sequence seq.
ljust(width[, fillchar]) Return an array with the elements of self left-justified
in a string of length width.
lower() Return an array with the elements of self converted to
lowercase.
lstrip([chars]) For each element in self, return a copy with the leading
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(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(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].
Continued on next page

1.6. Standard array subclasses 163

NumPy Reference, Release 1.20.0

Table 41 – continued from previous page

rindex(sub[, start, end]) Like rfind, but raises ValueError when the substring
sub is not found.
rjust(width[, fillchar]) Return an array with the elements of self right-
justified in a string of length width.
rsplit([sep, maxsplit]) For each element in self, return a list of the words in
the string, using sep as the delimiter string.
rstrip([chars]) For each element in self, return a copy with the trailing
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.
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([sep, maxsplit]) For each element in self, return a list of the words in
the string, using sep as the delimiter string.
splitlines([keepends]) For each element in self, return a list of the lines in the
element, breaking at line boundaries.
squeeze([axis]) Remove axes of length one from a.
startswith(prefix[, start, end]) Returns a boolean array which is True where the string
element in self starts with prefix, otherwise False.
strip([chars]) For each element in self, return a copy with the leading
and trailing characters removed.
swapaxes(axis1, axis2) Return a view of the array with axis1 and axis2 inter-
changed.
swapcase() 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() 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]) A compatibility alias for tobytes, with exactly the
same behavior.
translate(table[, deletechars]) For each element in self, return a copy of the string
where all characters occurring in the optional argu-
ment deletechars are removed, and the remaining char-
acters have been mapped through the given translation
table.
transpose(*axes) Returns a view of the array with axes transposed.
upper() Return an array with the elements of self converted to
uppercase.
view([dtype][, type]) New view of array with the same data.
zfill(width) Return the numeric string left-filled with zeros in a
string of length width.

164 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 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 re-
turned 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.6. Standard array subclasses 165

NumPy Reference, Release 1.20.0

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:

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

166 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 167

NumPy Reference, Release 1.20.0

None

method
chararray.encode(encoding=None, errors=None)
Calls str.encode element-wise.
See also:

char.encode

method
chararray.endswith(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(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
chararray.find(sub, start=0, end=None)
For each element, return the lowest index in the string where substring sub is found.
See also:

char.find

168 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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.

1.6. Standard array subclasses 169

NumPy Reference, Release 1.20.0

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(sub, start=0, end=None)
Like find, but raises ValueError when the substring is not found.
See also:

char.index

method
chararray.isalnum()
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()
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()
For each element in self, return True if there are only decimal characters in the element.
See also:

char.isdecimal

method

170 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

chararray.isdigit()
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

method
chararray.islower()
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()
For each element in self, return True if there are only numeric characters in the element.
See also:

char.isnumeric

method
chararray.isspace()
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()
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()
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

1.6. Standard array subclasses 171

NumPy Reference, Release 1.20.0

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

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(seq)
Return a string which is the concatenation of the strings in the sequence seq.
See also:

172 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

char.join

method
chararray.ljust(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()
Return an array with the elements of self converted to lowercase.
See also:

char.lower

method
chararray.lstrip(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.

1.6. Standard array subclasses 173

NumPy Reference, Release 1.20.0

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

174 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

1.6. Standard array subclasses 175

NumPy Reference, Release 1.20.0

>>> 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(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(sub, start=0, end=None)
Like rfind, but raises ValueError when the substring sub is not found.
See also:

char.rindex

method
chararray.rjust(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(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

176 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
chararray.rstrip(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 177

NumPy Reference, Release 1.20.0

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, UPDATEIF-
COPY, 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 compiler);
UPDATEIFCOPY (U) (deprecated), replaced by WRITEBACKIFCOPY;

178 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
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 default is
‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers and, in gen-
eral, 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

1.6. Standard array subclasses 179

NumPy Reference, Release 1.20.0

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

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

180 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
chararray.splitlines(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 axes of length one from a.
Refer to numpy.squeeze for full documentation.
See also:

numpy.squeeze
equivalent function

method
chararray.startswith(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(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()
For each element in self, return a copy of the string with uppercase characters converted to lowercase and
vice versa.
See also:

char.swapcase

1.6. Standard array subclasses 181

NumPy Reference, Release 1.20.0

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

182 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 pre-
cision.

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])]
>>> 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):
...
(continues on next page)

1.6. Standard array subclasses 183

NumPy Reference, Release 1.20.0

(continued from previous page)

TypeError: iteration over a 0-d array
>>> a.tolist()
1

method
chararray.tostring(order=’C’)
A compatibility alias for tobytes, with exactly the same behavior.
Despite its name, it returns bytes not strs.
Deprecated since version 1.19.0.
method
chararray.translate(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 or-
der 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.

184 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
chararray.upper()
Return an array with the elements of self converted to uppercase.
See also:

char.upper

method
chararray.view([dtype][, type])
New view of array with the same data.

Note: Passing None for dtype is different from omitting the parameter, since the former invokes
dtype(None) which is an alias for dtype('float_').

Parameters

dtype
[data-type or ndarray sub-class, optional] Data-type descriptor of the returned view, e.g.,
float32 or int16. Omitting it 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, omission
of the parameter results in type preservation.

1.6. Standard array subclasses 185

NumPy Reference, Release 1.20.0

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 reinterpre-
tation of the memory.
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.

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)

186 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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(width)
Return the numeric string left-filled with zeros in a string of length width.
See also:

char.zfill

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

1.6. Standard array subclasses 187

NumPy Reference, Release 1.20.0

[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 corre-
sponding 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,
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 for-
mats, names, titles, aligned and byteorder.

188 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 di-
rectly, 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:

core.records.fromrecords
Construct a record array from data.
record
fundamental data-type for recarray.
format_parser
determine a data-type from formats, names, titles.

1.6. Standard array subclasses 189

NumPy Reference, Release 1.20.0

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.

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.

190 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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([axis, out, keepdims, where]) Returns True if all elements evaluate to True.
any([axis, out, keepdims, where]) 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.
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].
Continued on next page

1.6. Standard array subclasses 191

NumPy Reference, Release 1.20.0

Table 43 – continued from previous page

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, where]) 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 dif-
ferent 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 posi-
tion 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 num-
ber 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.
Continued on next page

192 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Table 43 – continued from previous page

squeeze([axis]) Remove axes of length one from a.
std([axis, dtype, out, ddof, keepdims, where]) 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 inter-
changed.
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]) A compatibility alias for tobytes, with exactly the
same behavior.
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, where]) 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, *, where=True)
Returns True if all elements evaluate to True.
Refer to numpy.all for full documentation.
See also:

numpy.all
equivalent function

method
recarray.any(axis=None, out=None, keepdims=False, *, where=True)
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:

1.6. Standard array subclasses 193

NumPy Reference, Release 1.20.0

numpy.argmax
equivalent function

method
recarray.argmin(axis=None, out=None)
Return indices of the minimum values along the given axis.
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.
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’.

194 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 re-
turned 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.

1.6. Standard array subclasses 195

NumPy Reference, Release 1.20.0

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
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 representation 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)
(continues on next page)

196 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

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

1.6. Standard array subclasses 197

NumPy Reference, Release 1.20.0

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

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:

198 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 199

NumPy Reference, Release 1.20.0

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

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

200 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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:

1.6. Standard array subclasses 201

NumPy Reference, Release 1.20.0

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

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

202 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
recarray.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 arguments:
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, *, where=True)
Returns the average of the array elements along given axis.
Refer to numpy.mean for full documentation.

1.6. Standard array subclasses 203

NumPy Reference, Release 1.20.0

See also:

numpy.mean
equivalent function

method
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
• {‘<’, ‘little’} - little endian
• {‘>’, ‘big’} - big endian
• ‘=’ - native order, equivalent to sys.byteorder
• {‘|’, ‘I’} - ignore (no change to byte order)
The default value (‘S’) results in swapping the current byte order.

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:

204 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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 205

NumPy Reference, Release 1.20.0

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:

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.

206 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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.
refcheck
[bool, optional] If False, reference count will not be checked. Default is True.

Returns

None

Raises

1.6. Standard array subclasses 207

NumPy Reference, Release 1.20.0

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

>>> 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):
(continues on next page)

208 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

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

1.6. Standard array subclasses 209

NumPy Reference, Release 1.20.0

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

210 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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, UPDATEIF-
COPY, 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 compiler);
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
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.

1.6. Standard array subclasses 211

NumPy Reference, Release 1.20.0

kind
[{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional] Sorting algorithm. The default is
‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers and, in gen-
eral, 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.

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:

212 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

>>> 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 axes of length one from 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, *, where=True)
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:

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

1.6. Standard array subclasses 213

NumPy Reference, Release 1.20.0

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 is produced
in C-order by default. This behavior is controlled by the order parameter.
New in version 1.9.0.
Parameters

order
[{‘C’, ‘F’, ‘A’}, optional] Controls the memory layout of the bytes object. ‘C’ means C-order,
‘F’ means F-order, ‘A’ (short for Any) means ‘F’ if a is Fortran contiguous, ‘C’ otherwise.
Default is ‘C’.

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

214 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 pre-
cision.

1.6. Standard array subclasses 215

NumPy Reference, Release 1.20.0

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])]
>>> 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’)
A compatibility alias for tobytes, with exactly the same behavior.
Despite its name, it returns bytes not strs.
Deprecated since version 1.19.0.
method
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.

216 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 or-
der 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.

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
recarray.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True)
Returns the variance of the array elements, along given axis.
Refer to numpy.var for full documentation.

1.6. Standard array subclasses 217

NumPy Reference, Release 1.20.0

See also:

numpy.var
equivalent function

method
recarray.view([dtype][, type])
New view of array with the same data.

Note: Passing None for dtype is different from omitting the parameter, since the former invokes
dtype(None) which is an alias for dtype('float_').

Parameters

dtype
[data-type or ndarray sub-class, optional] Data-type descriptor of the returned view, e.g.,
float32 or int16. Omitting it 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, omission
of the parameter 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 reinterpre-
tation of the memory.
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.

218 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.6. Standard array subclasses 219

NumPy Reference, Release 1.20.0

field

class numpy.record
A data-type scalar that allows field access as attribute lookup.
Attributes

T
Scalar attribute identical to the corresponding array attribute.
base
base object
data
Pointer to start of data.
dtype
dtype object
flags
integer value of flags
flat
A 1-D view of the scalar.
imag
The imaginary part of the scalar.
itemsize
The length of one element in bytes.
nbytes
The length of the scalar in bytes.
ndim
The number of array dimensions.
real
The real part of the scalar.
shape
Tuple of array dimensions.
size
The number of elements in the gentype.
strides
Tuple of bytes steps in each dimension.

220 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Methods

all Scalar method identical to the corresponding array at-

tribute.
any Scalar method identical to the corresponding array at-
tribute.
argmax Scalar method identical to the corresponding array at-
tribute.
argmin Scalar method identical to the corresponding array at-
tribute.
argsort Scalar method identical to the corresponding array at-
tribute.
astype Scalar method identical to the corresponding array at-
tribute.
byteswap Scalar method identical to the corresponding array at-
tribute.
choose Scalar method identical to the corresponding array at-
tribute.
clip Scalar method identical to the corresponding array at-
tribute.
compress Scalar method identical to the corresponding array at-
tribute.
conjugate Scalar method identical to the corresponding array at-
tribute.
copy Scalar method identical to the corresponding array at-
tribute.
cumprod Scalar method identical to the corresponding array at-
tribute.
cumsum Scalar method identical to the corresponding array at-
tribute.
diagonal Scalar method identical to the corresponding array at-
tribute.
dump Scalar method identical to the corresponding array at-
tribute.
dumps Scalar method identical to the corresponding array at-
tribute.
fill Scalar method identical to the corresponding array at-
tribute.
flatten Scalar method identical to the corresponding array at-
tribute.
getfield Scalar method identical to the corresponding array at-
tribute.
item Scalar method identical to the corresponding array at-
tribute.
itemset Scalar method identical to the corresponding array at-
tribute.
max Scalar method identical to the corresponding array at-
tribute.
mean Scalar method identical to the corresponding array at-
tribute.
Continued on next page

1.6. Standard array subclasses 221

NumPy Reference, Release 1.20.0

Table 44 – continued from previous page

min Scalar method identical to the corresponding array at-
tribute.
newbyteorder([new_order]) Return a new dtype with a different byte order.
nonzero Scalar method identical to the corresponding array at-
tribute.
pprint() Pretty-print all fields.
prod Scalar method identical to the corresponding array at-
tribute.
ptp Scalar method identical to the corresponding array at-
tribute.
put Scalar method identical to the corresponding array at-
tribute.
ravel Scalar method identical to the corresponding array at-
tribute.
repeat Scalar method identical to the corresponding array at-
tribute.
reshape Scalar method identical to the corresponding array at-
tribute.
resize Scalar method identical to the corresponding array at-
tribute.
round Scalar method identical to the corresponding array at-
tribute.
searchsorted Scalar method identical to the corresponding array at-
tribute.
setfield Scalar method identical to the corresponding array at-
tribute.
setflags Scalar method identical to the corresponding array at-
tribute.
sort Scalar method identical to the corresponding array at-
tribute.
squeeze Scalar method identical to the corresponding array at-
tribute.
std Scalar method identical to the corresponding array at-
tribute.
sum Scalar method identical to the corresponding array at-
tribute.
swapaxes Scalar method identical to the corresponding array at-
tribute.
take Scalar method identical to the corresponding array at-
tribute.
tofile Scalar method identical to the corresponding array at-
tribute.
tolist Scalar method identical to the corresponding array at-
tribute.
tostring Scalar method identical to the corresponding array at-
tribute.
trace Scalar method identical to the corresponding array at-
tribute.
transpose Scalar method identical to the corresponding array at-
tribute.
Continued on next page

222 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Table 44 – continued from previous page

var Scalar method identical to the corresponding array at-
tribute.
view Scalar method identical to the corresponding array at-
tribute.

method
record.all()
Scalar method identical to the corresponding array attribute.
Please see ndarray.all.
method
record.any()
Scalar method identical to the corresponding array attribute.
Please see ndarray.any.
method
record.argmax()
Scalar method identical to the corresponding array attribute.
Please see ndarray.argmax.
method
record.argmin()
Scalar method identical to the corresponding array attribute.
Please see ndarray.argmin.
method
record.argsort()
Scalar method identical to the corresponding array attribute.
Please see ndarray.argsort.
method
record.astype()
Scalar method identical to the corresponding array attribute.
Please see ndarray.astype.
method
record.byteswap()
Scalar method identical to the corresponding array attribute.
Please see ndarray.byteswap.
method
record.choose()
Scalar method identical to the corresponding array attribute.
Please see ndarray.choose.
method

1.6. Standard array subclasses 223

NumPy Reference, Release 1.20.0

record.clip()
Scalar method identical to the corresponding array attribute.
Please see ndarray.clip.
method
record.compress()
Scalar method identical to the corresponding array attribute.
Please see ndarray.compress.
method
record.conjugate()
Scalar method identical to the corresponding array attribute.
Please see ndarray.conjugate.
method
record.copy()
Scalar method identical to the corresponding array attribute.
Please see ndarray.copy.
method
record.cumprod()
Scalar method identical to the corresponding array attribute.
Please see ndarray.cumprod.
method
record.cumsum()
Scalar method identical to the corresponding array attribute.
Please see ndarray.cumsum.
method
record.diagonal()
Scalar method identical to the corresponding array attribute.
Please see ndarray.diagonal.
method
record.dump()
Scalar method identical to the corresponding array attribute.
Please see ndarray.dump.
method
record.dumps()
Scalar method identical to the corresponding array attribute.
Please see ndarray.dumps.
method
record.fill()
Scalar method identical to the corresponding array attribute.
Please see ndarray.fill.

224 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
record.flatten()
Scalar method identical to the corresponding array attribute.
Please see ndarray.flatten.
method
record.getfield()
Scalar method identical to the corresponding array attribute.
Please see ndarray.getfield.
method
record.item()
Scalar method identical to the corresponding array attribute.
Please see ndarray.item.
method
record.itemset()
Scalar method identical to the corresponding array attribute.
Please see ndarray.itemset.
method
record.max()
Scalar method identical to the corresponding array attribute.
Please see ndarray.max.
method
record.mean()
Scalar method identical to the corresponding array attribute.
Please see ndarray.mean.
method
record.min()
Scalar method identical to the corresponding array attribute.
Please see ndarray.min.
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
• {‘<’, ‘little’} - little endian
• {‘>’, ‘big’} - big endian
• ‘=’ - native order
• {‘|’, ‘I’} - ignore (no change to byte order)

1.6. Standard array subclasses 225

NumPy Reference, Release 1.20.0

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.

Returns

new_dtype
[dtype] New dtype object with the given change to the byte order.

method
record.nonzero()
Scalar method identical to the corresponding array attribute.
Please see ndarray.nonzero.
method
record.pprint()
Pretty-print all fields.
method
record.prod()
Scalar method identical to the corresponding array attribute.
Please see ndarray.prod.
method
record.ptp()
Scalar method identical to the corresponding array attribute.
Please see ndarray.ptp.
method
record.put()
Scalar method identical to the corresponding array attribute.
Please see ndarray.put.
method
record.ravel()
Scalar method identical to the corresponding array attribute.
Please see ndarray.ravel.
method
record.repeat()
Scalar method identical to the corresponding array attribute.
Please see ndarray.repeat.
method
record.reshape()
Scalar method identical to the corresponding array attribute.
Please see ndarray.reshape.

226 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

method
record.resize()
Scalar method identical to the corresponding array attribute.
Please see ndarray.resize.
method
record.round()
Scalar method identical to the corresponding array attribute.
Please see ndarray.round.
method
record.searchsorted()
Scalar method identical to the corresponding array attribute.
Please see ndarray.searchsorted.
method
record.setfield()
Scalar method identical to the corresponding array attribute.
Please see ndarray.setfield.
method
record.setflags()
Scalar method identical to the corresponding array attribute.
Please see ndarray.setflags.
method
record.sort()
Scalar method identical to the corresponding array attribute.
Please see ndarray.sort.
method
record.squeeze()
Scalar method identical to the corresponding array attribute.
Please see ndarray.squeeze.
method
record.std()
Scalar method identical to the corresponding array attribute.
Please see ndarray.std.
method
record.sum()
Scalar method identical to the corresponding array attribute.
Please see ndarray.sum.
method
record.swapaxes()
Scalar method identical to the corresponding array attribute.

1.6. Standard array subclasses 227

NumPy Reference, Release 1.20.0

Please see ndarray.swapaxes.

method
record.take()
Scalar method identical to the corresponding array attribute.
Please see ndarray.take.
method
record.tofile()
Scalar method identical to the corresponding array attribute.
Please see ndarray.tofile.
method
record.tolist()
Scalar method identical to the corresponding array attribute.
Please see ndarray.tolist.
method
record.tostring()
Scalar method identical to the corresponding array attribute.
Please see ndarray.tostring.
method
record.trace()
Scalar method identical to the corresponding array attribute.
Please see ndarray.trace.
method
record.transpose()
Scalar method identical to the corresponding array attribute.
Please see ndarray.transpose.
method
record.var()
Scalar method identical to the corresponding array attribute.
Please see ndarray.var.
method
record.view()
Scalar method identical to the corresponding array attribute.
Please see ndarray.view.

conj
tobytes

228 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 ndar-
ray 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.

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 N -dimensional enumeration.

1.6. Standard array subclasses 229

NumPy Reference, Release 1.20.0

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 N − 1 from the array. This can be a useful construct for defining
recursive algorithms. To loop over the entire array requires N for-loops.

>>> a = np.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)
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.

230 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

Sometimes it may be useful to get the N-dimensional index while iterating. The ndenumerate iterator can achieve this.

>>> for i, val in np.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
broadcast_shapes

1.6. Standard array subclasses 231

NumPy Reference, Release 1.20.0

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

232 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 N
objects as inputs and returns an iterator that returns tuples providing each of the input sequence elements in the broadcasted
result.

>>> for val in np.broadcast([[1,0],[2,3]],[0,1]):

... print(val)
(1, 0)
(0, 1)
(2, 0)
(3, 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. Masked arrays 233

NumPy Reference, Release 1.20.0

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:

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

234 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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

1.7. Masked arrays 235

NumPy Reference, Release 1.20.0

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

Examples

The mask can be initialized with an array of boolean values with the same shape as data.

>>> data = np.arange(6).reshape((2, 3))

>>> np.ma.MaskedArray(data, mask=[[False, True, False],
... [False, False, True]])
masked_array(
data=[[0, --, 2],
[3, 4, --]],
mask=[[False, True, False],
[False, False, True]],
fill_value=999999)

Alternatively, the mask can be initialized to homogeneous boolean array with the same shape as data by
passing in a scalar boolean value:

>>> np.ma.MaskedArray(data, mask=False)

masked_array(
data=[[0, 1, 2],
[3, 4, 5]],
mask=[[False, False, False],
[False, False, False]],
fill_value=999999)

>>> np.ma.MaskedArray(data, mask=True)

masked_array(
data=[[--, --, --],
[--, --, --]],
mask=[[ True, True, True],
[ True, True, True]],
fill_value=999999,
dtype=int64)

Note: The recommended practice for initializing mask with a scalar boolean value is to use True/False
rather than np.True_/np.False_. The reason is nomask is represented internally as np.False_.

236 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

>>> np.False_ is np.ma.nomask

True

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.

ma.asarray(a, dtype=None, order=None)

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

1.7. Masked arrays 237

NumPy Reference, Release 1.20.0

[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 (‘FORTRAN’) mem-
ory 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'>

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 (‘FORTRAN’) mem-
ory representation. Default is ‘C’.

238 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Returns

out
[MaskedArray] MaskedArray interpretation of a.

See also:

asarray
Similar to asanyarray, but does not conserve subclass.

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

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.

1.7. Masked arrays 239

NumPy Reference, Release 1.20.0

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])
>>> x.data
array([ 1., -1., nan, inf])

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)

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:

240 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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)

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.

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)

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.

1.7. Masked arrays 241

NumPy Reference, Release 1.20.0

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)

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.

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)

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.

242 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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)

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)

ma.masked_not_equal(x, value, copy=True)

Mask an array where not 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_not_equal(a, 2)
masked_array(data=[--, --, 2, --],
mask=[ True, True, False, True],
fill_value=999999)

1.7. Masked arrays 243

NumPy Reference, Release 1.20.0

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')
>>> eat
masked_array(data=['cheese', 'ham', 'pineapple'],
mask=False,
(continues on next page)

244 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

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)

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)

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

1.7. Masked arrays 245

NumPy Reference, Release 1.20.0

x
[array_like] Array to mask.
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],
(continues on next page)

246 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

fill_value=2)
>>> ma.masked_equal(x, 2)
masked_array(data=[0, 1, --, 3, 4],
mask=[False, False, True, False, False],
fill_value=2)

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, con-
sider using masked_values instead.
a
[array_like] Array to mask.
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.

1.7. Masked arrays 247

NumPy Reference, Release 1.20.0

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],
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.

248 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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)

1.7. Masked arrays 249

NumPy Reference, Release 1.20.0

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

250 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.7. Masked arrays 251

NumPy Reference, Release 1.20.0

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

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

252 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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:

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

1.7. Masked arrays 253

NumPy Reference, Release 1.20.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.

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. It is represented internally as np.False_.
numpy.ma.masked_print_options
String used in lieu of missing data when a masked array is printed. By default, this string is '--'.

254 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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.

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.

1.7. Masked arrays 255

NumPy Reference, Release 1.20.0

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

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 traversing
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
ma.MaskedArray.base

256 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
ma.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 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)

1.7. Masked arrays 257

NumPy Reference, Release 1.20.0

_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 at-
tribute. This ctypes array contains the strides information from the underlying array. This strides information
is important for showing how many bytes must be jumped to get to the next element in the array.
_ctypes.data_as(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(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(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.

Examples

>>> import ctypes

>>> x = np.array([[0, 1], [2, 3]], dtype=np.int32)
>>> x
array([[0, 1],
[2, 3]], dtype=int32)
>>> x.ctypes.data
31962608 # may vary
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32))
<__main__.LP_c_uint object at 0x7ff2fc1fc200> # may vary
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32)).contents
c_uint(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint64)).contents
c_ulong(4294967296)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x7ff2fc1fce60> # may vary
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x7ff2fc1ff320> # may vary

property
property ma.MaskedArray.dtype
Data-type of the array’s elements.
Parameters

None

258 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
ma.MaskedArray.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.

1.7. Masked arrays 259

NumPy Reference, Release 1.20.0

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
ma.MaskedArray.itemsize
Length of one array element in bytes.

260 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

numpy.reshape
similar function

1.7. Masked arrays 261

NumPy Reference, Release 1.20.0

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 in-place modification. Use
`.reshape()` to make a copy with the desired shape.

attribute
ma.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 ob-
taining 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
ma.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:

262 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813

property
property ma.MaskedArray.imag
The imaginary part of the masked array.
This property is a view on the imaginary part of this MaskedArray.
See also:

1.7. Masked arrays 263

NumPy Reference, Release 1.20.0

real

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 ma.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 ma.MaskedArray.flat
Return a flat iterator, or set a flattened version of self to value.
attribute
ma.MaskedArray.__array_priority__ = 15

1.7.6 MaskedArray methods

See also:
Array methods

Conversion

MaskedArray.__float__() Convert to float.

MaskedArray.__int__() Convert to int.
MaskedArray.view([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() Return all the non-masked data as a 1-D array.
Continued on next page

264 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

Table 53 – continued from previous page

MaskedArray.filled([fill_value]) Return a copy of self, with masked values filled with a
given value.
MaskedArray.tofile(fid[, sep, format]) Save a masked array to a file in binary format.
MaskedArray.toflex() Transforms a masked array into a flexible-type array.
MaskedArray.tolist([fill_value]) Return the data portion of the masked array as a hierar-
chical Python list.
MaskedArray.torecords() Transforms a masked array into a flexible-type array.
MaskedArray.tostring([fill_value, order]) A compatibility alias for tobytes, with exactly the same
behavior.
MaskedArray.tobytes([fill_value, order]) Return the array data as a string containing the raw bytes
in the array.

method
ma.MaskedArray.__float__()
Convert to float.
method
ma.MaskedArray.__int__()
Convert to int.
method
ma.MaskedArray.view(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.

1.7. Masked arrays 265

NumPy Reference, Release 1.20.0

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
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
ma.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 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 re-
turned array will be forced to be a base-class array.
copy

266 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

[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 sat-
isfied (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
ma.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.

1.7. Masked arrays 267

NumPy Reference, Release 1.20.0

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 representation 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
ma.MaskedArray.compressed()
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

268 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

ma.MaskedArray.filled(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 argu-
ment or the attribute of self), or self itself as an ndarray if there are no invalid entries to
be replaced.

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
ma.MaskedArray.tofile(fid, sep=”, format=’%s’)
Save a masked array to a file in binary format.

Warning: This function is not implemented yet.

Raises

1.7. Masked arrays 269

NumPy Reference, Release 1.20.0

NotImplementedError
When tofile is called.

method
ma.MaskedArray.toflex()
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.

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
ma.MaskedArray.tolist(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.

270 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
ma.MaskedArray.torecords()
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.

Notes

A side-effect of transforming a masked array into a flexible ndarray is that meta information (fill_value,
…) will be lost.

1.7. Masked arrays 271

NumPy Reference, Release 1.20.0

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
ma.MaskedArray.tostring(fill_value=None, order=’C’)
A compatibility alias for tobytes, with exactly the same behavior.
Despite its name, it returns bytes not strs.
Deprecated since version 1.19.0.
method
ma.MaskedArray.tobytes(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’.

See also:

numpy.ndarray.tobytes
tolist, tofile

272 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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([order]) Returns a 1D version of self, as a view.
MaskedArray.reshape(*s, **kwargs) Give a new shape to the array without changing its data.
MaskedArray.resize(newshape[, refcheck, order])
MaskedArray.squeeze([axis]) Remove axes of length one from 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
ma.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

1.7. Masked arrays 273

NumPy Reference, Release 1.20.0

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
ma.MaskedArray.ravel(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

274 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

ma.MaskedArray.reshape(*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

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],
(continues on next page)

1.7. Masked arrays 275

NumPy Reference, Release 1.20.0

(continued from previous page)

[3],
[--]],
mask=[[ True],
[False],
[False],
[ True]],
fill_value=999999)

method
ma.MaskedArray.resize(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
ma.MaskedArray.squeeze(axis=None)
Remove axes of length one from a.
Refer to numpy.squeeze for full documentation.
See also:

numpy.squeeze
equivalent function

method
ma.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
ma.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

276 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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.

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 ma.MaskedArray.T

1.7. Masked arrays 277

NumPy Reference, Release 1.20.0

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([axis, fill_value, out]) Returns array of indices of the maximum values along the
given axis.
MaskedArray.argmin([axis, fill_value, out]) Return array of indices to the minimum values along the
given axis.
MaskedArray.argsort([axis, kind, order, …]) 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(condition[, axis, out]) 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() Return the indices of unmasked elements that are not
zero.
MaskedArray.put(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([axis, kind, order, …]) Sort the array, in-place
MaskedArray.take(indices[, axis, out, mode])

method
ma.MaskedArray.argmax(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

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 maxi-
mum_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}]

278 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
ma.MaskedArray.argmin(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 mini-
mum_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])
>>> x.argmin(axis=0, fill_value=9)
array([1, 1])

method

1.7. Masked arrays 279

NumPy Reference, Release 1.20.0

ma.MaskedArray.argsort(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:

ma.MaskedArray.sort
Describes sorting algorithms used.
lexsort
Indirect stable sort with multiple keys.
numpy.ndarray.sort
Inplace sort.

280 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

method
ma.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
ma.MaskedArray.compress(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.

1.7. Masked arrays 281

NumPy Reference, Release 1.20.0

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],
[--, --],
[7, 9]],
mask=[[False, False],
[ True, True],
[False, False]],
fill_value=999999)

method
ma.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
ma.MaskedArray.fill(value)
Fill the array with a scalar value.
Parameters

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

282 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

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.7. Masked arrays 283

NumPy Reference, Release 1.20.0

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
ma.MaskedArray.nonzero()
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.

284 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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

1.7. Masked arrays 285

NumPy Reference, Release 1.20.0

ma.MaskedArray.put(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],
(continues on next page)

286 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

[False, True, False]],
fill_value=999999)

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

numpy.repeat
equivalent function

method
ma.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
ma.MaskedArray.sort(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 compare
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.

1.7. Masked arrays 287

NumPy Reference, Release 1.20.0

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.

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],
(continues on next page)

288 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

(continued from previous page)

mask=[False, True, True, False, False],
fill_value=999999)

method
ma.MaskedArray.take(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
ma.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

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

1.7. Masked arrays 289

NumPy Reference, Release 1.20.0

method
ma.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
ma.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([axis, out, keepdims]) Returns True if all elements evaluate to True.

MaskedArray.anom([axis, dtype]) Compute the anomalies (deviations from the arithmetic
mean) along the given axis.
MaskedArray.any([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([axis, dtype, out]) Return the cumulative product of the array elements over
the given axis.
MaskedArray.cumsum([axis, dtype, out]) Return the cumulative sum of the array elements over the
given axis.
MaskedArray.max([axis, out, fill_value, …]) Return the maximum along a given axis.
MaskedArray.mean([axis, dtype, out, keepdims]) Returns the average of the array elements along given
axis.
MaskedArray.min([axis, out, fill_value, …]) Return the minimum along a given axis.
MaskedArray.prod([axis, dtype, out, keepdims]) Return the product of the array elements over the given
axis.
MaskedArray.product([axis, dtype, out, keep- Return the product of the array elements over the given
dims]) axis.
MaskedArray.ptp([axis, out, fill_value, …]) Return (maximum - minimum) along the given dimension
(i.e.
MaskedArray.round([decimals, out]) Return each element rounded to the given number of dec-
imals.
MaskedArray.std([axis, dtype, out, ddof, …]) Returns the standard deviation of the array elements along
given axis.
MaskedArray.sum([axis, dtype, out, keepdims]) 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([axis, dtype, out, ddof, …]) Compute the variance along the specified axis.

method

290 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

ma.MaskedArray.all(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
ma.MaskedArray.anom(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]
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.

1.7. Masked arrays 291

NumPy Reference, Release 1.20.0

Examples

>>> a = np.ma.array([1,2,3])
>>> a.anom()
masked_array(data=[-1., 0., 1.],
mask=False,
fill_value=1e+20)

method
ma.MaskedArray.any(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
ma.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
ma.MaskedArray.conj()
Complex-conjugate all elements.
Refer to numpy.conjugate for full documentation.
See also:

numpy.conjugate
equivalent function

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

292 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

numpy.conjugate
equivalent function

method
ma.MaskedArray.cumprod(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
ma.MaskedArray.cumsum(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 ma.MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.

1.7. Masked arrays 293

NumPy Reference, Release 1.20.0

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
ma.MaskedArray.max(axis=None, out=None, fill_value=None, keepdims=<no value>)
Return the maximum along a given axis.
Parameters

axis
[{None, int}, optional] Axis along which to operate. By default, axis is None and the flat-
tened 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 maxi-
mum_fill_value().
keepdims
[bool, optional] If this is set to True, the axes which are reduced are left in the result as dimen-
sions 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:

ma.maximum_fill_value
Returns the maximum filling value for a given datatype.

method
ma.MaskedArray.mean(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

294 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
ma.MaskedArray.min(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 flat-
tened 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 mini-
mum_fill_value.
keepdims
[bool, optional] If this is set to True, the axes which are reduced are left in the result as dimen-
sions 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:

ma.minimum_fill_value
Returns the minimum filling value for a given datatype.

method

1.7. Masked arrays 295

NumPy Reference, Release 1.20.0

ma.MaskedArray.prod(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
ma.MaskedArray.product(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
ma.MaskedArray.ptp(axis=None, out=None, fill_value=None, keepdims=False)
Return (maximum - minimum) along the given dimension (i.e. peak-to-peak value).

Warning: ptp preserves the data type of the array. This means the return value for an input of signed integers
with n bits (e.g. np.int8, np.int16, etc) is also a signed integer with n bits. In that case, peak-to-peak values
greater than 2**(n-1)-1 will be returned as negative values. An example with a work-around is shown
below.

Parameters

axis
[{None, int}, optional] Axis along which to find the peaks. If None (default) the flattened array
is used.

296 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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 dimen-
sions 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 reference
to out is returned.

Examples

>>> x = np.ma.MaskedArray([[4, 9, 2, 10],

... [6, 9, 7, 12]])

>>> x.ptp(axis=1)
masked_array(data=[8, 6],
mask=False,
fill_value=999999)

>>> x.ptp(axis=0)
masked_array(data=[2, 0, 5, 2],
mask=False,
fill_value=999999)

>>> x.ptp()
10

This example shows that a negative value can be returned when the input is an array of signed integers.

>>> y = np.ma.MaskedArray([[1, 127],

... [0, 127],
... [-1, 127],
... [-2, 127]], dtype=np.int8)
>>> y.ptp(axis=1)
masked_array(data=[ 126, 127, -128, -127],
mask=False,
fill_value=999999,
dtype=int8)

A work-around is to use the view() method to view the result as unsigned integers with the same bit width:

>>> y.ptp(axis=1).view(np.uint8)
masked_array(data=[126, 127, 128, 129],
(continues on next page)

1.7. Masked arrays 297

NumPy Reference, Release 1.20.0

(continued from previous page)

mask=False,
fill_value=999999,
dtype=uint8)

method
ma.MaskedArray.round(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.round
corresponding function for ndarrays
numpy.around
equivalent function

method
ma.MaskedArray.std(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
ma.MaskedArray.sum(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

298 Chapter 1. Array objects

 NumPy Reference, Release 1.20.0

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
ma.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
ma.MaskedArray.var(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.

1.7. Masked arrays 299

NumPy Reference, Release 1.20.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.
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 di-
mensions 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