How to use the Numpy append function

This tutorial will show you how to use the NumPy append function (sometimes called np.append).

Here, I’ll explain what the function does. I’ll explain the syntax (piece by piece), and I’ll show you some step-by-step examples so you can see exactly how np.append works.

Let’s get to it.

Numpy append appends values to an existing numpy array

The NumPy append function enables you to append new values to an existing NumPy array.

Other tutorials here at Sharp Sight have shown you ways to create a NumPy array. You can create one from a list using the np.array function. You can use the zeros function to create a NumPy array with all zeros. You can use the NumPy arange function to create NumPy arrays as sequences of regularly spaced values. All of those methodologies enable you to create a new NumPy array.

But often times, you’ll have an existing array and you need to add new elements. To do that, none of those functions will do. You need a new tool.

Enter the np.append function.

The syntax of numpy append

Let’s take a look at the syntax of the np.append function.

Much like the other functions from NumPy, the syntax is fairly straightforward and easy to understand. Let’s break it down.

Typically, we call the function using the syntax np.append(). Keep in mind that this assumes that you’ve imported the NumPy module with the code import numpy as np.

Once you call the function itself – like all NumPy functions – there are a set of parameters that enable you to precisely control the behavior of the append function.

Let’s take a look at the parameters of NumPy append.

arr
The arr parameter specifies the base array to which you will append the new values. Said differently, it’s the array that you’re going to modify by appending new values.

values
The values parameter specifies the values that you want to append to the base array (i.e., the values you will append to the array specified in the arr parameter).

The values that you specify here can be presented as a list of literal values (i.e. [1, 2, 3]) or you can specify a ndarray object by providing the name of the NumPy array.

axis (optional)
The axis parameter specifies the axis upon which you will append the new values to the original array.

By default, axis = None. If you specify a value, you will specify axis equals 0 or 1.

Now at this point, you might be asking … “what the hell is an axis?”

I’ll be honest. Axes in the NumPy system are one of the hardest things for most beginners to understand. It’s not that hard once they are explained, but array axes are not intuitive (at least, they aren’t intuitive the way they’ve been implemented in NumPy).

Axes are best explained with examples, so further down in this tutorial, I’ll show you exactly what the array axes are and how to think of them with respect to this syntax.

Examples: how to use numpy append

Now that we’ve examined the syntax at a high level, let’s take a look at some simple examples.

(By the way, when you’re learning any new syntax, the best way to master it is by studying and practicing simple examples.)

In the following examples, we’re going to be referring to the NumPy module as np, so make sure that you run this code:

import numpy as np

Append values to a 1-dimensional array

First, we’ll work with a very simple example.

Here, we’re going to append values to the end of a 1-dimensional array. This is much simpler than some other examples, because in this case, we don’t have to specify the axis.

First, let’s just create a simple, 1-dimensional array filled with ones.

base_array_1d = np.ones(3, dtype = int)

Essentially, this creates a 1-d NumPy array that contains three ones. If we printed this out with the code print(base_array_1d), we would see the following contents:

[ 1  1  1 ]

Now, let’s append 3 new values to the end of this array. To do this, we’ll use the NumPy append function.

np.append(base_array_1d, [6,7,8])

Which produces the following output:

array([1, 1, 1, 6, 7, 8])

Visually though, we can think of this operation as follows:

The np.append function is basically taking the new values ([6, 7, 8]) and attaching them to the end of the original array.

It’s pretty straight forward.

Append values to a 2-d array, WITHOUT an axis

Now, let’s append values to a 2-dimensional array.

There are a couple ways to do this. Importantly, you can append new values as a new row, or a new column, so to speak. Additionally, you can append new values without specifying whether it should be a row or column. That’s actually the simplest to do, so we’ll look at that first.

First, let’s create a simple 2 dimensional array:

base_array_2x2 = np.ones(shape = (2, 2), dtype = int)

This code creates a simple 2 by 2 array filled with ones that looks like this:

[[1 1]
 [1 1]]

Now that we have a base array to work with, let’s append two values. We’re going to use np.append to append two new values to this array. However, we are not going to specify where to add them. That is, we are not going to use the axis parameter to specify whether we will add the values as a new row or a new column.

np.append(base_array_2x2, [6,7])

Remember that the array base_array_2x2 is 2 dimensional. Also, notice that we did not use the axis parameter here to specify exactly where to add these new vales.

How will NumPy append handle this?

If you have a multi-dimensional array and you do not specify an axis with the axis parameter, np.append will flatten the original array first. That is, it will transform the array from a multi-dimensional array to a 1-dimensional array.

Once the array is flattened out, it will simply append the new values to the end.

This is often not what people want when they try to append new values to a multi-dimensional NumPy array, so you need to be careful.

If you want the base-array to maintain its original shape, you need to use the axis parameter of np.append to specify exactly where and how to attach the new values.

Let’s take a look at some examples of how to do that.

How to append new values as a new row

As we just saw, appending new values to a NumPy array gets a little more complicated when you’re working with multi-dimensional arrays. In particular, things get more complicated when you want to add new values specifically as new rows or columns.

If you want to append new values as a row (or a column), then you have to use the axis parameter of the NumPy append function. There are also a couple other details that you need to be mindful of, otherwise you’ll get an error.

Let’s take a look at an example, so you can see what I mean.

Here, we’re going to append two new values as a new row of data. That is, we’re going to append the values to the bottom of a 2-d NumPy array.

First, let’s create our 2-d NumPy array:

base_array_2x2 = np.ones(shape = (2, 2), dtype = int)

This is a very simple 2-dimensional array that contains all 1’s:

[[1 1]
 [1 1]]

Next, we’re going to add two new values to the bottom of the array:

np.append(base_array_2x2, [[8, 8]], axis = 0)

Notice that in order to do this, we needed to use the axis parameter. Specifically, we set axis = 0.

I’m going to be honest. Array axes are one of the more challenging and un-intuitive things in NumPy. I’ll probably write a blog post to explain them at some point in the future.

Having said that, you need to remember that to add the values to the bottom of an array (i.e., as a new row of data), you need to set axis = 0.

There’s also something else that you need to pay attention to.

Critically, when you use the axis parameter to append new values to an existing NumPy array, the new values must have the right dimensions. So if your original array is a 2-dimensional array, the new values that you’re appending must also be structured as a 2-d array.

If the new values are not structured properly, you’ll get an error. For example:

np.append(base_array_2x2, [8, 8], axis = 0)  

This code produces the following error:

ValueError: all the input arrays must have same number of dimensions

Why? WTF is going on here?

Look very carefully at the code. The new values that we’re trying to append are structured as a 1-d structure. You can tell because they are only enclosed by single brackets: [8, 8]. NumPy append is basically treating this as a 1-d array of values, and it’s trying to append it to a pre-existing 2-d NumPy array. The dimensions do not match.

To get this to work properly, the new values must be structured as a 2-d array. In other words, the new values need to be passed to the append() function as a list-of-lists: [[8, 8]]. This is a little subtle if you’re a beginner so pay careful attention. The values here are enclosed by two sets of brackets: [[8, 8]]. The np.append function will treat this as a 2-d array (instead of a 1-d array). That’s why the code np.append(base_array_2x2, [[8, 8]], axis = 0) works, but np.append(base_array_2x2, [8, 8], axis = 0) doesn’t.

Essentially, when you’re appending values like this, need to watch the number of brackets. The number of brackets that will dictate the number of dimensions of your new values … and np.append expects the new values to have the same dimensions of the original array.

How to append new values as a new column

Now let’s append new values as a new column.

This works in a way that’s very similar to our prior example of adding values as a new row. Having said that, make sure you’ve read the prior example before trying this … the principle are the same, so you need to understand what was written in the prior example.

Ok. Here, we’re going to create a simple 2-d array containing all 1’s.

base_array_2x2 = np.ones(shape = (2, 2), dtype = int)

Next, we’re going to create another NumPy array that has 2 rows and 1 column. To do this, we’re going to create the array with the np.array function, and then reshape the array using np.reshape.

new_array_2x1 = np.array([9, 9]).reshape(2, 1)

We need this new array to be shaped in a particular way, because when we append new values to a multi-dimensional array, the array dimensions must match. (If you don’t understand this, please review the previous section.) In this case, it’s easier to create an array with the right dimensions by using np.array along with the reshape method.

Ok, now that we have two arrays with the right dimensions, we will append the new array to the base array using the np.append function:

np.append(base_array_2x2, new_array_2x1, axis = 1)

Notice here that we’re using the axis parameter again. Specifically, we’re setting axis = 1. Essentially, this indicates that we want to append the new values to the base array as a new column.

Once again, I’ll point out that the axis parameter can be a little confusing, especially for beginners. I recommend that you just memorize which is which.

When you use axis = 1, NumPy append will add the new values as a column. When you use axis = 0, NumPy append will add the new values as a row.

Numpy is important so make sure to master np.append

In general, NumPy is important for data science in Python.

In particular, many of the tools and libraries for data science in Python either use or are built on top of NumPy.

For example, the Pandas library is built on top of NumPy.

Moreover, there are important uses of NumPy in both machine learning and deep learning.

That being said, if you want to learn and master data science in Python, sign up for our email list.

For more Python data science tutorials, sign up for our email list

Here at Sharp Sight, we teach data science. We want to help you master data science as fast as possible.

If you sign up for our email list, you’ll receive Python data science tutorials delivered to your inbox.

You’ll get free tutorials on:

• NumPy
• Pandas
• Base Python
• Scikit learn
• Machine learning
• Deep learning
• … and more.

Want to learn data science in Python? Sign up now.