The N-dimensional array (ndarray)
The goal
Class has a very important job as a core container type in Python. It is really hard to find a good overview how to use them in a good practice manner.
Questions to David Rotermund
Chaining of (ndarray) methods
import numpy as np
a = np.ones((3, 3))
b = a.mean(axis=1).max()
print(b) # -> 1.0
numpy.ndarray.fill
ndarray.fill(value)
Fill the array with a scalar value.
import numpy as np
A = np.ones((3, 3))
A.fill(7)
print(A)
Output:
[[7. 7. 7.]
[7. 7. 7.]
[7. 7. 7.]]
numpy.ndarray.ndim
ndarray.ndim
Number of array dimensions.
import numpy as np
A = np.ones((3, 3))
print(A.ndim) # -> 2
numpy.ndarray.shape
ndarray.shape
Tuple of array dimensions.
import numpy as np
A = np.ones((3, 3))
print(A.shape) # -> (3, 3)
numpy.ndarray.size
ndarray.size
Number of elements in the array.
import numpy as np
A = np.ones((3, 3))
print(A.size) # -> 9
numpy.ndarray.nbytes
This is an optional topic!
ndarray.nbytes
Total bytes consumed by the elements of the array.
numpy.ndarray.itemsize
This is an optional topic!
ndarray.itemsize
Length of one array element in bytes.
numpy.ndarray.copy
ndarray.copy(order='C')
Return a copy of the array.
numpy.ndarray.view
ndarray.view([dtype][, type])
New view of array with the same data.
numpy.ndarray.reshape
ndarray.reshape(shape, order='C')
Returns an array containing the same data with a new shape.
import numpy as np
A = np.arange(0, 6)
print(A.reshape((2, 3)))
Output:
[[0 1 2]
[3 4 5]]
WARNING!!! Don’t confuse reshape with resize!
numpy.ndarray.squeeze
ndarray.squeeze(axis=None)
Remove axes of length one from a.
import numpy as np
A = np.zeros((4, 1, 1))
print(A.shape) # -> (4, 1, 1)
A = A.squeeze()
print(A.shape) # -> (4,)
A = np.zeros((4, 1, 9, 1)) # -> (4, 1, 9, 1)
print(A.shape)
B = A.squeeze(axis=1) # -> (4, 9, 1)
print(B.shape)
print(np.may_share_memory(A, B)) # -> True
numpy.moveaxis
numpy.moveaxis(a, source, destination)
Move axes of an array to new positions.
Other axes remain in their original order.
import numpy as np
A = np.zeros((4, 1, 9, 1))
print(A.shape) # -> (4, 1, 9, 1)
B = np.moveaxis(A, 0, 1)
print(B.shape) # -> (1, 4, 9, 1)
print(np.may_share_memory(A, B)) # -> True
numpy.ndarray.swapaxes
ndarray.swapaxes(axis1, axis2)
Return a view of the array with axis1 and axis2 interchanged.
import numpy as np
A = np.zeros((4, 1, 9, 1))
print(A.shape) # -> (4, 1, 9, 1)
B = A.swapaxes(0, 1)
print(B.shape) # -> (1, 4, 9, 1)
print(np.may_share_memory(A, B)) # -> True
numpy.ndarray.T (Transposing a 2d matrix)
ndarray.T
View of the transposed array.
Same as self.transpose().
import numpy as np
A = np.zeros((4, 9))
B = A.T
print(A.shape) # -> (4, 9)
print(B.shape) # -> (9, 4)
print(np.may_share_memory(A, B)) # -> True
numpy.ndarray.transpose
This is an optional topic!
ndarray.transpose(*axes)
Returns a view of the array with axes transposed.
numpy.ndarray.flatten
ndarray.flatten(order='C')
Return a copy of the array collapsed into one dimension.
import numpy as np
A = np.arange(0, 6)
A = A.reshape((2, 3))
print(A)
print()
B = A.flatten()
print(B)
print(np.may_share_memory(A, B)) # -> False
Output:
[[0 1 2]
[3 4 5]]
[0 1 2 3 4 5]
numpy.ndarray.flat
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.
import numpy as np
A = np.arange(0, 6)
A = A.reshape((2, 3))
print(A.flat[0]) # -> 0
print(A.flat[1]) # -> 1
print(A.flat[2]) # -> 2
print(A.flat[3]) # -> 3
print(A.flat[4]) # -> 4
print(A.flat[5]) # -> 5
for i in A:
print(i)
print("----")
for i in A.flat:
print(i)
Output:
[0 1 2]
[3 4 5]
----
0
1
2
3
4
5
numpy.ndarray.dtype
ndarray.dtype
Data-type of the array’s elements.
import numpy as np
A = np.zeros((0, 6), dtype=np.float32)
print(A.dtype) # -> float32
B = A.astype(dtype=np.int64)
print(B.dtype) # -> int64
print(np.may_share_memory(A, B)) # -> False
numpy.ndarray.astype
ndarray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
Copy of the array, cast to a specified type.
import numpy as np
A = np.zeros((0, 6), dtype=np.float32)
print(A.dtype) # -> float32
B = A.astype(dtype=np.int64)
print(B.dtype) # -> int64
print(np.may_share_memory(A, B)) # -> False
Complex numbers
numpy.ndarray.real
ndarray.real
The real part of the array.
import numpy as np
A = np.array(1 + 0.5j)
print(A.real) # -> 1.0
numpy.ndarray.imag
ndarray.imag
The imaginary part of the array.
import numpy as np
A = np.array(1 + 0.5j)
print(A.imag) # -> 0.5
numpy.ndarray.conj
ndarray.conj()
Complex-conjugate all elements.
import numpy as np
A = np.array(1 + 0.5j)
print(A.conj()) # -> (1-0.5j)
numpy.ndarray.sort
ndarray.sort(axis=-1, kind=None, order=None)
Sort an array in-place. Refer to numpy.sort for full documentation.
import numpy as np
A = np.arange(0, 6)
A = np.concatenate((A, A))
print(A) # -> [0 1 2 3 4 5 0 1 2 3 4 5]
print()
A.sort()
print(A) # -> [0 0 1 1 2 2 3 3 4 4 5 5]
numpy.ndarray.argsort
ndarray.argsort(axis=-1, kind=None, order=None)
Returns the indices that would sort this array.
import numpy as np
A = np.arange(0, 6)
A = np.concatenate((A, A))
print(A) # -> [0 1 2 3 4 5 0 1 2 3 4 5]
print()
idx = A.argsort()
print(idx) # -> [ 0 6 1 7 2 8 3 9 4 10 5 11]
numpy.ndarray.sum and numpy.ndarray.mean
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.
ndarray.mean(axis=None, dtype=None, out=None, keepdims=False, *, where=True)
Returns the average of the array elements along given axis.
import numpy as np
A = np.arange(0, 6).reshape((2, 3))
print(A.sum()) # -> 15
print(A.sum(axis=0)) # -> [3 5 7]
print(A.sum(axis=0).shape) # -> (3,)
print(A.sum(axis=1)) # -> [ 3 12]
print(A.sum(axis=1).shape) # -> (2,)
print(A.sum(axis=0, keepdims=True))
print(A.sum(axis=0, keepdims=True).shape) # -> (1, 3)
print()
print(A.sum(axis=1, keepdims=True))
print(A.sum(axis=0, keepdims=True).shape) # -> (1, 3)
Output:
[[3 5 7]]
[[ 3]
[12]]
numpy.ndarray.cumsum
ndarray.cumsum(axis=None, dtype=None, out=None)
Return the cumulative sum of the elements along the given axis.
import numpy as np
A = np.arange(0, 6).reshape((2, 3))
print(A)
print()
print(A.cumsum()) # -> [ 0 1 3 6 10 15]
print(A.cumsum().shape) # -> (6,)
print(A.cumsum(axis=0))
print()
print(A.cumsum(axis=0).shape) # -> (2, 3)
print(A.cumsum(axis=1))
print(A.cumsum(axis=1).shape) # -> (2, 3)
Output:
[[0 1 2]
[3 4 5]]
[[0 1 2]
[3 5 7]]
[[ 0 1 3]
[ 3 7 12]]
numpy.ndarray.prod
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
import numpy as np
A = np.arange(1, 7).reshape((2, 3))
print(A)
print(A.prod()) # -> 720
print(A.prod().shape) # -> ()
print(A.prod(axis=0)) # -> [ 4 10 18]
print(A.prod(axis=0).shape) # -> (3,)
print(A.prod(axis=1)) # -> [ 6 120]
print(A.prod(axis=1).shape) # -> (2,)
Output:
[[1 2 3]
[4 5 6]]
numpy.ndarray.cumprod
ndarray.cumprod(axis=None, dtype=None, out=None)
Return the cumulative product of the elements along the given axis.
import numpy as np
A = np.arange(1, 7).reshape((2, 3))
print(A)
print()
print(A.cumprod()) # -> [ 1 2 6 24 120 720]
print(A.cumprod().shape) # -> (6,)
print(A.cumprod(axis=0))
print()
print(A.cumprod(axis=0).shape) # -> (2, 3)
print(A.cumprod(axis=1))
print(A.cumprod(axis=1).shape) # -> (2, 3)
Output:
[[1 2 3]
[4 5 6]]
[[ 1 2 3]
[ 4 10 18]]
[[ 1 2 6]
[ 4 20 120]]
numpy.ndarray.clip
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.
import numpy as np
A = np.arange(0, 8).reshape((2, 4))
print(A)
print()
print(A.clip(min=1, max=6))
Output:
[[0 1 2 3]
[4 5 6 7]]
[[1 1 2 3]
[4 5 6 6]]
numpy.ndarray.max and numpy.ndarray.min
ndarray.max(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
Return the maximum along a given axis.
ndarray.min(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
Return the minimum along a given axis.
import numpy as np
A = np.arange(0, 6).reshape((2, 3))
print(A)
print()
print(A.max()) # -> 5
print(A.max(axis=0)) # -> [3 4 5]
print(A.max(axis=0).shape) # -> (3,)
print(A.max(axis=1)) # -> [2 5]
print(A.max(axis=1).shape) # -> (2,)
print(A.max(axis=0, keepdims=True)) # -> [[3 4 5]]
print(A.max(axis=0, keepdims=True).shape) # -> (1, 3)
print(A.max(axis=1, keepdims=True))
print(A.max(axis=0, keepdims=True).shape) # -> (1, 3)
Output:
[[0 1 2]
[3 4 5]]
[[2]
[5]]
numpy.ndarray.argmax and numpy.ndarray.argmin
ndarray.argmax(axis=None, out=None, *, keepdims=False)
Return indices of the maximum values along the given axis.
ndarray.argmin(axis=None, out=None, *, keepdims=False)
Return indices of the minimum values along the given axis.
import numpy as np
A = np.arange(0, 6).reshape((2, 3))
print(A)
print()
print(A.argmax()) # -> 5
print(A.argmax(axis=0)) # -> [1 1 1]
print(A.argmax(axis=0).shape) # -> (3,)
print(A.argmax(axis=1)) # -> [2 2]
print(A.argmax(axis=1).shape) # -> (2,)
print(A.argmax(axis=0, keepdims=True)) # -> [[1 1 1]]
print(A.argmax(axis=0, keepdims=True).shape) # -> (1, 3)
print(A.argmax(axis=1, keepdims=True))
print(A.argmax(axis=0, keepdims=True).shape) # -> (1, 3)
Output:
[[0 1 2]
[3 4 5]]
[[2]
[2]]
numpy.ndarray.std and numpy.ndarray.var
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.
ndarray.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True)
Returns the variance of the array elements, along given axis.
import numpy as np
rng = np.random.default_rng()
A = rng.random((2, 3))
print(A)
print()
print(A.var()) # -> 0.15743358550255018
print(A.var(axis=0)) # -> [0.19429192 0.15604444 0.00441136]
print(A.var(axis=0).shape) # -> (3,)
print(A.var(axis=1)) # -> [0.18135622 0.00196335]
print(A.var(axis=1).shape) # -> (2,)
print(A.var(axis=0, keepdims=True)) # -> [[0.19429192 0.15604444 0.00441136]]
print(A.var(axis=0, keepdims=True).shape) # -> (1, 3)
print(A.var(axis=1, keepdims=True))
print(A.var(axis=0, keepdims=True).shape) # -> (1, 3)
Output:
[[0.9804056 0.82416017 0.00909 ]
[0.09883446 0.03411095 0.1419262 ]]
[[0.18135622]
[0.00196335]]
numpy.ndarray.round
ndarray.round(decimals=0, out=None)
Return a with each element rounded to the given number of decimals.
import numpy as np
A = np.array(np.pi)
print(A) # -> 3.141592653589793
print(A.round(decimals=0)) # -> 3.0
print(A.round(decimals=1)) # -> 3.1
print(A.round(decimals=2)) # -> 3.14
print(A.round(decimals=3)) # -> 3.142
WARNING!!! This might be unexpected behavior for you:
import numpy as np
print(np.round(1.5)) # -> 2.0
print(np.round(2.5)) # -> 2.0
print(np.round(2.5 + 1e-15)) # -> 3.0
numpy.ndarray.trace
ndarray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)
Return the sum along diagonals of the array.
import numpy as np
A = np.eye(3)
print(A)
print(A.trace()) # -> 3.0
[[1. 0. 0.]
[0. 1. 0.]
[0. 0. 1.]]
numpy.ndarray.diagonal
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.
import numpy as np
rng = np.random.default_rng()
A = rng.random((3, 3))
print(A)
print(A.diagonal()) # -> [0.7434178 0.11672896]
print(A.diagonal(offset=1)) # -> [0.7434178 0.11672896]
print(A.diagonal(offset=2)) # -> [0.84915636]
print(A.diagonal(offset=-1)) # -> [0.10826248 0.50223328]
print(A.diagonal(offset=-2)) # -> [0.43068892]
Output
[[0.82574583 0.7434178 0.84915636]
[0.10826248 0.39898052 0.11672896]
[0.43068892 0.50223328 0.63444263]]
Array methods
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, WRITEBACKIFCOPY, respectively. |
| ndarray.fill(value) | Fill the array with a scalar value. |
Shape manipulation
| 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 interchanged. |
| 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
| 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. | |
| 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
| ndarray.max([axis, out, keepdims, initial, …]) | Return the maximum along a given axis. |
| ndarray.argmax([axis, out, keepdims]) | 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, keepdims]) | 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. |
Arithmetic, matrix multiplication, and comparison operations
Each of the arithmetic operations (+, -, *, /, //, %, divmod(), ** or pow(), «, », &, ^, |, ~) and the comparisons (==, <, >, <=, >=, !=) is equivalent to the corresponding universal function in NumPy.
for in-place operations see here
Special methods
The source code is Open Source and can be found on GitHub.