How To Use The NumPy dstack Function

Posted on by Robert Charles

In NumPy dstack is one of the functions made for stacking and concatenation operations. What makes it special? Read on to find out.

Table of Contents

NumPy dstack Function

The numpy.dstack() function is used to “stack” arrays along the third dimension (the “depth” dimension), which can be useful for certain types of operations.

There are no optional arguments. The only object you need to pass to this function is a tuple of arrays.

Except for the third dimension, they must have the same shape along all axes. This means if you stack 1D or 2D arrays, they must have the same shape.

In the case of 2D arrays, numpy.dstack() treats them as if they are 3D arrays with only one element in the third dimension. Likewise, 1D arrays will be reshaped into 3D arrays, with the first and third dimensions having only one element.

Here is an example of how it might be used. First, we create two 1D NumPy arrays (ndarrays), all of which have the (1, 3) shape. Then we stack them with the nump.dstack() function.

import numpy as np
a = np.array([1, 2, 3])
b = np.array([4, 5, 6])
c = np.dstack([a, b])
c.shape # (1, 3, 2)

print(c)

Output

[[[1 4]
  [2 5]
  [3 6]]]

As you can see, the original arrays a and b have been stacked along the third dimension to create a new three-dimensional array c.

The resulting array has a shape of (1, 3, 2), which indicates that it has three rows, two columns, and one depth element.

Remember that you must NumPy first before invoking dstack() as this isn’t a built-in Python function.

The following example will demonstrate how this function works with 2D arrays.

import numpy as np
a = np.array([[1, 2, 3], [4, 5, 6]])
b = np.array([[7, 8, 9], [10, 11, 12]])
c = np.array([[13, 14, 15], [16, 17, 18]])
d = np.array([[19, 20, 21], [22, 23, 24]])
e = np.dstack([a, b, c, d])

e.shape # (2, 3, 4)
print(e)

Output

[[[ 1 7 13 19]
  [ 2 8 14 20]
  [ 3 9 15 21]]
 [[ 4 10 16 22]
  [ 5 11 17 23]
  [ 6 12 18 24]]]

Here we have 4 2D arrays of the same shape (2, 3). When stacking them with the dstack() function, we get a 3D array with the shape of (2, 3, 4). There are 4 elements in the first dimension, corresponding to the fact that we stack 4 arrays.

To ensure that shape, dstack() works by transforming rows in original arrays into columns in the returned array.

Each depth element will have elements of a row from every input array. And the number of columns in original arrays will become the number of rows in each depth element of the returned array instead.

While numpy.dstack() is most commonly used with 1D and 3D arrays, you can stack higher-dimensional arrays with it too.

For example, here are two 3D arrays with the shape of (3, 2, 2):

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

b = np.array([[[10, 20], [30, 40]], [[50, 60], [70, 80]], [[90, 100], [110, 120]]])                                                                                                                                    

When we stack them with nump.dstack(), the function will return a (3, 2, 4) array:

>>> c = np.dstack([a, b])
>>> c.shape
(3, 2, 4)
>>> print(c)
[[[ 1 2 10 20]
  [ 3 4 30 40]]
 [[ 5 6 50 60]
  [ 7 8 70 80]]
 [[ 9 10 90 100]
  [ 11 12 110 120]]]

Summary

The NumPy dstack function can help you with stacking arrays depth-wide. This is an axis-specific function. For more general stacking operations, check out the numpy.stack() function.

Related Posts

Leave a Reply

Your email address will not be published. Required fields are marked *