NumPy stack()

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

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

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

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