NumPy is a famous Python library used for working with arrays. One of the important functions of this library is stack().

Important points:

• stack() is used for joining multiple NumPy arrays. Unlike, concatenate(), it joins arrays along a new axis. It returns a NumPy array.
• to join 2 arrays, they must have the same shape and dimensions. (e.g. both (2,3)--> 2 rows,3 columns)
• stack() creates a new array which has 1 more dimension than the input arrays. If we stack 2 1-D arrays, the resultant array will have 2 dimensions.

Syntax:  numpy.stack(arrays, axis=0, out=None)

Parameters:

• arrays: Sequence of input arrays (required)
• axis: Along this axis, in the new array, input arrays are stacked. Possible values are 0 to (n-1) positive integer for n-dimensional output array. For example, in the case of a resultant 2-D array, there are 2 possible axis options :0 and 1. axis=0 means 1D input arrays will be stacked row-wise. axis=1 means 1D input arrays will be stacked column-wise. We shall see the example later in detail. -1 means last dimension. e.g. for 2D arrays axis 1 and -1 are same. (optional)
• out: The destination to place the resultant array.

Example #1 : stacking two 1d arrays

import numpy as np

# input array
a = np.array([1, 2, 3])
b = np.array([4, 5, 6])

# Stacking 2 1-d arrays
c = np.stack((a, b),axis=0)
print(c)

output - 

array([[1, 2, 3],
      [4, 5, 6]])

  Notice, output is a 2-D array. They are stacked row-wise. Now, let's change the axis to 1.

# stack 2 1-d arrays column-wise
np.stack((a,b),axis=1)

output - 

array([[1, 4],
      [2, 5],
      [3, 6]])

Here, stack() takes 2 1-D arrays and stacks them one after another as if it fills elements in new array column-wise.

#stacking 2 arrays along -1 axis
np.stack((a,b),axis=-1)

 output -

array([[1, 4],
      [2, 5],
      [3, 6]])

-1 represents 'last dimension-wise'. Here 2 axis are possible. 0 and 1. So, -1 is same as 1.

Example #2 : stacking two 2d arrays

# input arrays
x=np.array([[1,2,3],
            [4,5,6]])

y=np.array([[7,8,9],
            [10,11,12]])

1. stacking with axis=0

np.stack((x,y),axis=0)

output - 

array([[[ 1,  2,  3],
       [ 4,  5,  6]],

      [[ 7,  8,  9],
       [10, 11, 12]]])

Imagine as if they are stacked one after another and made a 3-D array.

2. stacking with axis=1

np.stack((x,y),axis=1)

Output - 3D array. 1st dimension has 1st rows. 2nd dimension has 2nd rows. [Row-wise stacking]

array([[[ 1,  2,  3],
       [ 7,  8,  9]],

      [[ 4,  5,  6],
       [10, 11, 12]]])

3. stacking with axis =2

np.stack((x,y),axis=2)

Output - 3D array. 1st dimension has 1st rows. 2nd dimension has 2nd rows. [Column-wise stacking]

array([[[ 1,  7],
       [ 2,  8],
       [ 3,  9]],

      [[ 4, 10],
       [ 5, 11],
       [ 6, 12]]])

Example #2 : stacking more than two 2d arrays

1. with axis=0 : Just stacking. 

x=np.array([[1,2,3],
            [4,5,6]])
y=np.array([[7,8,9],
            [10,11,12]])
z=np.array([[13,14,15],
            [16,17,18]])

np.stack((x,y,z),axis=0)

 output - 

array([[[ 1,  2,  3],
       [ 4,  5,  6]],

      [[ 7,  8,  9],
       [10, 11, 12]],

      [[13, 14, 15],
       [16, 17, 18]]])

2. with axis =1 (row-wise stacking)

np.stack((x,y,z),axis=1)

output - 

array([[[ 1,  2,  3],
       [ 7,  8,  9],
       [13, 14, 15]],

      [[ 4,  5,  6],
       [10, 11, 12],
       [16, 17, 18]]])

3. with axis =2 (column-wise stacking)

np.stack((x,y,z),axis=2)

output-

array([[[ 1,  7, 13],
       [ 2,  8, 14],
       [ 3,  9, 15]],

      [[ 4, 10, 16],
       [ 5, 11, 17],
       [ 6, 12, 18]]])

Example #3 : stacking two 3d arrays

1. axis=0. Just stacking

#2 input 3d arrays

m=np.array([[[1,2,3],
            [4,5,6],
            [7,8,9]],

            [[10,11,12],
            [13,14,15],
            [16,17,18]]])

n=np.array([[[51,52,53],
            [54,55,56],
            [57,58,59]],

            [[110,111,112],
            [113,114,115],
            [116,117,118]]])

# stacking
np.stack((m,n),axis=0)

 output - 

array([[[[  1,   2,   3],
        [  4,   5,   6],
        [  7,   8,   9]],

       [[ 10,  11,  12],
        [ 13,  14,  15],
        [ 16,  17,  18]]],

      [[[ 51,  52,  53],
        [ 54,  55,  56],
        [ 57,  58,  59]],

       [[110, 111, 112],
        [113, 114, 115],
        [116, 117, 118]]]])

2. with axis=1 

np.stack((m,n),axis=1)

output - Imagine as if the resultant array takes 1st plane of each array for 1st dimension and so on.

array([[[[  1,   2,   3],
        [  4,   5,   6],
        [  7,   8,   9]],

       [[ 51,  52,  53],
        [ 54,  55,  56],
        [ 57,  58,  59]]],

      [[[ 10,  11,  12],
        [ 13,  14,  15],
        [ 16,  17,  18]],

       [[110, 111, 112],
        [113, 114, 115],
        [116, 117, 118]]]])

3. with axis = 2 

np.stack((m,n),axis=2)

output - 

array([[[[  1,   2,   3],
        [ 51,  52,  53]],

       [[  4,   5,   6],
        [ 54,  55,  56]],

       [[  7,   8,   9],
        [ 57,  58,  59]]],

      [[[ 10,  11,  12],
        [110, 111, 112]],

       [[ 13,  14,  15],
        [113, 114, 115]],

       [[ 16,  17,  18],
        [116, 117, 118]]]])

4. with axis = 3

np.stack((m,n),axis=3)

output - 

array([[[[  1,  51],
        [  2,  52],
        [  3,  53]],

       [[  4,  54],
        [  5,  55],
        [  6,  56]],

       [[  7,  57],
        [  8,  58],
        [  9,  59]]],

      [[[ 10, 110],
        [ 11, 111],
        [ 12, 112]],

       [[ 13, 113],
        [ 14, 114],
        [ 15, 115]],

       [[ 16, 116],
        [ 17, 117],
        [ 18, 118]]]])