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 positive 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.
Different ndarrays can share the same data, so that changes made in one ndarray may be visible in another. That is, an ndarray can be a "view" to another ndarray, and the data it is referring to is taken care of by the "base" ndarray. ndarrays can also be views to memory owned by Python strings or objects implementing the buffer or array interfaces.
Example
A 2-dimensional array of size 2 x 3, composed of 4-byte integer elements:
>>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
>>> type(x)
<type 'numpy.ndarray'>
>>> x.shape
(2, 3)
>>> x.dtype
dtype('int32')
The array can be indexed using Python container-like syntax:
>>> x[1,2] # i.e., the element of x in the *second* row, *third* column, namely, 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]])
Constructing arrays
New arrays can be constructed using the routines detailed in routines.array-creation, and also by using the low-level ndarray constructor:
| ndarray | 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.) |
Indexing arrays
Arrays can be indexed using an extended Python slicing syntax, array[selection]. Similar syntax is also used for accessing fields in a record array.
See also
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 
corresponds to the offset (in bytes):
from the beginning of the memory block associated with the
array. Here, 
are integers which specify the strides of the array. The column-major order (used,
for example, in the Fortran language and in Matlab) and
row-major order (used in C) schemes are just specific kinds of
strided scheme, and correspond to the strides:
where 
= self.itemsize * 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.
Data in new ndarrays is in the row-major (C) order, unless otherwise specified, but, for example, basic array slicing often produces views <view> 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.
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. |
Data type
See also
The data type object associated with the array can be found in the dtype attribute:
| ndarray.dtype | Data-type of the array's elements. |
Other attributes
| ndarray.T | Same as self.transpose(), except that self is returned if self.ndim < 2. |
| 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. |
| __array_priority__ | <failed to parse summary> |
Array interface
See also
| __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. |
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, argsort, choose, clip, compress, copy, cumprod, cumsum, diagonal, imag, max, mean, min, nonzero, prod, ptp, put, ravel, real, repeat, reshape, round, searchsorted, sort, squeeze, std, sum, swapaxes, take, trace, transpose, var.
Array conversion
| ndarray.item | Copy an element of an array to a standard Python scalar and return it. |
| ndarray.tolist | Return the array as a (possibly nested) list. |
| ndarray.itemset | Insert scalar into an array (scalar is cast to array's dtype, if possible) |
| ndarray.setasflat | Equivalent to a.flat = arr.flat, but is generally more efficient. This function does not check for overlap, so if ``arr`` and ``a`` are viewing the same data with different strides, the results will be unpredictable. |
| ndarray.tostring | Construct a Python string containing the raw data bytes in the array. |
| ndarray.tofile | Write array to a file as text or binary (default). |
| ndarray.dump | Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load. |
| ndarray.dumps | Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array. |
| ndarray.astype | Copy of the array, cast to a specified type. |
| ndarray.byteswap | Swap the bytes of the array elements |
| ndarray.copy | Return a copy of the array. |
| ndarray.view | New view of array with the same data. |
| ndarray.getfield | Returns a field of the given array as a certain type. |
| ndarray.setflags | Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively. |
| ndarray.fill | 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 | Returns an array containing the same data with a new shape. |
| ndarray.resize | Change shape and size of array in-place. |
| ndarray.transpose | Returns a view of the array with axes transposed. |
| ndarray.swapaxes | Return a view of the array with `axis1` and `axis2` interchanged. |
| ndarray.flatten | Return a copy of the array collapsed into one dimension. |
| ndarray.ravel | Return a flattened array. |
| ndarray.squeeze | Remove single-dimensional entries from the shape of `a`. |
Item selection and manipulation
For array methods that take an axis keyword, it defaults to None. If axis is None, then the array is treated as a 1-D array. Any other value for axis represents the dimension along which the operation should proceed.
| ndarray.take | Return an array formed from the elements of `a` at the given indices. |
| ndarray.put | Set ``a.flat[n] = values[n]`` for all `n` in indices. |
| ndarray.repeat | Repeat elements of an array. |
| ndarray.choose | Use an index array to construct a new array from a set of choices. |
| ndarray.sort | Sort an array, in-place. |
| ndarray.argsort | Returns the indices that would sort this array. |
| ndarray.searchsorted | 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 | Return selected slices of this array along given axis. |
| ndarray.diagonal | Return specified diagonals. |
Calculation
Many of these methods take an argument named axis. In such cases,
- If axis is None (the default), the array is treated as a 1-D array and the operation is performed over the entire array. This behavior is also the default if self is a 0-dimensional array or array scalar. (An array scalar is an instance of the types/classes float32, float64, etc., whereas a 0-dimensional array is an ndarray instance containing precisely one array scalar.)
- If axis is an integer, then the operation is done over the given axis (for each 1-D subarray that can be created along the given axis).
Example of the axis argument
A 3-dimensional array of size 3 x 3 x 3, summed over each of its three axes
>>> x
array([[[ 0, 1, 2],
[ 3, 4, 5],
[ 6, 7, 8]],
[[ 9, 10, 11],
[12, 13, 14],
[15, 16, 17]],
[[18, 19, 20],
[21, 22, 23],
[24, 25, 26]]])
>>> x.sum(axis=0)
array([[27, 30, 33],
[36, 39, 42],
[45, 48, 51]])
>>> # for sum, axis is the first keyword, so we may omit it,
>>> # specifying only its value
>>> x.sum(0), x.sum(1), x.sum(2)
(array([[27, 30, 33],
[36, 39, 42],
[45, 48, 51]]),
array([[ 9, 12, 15],
[36, 39, 42],
[63, 66, 69]]),
array([[ 3, 12, 21],
[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.argmax | Return indices of the maximum values along the given axis. |
| ndarray.min | Return the minimum along a given axis. |
| ndarray.argmin | Return indices of the minimum values along the given axis of `a`. |
| ndarray.ptp | Peak to peak (maximum - minimum) value along a given axis. |
| ndarray.clip | Return an array whose values are limited to ``[a_min, a_max]``. |
| ndarray.conj | Complex-conjugate all elements. |
| ndarray.round | Return `a` with each element rounded to the given number of decimals. |
| ndarray.trace | Return the sum along diagonals of the array. |
| ndarray.sum | Return the sum of the array elements over the given axis. |
| ndarray.cumsum | Return the cumulative sum of the elements along the given axis. |
| ndarray.mean | Returns the average of the array elements along given axis. |
| ndarray.var | Returns the variance of the array elements, along given axis. |
| ndarray.std | Returns the standard deviation of the array elements along given axis. |
| ndarray.prod | Return the product of the array elements over the given axis |
| ndarray.cumprod | Return the cumulative product of the elements along the given axis. |
| ndarray.all | Returns True if all elements evaluate to True. |
| ndarray.any | Returns True if any of the elements of `a` evaluate to True. |
Arithmetic 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__ | <> |
| ndarray.__le__ | <> |
| ndarray.__gt__ | <> |
| ndarray.__ge__ | <> |
| ndarray.__eq__ | <> |
| ndarray.__ne__ | <> |
Truth value of an array (bool()):
| ndarray.__nonzero__ | <> |
Note
Truth-value testing of an array invokes ndarray.__nonzero__, which raises an error if the number of elements in the the array is larger than 1, because the truth value of such arrays is ambiguous. Use .any() and .all() instead to be clear about what is meant in such cases. (If the number of elements is 0, the array evaluates to False.)
Unary operations:
| ndarray.__neg__ | <> |
| ndarray.__pos__ | <> |
| ndarray.__abs__ | <> |
| ndarray.__invert__ | <> |
Arithmetic:
Note
- Any third argument to pow() is silently ignored, as the underlying ufunc takes only two arguments.
- The three division operators are all defined; div is active by default, truediv is active when __future__ division is in effect.
- Because ndarray is a built-in type (written in C), the __r{op}__ special methods are not directly defined.
- The functions called to implement many arithmetic special methods for arrays can be modified using set_numeric_ops.
Arithmetic, in-place:
Warning
In place operations will perform the calculation using the precision decided by the data type of the two operands, but will silently downcast the result (if necessary) so it can fit back into the array. Therefore, for mixed precision calculations, A {op}= B can be different than A = A {op} B. For example, suppose a = ones((3,3)). Then, a += 3j is different than a = a + 3j: while they both perform the same computation, a += 3 casts the result to fit back in a, whereas a = a + 3j re-binds the name a to the result.
Special methods
For standard library functions:
| ndarray.__copy__ | <> |
| ndarray.__deepcopy__ | <> |
| ndarray.__reduce__ | <> |
| ndarray.__setstate__ | <> |
Basic customization:
| ndarray.__new__ | <> |
| ndarray.__array__ | <> |
| ndarray.__array_wrap__ | <failed to parse summary> |
Container customization: (see Indexing)
| ndarray.__len__ | <> |
| ndarray.__getitem__ | <> |
| ndarray.__setitem__ | <> |
| ndarray.__getslice__ | <> |
| ndarray.__setslice__ | <> |
| ndarray.__contains__ | <> |
Conversion; the operations complex(), int(), long(), float(), oct(), and hex(). They work only on arrays that have one element in them and return the appropriate scalar.
| ndarray.__int__ | <> |
| ndarray.__long__ | <> |
| ndarray.__float__ | <> |
| ndarray.__oct__ | <> |
| ndarray.__hex__ | <> |
String representations:
| ndarray.__str__ | <> |
| ndarray.__repr__ | <> |
Discussion
Show resolvedThe
in
need defining.
Regarding the phrase "0-dimensional array or array scalar" occurring in the passage "If axis is None ... if self is a 0-dimensional array or array scalar" under the heading "Calculation": are "0-dimensional array" and "array scalar" synonymous? If not, how do they differ? (I assume they both differ from a simple scalar in that they are both of type ndarray, whereas a simple scalar has one of the "intrinsic" data types.) I don't necessarily expect an explanation/clarification at this place in this rst file, unless it's immediately relevant here, but as soon as I read it, I wondered what the difference is, and thought a comment here about it might be appropriate.
Oh, wait, I think I figured it out: a "0-dimensional array" is an empty array (i.e., an ndarray object w/ no data in it), whereas an "array scalar" is an ndarray object with exactly one scalar element in it? If so, IMO it wouldn't muck things up too much to add these explanations parenthetically following there respective occurrences, i.e., something like: "0-dimensional array (i.e., an empty ndarray) or array scalar (i.e., an ndarray containing exactly one scalar value)."
A couple more comments regarding the material under the heading "Calculation":
At least one example (but preferably two or three) should be furnished here, unless these are given elsewhere, in which case a reference/link to that place should be provided here.
Presently, in many of the docstrings for functions/methods which have an optional out argument, it is undocumented; if possible, an anchor should be added here so that a link directly to this passage may be inserted into such docstrings.
Regarding the note "Because ndarray is a built-in type (written in C), the __r{op}__ special methods," r{op} special methods should include a ref/link to more information; if more information doesn't presently exist, it needs to be written.
@dgoldsmith:
Replies to your points:
Again, thanks!
I just searched the "Guide to NumPy" for r{op}, {op} (and for r{+} and r{/} for good measure) and got no hits.
I'm moving the "XXX" notes here, A) because I've been asked to get them out of the main part of the text, and B) because if I conscientiously do as some of them prescribe, it may take a little while and require more than just a trivial response (which, even if it's just "Done," doesn't belong in the main part of the text anyway).
"Note XXX: update and check these docstrings." applies to the sections titled "Memory layout," "ctypes foreign function interface," and "Array conversion."
"Note XXX: update the dtype attribute docstring: setting etc." applies to the section titled "Data type."
"Note XXX: write all attributes explicitly here instead of relying on the auto* stuff?" applies to the section titled "Arithmetic and comparison operations." (I don't know who wrote this one - it's in the "Source" revision - why, or how to answer it.)