11. NumPy

11.1Overview¶

NumPy is a first-rate library for numerical programming

• Widely used in academia, finance and industry.
• Mature, fast, stable and under continuous development.

We have already seen some code involving NumPy in the preceding lectures.

In this lecture, we will start a more systematic discussion of

1. NumPy arrays and
2. the fundamental array processing operations provided by NumPy.

(For an alternative reference, see the official NumPy documentation.)

We will use the following imports.

11.2NumPy Arrays¶

The essential problem that NumPy solves is fast array processing.

The most important structure that NumPy defines is an array data type, formally called a numpy.ndarray.

NumPy arrays power a very large proportion of the scientific Python ecosystem.

To create a NumPy array containing only zeros we use np.zeros

NumPy arrays are somewhat like native Python lists, except that

• Data must be homogeneous (all elements of the same type).
• These types must be one of the data types (dtypes) provided by NumPy.

The most important of these dtypes are:

• float64: 64 bit floating-point number
• int64: 64 bit integer
• bool: 8 bit True or False

There are also dtypes to represent complex numbers, unsigned integers, etc.

On modern machines, the default dtype for arrays is float64

If we want to use integers we can specify as follows:

11.2.1Shape and Dimension¶

Consider the following assignment

Here z is a flat array with no dimension --- neither row nor column vector.

The dimension is recorded in the shape attribute, which is a tuple

Here the shape tuple has only one element, which is the length of the array (tuples with one element end with a comma).

To give it dimension, we can change the shape attribute

In the last case, to make the 2 by 2 array, we could also pass a tuple to the zeros() function, as in z = np.zeros((2, 2)).

11.2.2Creating Arrays¶

As we’ve seen, the np.zeros function creates an array of zeros.

You can probably guess what np.ones creates.

Related is np.empty, which creates arrays in memory that can later be populated with data

The numbers you see here are garbage values.

(Python allocates 3 contiguous 64 bit pieces of memory, and the existing contents of those memory slots are interpreted as float64 values)

To set up a grid of evenly spaced numbers use np.linspace

To create an identity matrix use either np.identity or np.eye

In addition, NumPy arrays can be created from Python lists, tuples, etc. using np.array

See also np.asarray, which performs a similar function, but does not make a distinct copy of data already in a NumPy array.

To read in the array data from a text file containing numeric data use np.loadtxt or np.genfromtxt---see the documentation for details.

11.2.3Array Indexing¶

For a flat array, indexing is the same as Python sequences:

For 2D arrays the index syntax is as follows:

And so on.

Note that indices are still zero-based, to maintain compatibility with Python sequences.

Columns and rows can be extracted as follows

NumPy arrays of integers can also be used to extract elements

Finally, an array of dtype bool can be used to extract elements

We’ll see why this is useful below.

An aside: all elements of an array can be set equal to one number using slice notation

11.2.4Array Methods¶

Arrays have useful methods, all of which are carefully optimized

Another method worth knowing is searchsorted().

If z is a nondecreasing array, then z.searchsorted(a) returns the index of the first element of z that is >= a

Many of the methods discussed above have equivalent functions in the NumPy namespace

11.3Arithmetic Operations¶

The operators +, -, *, / and ** all act elementwise on arrays

We can add a scalar to each element as follows

Scalar multiplication is similar

The two-dimensional arrays follow the same general rules

In particular, A * B is not the matrix product, it is an element-wise product.

11.4Matrix Multiplication¶

With Anaconda’s scientific Python package based around Python 3.5 and above, one can use the @ symbol for matrix multiplication, as follows:

(For older versions of Python and NumPy you need to use the np.dot function)

We can also use @ to take the inner product of two flat arrays

In fact, we can use @ when one element is a Python list or tuple

Since we are post-multiplying, the tuple is treated as a column vector.

11.5Broadcasting¶

(This section extends an excellent discussion of broadcasting provided by Jake VanderPlas.)

In element-wise operations, arrays may not have the same shape.

When this happens, NumPy will automatically expand arrays to the same shape whenever possible.

This useful (but sometimes confusing) feature in NumPy is called broadcasting.

The value of broadcasting is that

• for loops can be avoided, which helps numerical code run fast and
• broadcasting can allow us to implement operations on arrays without actually creating some dimensions of these arrays in memory, which can be important when arrays are large.

For example, suppose a is a $3 \times 3$ array (a -> (3, 3)), while b is a flat array with three elements (b -> (3,)).

When adding them together, NumPy will automatically expand b -> (3,) to b -> (3, 3).

The element-wise addition will result in a $3 \times 3$ array

Here is a visual representation of this broadcasting operation:

How about b -> (3, 1)?

In this case, NumPy will automatically expand b -> (3, 1) to b -> (3, 3).

Element-wise addition will then result in a $3 \times 3$ matrix

Here is a visual representation of this broadcasting operation:

The previous broadcasting operation is equivalent to the following for loop

In some cases, both operands will be expanded.

When we have a -> (3,) and b -> (3, 1), a will be expanded to a -> (3, 3), and b will be expanded to b -> (3, 3).

In this case, element-wise addition will result in a $3 \times 3$ matrix

Here is a visual representation of this broadcasting operation:

While broadcasting is very useful, it can sometimes seem confusing.

For example, let’s try adding a -> (3, 2) and b -> (3,).

The ValueError tells us that operands could not be broadcast together.

Here is a visual representation to show why this broadcasting cannot be executed:

We can see that NumPy cannot expand the arrays to the same size.

It is because, when b is expanded from b -> (3,) to b -> (3, 3), NumPy cannot match b with a -> (3, 2).

Things get even trickier when we move to higher dimensions.

To help us, we can use the following list of rules:

• Step 1: When the dimensions of two arrays do not match, NumPy will expand the one with fewer dimensions by adding dimension(s) on the left of the existing dimensions.

  • For example, if a -> (3, 3) and b -> (3,), then broadcasting will add a dimension to the left so that b -> (1, 3);
  • If a -> (2, 2, 2) and b -> (2, 2), then broadcasting will add a dimension to the left so that b -> (1, 2, 2);
  • If a -> (3, 2, 2) and b -> (2,), then broadcasting will add two dimensions to the left so that b -> (1, 1, 2) (you can also see this process as going through Step 1 twice).

• Step 2: When the two arrays have the same dimension but different shapes, NumPy will try to expand dimensions where the shape index is 1.

  • For example, if a -> (1, 3) and b -> (3, 1), then broadcasting will expand dimensions with shape 1 in both a and b so that a -> (3, 3) and b -> (3, 3);
  • If a -> (2, 2, 2) and b -> (1, 2, 2), then broadcasting will expand the first dimension of b so that b -> (2, 2, 2);
  • If a -> (3, 2, 2) and b -> (1, 1, 2), then broadcasting will expand b on all dimensions with shape 1 so that b -> (3, 2, 2).

Here are code examples for broadcasting higher dimensional arrays

• Step 3: After Step 1 and 2, if the two arrays still do not match, a ValueError will be raised. For example, suppose a -> (2, 2, 3) and b -> (2, 2)
  • By Step 1, b will be expanded to b -> (1, 2, 2);
  • By Step 2, b will be expanded to b -> (2, 2, 2);
  • We can see that they do not match each other after the first two steps. Thus, a ValueError will be raised

11.6Mutability and Copying Arrays¶

NumPy arrays are mutable data types, like Python lists.

In other words, their contents can be altered (mutated) in memory after initialization.

We already saw examples above.

Here’s another example:

Mutability leads to the following behavior (which can be shocking to MATLAB programmers...)

What’s happened is that we have changed a by changing b.

The name b is bound to a and becomes just another reference to the array the Python assignment model is described in more detail later in the course.

Hence, it has equal rights to make changes to that array.

This is in fact the most sensible default behavior!

It means that we pass around only pointers to data, rather than making copies.

Making copies is expensive in terms of both speed and memory.

11.6.1Making Copies¶

It is of course possible to make b an independent copy of a when required.

This can be done using np.copy

Now b is an independent copy (called a deep copy)

Note that the change to b has not affected a.

11.7Additional Functionality¶

Let’s look at some other useful things we can do with NumPy.

11.7.1Vectorized Functions¶

NumPy provides versions of the standard functions log, exp, sin, etc. that act element-wise on arrays

This eliminates the need for explicit element-by-element loops such as

Because they act element-wise on arrays, these functions are called vectorized functions.

In NumPy-speak, they are also called ufuncs, which stands for “universal functions”.

As we saw above, the usual arithmetic operations (+, *, etc.) also work element-wise, and combining these with the ufuncs gives a very large set of fast element-wise functions.

Not all user-defined functions will act element-wise.

For example, passing the function f defined below a NumPy array causes a ValueError

The NumPy function np.where provides a vectorized alternative:

You can also use np.vectorize to vectorize a given function

However, this approach doesn’t always obtain the same speed as a more carefully crafted vectorized function.

11.7.2Comparisons¶

As a rule, comparisons on arrays are done element-wise

The situation is similar for >, <, >= and <=.

We can also do comparisons against scalars

This is particularly useful for conditional extraction

Of course we can---and frequently do---perform this in one step

11.7.3Sub-packages¶

NumPy provides some additional functionality related to scientific programming through its sub-packages.

We’ve already seen how we can generate random variables using np.random

Another commonly used subpackage is np.linalg

Much of this functionality is also available in SciPy, a collection of modules that are built on top of NumPy.

We’ll cover the SciPy versions in more detail soon.

For a comprehensive list of what’s available in NumPy see this documentation.

11.8Speed Comparisons¶

We mentioned in an previous lecture that NumPy-based vectorization can accelerate scientific applications.

In this section we try some speed comparisons to illustrate this fact.

11.8.1Vectorization vs Loops¶

Let’s begin with some non-vectorized code, which uses a native Python loop to generate, square and then sum a large number of random variables:

The following vectorized code achieves the same thing.

As you can see, the second code block runs much faster. Why?

The second code block breaks the loop down into three basic operations

1. draw n uniforms
2. square them
3. sum them

These are sent as batch operators to optimized machine code.

Apart from minor overheads associated with sending data back and forth, the result is C or Fortran-like speed.

When we run batch operations on arrays like this, we say that the code is vectorized.

The next section illustrates this point.

11.8.2Universal Functions¶

As discussed above, many functions provided by NumPy are universal functions (ufuncs).

By exploiting ufuncs, many operations can be vectorized, leading to faster execution.

For example, consider the problem of maximizing a function $f$ of two variables $(x,y)$ over the square $[-a, a] \times [-a, a]$.

For $f$ and $a$ let’s choose

Here’s a plot of $f$

To maximize it, we’re going to use a naive grid search:

1. Evaluate $f$ for all $(x,y)$ in a grid on the square.
2. Return the maximum of observed values.

The grid will be

Here’s a non-vectorized version that uses Python loops.

And here’s a vectorized version

In the vectorized version, all the looping takes place in compiled code.

As you can see, the second version is much faster.

11.9Exercises¶

def p(x, coef):
    X = np.ones_like(coef)
    X[1:] = x
    y = np.cumprod(X)   # y = [1, x, x**2,...]
    return coef @ y

x = 2
coef = np.linspace(2, 4, 3)
print(coef)
print(p(x, coef))
# For comparison
q = np.poly1d(np.flip(coef))
print(q(x))

[2. 3. 4.]
24.0
24.0

from numpy import cumsum
from numpy.random import uniform

class DiscreteRV:
    """
    Generates an array of draws from a discrete random variable with vector of
    probabilities given by q.
    """

    def __init__(self, q):
        """
        The argument q is a NumPy array, or array like, nonnegative and sums
        to 1
        """
        self.q = q
        self.Q = cumsum(q)

    def draw(self, k=1):
        """
        Returns k draws from q. For each such draw, the value i is returned
        with probability q[i].
        """
        return self.Q.searchsorted(uniform(0, 1, size=k))

q = (0.1, 0.9)
d = DiscreteRV(q)
d.q = (0.5, 0.5)

Solution to Exercise 3

An example solution is given below.

In essence, we’ve just taken this code from QuantEcon and added in a plot method

"""
Modifies ecdf.py from QuantEcon to add in a plot method

"""

class ECDF:
    """
    One-dimensional empirical distribution function given a vector of
    observations.

    Parameters
    ----------
    observations : array_like
        An array of observations

    Attributes
    ----------
    observations : array_like
        An array of observations

    """

    def __init__(self, observations):
        self.observations = np.asarray(observations)

    def __call__(self, x):
        """
        Evaluates the ecdf at x

        Parameters
        ----------
        x : scalar(float)
            The x at which the ecdf is evaluated

        Returns
        -------
        scalar(float)
            Fraction of the sample less than x

        """
        return np.mean(self.observations <= x)

    def plot(self, ax, a=None, b=None):
        """
        Plot the ecdf on the interval [a, b].

        Parameters
        ----------
        a : scalar(float), optional(default=None)
            Lower endpoint of the plot interval
        b : scalar(float), optional(default=None)
            Upper endpoint of the plot interval

        """

        # === choose reasonable interval if [a, b] not specified === #
        if a is None:
            a = self.observations.min() - self.observations.std()
        if b is None:
            b = self.observations.max() + self.observations.std()

        # === generate plot === #
        x_vals = np.linspace(a, b, num=100)
        f = np.vectorize(self.__call__)
        ax.plot(x_vals, f(x_vals))
        plt.show()

Here’s an example of usage

fig, ax = plt.subplots()
X = np.random.randn(1000)
F = ECDF(X)
F.plot(ax)

np.random.seed(123)
x = np.random.randn(4, 4)
y = np.random.randn(4)

C = np.empty_like(x)
n = len(x)
for i in range(n):
    for j in range(n):
        C[i, j] = x[i, j] / y[j]

print(C)

[[-0.49214189  0.45607819  0.28183596 -3.90043439]
 [-0.26229311  0.75518888 -2.41688145 -1.11063629]
 [ 0.57387869 -0.39635354 -0.67614513 -0.2452416 ]
 [ 0.676082   -0.29216483 -0.44218937 -1.12471925]]

print(np.array_equal(A, C))

True

np.random.seed(123)
x = np.random.randn(1000, 100, 100)
y = np.random.randn(100)

qe.tic()
D = np.empty_like(x)
d1, d2, d3 = x.shape
for i in range(d1):
    for j in range(d2):
        for k in range(d3):
            D[i, j, k] = x[i, j, k] / y[k]
qe.toc()

TOC: Elapsed: 0:00:12.46

print(D)

[[[ 1.85764005 -0.89419976  0.24485371 ... -3.04214618  0.17711597
   -0.22643801]
  [-1.09863014  1.77333433  0.61630351 ... -0.24732757 -0.15931155
   -0.13015397]
  [-1.20344529  0.53624915  1.90420857 ...  0.92748804  0.07494711
    0.48954772]
  ...
  [-1.09763323  0.68632802 -1.21568707 ... -3.87025031 -0.19456046
    0.18331773]
  [-0.47546852 -0.16883695  2.92991418 ... -0.05967182 -0.20796073
   -0.49082994]
  [ 1.14380091  1.93460538 -0.76305492 ... -1.0537099   0.27167901
    0.57963424]]

 [[ 2.12344323  0.28058176 -0.73457091 ...  3.55049699  0.59737154
   -0.31414907]
  [ 1.40074417 -0.09113173  0.50276294 ... -1.85572391  0.13914077
   -0.93776321]
  [ 2.35739042 -0.79089649  0.20835615 ... -0.11001198  0.86250367
   -1.26949634]
  ...
  [ 2.11831946  0.15242396 -0.17269536 ...  0.03469371 -0.06074779
    0.10114045]
  [-0.08300138  0.47232405 -0.89930099 ...  0.66104947 -0.45183377
   -1.05885526]
  [ 0.282155   -1.44848315 -1.25832989 ... -3.12998376  0.48762406
    0.22052869]]

 [[-1.76517625 -1.19419485  0.08293115 ...  0.7919151  -0.03812759
   -1.19540255]
  [-0.66639955  0.16580616 -0.32083535 ...  0.72351825 -0.72239583
   -0.46386281]
  [-0.45163238 -1.5262587  -0.38541194 ...  1.82015759  0.23151272
    0.81609303]
  ...
  [ 1.14317214 -0.60571044 -0.74962613 ... -3.13330221  0.61817627
    0.37738869]
  [-0.65686356  0.41024983  0.2700362  ... -0.08588743  0.20408508
    0.33667429]
  [-0.43851304  0.58339651 -0.9076869  ... -2.55408527 -0.22112928
    0.9912754 ]]

 ...

 [[ 1.13470002 -0.20836287 -0.50483798 ...  0.32733859 -0.32203002
    0.43385307]
  [-0.11763272 -0.77698937 -0.46659376 ...  2.01256989 -0.19222608
   -0.48021737]
  [ 0.89558661  0.93447059  0.35386499 ... -1.2218747   0.42826019
    0.73980809]
  ...
  [-0.30040698 -1.14758822 -1.2785068  ...  3.9600491  -0.25830068
   -1.09906439]
  [-2.89569174 -0.67988752 -0.26342148 ...  0.62855881  0.05570693
   -0.05084807]
  [ 0.87738281 -2.37555322  1.66177996 ...  0.09857952  0.35564132
   -1.22140972]]

 [[-3.31843223  0.19402721  0.87502303 ... -1.47591384 -0.25236749
   -0.85281481]
  [-2.84794867 -0.31042414  0.43040259 ... -4.01127498  0.06267678
   -0.2073196 ]
  [-0.47909317 -0.77256923 -0.49818879 ... -0.17526151  0.64720631
   -0.06831215]
  ...
  [ 0.35509683 -0.48189502 -0.18528007 ...  2.03614189 -0.15287291
    0.0979404 ]
  [-1.20730244 -0.24269721 -0.28048927 ...  0.94378219 -0.21283324
   -0.30738091]
  [-1.81004008  1.01260185 -0.62311067 ... -0.03158149 -0.36355966
    0.43427753]]

 [[-1.43227284 -0.20319046  1.37271425 ...  2.34113161  0.18025411
   -0.247025  ]
  [ 0.47792311  0.61186236  0.73460309 ... -1.52671835 -0.10967386
   -0.04788996]
  [-1.51873339  0.73425213 -0.54033092 ...  0.21434631 -0.31597544
   -0.24364054]
  ...
  [-0.24128379 -0.72604109 -0.36722827 ...  2.20219708  1.04943754
   -0.44221604]
  [-1.43364744  0.54701702  1.08795598 ...  0.19549939 -0.12604844
   -0.74936097]
  [-0.59335595  0.46807169 -0.04178975 ... -1.1783837   0.0395992
    0.55109001]]]

print(np.array_equal(B, D))

True