How to Use Numpy vstack

by

In this tutorial, I’ll explain how to use the NumPy vstack function, which is also called numpy.vstack or np.vstack.

This is a very simple NumPy function, but in case you’re more of a beginner, this tutorial will explain almost everything you need to know. It will give you a quick background to NumPy, explain the syntax of NumPy vstack, and it will show you clear, step-by-step examples.

That said, if you’re in a hurry and want to find a quick answer to something, you can click on any of the following links and it will take you to the appropriate place in the tutorial.

Contents:

Ok. Let’s get started.

A quick review of NumPy

First, let’s talk about NumPy.

For people who are getting started with Python, and data science in Python, NumPy is a little confusing.

Let me clear things up.

NumPy is just a toolkit for working with numbers in Python.

More specifically, it’s a toolkit for working with arrays of numbers.

These special arrays of numbers are called NumPy arrays.

These NumPy arrays can be 1-dimensional, like this …

A simple example of a 1-dimensional numpy array with the numbers 0 to 3.

Or they can have 2-dimensions …

An example of a 2-dimensional NumPy array with the numbers 0 to 7.

They can even have multiple dimensions (more than two).

NumPy provides tools for creating these arrays of numbers.

And it also has tools for manipulating these arrays of numbers. For example, there are tools for reshaping arrays.

One of the common things that you will need to do with arrays is combine them together.

… which brings us to NumPy vstack.

A quick introduction to NumPy vstack

NumPy vstack is a tool for combining together Numpy arrays.

It’s essentially a data manipulation tool in NumPy.

Numpy vstack is actually one of several Numpy tools for combining Numpy arrays. Numpy vstack, Numpy hstack, and Numpy concatenate are all somewhat similar. For example, NumPy concatenate is a very flexible tool for combining together NumPy arrays, either vertically or horizontally. And then there’s NumPy hstack, which enables you to combine together arrays horizontally.

NumPy vstack is related to NumPy concatenate and NumPy hstack, except it enables you to combine together NumPy arrays vertically.

A visual example showing how NumPy vstack combines together arrays vertically.

So it’s sort of like the sibling of np.hstack. NumPy hstack combines arrays horizontally and NumPy vstack combines together arrays vertically.

So now that you know what NumPy vstack does, let’s take a look at the syntax.

NumPy vstack syntax

The syntax of NumPy vstack is very simple.

Typically, we’ll call the function with the name np.vstack(), although exactly how you call it depends on how you import the NumPy module.

If you import NumPy with the code import numpy as np, then you can refer to NumPy in your syntax with the alias np. This is a common convention, so I’ll use it here (although I will also refer to the function as numpy.hstack).

Having said all of that, let’s take closer look at the syntax.

The syntax of np.vstack

As I noted a couple of paragraphs ago, the syntax of np.vstack is extremely simple.

You call the function with the code np.vstack(), and then inside of the function, we need to provide the names of the arrays that we want to combine.

A visual explanation of the syntax of np.vstack.

In fact, the arrays that you want to combine together are the only argument to the function.

Having said that, there is a little bit of flexibility in terms of how we specify the inputs, so let’s talk about the input argument.

The arguments of np.vstack

As I mentioned, there’s only one real argument to the np.vstack function … the input arrays that you want to combine together.

Here, I’ll refer to the input arrays collectively as input-arrays

input-arrays (required)

The collection of input arrays is the only thing you need to provide as an input (AKA, argument) to the function.

Having said that, np.vstack is flexible. It will accept a variety of input types, and they can be presented inside of a few different structures.

Let me explain what I mean.

The input arrays can be organized inside of any Python sequence

According to the documentation of NumPy vstack, the input should be a sequence of NumPy arrays. So you need to provide multiple NumPy arrays inside of some type of sequence.

Furthermore, the documentation shows the arrays organized inside of a tuple. So if you had two NumPy arrays, array1 and array2, you could write the code something like this:

# OPTION 1
np.vstack((array1, array2))

Notice that the arrays in the above code, array1 and array2, are organized inside of a tuple. We can tell that they are organized as a tuple, because they are enclosed in parenthesis.

But you could also put those arrays together inside of a Python list.

# OPTION 2
np.vstack([array1, array2])

Here, we can tell that they are organized as a list, because they are enclosed inside of square brackets.

So, both lists of arrays and tuples of arrays will work as on input.

In fact, when we present our input arrays to np.vstack, they can be organized inside of almost any type of Python sequence … a list, a tuple, etc.

NumPy vstack will also operate on lists of numbers

Furthermore, np.vstack will actually operate on things other than NumPy arrays.

Specifically, you can give it lists of numbers.

So the following will work:

np.vstack(([0,0],[1,1]))

Here, instead of inputting two NumPy arrays inside of a tuple, we’re using two Python lists inside of a tuple.

We could even use two Python lists inside of a list: np.vstack([[0,0],[1,1]]).

What I’m getting at is that the np.vstack function is extremely flexible in terms of the inputs that it will accept.

Having said that, I think this will be easier to understand when you can play with some working code, so let’s take a look at some examples.

Examples of how to use NumPy vstack

Here, we’ll take a look at a few examples of NumPy vstack.

The examples will start simple, and we’ll increase the complexity a little bit as we move forward.

Examples:

Run this code first

One quick note before you get started.

As I mentioned in the syntax section, how exactly you call the function depends on how you import NumPy.

If you import NumPy with the code import numpy, then you can call the function with the code numpy.vstack().

However, if you import NumPy with the code import numpy as np, then you call the function with the code np.vstack().

We’ll be using the later convention, so you need to import NumPy with the following code:

import numpy as np

Make sure you run that before you run these examples!

Example 1: combine two Python lists with np.vstack

Ok, first, we’re going to start simple.

Remember in the section about np.vstack syntax, I mentioned that the np.vstack function will actually accept Python lists as inputs … lists of numbers organized inside of a sequence.

That’s what I’m going to show you here, because I think this is an intuitive example. You can actually see the numeric inputs directly, and watch how they are transformed into the output.

Ok, let’s take a look.

As an input, we’re going to provide two Python lists, organized inside of a tuple:

np.vstack(([0,0],[1,1]))

Which produces the following output:

array([[0, 0],
       [1, 1]])

So what happened here?

We gave the np.vstack function two Python lists: [0,0] and [1,1].

These were collected together inside of a tuple: ([0,0],[1,1]).

That tuple was passed as the argument to the function.

And the Numpy vstack function just took those lists of numbers and stacked them on top of each other.

A visual example of how NumPy vstack combines two Python lists in the vertical direction.

NumPy vstack just “stacked” the two lists vertically.

That’s really all the function does!

Notice one thing though … even though the inputs are Python lists (organized inside of a tuple) the output is a NumPy array.

Example 2: combine two 1-d NumPy arrays with np.vstack

Next, let’s make this a little more complicated.

Here, we’re going to essentially re-do the previous example, but with proper NumPy arrays instead of Python lists.

Create NumPy arrays

First, let’s just create the NumPy arrays. 

np_array_zeros_1d = np.array([0,0])
np_array_ones_1d = np.array([1,1])

And we can print them to see what they contain:

print(np_array_zeros_1d)
print(np_array_ones_1d)

OUT:

[0 0]

[1 1]

The first array, np_array_zeros_1d, is a 1-dimensional NumPy array that contains zeros.

And the second array, np_array_ones_1d, is a 1-dimensional NumPy array that contains ones.

Stack the arrays using np.vstack

Now, we’re going to stack these arrays vertically using NumPy vstack.

np.vstack((np_array_zeros_1d,np_array_ones_1d))

OUT:

array([[0, 0],
       [1, 1]])

So what happened here?

We used two NumPy arrays as inputs, np_array_zeros_1d and np_array_ones_1d.

We organized these two arrays inside of a tuple: (np_array_zeros_1d,np_array_ones_1d).

And we passed that tuple as the input to np.vstack.

The output was a NumPy array that vertically stacked the contents of the two input arrays.

Example 3: combine two 2-d NumPy arrays with np.vstack

Now, let’s combine two 2-dimensional NumPy arrays.

This is very similar to the previous example … the only major difference is that we’re going to provide 2-dimensional inputs.

Create numpy arrays

First, we’ll create the arrays.

np_array_zeros_2d = np.zeros(shape = (2,2), dtype = 'int')
np_array_ones_2d = np.ones(shape = (3,2), dtype = 'int')

And we can print them out using the print function:

print(np_array_zeros_2d)

print(np_array_ones_2d)

OUT:

[[0 0]
 [0 0]]

[[1 1]
 [1 1]
 [1 1]]

So we have two 2-dimensional NumPy arrays. Notice also that they have the same number of columns but different numbers of rows.

This is important. Because we are going to stack these arryas vertically they need to have the same number of columns.

Combine arrays with numpy vstack

Ok, now we’re going to combine the arrays.

np.vstack((np_array_zeros_2d, np_array_ones_2d))

Which produces the following NumPy array as output:

array([[0, 0],
       [0, 0],
       [1, 1],
       [1, 1],
       [1, 1]])

So what happened here?

If you paid attention to the earlier, simpler examples, this should make sense.

NumPy vstack just took the input arrays and stacked them vertically. It combined them “row wise.”

A visual showing how np.vstack combines two 2-dimensional NumPy arrays by stacking them vertically.

This is essentially all that np.vstack does … it vertically stacks NumPy arrays.

NumPy vstack FAQ

If you’ve been following along in the tutorial, it should be clear that NumPy vstack is fairly simple.

But, there are a few questions that people ask about it. Let me quickly answer some of those questions.

Frequently asked questions:

What’s the difference between np.hstack and np.vstack?

NumPy hstack and NumPy vstack are similar in that they both combine NumPy arrays together.

The major difference is that np.hstack combines NumPy arrays horizontally and np.vstack combines arrays vertically.

Other than that though, the syntax and behavior is very similar.

For more information about np.hstack, check out our tutorial about NumPy hstack.

What’s the difference between np.vstack and np.concatenate?

NumPy concatenate is like a more flexible version of np.vstack.

NumPy concatenate also combines together NumPy arrays, but it can combine arrays together either horizontally or vertically.

So NumPy concatenate has the ability to combine arrays together like np.vstack and it also has the ability to combine arrays together like np.hstack. How np.concatenate behaves depends on how you use the axis parameter in the syntax.

Another way of saying this is that np.vstack is like a special case of np.concatenate.

Let me show you an example.

If you have two NumPy arrays, you can combine them together vertically using np.vstack:

# CREATE ARRAYS
np_array_zeros_2d = np.zeros(shape = (2,2), dtype = 'int')
np_array_ones_2d = np.ones(shape = (3,2), dtype = 'int')

# COMBINE ARRAYS
np.vstack((np_array_zeros_2d, np_array_ones_2d))

Or you can combine them together vertically using np.concatenate, with the axis parameter set to 0:

# COMBINE ARRAYS
np.concatenate((np_array_zeros_2d, np_array_ones_2d), axis = 0)

Both of these functions will produce the same output:

array([[0, 0],
       [0, 0],
       [1, 1],
       [1, 1],
       [1, 1]])

Do the number of rows need to be the same?

No, when you use NumPy vstack, the input arrays can have a different number of rows.

Do the number of columns need to be the same?

Yes.

When you use NumPy vstack, the input arrays need to have the same number of columns.

There’s a lot more to learn about numpy

In this tutorial, I showed you how to use the NumPy vstack function.

But if you’re learning NumPy, there’s a lot more to learn.

There are quite a few functions for creating NumPy arrays. For example, the NumPy arange function creates arrays with ranges of numbers. Or the NumPy random normal function creates arrays with normally distributed data.

And there are quite a few NumPy functions for performing numeric calculations, like NumPy power, the np.exp function, etcetera.

Furthermore, if you’re serious about data science in Python, you should also learn about Pandas, matplotlib, seaborn, and sci-kit learn.

For data science tutorials, sign up for our email list

If you want FREE access to tutorials about all of those Python data science topics, then sign up for our email list.

When you sign up, you’ll get FREE tutorials on:

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

If you’re ready to learn more about NumPy and data science in Python, then sign up now.

Joshua Ebner

Joshua Ebner is the founder, CEO, and Chief Data Scientist of Sharp Sight.   Prior to founding the company, Josh worked as a Data Scientist at Apple.   He has a degree in Physics from Cornell University.   For more daily data science advice, follow Josh on LinkedIn.

Leave a Comment