This notebook provides an overview of and playground for NumPy, a core library for scientific computing in Python. NumPy provides a high-performance multidimensional array object and tools for working with these arrays. This array is the fundamental data struture of SciPy and other analysis libraries.
This tutorial is heavily based on the NumPy tutorial by Justin Johnson, Volodymyr Kuleshov, and Isaac Caswell for Stanford's course on Convolutional Neural Neworks for Visual Recognition. You can view their original raw notebook here.
The tutorial is best viewed in an interactive Jupyter Notebook environment so you can edit, modify, run, and iterate on the code yourself—the best way to learn! If you're reading a static (non-interactive) version of this page on our website, you can open an interactive version with a single click using Binder or Colab. You can also clone our GitHub repository and run this notebook locally using Jupyter Notebook.
Please also see the official NumPy reference and quickstart tutorial. If you are already familiar with MATLAB, you might find this tutorial useful to get started with NumPy.
To use Numpy, we first need to import the numpy package. It's convention to import it as np:
import numpy as np
NumPy's main object is a multidimensional array called np.array. Unlike traditional Python lists, which can intermix multiple types, all types in a NumPy array must be the same.
We can initialize numpy arrays from nested Python lists, and access elements using square brackets:
a = np.array([1, 2, 3]) # Create a rank 1 array
print(type(a), a.shape, a[0], a[1], a[2])
print(a)
a[0] = 5 # Change an element of the array
print(a)
b = np.array([[1,2,3],[4,5,6]]) # Create a rank 2 array
print(b)
We can access elements by (row, col)
print(b.shape)
print(b)
row = 0
col = 0
print()
print("Row: {} Col: {} Val: {}".format(row, col, b[row, col])) # access elements by row, column
row = 1
col = 2
print("Row: {} Col: {} Val: {}".format(row, col, b[row, col])) # access elements by row, column
A frequent error consists in calling array with multiple numeric arguments, rather than providing a single list of numbers as an argument.
# This cell will throw an exception
a = np.array(1,2,3,4) # WRONG, will throw an exception
a = np.array([1,2,3,4]) # RIGHT
Another common error is accidentally using Python lists rather than NumPy arrays. And sometimes, these errors are "hidden." For, example:
normal_list = [1, 2, 3, 4]
new_list = normal_list * 2 # will make another copy of the list and append
print(new_list)
np_array = np.array([1, 2, 3, 4])
new_array = np_array * 2 # will perform a computation on the list (multiply each element by 2)
print(new_array)
For many of our lessons, we will be using 1D NumPy arrays, so the following isn't particularly important—at least not at this point. However, it's important to remember that NumPy was built specifically as a multidimensional data structure. It is a table of elements.
In NumPy dimensions are called axes. The number of axes is rank.
For example, the coordinates of a point in 3D space [1, 2, 1] is an array of rank 1, because it has one axis (and that axis has a length of 3).
a = np.array([1,2,1])
print(a)
print("Rank: ", np.ndim(a))
print("Shape: ", np.shape(a))
In the example below, the numpy array has rank 2 (it is 2-dimensional). The first dimension (axis) has a length of 2, the second dimension has a length of 3.
a = np.array([[ 1., 0., 0.],[ 0., 1., 2.]])
print(a)
print("Rank: ", np.ndim(a))
print("Shape: ", np.shape(a))
Every numpy array is a grid of elements of the same type. Numpy provides a large set of numeric datatypes that you can use to construct arrays. Numpy tries to infer a datatype when you create an array, but functions that construct arrays usually also include an optional argument to explicitly specify the datatype. Here is an example:
x = np.array([1, 2]) # Let numpy choose the datatype
y = np.array([1.0, 2.0]) # Let numpy choose the datatype
z = np.array([1, 2], dtype=np.int64) # Force a particular datatype
print(x.dtype, y.dtype, z.dtype)
When operating with arrays of different types, the type of the resulting array corresponds to the more general or precise one (a behavior known as upcasting).
import math
a = np.ones(3, dtype=np.int32)
b = np.linspace(0,math.pi,3) # Return evenly spaced numbers over a specified interval.
print(a.dtype, a)
print(b.dtype, b)
c = a + b
print(c.dtype, c)
You can read all about NumPy datatypes in the documentation.
Numpy also provides many functions to create arrays:
# arange returns evenly spaced values within a given interval.
# see: https://docs.scipy.org/doc/numpy/reference/generated/numpy.arange.html
a = np.arange(6) # 1d array
print(a)
b = np.arange(12).reshape(4,3) # 2d array
print(b)
c = np.arange(24).reshape(2,3,4) # 3d array
print(c)
# you can also give arange a step size, which defaults to 1
print(np.arange(1,5))
print(np.arange(1,5,0.5))
a = np.zeros((2,2)) # Create an array of 2x2 of all zeros
print(a)
print(np.zeros((3,2))) # a 3 rows x 2 columns array of zeros
print(np.zeros((2,4))) # a 2 rows x 4 columns array of zeros
b = np.ones((1,2)) # Create an array of all ones
print(b)
print(np.ones((3,2))) # a 3 rows x 2 columns array of ones
print(np.ones((2,4))) # a 2 rows x 4 columns array of ones
c = np.full((2,2), 7) # Create a constant array
print(c)
c = np.full((2,2), 1) # Same as np.ones((2,2))
print(c)
d = np.eye(2) # Create a 2x2 identity matrix
print(d)
d = np.eye(4) # create a 4x3 identity matrix
print(d)
e = np.random.random((2,2)) # Create an array filled with random values
print(e)
e = np.random.random((4,6))
print(e)
e = np.random.random((1,20))
print(e)
Numpy offers several ways to index into arrays (link)
Similar to Python lists, numpy arrays can be sliced. Since arrays may be multidimensional, you must specify a slice for each dimension of the array:
# Playing around with slicing (trimming) array
a = np.array([1, 2, 3, 4, 5, 1, 2])
print(a[:4]) # prints [1 2 3 4]
print(a[:1]) # prints [1]
print(a[3:4]) # prints [4]
print(a[1:]) # prints [2 3 4 5 1 2]
# Create the following rank 2 array with shape (3, 4)
# [[ 1 2 3 4]
# [ 5 6 7 8]
# [ 9 10 11 12]]
a = np.array([[1,2,3,4], [5,6,7,8], [9,10,11,12]])
print(a)
# Use slicing to pull out the subarray consisting of the first 2 rows
# and columns 1 and 2; b is the following array of shape (2, 2):
# [[2 3]
# [6 7]]
b = a[:2, 1:3]
print(b)
Importantly, a slice of an array is a view into the same data, so modifying it will modify the original array.
a[0, 1] = 2
b = a[:2, 1:3]
print(a)
print(b)
print(a[0, 1])
b[0, 0] = 77 # b[0, 0] is the same piece of data as a[0, 1]
print(a[0, 1]) # should print 77
# To select a row in a 2D array in numpy, use P[i]. For example, P[0] will return the first row of P
# To select a column in a 2D array in numpy, use P[:, i]. The : essentially means "select all rows".
# For example, P[:, 1] will select all rows from the second column of P.
# this sets columns
a = np.zeros((2,2))
a[:, 0] = [1, 2] # set column 0 to [1, 2]
print(a)
a[:, 1] = [3, 4] # set column 1 to [3, 4]
print(a)
# this sets rows
b = np.zeros((2,2))
b[0] = [1, 2] # set row 0 to [1, 2]
print(b)
b[1] = [3, 4] # set row 1 to [3, 4]
print(b)
When you index into numpy arrays using slicing, the resulting array view will always be a subarray of the original array. In contrast, integer array indexing allows you to construct arbitrary arrays using the data from another array. Here is an example:
a = np.array([[1,2], [3, 4], [5, 6]])
print(a)
# An example of integer array indexing.
# The returned array will have shape (3,) and
print(a[[0, 1, 2], [0, 1, 0]])
# The above example of integer array indexing is equivalent to this:
print(np.array([a[0, 0], a[1, 1], a[2, 0]]))
Boolean array indexing lets you pick out arbitrary elements of an array. Frequently this type of indexing is used to select the elements of an array that satisfy some condition. Here is an example:
import numpy as np
a = np.array([[1,2], [3, 4], [5, 6]])
bool_idx = (a > 2) # Find the elements of a that are bigger than 2;
# this returns a numpy array of Booleans of the same
# shape as a, where each slot of bool_idx tells
# whether that element of a is > 2.
print(bool_idx)
# We use boolean array indexing to construct a rank 1 array
# consisting of the elements of a corresponding to the True values
# of bool_idx
print(a[bool_idx])
# We can do all of the above in a single concise statement:
print(a[a > 2])
# We can also use boolean array indexing to replace values
a = np.array([1, 2, 3, 4, 5, 1, 2])
a[a > 2] = 0
print(a)
You can also run queries on the arrays themselves.
# In this example, we show how the numpy 'where' method supports string matching
a = np.array(['apple', 'orange', 'apple', 'banana'])
arr_index = np.where(a == 'apple')
print(a)
print (arr_index) # prints (array([0, 2]),)
print (a[arr_index]) # prints ['apple' 'apple']
# This also works in multiple dimensions
a = np.array([['apple', 'orange', 'apple', 'banana'],['apple', 'apple', 'apple', 'banana']])
arr_index = np.where(a == 'apple')
print(a)
print (arr_index)
print (a[arr_index])
The NumPy sort method sorts the array in place:
x = np.array([5, 2, 0, 4, 3, 1])
print(x)
x.sort()
print(x)
We can also use argsort to calculate the indices to sort the array:
x = np.array([9, 6, 8, 7])
sorted_indices = np.argsort(x)
print(sorted_indices)
for sorted_idx in sorted_indices:
print("{}: {}".format(sorted_idx, x[sorted_idx]))
x = np.array([[1,2],[3,4]], dtype=np.float64)
y = np.array([[5,6],[7,8]], dtype=np.float64)
# Elementwise sum; both produce the same array
print(x + y)
print(np.add(x, y))
# Elementwise difference; both produce the same array
print(x - y)
print(np.subtract(x, y))
# Elementwise product; both produce the same array
print(x * y)
print(np.multiply(x, y))
# Elementwise division; both produce the same array
# [[ 0.2 0.33333333]
# [ 0.42857143 0.5 ]]
print(x / y)
print(np.divide(x, y))
# Elementwise division
a = np.array([1, 2, 3, 4, 5])
half_a = a / 2
print(half_a)
# Elementwise square root; produces the array
# [[ 1. 1.41421356]
# [ 1.73205081 2. ]]
print(np.sqrt(x))
Note that unlike MATLAB, * is elementwise multiplication, not matrix multiplication. We instead use the dot function to compute inner products of vectors, to multiply a vector by a matrix, and to multiply matrices. dot is available both as a function in the numpy module and as an instance method of array objects:
x = np.array([[1,2],[3,4]])
y = np.array([[5,6],[7,8]])
v = np.array([9,10])
w = np.array([11, 12])
# Inner product of vectors; all produce 219
print(v.dot(w))
print(np.dot(v, w))
print(v @ w)
# Matrix / vector product; all produce the rank 1 array [29 67]
print(x.dot(v))
print(np.dot(x, v))
print(x @ v)
# Matrix / matrix product; all produce the rank 2 array
# [[19 22]
# [43 50]]
print(x.dot(y))
print(np.dot(x, y))
print(x @ y)
In order for these array-based operations to work, the arrays must be the same shape
x = np.array([1, 2, 3, 4, 5])
y = np.array([1, 2, 4, 7, 5])
diff = x - y
print(diff) # prints [0 0 1 3 0]
# This cell will fail due to mismatched sizes
x = np.array([1, 2, 3, 4, 5])
y = np.array([1, 2, 3])
diff = x - y # this will throw an exception because of shape mismatched sizes
print(diff)
Numpy provides many useful functions for performing computations on arrays; one of the most useful is sum:
x = np.array([[1,2],[3,4]])
print(x)
print(np.sum(x)) # Compute sum of all elements; prints "10"
print(np.sum(x, axis=0)) # Compute sum of each column; prints "[4 6]"
print(np.sum(x, axis=1)) # Compute sum of each row; prints "[3 7]"
You can find the full list of mathematical functions provided by numpy in the documentation.
You can also perform scalar operations on NumPy arrays.
x = np.array([1, 2, 3, 4])
x *= 2
print(x)
x = np.array([1, 2, 3, 4])
y = x + 10
print(x)
print(y)
You can resize an array using padding
np1 = np.array([1, 2, 3, 4, 5])
np2 = np.array([1, 2, 3])
# Resize the array by padding. In this case, with zeros
# See: https://docs.scipy.org/doc/numpy/reference/generated/numpy.pad.html
np2_resized = np.pad(np2, (0, 2), 'constant', constant_values=0)
np_diff = np2_resized - np1
print(np_diff)
To transpose a matrix, simply use the T attribute of an array object:
x = np.array([[1,2],[3,4]])
print(x)
print(x.T)
v = np.array([[1,2,3]])
print(v)
print(v.T)
Broadcasting is a powerful mechanism that allows numpy to work with arrays of different shapes when performing arithmetic operations. Frequently we have a smaller array and a larger array, and we want to use the smaller array multiple times to perform some operation on the larger array.
For example, suppose that we want to add a constant vector to each row of a matrix. We could do it like this:
# We will add the vector v to each row of the matrix x,
# storing the result in the matrix y
x = np.array([[1,2,3], [4,5,6], [7,8,9], [10, 11, 12]])
v = np.array([1, 0, 1])
y = np.empty_like(x) # Create an empty matrix with the same shape as x
# Add the vector v to each row of the matrix x with an explicit loop
for i in range(4):
y[i, :] = x[i, :] + v # [i, :] selects the ith row
print(x)
print(v)
print(y)
This works; however when the matrix x is very large, computing an explicit loop in Python could be slow. Note that adding the vector v to each row of the matrix x is equivalent to forming a matrix v_tiled by stacking multiple copies of v vertically, then performing elementwise summation of x and v_tiled. We could implement this approach like this:
v_tiled = np.tile(v, (4, 1)) # Stack 4 copies of v on top of each other
print(v_tiled) # Prints "[[1 0 1]
# [1 0 1]
# [1 0 1]
# [1 0 1]]"
y = x + v_tiled # Add x and vv elementwise
print(x)
print(v_tiled)
print(y)
Numpy broadcasting allows us to perform this computation without actually creating multiple copies of v. Consider this version, using broadcasting:
import numpy as np
# We will add the vector v to each row of the matrix x,
# storing the result in the matrix y
x = np.array([[1,2,3], [4,5,6], [7,8,9], [10, 11, 12]])
v = np.array([1, 0, 1])
y = x + v # Add v to each row of x using broadcasting
print(y)
The line y = x + v works even though x has shape (4, 3) and v has shape (3,) due to broadcasting; this line works as if v actually had shape (4, 3), where each row was a copy of v, and the sum was performed elementwise.
Broadcasting two arrays together follows these rules:
If this explanation does not make sense, try reading the explanation from the documentation or this explanation.
Functions that support broadcasting are known as universal functions. You can find the list of all universal functions in the documentation.
Here are some applications of broadcasting:
# Compute outer product of vectors
v = np.array([1,2,3]) # v has shape (3,)
w = np.array([4,5]) # w has shape (2,)
# To compute an outer product, we first reshape v to be a column
# vector of shape (3, 1); we can then broadcast it against w to yield
# an output of shape (3, 2), which is the outer product of v and w:
print(np.reshape(v, (3, 1)) * w)
# Add a vector to each row of a matrix
x = np.array([[1,2,3], [4,5,6]])
# x has shape (2, 3) and v has shape (3,) so they broadcast to (2, 3),
# giving the following matrix:
print(x + v)
# Add a vector to each column of a matrix
# x has shape (2, 3) and w has shape (2,).
# If we transpose x then it has shape (3, 2) and can be broadcast
# against w to yield a result of shape (3, 2); transposing this result
# yields the final result of shape (2, 3) which is the matrix x with
# the vector w added to each column. Gives the following matrix:
print((x.T + w).T)
# Another solution is to reshape w to be a row vector of shape (2, 1);
# we can then broadcast it directly against x to produce the same
# output.
print(x + np.reshape(w, (2, 1)))
# Multiply a matrix by a constant:
# x has shape (2, 3). Numpy treats scalars as arrays of shape ();
# these can be broadcast together to shape (2, 3), producing the
# following array:
print(x * 2)
Broadcasting typically makes your code more concise and faster, so you should strive to use it where possible.