A Workshop Introduction to NumPy

The Python language is an excellent tool for general-purpose programming, with a highly readable syntax, rich and powerful data types (strings, lists, sets, dictionaries, arbitrary length integers, etc) and a very comprehensive standard library. It was not, however, designed specifically for mathematical and scientific computing. Neither the language nor its standard library have facilities for the efficient representation of multidimensional datasets, tools for linear algebra and general matrix manipulations (essential building blocks of virtually all scientific computing).

For example, Python lists are very flexible containers that can be nested arbitrarily deep and can hold any Python object in them, but they are poorly suited to represent common mathematical constructs like vectors and matrices. It is for this reason that NumPy exists.

Workshop Aims

The aim of this workshop is to enable you use NumPy to:

  • manipulate numerical arrays, and
  • perform efficient array calculations.

Getting Started with NumPy

Learning outcome: by the end of this section, you will be able to create NumPy arrays with the aid of the NumPy documentation.

NumPy is the fundamental package for scientific computing with Python. Its primary purpose is to provide a powerful N-dimensional array object; the focus for this workshop.

To begin with let's import NumPy, check where it is being imported from and check the version.


In [ ]:
# NumPy is generally imported as 'np'.
import numpy as np
print(np)
print(np.__version__)

Documentation

Here is a link to the NumPy documentation for v1.11: https://docs.scipy.org/doc/numpy-1.11.0/reference/

There are many online forums with tips and suggestions for solving problems with NumPy, such as http://stackoverflow.com/

Explore: creating arrays

NumPy provides many different ways to create arrays. These are listed in the documentation at: https://docs.scipy.org/doc/numpy-1.11.0/user/basics.creation.html#arrays-creation.

Exercise

Part 1

Try out some of these ways of creating NumPy arrays. See if you can produce:

  • a NumPy array from a list of numbers,
  • a 3-dimensional NumPy array filled with a constant value -- either 0 or 1,
  • a NumPy array filled with a constant value -- not 0 or 1. (Hint: this can be achieved using the last array you created, or you could use np.empty and find a way of filling the array with a constant value),
  • a NumPy array of 8 elements with a range of values starting from 0 and a spacing of 3 between each element, and
  • a NumPy array of 10 elements that are logarithmically spaced.

In [ ]:


In [ ]:


In [ ]:

Part 2

How could you change the shape of the 8-element array you created previously to have shape (2, 2, 2)? Hint: this can be done without creating a new array.


In [ ]:

Motivation: what are arrays good for?

Learning outcome: by the end of this section, you will understand key benefits of using NumPy arrays for numerical processing in Python.

Extensive Features

NumPy provides routines for fast operations on arrays, including mathematical, logical, shape manipulation, sorting, selecting, I/O, discrete Fourier transforms, basic linear algebra, basic statistical operations, random simulation and much more.

Fast Calculations

It is a lot faster than Python alone for numerical computing tasks.

Element-by-element operations are the “default mode” when an ndarray is involved, but the element-by-element operation is speedily executed by pre-compiled C code.

Clear Syntax

In NumPy,

c = a * b

calculates the element-wise product of a and b, at near-C speeds, but with the code simplicity we expect from the Python language.

This demonstrates a core feature of NumPy, called vectorization. This removes the need for loops iterating through elements of arrays, which can make code easier to read, as well as performing fast calculations.

Interfacing to other Libraries

Many scientific Python libraries use NumPy as their core array representation. From plotting libraries such as matplotlib, to parallel processing libraries such as Dask, to data interoperability libraries such as Iris, NumPy arrays are at the core of how these libraries operate and communicate.

The Array Object

Learning outcome: by the end of this section, you will be able to manipulate NumPy array objects through indexing and explain key features and properties of NumPy arrays.

The multidimensional array object is at the core of all of NumPy's functionality. Let's explore this object some more.

Array properties

Let's create a NumPy array and take a look at some of its properties.


In [ ]:
arr = np.ones((3, 2, 4))

print("Array shape:", arr.shape)
print("Array element dtype:", arr.dtype)

Exercise

Part 1

Use the code cells below to explore features of this array.


In [ ]:


In [ ]:

Part 2

Consider the following NumPy array properties:

  • ndim,
  • nbytes,
  • size,
  • T.

For each of these properties:

  • Use information from the array documentation to find out more about each array property.
  • Apply each property to the array arr defined above. Can you explain the results you get in each case?

In [ ]:


In [ ]:

Indexing

You can index NumPy arrays in the same way as other Python objects, by using square brackets []. This means we can index to retrieve a single element, multiple consecutive elements, or a more complex sequence:


In [ ]:
arr = np.array([1, 2, 3, 4, 5, 6])
print(arr)

In [ ]:
print("arr[2] = {}".format(arr[2]))
print("arr[2:5] = {}".format(arr[2:5]))
print("arr[::2] = {}".format(arr[::2]))

You can also index multidimensional arrays using an enhanced indexing syntax, which allows for multi-element indexing. (Sometimes this is referred to as "extended slicing".) Remember that Python uses zero-based indexing!


In [ ]:
lst_2d = [[1, 2, 3], [4, 5, 6]]
arr_2d = arr.reshape(2, 3)

print("2D list:")
print(lst_2d)

In [ ]:
print("2D array:")
print(arr_2d)

In [ ]:
print("Single array element:")
print(arr_2d[1, 2])

In [ ]:
print("Single row:")
print(arr_2d[1])
print("First two columns:")
print(arr_2d[:, :2])

If you only provide one index to slice a multidimensional array, then the slice will be expanded to ":" for all of the remaining dimensions:


In [ ]:
print('Second row: {} is equivalent to {}'.format(arr_2d[1], arr_2d[1, :]))

This is known as ellipsis. Ellipsis can be specified explicitly using "...", which automatically expands to ":" for each dimension unspecified in the slice:


In [ ]:
arr1 = np.empty((4, 6, 3))
print('Original shape: ', arr1.shape)
print(arr1[...].shape)
print(arr1[..., 0:2].shape)
print(arr1[2:4, ..., ::2].shape)
print(arr1[2:4, :, ..., ::-1].shape)

Boolean Indexing

NumPy provides syntax to index conditionally, based on the data in the array.

You can pass in an array of True and False values (a boolean array), or, more commonly, a condition that returns a boolean array.


In [ ]:
print(arr_2d)

In [ ]:
bools = arr_2d % 2 == 0
print(bools)

In [ ]:
print(arr_2d[bools])

Exercise

Part 1

Why do these indexing examples give the stated results?

  • result of arr_2d[1, 0] is 4
  • result of arr_2d[0] is [1, 2, 3]
  • result of arr_2d[1, 1:] is [5, 6]
  • result of arr_2d[0:, ::2] is [[1, 3], [4, 6]]

In [ ]:

Part 2

How would you index arr_2d to retrieve:

  • the third value: resulting in 3
  • the second row: resulting in [4 5 6]
  • the first column: resulting in [1 4]
  • the first column, retaining the outside dimension: resulting in [[1] [4]]
  • only values greater than or equal to 3: resulting in [3 4 5 6]

In [ ]:

Arrays are not lists

Question: why do the following examples produce different results?


In [ ]:
print(lst_2d[0:2][1])
print(arr_2d[0:2, 1])

The result we just received points to an important piece of learning, which is that in most cases NumPy arrays behave very differently to Python lists. Let's explore the differences (and some similarities) between the two.

dtype

A NumPy array has a fixed data type, called dtype. This is the type of all the elements of the array.

This is in contrast to Python lists, which can hold elements of different types.

Exercise

  • What happens in Python when you add an integer to a float?
  • What happens when you put an integer into a NumPy float array?
  • What happens when you do numerical calculations between arrays of different types?

In [ ]:


In [ ]:


In [ ]:

Generating 2D coordinate arrays

A common requirement of NumPy arrays is to generate arrays that represent the coordinates of our data.

When orthogonal 1d coordinate arrays already exist, NumPy's meshgrid function is very useful:


In [ ]:
x = np.linspace(0, 9, 3)
y = np.linspace(4, 8, 3)
x2d, y2d = np.meshgrid(x, y)
print(x2d)
print(y2d)

The Array Object: Summary of key points

  • properties : shape, dtype.
  • arrays are homogeneous; all elements have the same type: dtype.
  • indexing arrays to produce further arrays: views on the original arrays.
  • multi-dimensional indexing (slicing) and boolean indexing.
  • combinations to form 2D arrays: meshgrid

Application: Arithmetic and Broadcasting

Learning outcome: by the end of this section you will be able to explain how broadcasting allows mathematical operations between NumPy arrays.

Elementwise Arithmetic

You can use NumPy to perform arithmetic operations between two arrays in an element-by-element fashion.


In [ ]:
arr1 = np.arange(4)
arr2 = np.arange(4)

print('{} + {} = {}'.format(arr1, arr2, arr1 + arr2))

Exercise

Explore arithmetic operations between arrays:

  • Create a number of arrays of different shapes and dtypes. Make sure some of them include values of 0.
  • Make use of all the basic Python mathematical operators (i.e. +, -, *, /, //, %).

What operations work? What operations do not work? Can you explain why operations do or do not work?


In [ ]:


In [ ]:


In [ ]:

It makes intrinsic sense that you should be able to add a constant to all values in an array:


In [ ]:
arr = np.arange(4)
const = 5

print("Original array: {}".format(arr))
print("")
print("Array + const: {}".format(arr + const))

Broadcasting

There are times when you need to perform calculations between NumPy arrays of different sizes. NumPy allows you to do this easily using a powerful piece of functionality called broadcasting.

Broadcasting is a way of treating the arrays as if they had the same dimensions and thus have elements all corresponding. It is then easy to perform the calculation, element-wise. It does this by matching dimensions in one array to the other where possible, and using repeated values where there is no corresponding dimension in the other array.

Rules of Broadcasting

Broadcasting applies these three rules:

  1. If the two arrays differ in their number of dimensions, the shape of the array with fewer dimensions is padded with ones on its leading (left) side.

  2. If the shape of the two arrays does not match in any dimension, either array with shape equal to 1 in a given dimension is stretched to match the other shape.

  3. If in any dimension the sizes disagree and neither has shape equal to 1, an error is raised.

Note that all of this happens without ever actually creating the expanded arrays in memory! This broadcasting behavior is in practice enormously powerful, especially given that when NumPy broadcasts to create new dimensions or to 'stretch' existing ones, it doesn't actually duplicate the data. In the example above the operation is carried out as if the scalar 1.5 was a 1D array with 1.5 in all of its entries, but no actual array is ever created. This can save lots of memory in cases when the arrays in question are large. As such this can have significant performance implications.

Exercise

For the following cases:

  • What will be the result of adding arr1 to arr2?
  • What will be the shape of the resulting array?
  • What rules of broadcasting are being used?

In [ ]:
arr1 = np.ones((2, 3))
arr2 = np.ones((2, 1))

# (arr1 + arr2).shape

In [ ]:
arr1 = np.ones((2, 3))
arr2 = np.ones(3)

# (arr1 + arr2).shape

In [ ]:
arr1 = np.ones((1, 3))
arr2 = np.ones((2, 1))

# (arr1 + arr2).shape

In [ ]:
arr1 = np.ones((1, 3))
arr2 = np.ones((1, 2))

# (arr1 + arr2).shape

Reshaping arrays to aid broadcasting

NumPy allows you to change the shape of an array, so long as the total number of elements in the array does not change. For example, we could reshape a flat array with 12 elements to a 2D array with shape (2, 6), or (3, 2, 2), or even (3, 4, 1). We could not, however, reshape it to have shape (2, 5), because the total number of elements would not be kept constant.

Exercise, continued

For the failing example above, what reshape operation could you apply to arr2 so that it can be broadcast with arr1?


In [ ]:

Arithmetic and Broadcasting: Summary of key points

  • arithmetic operations are performed in an element-by-element fashion,
  • operations can be performed between arrays of different shapes,
  • the arrays' dimensions are aligned according to fixed rules; where one input lacks a given dimension, values are repeated,
  • reshaping can be used to get arrays to combine as required.

Application: Statistics and Masked Arrays

Learning outcome: By the end of this section, you will be able to apply statistical operations and masked arrays to real-world problems.

Statistics

Numpy arrays support many common statistical calculations. For a list of common operations, see: https://docs.scipy.org/doc/numpy/reference/routines.statistics.html.

The simplest operations consist of calculating a single statistical value from an array of numbers -- such as a mean value, a variance or a minimum.

For example:


In [ ]:
a = np.arange(12).reshape((3, 4))
mean = np.mean(a)
print(a)
print(mean)

Used without any further arguments, statistical functions simply reduce the whole array to a single value. In practice, however, we very often want to calculate statistics over only some of the dimensions. The most common requirement is to calculate a statistic along a single array dimension, while leaving all the other dimensions intact. This is referred to as "collapsing" or "reducing" the chosen dimension.

This is done by adding an "axis" keyword specifying the dimension to collapse:


In [ ]:
print(np.mean(a, axis=1))

Exercise

  • What other similar statistical operations exist (see above link)?
  • A mean value can also be calculated with <array>.mean(). Is that the same thing?
  • Create a 3D array (that could be considered to describe [time, x, y]) and find the mean over all x and y at each timestep.
  • What shape does the result have?

In [ ]:


In [ ]:


In [ ]:

Masked Arrays

Real-world measurements processes often result in certain datapoint values being uncertain or simply "missing". This is usually indicated by additional data quality information, stored alongside the data values.

In these cases we often need to make calculations that count only the valid datapoints. NumPy provides a special "masked array" type for this type of calculation. Here's a link to the documentation for NumPy masked arrays: https://docs.scipy.org/doc/numpy-1.11.0/reference/maskedarray.generic.html#maskedarray-generic-constructing.

To construct a masked array we need some data and a mask. The data can be any kind of NumPy array, but the mask array must contain a boolean-type values only (either True and False or 1 and 0). Let's make each of these and convert them together into a NumPy masked array:


In [ ]:
data = np.arange(4)
mask = np.array([0, 0, 1, 0])
print('Data: {}'.format(data))
print('Mask: {}'.format(mask))
masked_data = np.ma.masked_array(data, mask)
print('Masked data: {}'.format(masked_data))

The mask is applied where the values in the mask array are True. Masked arrays are printed with a double-dash -- denoting the locations in the array where the mask has been applied.

The statistics of masked data are different:


In [ ]:
print('Unmasked average: {}'.format(np.mean(data)))
print('Masked average: {}'.format(np.ma.mean(masked_data)))

Note that most file formats represent missing data in a different way, using a distinct "missing data" value appearing in the data. There is special support for converting between this type of representation and NumPy masked arrays. Every masked array has a fill_value property and a filled() method to fill the masked points with the fill value.

Exercise

  • Create a masked array from the numbers 0-11, where all the values less than 5 are masked.
  • Create a masked array of positive values, with a value of -1.0 to represent missing points.
  • Look up the masked array creation documentation. What routines exist to produce masked arrays like the ones you've just created more efficiently?
  • Use np.ma.filled() to create a 'plain' (i.e. unmasked) array from a masked array.
  • How can you create a plain array from a masked array, but using a different fill-value for masked points?
  • Try performing a mathematical operation between two masked arrays. What happens to the 'fill_value' properties when you do so?

In [ ]:


In [ ]:

Statistics and Masked Arrays: Summary of key points

  • most statistical functions are available in two different forms, as in array.mean() and also np.mean(array), the choice being mostly a question of style.
  • statistical operations operate over, and remove (or "collapse") the array dimensions that they are applied to.
  • an "axis" keyword specifies operation over dimensions : this can be one; multiple; or all.
    • NOTE: not all operations permit operation over specifically selected dimensions
  • Statistical operations are not really part of NumPy itself, but are defined by the higher-level Scipy project.
  • Missing datapoints can be represented using "masked arrays"
    • these are useful for calculation, but usually require converting to another form for data storage

Application: Efficiency

Learning outcome: by the end of this section, you will be able to apply concepts that allow you to perform fast and efficient calculations on NumPy arrays.

Views on Arrays

NumPy attempts to not make copies of arrays. Many NumPy operations will produce a reference to an existing array, known as a "view", instead of making a whole new array. For example, indexing and reshaping provide a view of the same memory wherever possible.


In [ ]:
arr = np.arange(8)
arr_view = arr.reshape(2, 4)

# Print the "view" array from reshape.
print('Before\n{}'.format(arr_view))

# Update the first element of the original array.
arr[0] = 1000

# Print the "view" array from reshape again,
# noticing the first value has changed.
print('After\n{}'.format(arr_view))

What this means is that if one array (arr) is modified, the other (arr_view) will also be updated : the same memory is being shared. This is a valuable tool which enables the system memory overhead to be managed, which is particularly useful when handling lots of large arrays. The lack of copying allows for very efficient vectorized operations.

Remember, this behaviour is automatic in most of NumPy, so it requires some consideration in your code, it can lead to some bugs that are hard to track down. For example, if you are changing some elements of an array that you are using elsewhere, you may want to explicitly copy that array before making changes. If in doubt, you can always copy the data to a different block of memory with the copy() method.

For example:


In [ ]:
arr = np.arange(8)
arr_view = arr.reshape(2, 4).copy()

# Print the "view" array from reshape.
print('Before\n{}'.format(arr_view))

# Update the first element of the original array.
arr[0] = 1000

# Print the "view" array from reshape again,
# noticing the first value has changed.
print('After\n{}'.format(arr_view))

Loops and Vectorised Operations

We will now explore calculation performance and consider efficiency in terms of processing time.

Firstly let's look at a simple processing time tool that is provided in notebooks; %%timeit :


In [ ]:
%%timeit 
x = range(500)

Repeat that, specifying only 100 loops and fastest time of 5 runs


In [ ]:
%%timeit -n 100 -r 5
x = range(500)

This gives us an easy way to evaluate performance for implementations ...


In [ ]:
rands = np.random.random(1000000).reshape(100, 100, 100)

In [ ]:
%%timeit -n 10 -r 5
overPointEightLoop = 0
for i in range(100):
    for j in range(100):
        for k in range(100):
            if rands[i, j, k] > 0.8:
                overPointEightLoop +=1

In [ ]:
%%timeit -n 10 -r 5
overPointEightWhere = rands[rands > 0.8].size

Efficiency: Summary of key points

  • NumPy enables vectorised calculations that are fast:
    • Python loops are much slower.
  • NumPy can only use the system memory available to hold arrays:
    • very large arrays can result in a MemoryError.
  • Many NumPy operations return views on exisiting array:
    • a view shares memory with the original array,
    • changing array contents in place will affect all related views,
    • sometimes it is useful to explicitly copy arrays.

Exercise: trapezoidal integration

In this exercise, you are tasked with implementing the simple trapezoid rule formula for numerical integration. If we want to compute the definite integral

$$ \int_{a}^{b}f(x)dx $$

we can partition the integration interval $[a,b]$ into smaller subintervals. We then approximate the area under the curve for each subinterval by calculating the area of the trapezoid created by linearly interpolating between the two function values at each end of the subinterval:

For a pre-computed $y$ array (where $y = f(x)$ at discrete samples) the trapezoidal rule equation is:

$$ \int_{a}^{b}f(x)dx\approx\frac{1}{2}\sum_{i=1}^{n}\left(x_{i}-x_{i-1}\right)\left(y_{i}+y_{i-1}\right). $$

In pure python, this can be written as:

def trapz_slow(x, y):
    area = 0.
    for i in range(1, len(x)):
        area += (x[i] - x[i-1]) * (y[i] + y[i-1])
    return area / 2

Part 1

Create two arrays $x$ and $y$, where $x$ is a linearly spaced array in the interval $[0, 3]$ of length 11, and $y$ represents the function $f(x) = x^2$ sampled at $x$.


In [ ]:

Part 2

Use indexing (not a for loop) to find the 10 values representing $y_{i}+y_{i-1}$ for $i$ between 1 and 11.

Hint: What indexing would be needed to get all but the last element of the 1d array y. Similarly what indexing would be needed to get all but the first element of a 1d array.


In [ ]:

Part 3

Write a function trapz(x, y), that applies the trapezoid formula to pre-computed values, where x and y are 1-d arrays. The function should not use a for loop.


In [ ]:

Part 4

Verify that your function is correct by using the arrays created in #1 as input to trapz. Your answer should be a close approximation of $\int_0^3 x^2$ which is $9$.


In [ ]:

Part 5 (extension)

numpy and scipy.integrate provide many common integration schemes. Find the documentation for NumPy's own version of the trapezoidal integration scheme and check its result with your own:


In [ ]:

Part 6 (extension)

Write a function trapzf(f, a, b, npts=100) that accepts a function f, the endpoints a and b and the number of samples to take npts. Sample the function uniformly at these points and return the value of the integral.

Use the trapzf function to identify the minimum number of sampling points needed to approximate the integral $\int_0^3 x^2$ with an absolute error of $<=0.0001$. (A loop is necessary here.)


In [ ]:

Further Reading

Here are a selection of topics we chose not to include in this workshop, or only touched upon briefly. You may come across some of them or find these links and terms useful in the future.

Concepts:

Functions: