NumPy stack()

The NumPy stack() method joins a sequence of arrays along a new axis.

Example

import numpy as np

# create 2-D arrays
array1 = np.array([[0, 1], [2, 3]])
array2 = np.array([[4, 5], [6, 7]])

# join the arrays stackedArray= np.stack((array1, array2))
print(stackedArray) ''' Output: [[[0 1] [2 3]] [[4 5] [6 7]]] '''

Here, the stack() method combines two 2-D arrays along a new axis, resulting in a 3D array.


stack() Syntax

The syntax of stack() is:

numpy.stack((array1, array2, …), axis = 0, out)

stack() Arguments

The stack() method takes the following arguments:

  • (array1, array2, …) - the sequence of arrays to be joined
  • axis (optional) - defines the dimension in which the arrays are joined
  • out (optional) - destination to store the result.
  • dtype (optional) - datatype of the resultant array

Notes:

  • Only one of out and dtype arguments can be passed.
  • The shape of all arrays in the input tuple should be the same.

stack() Return Value

The stack() method returns the joined array.


Example 1: Stack Three Arrays

import numpy as np

array1 = np.array( [[1, 2], [3, 4]] )
array2 = np.array( [[5, 6], [7, 8]] )
array3 = np.array( [[9, 10], [11, 12]] )

# stack 3 arrays stackedArray = np.stack((array1, array2, array3))
print(stackedArray)

Output

[[[ 1  2]
  [ 3  4]]

 [[ 5  6]
  [ 7  8]]

 [[ 9 10]
  [11 12]]]

Here, the stack() method joined three 2-D arrays and returned a 3-D array.

Notice we haven't passed the axis argument. So the axis is 0 by default and the arrays are stacked row-wise (vertically).

Note:

  • stack(): Adds a new dimension and combines arrays into a higher-dimensional array.
  • concatenate(): Joins arrays along an existing axis without introducing a new dimension

Example 2: Stack Two Arrays in Different Dimensions

import numpy as np

array1 = np.array([0, 1])
array2 = np.array([2, 3])

print('Joining the array when axis = 0')

# join the arrays at axis 0 stackedArray = np.stack((array1, array2), 0)
print(stackedArray) print('Joining the array when axis = 1')
# join the arrays at axis 1 stackedArray = np.stack((array1, array2), 1)
print(stackedArray)

Output

Joining the array when axis = 0
[[0 1]
 [2 3]]
Joining the array when axis = 1
[[0 2]
 [1 3]]

Here, when the axis is 0, the arrays are stacked row-wise, and when axis is 1, the arrays are stacked column-wise.


Example 3: Return an Existing Array as Stacked Array

In our previous examples, the stack() function generated a new array as output.

However, we can use an existing array to store the output using the out argument.

import numpy as np

array1 = np.array([[0, 1], [2, 3]])
array2 = np.array([[10, 11], [12, 13]])

# create an array of shape (2, 2, 2)
# and initialize all elements to 0
array3 = np.zeros((2, 2, 2)) 

# join the arrays and store the result in array3 np.stack((array1, array2), out = array3)
print(array3)

Output

[[[ 0.  1.]
  [ 2.  3.]]

 [[10. 11.]
  [12. 13.]]]

Note: The shape of the output array must match the shape of the stacked array, otherwise we will get an error.


Example 4: Specify the Datatype of a Stacked Array

We can change the data type of the stacked array by passing the dtype argument.

import numpy as np

array1 = np.array([[0, 1], [2, 3]])
array2 = np.array([[10, 11], [12, 13]])

# change elements of the stacked array to string stackedArray = np.stack((array1, array2), dtype = str)
print(stackedArray)

Output

[[['0' '1']
  ['2' '3']]

 [['10' '11']
  ['12' '13']]]