How to use NumPy hstack

In this tutorial, I’m going to show you how to use the NumPy hstack function, which is also called np.hstack or numpy.hstack.

This is a very simple tool that we use to manipulate NumPy arrays. Specifically, we use np.hstack to combine NumPy arrays horizontally. The function “stacks” arrays in the horizontal direction.

Again, this is a fairly simple function, but to use it properly, you need to know a few things. You first need to have a basic understanding of NumPy. You also need to know how the syntax works for this particular function. Once you have those things, you can start playing around with some code.

That being the case, this tutorial will give both a quick review of NumPy and it will then explain the syntax. Later in the tutorial, I’ll show you clear examples of how to use np.hstack.

Contents:

• A quick review of NumPy
• Introduction to NumPy hstack
• The syntax of np.hstack
• NumPy hstack examples
• Frequently asked questions about NumPy hstack

You can click on any of the above links to go to the appropriate section of the tutorial. But if you’re relatively new with NumPy, you should probably read everything.

Let’s get started.

A quick review of NumPy

If you’ve done data science in Python for a while, you might know a little bit about NumPy.

But if you’re a beginner, you might still be a little confused about what NumPy is.

To put it simply, NumPy is just a toolkit for working with numeric data in Python.

A little more specifically, NumPy provides tools for working with arrays of numbers.

You can visualize these arrays as something like this:

NumPy arrays can be 2-dimensional (like the one above), but also 1-dimensional (like a vector), or multi-dimensional.

NumPy provides tools for creating NumPy arrays

The NumPy package provides tools for creating these arrays. For example, there are tools for creating arrays of all zeros or creating arrays of all ones. There are also tools for transforming other Python objects into NumPy arrays. For example, the np.array() function can transform a list or tuple into a NumPy array.

NumPy provides tools for manipulating arrays

The NumPy package also provides tools for manipulating and organizing these arrays.

So there are tools to change the shape of a NumPy array or to summarize a NumPy array.

And there are tools for combining NumPy arrays together.

That’s exactly what NumPy hstack does. It’s one of several tools that helps you combine together other NumPy arrays.

Let’s take a closer look at numpy.hstack and how it works.

A quick introduction to NumPy hstack

As I just mentioned, the NumPy hstack is just a function for combining together other NumPy arrays.

Specifically, it combines together NumPy arrays in the “horizontal” direction. Another way of saying this is that it combines together NumPy arrays “column wise.”

This might not make sense, so let’s take a look at a visual example.

Let’s say that you have two NumPy arrays. One of the arrays is filled with 0’s and the other is filled with 1’s.

You want to combine them together horizontally.

To do this, you can use the NumPy hstack function:

There are other ways to combine together NumPy arrays, but np.hstack is simpler than the other options. It’s easier to use than np.concatenate (although np.concatenate is more flexible).

That’s essentially it ….

NumPy hstack is just a function for combining together NumPy arrays.

Having said that, let’s start to examine the specific details of how it works.

Let’s take a look at the syntax.

Numpy hstack syntax

The syntax is fairly simple.

If you’ve imported NumPy as np, then you can call the NumPy hstack function with the code np.hstack(). Then, inside of the parenthesis, you provide the NumPy arrays that you want to combine.

There are a few important details to consider though, so let’s talk about some of them.

Make sure to import NumPy properly

One thing that might confuse a beginner is the prefix np. This is sort of a nickname that we give to the NumPy module in our code. It’s a common convention.

Having said that, in order to make that nickname work properly, you need to import NumPy a certain way. You need to import NumPy with the code import numpy as np.

It’s also possible to import numpy with the code import numpy. If you do it that way, you actually would need to call the function with the code numpy.hstack().

The point that I’m trying to emphasize is that how exactly you call the function depends on how you’ve imported NumPy.

Going forward though, we’ll be referring to the function as np.hstack.

Ok … having explained that, let’s now talk about the inputs to the np.hstack function.

The parameters of np.hstack

There’s really only one input to the function, and that’s a tuple of input arrays.

For the sake of clarity, I’ll call this tuple-of-input-arrays.

tuple-of-input-arrays (required)

The only input to np.hstack is a group of arrays, organized into a Python tuple.

Having said that, there is a lot of flexibility in the types of inputs and how you specify the inputs.

Although the standard documentation for the function says that you should provide multiple NumPy arrays organized inside of a tuple, it will actually accept any group of array-like structure of numbers organized inside of a tuple or list.

So you can provide NumPy arrays organized inside of a tuple.

Or you can provide NumPy arrays organized inside of a list.

Or, you could even provide lists of numbers organized inside of a tuple or list.

My point here is that the np.hstack function is fairly flexible in terms of the inputs it will accept.

I’ll show you examples of this in the examples section.

Examples of how to use np.hstack

Speaking of examples, let’s look at some.

Examples:

• Use np.hstack on two lists of numbers
• Combine two 1-dimensional NumPy arrays
• Combine two 2-dimensional arrays

Run this code first

Before you run these examples, make sure you import NumPy properly.

Make sure you run the following code.

import numpy as np

This will import NumPy with the alias “np” which will enable us to refer to the function as np.hstack.

Ok, on to the first example.

Example 1: Use np.hstack on two lists of numbers

First, instead of operating on proper NumPy arrays, we’re actually going to combine two lists of numbers.

The reason for this is that by using lists in our syntax, it’s a little more obvious what’s going on.

This will also demonstrate that np.hstack operates on lists in addition to arrays.

Essentially, we’re going to give np.hstack two Python lists, organized inside of a Python tuple.

The first list is a list of two 0’s: [0,0].

The the second list is a list of two 1’s: [1,1].

And they are organized inside of a tuple: ([0,0],[1,1]).

Collectively, that tuple of lists is the input to np.hstack:

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

And here is the output:

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

As you can see, the output is a NumPy array.

So what happened here?

NumPy hstack just combined the inputs horizontally.

Note: you can also organize the inputs inside of a list

As I mentioned earlier, numpy.hstack is fairly flexible in terms of the inputs that it will allow.

Above, we took our two Python lists and organized them inside of a tuple: ([0,0],[1,1]).

But you can actually organize those two Python lists inside of a list instead: [[0,0],[1,1]].

If you did that, the code would look like this:

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

Which produces the following output:

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

This is the same output as the original syntax where we organized the lists inside of a tuple.

I’m showing you this to reinforce the idea that np.hstack is fairly flexible in terms of the types of inputs it will accept and the structure of those inputs.

Example 2: Combine two 1-dimensional NumPy arrays

Ok. Speaking of flexibility of inputs, let’s re-do the above example with proper NumPy arrays.

In the previous example, we were combining two 1D lists.

Now, we’re going to redo the same example with arrays.

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])

We can print them out so you can see the contents:

print(np_array_zeros_1d)
print(np_array_ones_1d)

OUT:

[0 0]

[1 1]

Essentially, np_array_zeros_1d is a 1-dimensional NumPy array of zeros and np_array_ones_1d is a 1-dimensional array of ones.

Combine arrays with np.hstack

Now, let’s combine those two NumPy arrays with np.hstack:

np.hstack((np_array_zeros_1d,np_array_ones_1d))

OUT:

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

This example is almost the same as the example in the previous section.

The output is identical.

The only difference is that here we used two NumPy arrays instead of two lists.

Essentially, np.hstack took the two 1-dimensional NumPy arrays and combined them together in the horizontal direction.

Example 3: Combine two 2-dimensional arrays

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

This is very similar to the other examples, so it helps if you’ve already reviewed the other two simpler examples.

Create two 2-dimensional numpy arrays

First, we’re just going to create two 2-dimensional numpy arrays.

We’re going to create an array of zeros with 2 rows and 2 columns:

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

And we’re going to create an array of ones with 2 rows and 3 columns:

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

And we can print them out quickly to see the contents:

print(np_array_zeros_2d)
print(np_array_ones_2d)

OUT:

[[0 0]
 [0 0]]

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

So we just have two 2-dimensional NumPy arrays.

Notice also that these arrays have the same number of rows. This is important when we use np.hstack on multi-dimensional arrays.

Combine arrays with np.hstack

Now, we’re going to combine the arrays with the np.hstack function.

This is extremely straight forward, and we’re going to do it almost exactly the same as how we did it in the previous examples.

We’re going to call the function, and provide the two NumPy arrays as inputs, inside of a tuple.

np.hstack((np_array_zeros_2d, np_array_ones_2d))

OUT:

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

Explanation

Again, this is really simple to understand if you’ve understood the previous examples.

The np.hstack just combined together the two arrays in the horizontal direction. It essentially combined the arrays together column-wise.

NumPy hstack FAQ

Let’s quickly cover some of the frequently asked questions about NumPy hstack.

Frequently asked questions:

• What’s the difference between np.hstack and np.vstack?
• What’s the difference between np.hstack and np.concatenate?
• Do the number of rows need to be the same?

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

If you’ve been paying attention to the earlier parts of this tutorial, you should already know that np.hstack combines arrays horizontally.

On the other hand, np.vstack combines arrays vertically.

They’re very similar in how they work … the major difference is that one combines horizontally and the other combines vertically.

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

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

Essentially, np.hstack is like a special case of np.concatenate.

Whereas np.hstack only combines horizontally, and np.vstack combines vertically, np.concatenate can combine arrays in any direction.

So again, np.hstack is like a special case of np.concatenate.

Another way of saying this is that np.concatenate is like a more general and more flexible version of np.vstack or np.hstack.

To give you an example though, take a look at the following:

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

np.hstack((np_array_zeros_2d, np_array_ones_2d))

Verses …

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

np.concatenate((np_array_zeros_2d, np_array_ones_2d), axis = 1)

In both cases, the output will be the same. The syntax for np.concatenate is a little more complicated, because you have to reference the appropriate array axis. But in either case, we’re combining NumPy arrays horizontally.

Do the number of rows need to be the same?

Yes.

Speaking generally, when you use np.hstack, the number of rows need to be the same for both arrays that you’re combining together.

If the number of rows is not the same, you’ll get an error.

Learn more NumPy

NumPy hstack is just one NumPy function among many functions.

To really master NumPy (and data science in Python), you’ll have to learn a lot more.

I recommend that you check out some of our other tutorials:

• How to use numpy random normal in Python
• An explanation of NumPy random seed
• How to use the NumPy min function
• How to use the NumPy append function

Those are just a few tutorials to help you get started.

For more free tutorials, sign up for our email list

If you want to get access to all of our free tutorials though, then sign up for our email list.

When you sign up, we’ll send you our free tutorials as soon as we publish them (about 2 to 4 times a month)

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 data science, then sign up now.