{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"# NumPy Broadcasting\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Overview\n",
"Before we begin, it is important to know that broadcasting is a valuable part of the power that NumPy provides. However, there's no looking past the fact that broadcasting can be conceptually difficult to digest. This information can be helpful and very powerful, but it may be more prudent to first start learning the other label-based elements of the Python ecosystem, [Pandas](../pandas) and [Xarray](../xarray). This can make understanding NumPy broadcasting easier or simpler when using real-world data. When you are ready to learn about NumPy broadcasting, this section is organized as follows:\n",
"\n",
"1. An introduction to broadcasting\n",
"1. Avoiding loops with vectorization"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Prerequisites\n",
"\n",
"| Concepts | Importance | Notes |\n",
"| --- | --- | --- |\n",
"| [NumPy Basics](numpy-basics) | Necessary | |\n",
"| [Intermediate NumPy](intermediate-numpy) | Helpful | |\n",
"| [Conceptual guide to broadcasting](https://numpy.org/doc/stable/user/theory.broadcasting.html#array-broadcasting-in-numpy) | Helpful | |\n",
"\n",
"* **Time to learn**: 30 minutes\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Imports\n",
"\n",
"As always, when working with NumPy, it must be imported first:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import numpy as np"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Using broadcasting to implicitly loop over data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### What is broadcasting?\n",
"Broadcasting is a useful NumPy tool that allows us to perform operations between arrays with different shapes, provided that they are compatible with each other in certain ways. To start, we can create an array below and add 5 to it:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a = np.array([10, 20, 30, 40])\n",
"a + 5"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This works even though 5 is not an array. It behaves as expected, adding 5 to each of the elements in `a`. This also works if 5 is an array:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"b = np.array([5])\n",
"a + b"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This takes the single element in `b` and adds it to each of the elements in `a`. This won't work for just any `b`, though; for instance, the following won't work:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"tags": [
"raises-exception"
]
},
"outputs": [],
"source": [
"b = np.array([5, 6, 7])\n",
"a + b"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It does work if `a` and `b` are the same shape:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"b = np.array([5, 5, 10, 10])\n",
"a + b"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"What if what we really want is pairwise addition of a and b? Without broadcasting, we could accomplish this by looping:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"b = np.array([1, 2, 3, 4, 5])"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"result = np.empty((5, 4), dtype=np.int32)\n",
"for row, valb in enumerate(b):\n",
" for col, vala in enumerate(a):\n",
" result[row, col] = vala + valb\n",
"result"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can also do this by manually repeating the arrays to the proper shape for the result, using `np.tile`. This avoids the need to manually loop:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"aa = np.tile(a, (5, 1))\n",
"aa"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Turn b into a column array, then tile it\n",
"bb = np.tile(b.reshape(5, 1), (1, 4))\n",
"bb"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"aa + bb"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Giving NumPy room for broadcasting\n",
"We can also do this using broadcasting, which is where NumPy implicitly repeats the array without using additional memory. With broadcasting, NumPy takes care of repeating for you, provided dimensions are \"compatible\". This works as follows:\n",
"1. Check the number of dimensions of the arrays. If they are different, *prepend* dimensions of size one until the arrays are the same dimension shape.\n",
"2. Check if each of the dimensions are compatible. This works as follows:\n",
" - Each dimension is checked.\n",
" - If one of the arrays has a size of 1 in the checked dimension, or both arrays have the same size in the checked dimension, the check passes.\n",
" - If all dimension checks pass, the dimensions are compatible.\n",
"\n",
"For example, consider the following arrays:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a.shape"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"b.shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Right now, these arrays both have the same number of dimensions. They both have only one dimension, but that dimension is incompatible. We can solve this by appending a dimension using `np.newaxis` when indexing, like this:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"bb = b[:, np.newaxis]\n",
"bb.shape"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a + bb"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"(a + bb).shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can also make the code more succinct by performing the newaxis and addition operations in a single line, like this:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a + b[:, np.newaxis]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Extending to higher dimensions\n",
"The same broadcasting ability and rules also apply for arrays of higher dimensions. Consider the following arrays `x`, `y`, and `z`, which are all different dimensions. We can use newaxis and broadcasting to perform $x^2 + y^2 + z^2$:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"x = np.array([1, 2])\n",
"y = np.array([3, 4, 5])\n",
"z = np.array([6, 7, 8, 9])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"First, we extend the `x` array using newaxis, and then square it. Then, we square `y`, and broadcast it onto the extended `x` array:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"d_2d = x[:, np.newaxis] ** 2 + y**2"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"d_2d.shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Finally, we further extend this new 2-D array to a 3-D array using newaxis, square the `z` array, and then broadcast `z` onto the newly extended array:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"d_3d = d_2d[..., np.newaxis] + z**2"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"d_3d.shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As described above, we can also perform these operations in a single line of code, like this:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"h = x[:, np.newaxis, np.newaxis] ** 2 + y[np.newaxis, :, np.newaxis] ** 2 + z**2"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can use the shape method to see the shape of the array created by the single line of code above. As you can see, it matches the shape of the array created by the multi-line process above:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"h.shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can also use the all method to confirm that both arrays contain the same data:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"np.all(h == d_3d)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Broadcasting is often useful when you want to do calculations with coordinate values, which are often given as 1-D arrays corresponding to positions along a particular array dimension. For example, we can use broadcasting to help with taking range and azimuth values for radar data (1-D separable polar coordinates) and converting to x,y pairs relative to the radar location."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Given the 3-D temperature field and 1-D pressure coordinates below, let's calculate $T * exp(P / 1000)$. We will need to use broadcasting to make the arrays compatible. The following code demonstrates how to use newaxis and broadcasting to perform this calculation:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"pressure = np.array([1000, 850, 500, 300])\n",
"temps = np.linspace(20, 30, 24).reshape(4, 3, 2)\n",
"pressure.shape, temps.shape"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"pressure[:, np.newaxis, np.newaxis].shape"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"temps * np.exp(pressure[:, np.newaxis, np.newaxis] / 1000)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Vectorize calculations to avoid explicit loops"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When working with arrays of data, loops over the individual array elements is a fact of life. However, for improved runtime performance, it is important to avoid performing these loops in Python as much as possible, and let NumPy handle the looping for you. Avoiding these loops frequently, but not always, results in shorter and clearer code as well."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Look ahead/behind\n",
"\n",
"One common pattern for vectorizing is in converting loops that work over the current point, in addition to the previous point and/or the next point. This comes up when doing finite-difference calculations, e.g., approximating derivatives:\n",
"\n",
"\\begin{equation*}\n",
"f'(x) = f_{i+1} - f_{i}\n",
"\\end{equation*}"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a = np.linspace(0, 20, 6)\n",
"a"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can calculate the forward difference for this array using a manual loop, like this:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"d = np.zeros(a.size - 1)\n",
"for i in range(len(a) - 1):\n",
" d[i] = a[i + 1] - a[i]\n",
"d"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It would be nice to express this calculation without a loop, if possible. To see how to go about this, let's consider the values that are involved in calculating `d[i]`; in other words, the values `a[i+1]` and `a[i]`. The values over the loop iterations are:\n",
"\n",
"| i | a[i+1] | a[i] |\n",
"| --- | ---- | ---- |\n",
"| 0 | 4 | 0 |\n",
"| 1 | 8 | 4 |\n",
"| 2 | 12 | 8 |\n",
"| 3 | 16 | 12 |\n",
"| 4 | 20 | 16 |\n",
"\n",
"We can then express the series of values for `a[i+1]` as follows:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a[1:]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can also express the series of values for `a[i]` as follows:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a[:-1]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This means that we can express the forward difference using the following statement:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"a[1:] - a[:-1]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It should be noted that using slices in this way returns only a **view** on the original array. In other words, you can use the slices to modify the original data, either intentionally or accidentally. Also, this is a quick operation that does not involve a copy and does not bloat memory usage."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### 2nd Derivative\n",
" \n",
"A finite-difference estimate of the 2nd derivative is given by the following equation (ignoring $\\Delta x$):\n",
"\n",
"\\begin{equation*}\n",
"f''(x) = 2\n",
"f_i - f_{i+1} - f_{i-1}\n",
"\\end{equation*}\n",
"\n",
"Let's write some vectorized code to calculate this finite difference for `a`, using slices. Analyze the code below, and compare the result to the values you would expect to see from the 2nd derivative of `a`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"2 * a[1:-1] - a[2:] - a[:-2]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Blocking\n",
"\n",
"Another application that can become more efficient using vectorization is operating on blocks of data. Let's start by creating some temperature data (rounding to make it easier to see and recognize the values):"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"temps = np.round(20 + np.random.randn(10) * 5, 1)\n",
"temps"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Let's start by writing a loop to take a 3-point running mean of the data. We'll do this by iterating over all points in the array and averaging the 3 points centered on each point. We'll simplify the problem by avoiding dealing with the cases at the edges of the array:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"avg = np.zeros_like(temps)\n",
"for i in range(1, len(temps) - 1):\n",
" sub = temps[i - 1 : i + 2]\n",
" avg[i] = sub.mean()"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"avg"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As with the case of doing finite differences, we can express this using slices of the original array instead of loops:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# i - 1 i i + 1\n",
"(temps[:-2] + temps[1:-1] + temps[2:]) / 3"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Another option to solve this type of problem is to use the powerful NumPy tool `as_strided` instead of slicing. This tool can result in some odd behavior, so take care when using it. However, the trade-off is that the `as_strided` tool can be used to perform powerful operations. What we're doing here is altering how NumPy is interpreting the values in the memory that underpins the array. Take this array, for example:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"temps"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Using `as_strided`, we can create a view of this array with a new, bigger shape, with rows made up of overlapping values. We do this by specifying a new shape of 8x3. There are 3 columns, for fitting blocks of data containing 3 values each, and 8 rows, to correspond to the 8 blocks of data of that size that are possible in the original 1-D array. We can then use the `strides` argument to control how NumPy walks between items in each dimension. The last item in the strides tuple simply states that the number of bytes to walk between items is just the size of an item. (Increasing this last item would skip items.) The first item says that when we go to a new element (in this example, a new row), only advance the size of a single item. This is what gives us overlapping rows. The code for these operations looks like this:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"block_size = 3\n",
"new_shape = (len(temps) - block_size + 1, block_size)\n",
"bytes_per_item = temps.dtype.itemsize\n",
"temps_strided = np.lib.stride_tricks.as_strided(\n",
" temps, shape=new_shape, strides=(bytes_per_item, bytes_per_item)\n",
")\n",
"temps_strided"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now that we have this view of the array with the rows representing overlapping blocks, we can operate across the rows with `mean` and the `axis=-1` argument to get our running average:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"temps_strided.mean(axis=-1)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It should be noted that there are no copies going on here, so if we change a value at a single indexed location, the change actually shows up in multiple locations:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"temps_strided[0, 2] = 2000\n",
"temps_strided"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Finding the difference between min and max\n",
"\n",
"Another operation that crops up when slicing and dicing data is trying to identify a set of indices along a particular axis, contained within a larger multidimensional array. For instance, say we have a 3-D array of temperatures, and we want to identify the location of the $-10^oC$ isotherm within each column:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"pressure = np.linspace(1000, 100, 25)\n",
"temps = np.random.randn(25, 30, 40) * 3 + np.linspace(25, -100, 25).reshape(-1, 1, 1)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"NumPy has the function `argmin()`, which returns the index of the minimum value. We can use this to find the minimum absolute difference between the value and -10:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Using axis=0 to tell it to operate along the pressure dimension\n",
"inds = np.argmin(np.abs(temps - -10), axis=0)\n",
"inds"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"inds.shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Great! We now have an array representing the index of the point closest to $-10^oC$ in each column of data. We can use this new array as a lookup index for our pressure coordinate array to find the pressure level for each column:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"pressure[inds]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now, we can try to find the closest actual temperature value using the new array:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"temps[inds, :, :].shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Unfortunately, this replaced the pressure dimension (size 25) with the shape of our index array (30 x 40), giving us a 30 x 40 x 30 x 40 array. Obviously, if scientifically relevant data values were being used, this result would almost certainly make such data invalid. One solution would be to set up a loop with the `ndenumerate` function, like this:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"output = np.empty(inds.shape, dtype=temps.dtype)\n",
"for (i, j), val in np.ndenumerate(inds):\n",
" output[i, j] = temps[val, i, j]\n",
"output"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Of course, what we really want to do is avoid the explicit loop. Let's temporarily simplify the problem to a single dimension. If we have a 1-D array, we can pass a 1-D array of indices (a full range), and get back the same as the original data array:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"pressure[np.arange(pressure.size)]"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"np.all(pressure[np.arange(pressure.size)] == pressure)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can use this to select all the indices on the other dimensions of our temperature array. We will also need to use the magic of broadcasting to combine arrays of indices across dimensions."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This can be written as a vectorized solution. For example:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"y_inds = np.arange(temps.shape[1])[:, np.newaxis]\n",
"x_inds = np.arange(temps.shape[2])\n",
"temps[inds, y_inds, x_inds]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now, we can use this new array to find, for example, the relative humidity at the $-10^oC$ isotherm:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"np.all(output == temps[inds, y_inds, x_inds])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Summary\n",
"We've previewed some advanced NumPy capabilities, with a focus on _vectorization_; in other words, using clever broadcasting and data windowing techniques to enhance the speed and readability of our calculation code. By making use of vectorization, you can reduce explicit construction of loops in your code, and improve speed of calculation throughout the execution of such code.\n",
"\n",
"### What's next\n",
"This is an advanced NumPy topic; however, it is important to learn this topic in order to design calculation code that maximizes scalability and speed. If you would like to explore this topic further, please review the links below. We also suggest diving into label-based indexing and subsetting with [Pandas](../pandas) and [Xarray](../xarray), where some of this broadcasting can be simplified, or have added context."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Resources and references\n",
"* [NumPy Broadcasting Documentation](https://docs.scipy.org/doc/numpy/user/basics.broadcasting.html)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.9"
}
},
"nbformat": 4,
"nbformat_minor": 4
}