The NumPy cumsum function is used to calculate the cumulative sum of elements in a NumPy array across a specified axis. In this tutorial, you’ll learn how to use the NumPy cumsum function to calculate cumulative sums of arrays. The function allows you to specify the axis on which to calculate sums as well as the data type of the resulting array.
By the end of this tutorial, you’ll have learned:
- How to understand the NumPy
cumsum()function - How to calculate cumulative sums of 1-dimensional and 2-dimensional NumPy arrays
- How to specify the axis along which to calculate cumulative sums
- How to specify the data type of cumulative sums in NumPy
Table of Contents
Understanding the NumPy cumsum Function
Before diving into how to use the NumPy cumsum() function, let’s take a look at what makes up the function. We’ll take a quick look at the different parameters of the function and their default arguments (if any). This gives you a good sense of what to expect in terms of being able to customize the cumulative sums that you calculate with NumPy.
# Understanding the NumPy cumsum() Function
np.cumsum(a, axis=None, dtype=None, out=None)The table below breaks down the parameters and the default arguments of the NumPy cumsum() function:
| Parameter | Description | Default Argument | Accepted Values |
|---|---|---|---|
a= | The input array | N/A | array like |
axis= | The axis along which to calculate the cumulative sum. By default, NumPy will flatten the array. | None | int |
dtype= | The type of the returned array. | None | dtype |
out= | Alternative output array, in which to place the result. | None | ndarray |
Now that you have a strong understanding of the function, let’s take a look at how you can calculate cumulative sums of 1-dimensional NumPy arrays.
Calculate Cumulative Sums of 1-Dimensional NumPy Arrays
To calculate a cumulative sum of a one-dimensional array, you can simply pass the array into the np.cumsum() function. This will return an array of the same length, containing the cumulative sum values. Let’s see what this looks like:
# Calculative Cumulative Sums of 1-D NumPy Arrays
import numpy as np
arr = np.arange(5)
cumsum = np.cumsum(arr)
print(cumsum)
# Returns: [ 0 1 3 6 10]Let’s break down what we did in the code above:
- We used the
np.arange()function to return an array containing values from 0 through 4 - We passed this array into the
np.cumsum()function to calculate cumulative sums
In the following section, you’ll learn how to calculate cumulative sums for Python lists.
Using NumPy cumsum To Calculate Cumulative Sums of Python Lists
The NumPy cumsum function expects only an array-like object to be passed into it. This means that we can also calculate cumulative sums of Python list values. Let’s see what this looks like:
# Calculative Cumulative Sums of Python Lists
import numpy as np
values = [0, 1, 2, 3, 4]
cumsum = np.cumsum(values)
print(cumsum)
# Returns: [ 0 1 3 6 10]In the code above we generate a list of values from 0 through 4. We then pass this list into the np.cumsum() function. This returns a NumPy array of the cumulative values. To return a list of values, you can simply pass this array into the list() constructor.
Calculate Cumulative Sums of 2-Dimensional NumPy Arrays
The np.cumsum() function also allows you to pass in two-dimensional arrays. Let’s see what happens when we pass in a 2-D NumPy array:
# Calculative Cumulative Sums of 2-D Arrays
import numpy as np
arr = np.array([
[0, 1, 2],
[3, 4, 5]
])
cumsum = np.cumsum(arr)
print(cumsum)
# Returns: [ 0 1 3 6 10 15]This result may surprise you: by default, the NumPy cumsum function will flatten a two-dimensional array unless an axis is specified. Because of this, the function first flattens the two-dimensional array and then returns the cumulative sum. Let’s see what this looks like when we specify an axis.
Modifying the Axis in NumPy cumsum
NumPy provides both the first and second axes. The first axis represents the “columns” of an array, while the second axis represents the “rows” of an array.
By calculating the cumulative sums across the 0th axis, you return an array of the same size and shape. In this array, the sums are calculated going “down” the columns, as shown below:
# Calculative Cumulative Sums Across Axis 0
import numpy as np
arr = np.array([
[0, 1, 2],
[3, 4, 5]
])
cumsum = np.cumsum(arr, axis=0)
print(cumsum)
# Returns:
# [[0 1 2]
# [3 5 7]]Similarly, we can calculate the cumulative sums across the 1st axis. This returns the cumulative sums across the “rows” of an array. Let’s see what this looks like:
# Calculative Cumulative Sums Across Axis 1
import numpy as np
arr = np.array([
[0, 1, 2],
[3, 4, 5]
])
cumsum = np.cumsum(arr, axis=1)
print(cumsum)
# Returns:
# [[ 0 1 3]
# [ 3 7 12]]We can see that this works in a very similar way. The function returns an array of the same shape and size, in this case, 2 by 3. The values are calculated across the rows.
In the following section, you’ll learn how to modify the data type of the resulting array.
Modifying the Data Type When Calculating NumPy Cumulative Sums
By default, NumPy will return an array matching the lowest common data type found in the array. We can modify the data type of the array by passing a data type in the dtype= parameter. In the array we’ve been using, all values are integers. Let’s specify that we want the resulting data type to be floats:
# Modify the Data Type When Calculating Cumulative Sums
import numpy as np
arr = np.arange(5)
cumsum = np.cumsum(arr, dtype='float')
print(cumsum)
# Returns: [ 0. 1. 3. 6. 10.]We can see that this returns the same cumulative sums as before, though each value is a floating point value, rather than an integer.
Conclusion
In this tutorial, you learned how to calculate cumulative sums with the NumPy cumsum() function. You first learned how the function works by exploring its parameters and default arguments. You then learned how to calculate cumulative sums of one-dimensional arrays and of Python lists. Then, you learned how to calculate cumulative sums of two-dimensional arrays, including by changing axes. Finally, you learned how to modify the data types of the resulting arrays.
Additional Resources
To learn more about related topics, check out the tutorials below: