Python - numpy.dsplit() Function

In Python, numpy.dsplit() function is used to split an array into multiple sub-arrays along the third axis (depth). This function is part of the numpy module. This function especially used for dividing an array into smaller arrays along the depth axis, particularly in 3D arrays or higher-dimensional arrays where we want to split along the third axis (axis=2).

The numpy.dsplit() is similar to numpy.split() with axis=2 for 3D arrays. When used, it returns a list of sub-arrays, each containing a portion of the input array split along the depth.

To use the numpy.dsplit() function, we need to import the numpy module −

import numpy as np

Syntax

Following is the syntax of the numpy.dsplit() function −

numpy.dsplit(array, indices_or_sections)

Parameters

Following are the parameters of the numpy.dsplit() function −

• array - The array to be split. It should be at least 3-dimensional.
• indices_or_sections - If an integer, it specifies the number of equal-sized sub-arrays to divide into. If a list, it specifies the indices at which to split the array along depth.

Return Values

This function returns a list of sub-arrays, each being a segment of the original array split along its depth axis as per the specified indices or sections.

Example

Following is a basic example that demonstrates splitting a 3D array into two equal parts along the depth axis using numpy.dsplit() −

import numpy as np
my_array = np.array([[[1, 2, 3, 4], [5, 6, 7, 8]], [[9, 10, 11, 12], [13, 14, 15, 16]]])
split_array = np.dsplit(my_array, 2)
print("Array -\n", my_array)
print("Depth-Split Array -\n", split_array)

Output

The output of the above code is as follows:

Array -
 [[[ 1  2  3  4]
   [ 5  6  7  8]]
 
  [[ 9 10 11 12]
   [13 14 15 16]]]
Depth-Split Array -
 [array([[[ 1,  2],
        [ 5,  6]],

       [[ 9, 10],
        [13, 14]]]), array([[[ 3,  4],
        [ 7,  8]],

       [[11, 12],
        [15, 16]]])]

Example - Splitting Array at Specified Indices

When specific indices are provided in the numpy.dsplit() function, it will split the array at the exact depth indices specified. Each index marks the start of a new sub-array along the depth.

In the following example, we split an array at depth indices 1 and 3 using the numpy.dsplit() function −

import numpy as np
my_array = np.array([[[10, 20, 30, 40], [50, 60, 70, 80]], [[90, 100, 110, 120], [130, 140, 150, 160]]])
split_array = np.dsplit(my_array, [1, 3])
print("Array -\n", my_array)
print("Depth-Split Array -\n", split_array)

Output

The output of the above code is as follows:

Array -
 [[[ 10  20  30  40]
   [ 50  60  70  80]]

  [[ 90 100 110 120]
   [130 140 150 160]]]
Depth-Split Array -
 [array([[[ 10],
        [ 50]],

       [[ 90],
        [130]]]), array([[[ 20,  30],
        [ 60,  70]],

       [[100, 110],
        [140, 150]]]), array([[[ 40],
        [ 80]],

       [[120],
        [160]]])]

Example - Unequal Splits Resulting in Error

In the numpy.dsplit() function, if the number of sections specified does not divide the array evenly along the depth, it raises a ValueError. In the following example, we attempt to split an array into unequal sections −

import numpy as np
my_array = np.array([[[1, 2, 3], [4, 5, 6]], [[7, 8, 9], [10, 11, 12]]])
try:
    split_array = np.dsplit(my_array, 4)
except ValueError as e:
    print("ValueError:", e)

Output

The output of the above code is as follows:

ValueError: array split does not result in an equal division