How to Use NumPy vstack() in Python

The NumPy vstack() function in Python is used to vertically(row-wise) stack arrays. It takes a sequence of arrays as input and stacks them vertically to create a new array. The arrays must have the same number of columns. It takes all elements from the given arrays and forms a single array, where the elements are added vertically. This process is similar to the concatenation of arrays along the default axis=0 after concatenating 1-D arrays of shape (N,) turn into reshaping(1, N).

It has only one parameter i.e. tuple of arrays. You can use vstack() very effectively up to three-dimensional arrays. In this article, I will explain numpy.vstack() function and use its syntax, parameters, and how you can create a single array by taking elements of one or more arrays.

1. Quick Examples of NumPy vstack() Function

If you are in a hurry, below are some quick examples of how to use vstack() function.


# Quick examples of numpy vstack() function

# Example 1 : Using vstack() 
# Get the stacked array
arr = np.array([1, 2, 3])
arr1 = np.array([4, 5, 6])
arr2 = np.vstack((arr, arr1))

# Example 2 : Get the stacked array 
arr = np.array([[1], [2], [3]])
arr1 = np.array([[4], [5], [6]])
arr2 = np.array([[7], [8], [9]])
arr3 = np.vstack((arr, arr1, arr2))

# Example 3 : Get the stacked array 
arr = np.array([[1], [2], [3]])
arr1 = np.array([[4], [5], [6]])
arr2 = np.array([[7], [8], [9]])
arr3 = np.vstack((arr, arr1, arr2))

# Example 4 : Get the 3-D stacked array
arr = np.array([[[1, 3], [2, 4]], [[3, 5], [5, 7]]])
arr1 = np.array([[[4, 1], [5, 7]], [[6, 8],[3, 5]]])
arr2 = np.vstack((arr, arr1))

2. Syntax of NumPy vstack()

Following is the syntax of the vstack() function.


# Syntax of vstack() 
numpy.vstack(tup)

2.1 Parameters of the vstack()

Following is the parameter of the NumPy vstack().

tup : tuple of ndarrays - The arrays to be stacked vertically. The arrays must have the same number of columns (i.e., the size of the second axis).

2.2 Return Value of the vstack()

Stacked ndarray: The vertically stacked array formed by concatenating the input arrays.

3. Usage of the NumPy vstack()

The vstack() function in NumPy is used specifically to vertically stack, or concatenate, a sequence of NumPy arrays along the vertical axis (axis=0). This results in a single array where the data from the input arrays is stacked vertically. Python NumPy module provides different types of functions which are concatenate(), stack(), vstack(), and hstack().

Below I have provided an image explaining how vstack works, it will give you better understanding.

Let's create 1-D arrays using numpy.array() and apply this function, it will return the stacked array., where the elements are stacked row-wise.

You can create two 1D NumPy arrays, arr and arr1, and then uses the numpy.vstack() function to vertically stack them into a 2D array, arr2.


# Import numpy
import numpy as np

# Create input array
arr = np.array([1, 2, 3])
print("First array:\n",arr) 
arr1 = np.array([4, 5, 6])
print("Second array:\n",arr1) 

# Using vstack() function
# Get the stacked array
arr2 = np.vstack((arr, arr1))
print("Stacked array:\n",arr2)

Yields below output.

As you can see, the np.vstack() function has combined the two 1D arrays arr and arr1 into a 2D array, arr2, by stacking them vertically. Each original array becomes a row in the resulting 2D array.

4. Get the 2-D Stacked NumPy Array

You are creating two 2D NumPy arrays, arr and arr1, and then using the np.vstack() function to vertically stack them into a new 2D array, arr2.


# Create 2D array
arr = np.array([[1, 2], [3, 4]])
arr1 = np.array([[4, 5], [6, 7]]) 

# Get the stacked array
arr2 = np.vstack((arr, arr1))
print("Stacked 2D array:\n",arr2) 

# Output:
# Stacked 2D array:
#  [[1 2]
#  [3 4]
#  [4 5]
#  [6 7]]

This time you will pass three 2-D NumPy arrays into this function, it will return the 2-D single array where the elements are stacked vertically.

To create three 2D NumPy arrays, arr, arr1, and arr2, each containing single-column vectors. Then, you're using the np.vstack() function to vertically stack them into a new 2D array, arr3.


# Create input array
arr = np.array([[1], [2], [3]])
arr1 = np.array([[4], [5], [6]])
arr2 = np.array([[7], [8], [9]])

# Get the stacked array
arr3 = np.vstack((arr, arr1, arr2))
print("Stacked 2D single array:\n",arr3)

# Output:
# Stacked 2D single array:
# [[1]
# [2]
# [3]
# [4]
# [5]
# [6]
# [7]
# [8]
# [9]]

5. Get the 3-D Stacked NumPy Array

You can pass 3-D NumPy arrays as a parameter into this function, it will return a single array. Let's take two 3-D arrays of shapes (2, 2, 2) and apply this function, it will return a single 3-D array of shapes (4, 2, 2). For example,


# Create 3D arrays
arr = np.array([[[1, 3], [2, 4]], [[3, 5], [5, 7]]])
arr1 = np.array([[[4, 1], [5, 7]], [[6, 8],[3, 5]]])

# Get the 3-D stacked array
arr2 = np.vstack((arr, arr1))
print("Stacked 3D array:\n",arr2)

Yields below output


# Output:
Stacked 3D array:
 [[[1 3]
  [2 4]]

 [[3 5]
  [5 7]]

 [[4 1]
  [5 7]]

 [[6 8]
  [3 5]]]

Frequently Asked Questions

The numpy.vstack() function in NumPy is used to vertically stack or concatenate arrays along the vertical axis (axis=0). It takes a sequence of arrays and stacks them vertically, forming a new array.

The numpy.vstack() function is flexible and allows you to stack more than two arrays. You can pass any number of arrays as a tuple to numpy.vstack().

you can use numpy.vstack() with 1D arrays as well. When you use it with 1D arrays, they will be treated as if they are 2D arrays with a single column. The resulting stacked array will be a 2D array.

You can vertically stack arrays with different data types using numpy.vstack(). When you vertically stack arrays with different data types, NumPy will attempt to promote them to a common data type that can accommodate all the data without loss of information.

An alternative to numpy.vstack() is numpy.concatenate() when you want to vertically stack arrays along the 0-axis (rows).

To vertically stack three 2D NumPy arrays, you can use the numpy.vstack() function.

Conclusion

In this article, I have explained numpy.vstack() and using this how you can stack the sequence of given arrays into a single array with examples.

References

https://numpy.org/doc/stable/reference/generated/numpy.stack.html