NumPy nancumsum() – Cumulative Sum of Array with NaN

NumPy nancumsum()

The numpy.nancumsum() function computes the cumulative sum of an array while treating NaN (Not a Number) values as zero. This ensures that the cumulative sum remains unaffected by NaNs, and leading NaNs are replaced with zeros.

Syntax

numpy.nancumsum(a, axis=None, dtype=None, out=None)

Parameters

Parameter	Type	Description
a	array_like	Input array containing numerical values and NaNs.
axis	int, optional	Specifies the axis along which to compute the cumulative sum. If None, the array is flattened before computation.
dtype	dtype, optional	Defines the data type of the output array and the accumulator. Defaults to the input array’s dtype unless the input has an integer dtype with lower precision than the platform’s default integer.
out	ndarray, optional	Optional output array to store results. Must have the same shape as expected output.

Return Value

Returns an array of the same shape as the input, containing the cumulative sum where NaNs are treated as zeros.

---

Examples

1. Computing Cumulative Sum While Ignoring NaN

In this example, we compute the cumulative sum of an array that contains NaN values.

import numpy as np

# Define an array with NaN values
arr = np.array([1, np.nan, 3, np.nan, 5])

# Compute the cumulative sum treating NaNs as zero
result = np.nancumsum(arr)

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

Output:

Original array: [ 1. nan  3. nan  5.]
Cumulative sum (ignoring NaNs): [ 1.  1.  4.  4.  9.]

2. Computing Cumulative Sum Along a Specific Axis

We calculate the cumulative sum along a specified axis in a 2D array containing NaNs.

import numpy as np

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

# Compute cumulative sum along axis 0 (column-wise)
result_axis0 = np.nancumsum(arr, axis=0)

# Compute cumulative sum along axis 1 (row-wise)
result_axis1 = np.nancumsum(arr, axis=1)

# Print the results
print("Original array:\n", arr)
print("\nCumulative sum along axis 0:\n", result_axis0)
print("\nCumulative sum along axis 1:\n", result_axis1)

Output:

Original array:
 [[ 1. nan  3.]
  [ 4.  5. nan]]

Cumulative sum along axis 0:
 [[ 1.  0.  3.]
  [ 5.  5.  3.]]

Cumulative sum along axis 1:
 [[ 1.  1.  4.]
  [ 4.  9.  9.]]

3. Using the dtype Parameter

Setting the output data type explicitly while computing the cumulative sum.

import numpy as np

# Define an integer array with NaNs
arr = np.array([1, np.nan, 3, np.nan, 5], dtype=float)

# Compute cumulative sum with dtype=float32
result = np.nancumsum(arr, dtype=np.float32)

# Print the results
print("Cumulative sum with dtype float32:", result)

Output:

Cumulative sum with dtype float32: [ 1.  1.  4.  4.  9.]

4. Using the out Parameter

Storing the result in an existing output array instead of creating a new one.

import numpy as np

# Define an array with NaN values
arr = np.array([2, np.nan, 4, np.nan, 6])

# Create an output array of the same shape
out_array = np.empty_like(arr)

# Compute cumulative sum and store result in out_array
np.nancumsum(arr, out=out_array)

# Print the results
print("Cumulative sum stored in output array:", out_array)

Output:

Cumulative sum stored in output array: [ 2.  2.  6.  6. 12.]