NumPy cumulative_sum()

The numpy.cumulative_sum() function computes the cumulative sum of array elements along a specified axis. It is an alternative to numpy.cumsum() and provides an option to include an initial value.

Syntax

</>

Copy

numpy.cumulative_sum(x, /, *, axis=None, dtype=None, out=None, include_initial=False)

Parameters

Parameter	Type	Description
`x`	array_like	Input array whose cumulative sum is computed.
`axis`	int, optional	Axis along which the cumulative sum is performed. For multi-dimensional arrays, this parameter is required.
`dtype`	dtype, optional	Defines the data type of the returned array. If not specified, it defaults to the input’s dtype.
`out`	ndarray, optional	Alternative output array to store the result. It must have the same shape as expected output.
`include_initial`	bool, optional	If `True`, includes an initial value (zero) as the first element in the output array.

Return Value

Returns a NumPy array containing the cumulative sum of the input elements along the specified axis. If include_initial=True, the shape of the output array is different from the input array.

Examples

1. Computing the Cumulative Sum of a 1D Array

This example computes the cumulative sum of a one-dimensional array.

</>

Copy

import numpy as np

# Define a 1D array
arr = np.array([1, 2, 3, 4, 5])

# Compute the cumulative sum
result = np.cumulative_sum(arr)

# Print the result
print("Original array:", arr)
print("Cumulative sum:", result)

Output:

Original array: [1 2 3 4 5]
Cumulative sum: [ 1  3  6 10 15]

2. Using the `axis` Parameter for a 2D Array

We compute the cumulative sum along different axes of a 2D array.

</>

Copy

import numpy as np

# Define a 2D array
arr = np.array([[1, 2, 3],
                [4, 5, 6]])

# Compute cumulative sum along rows (axis=1)
result_row = np.cumulative_sum(arr, axis=1)

# Compute cumulative sum along columns (axis=0)
result_col = np.cumulative_sum(arr, axis=0)

# Print results
print("Original array:\n", arr)
print("\nCumulative sum along rows:\n", result_row)
print("\nCumulative sum along columns:\n", result_col)

Output:

Original array:
 [[1 2 3]
 [4 5 6]]

Cumulative sum along rows:
 [[ 1  3  6]
 [ 4  9 15]]

Cumulative sum along columns:
 [[ 1  2  3]
 [ 5  7  9]]

3. Using the `include_initial` Parameter

Using include_initial=True adds an extra zero as the first element in the cumulative sum.

</>

Copy

import numpy as np

# Define an array
arr = np.array([3, 6, 9])

# Compute cumulative sum with an initial zero
result = np.cumulative_sum(arr, include_initial=True)

# Print results
print("Original array:", arr)
print("Cumulative sum with initial zero:", result)

Output:

Original array: [3 6 9]
Cumulative sum with initial zero: [ 0  3  9 18]

4. Using the `out` Parameter

Storing the cumulative sum results in an existing output array.

</>

Copy

import numpy as np

# Define an input array
arr = np.array([2, 4, 6, 8])

# Create an output array with the same shape
output_array = np.empty_like(arr)

# Compute cumulative sum and store it in output_array
np.cumulative_sum(arr, out=output_array)

# Print results
print("Original array:", arr)
print("Cumulative sum stored in output array:", output_array)

Output:

Original array: [2 4 6 8]
Cumulative sum stored in output array: [ 2  6 12 20]

TutorialKart

NumPy cumulative_sum() – Cumulative Sum of Array Elements