cumsum - Cumulative sum - MATLAB (original) (raw)

Syntax

Description

`B` = cumsum([A](#btrgrnv-1-A)) returns the cumulative sum of A starting at the beginning of the first array dimension in A whose size does not equal 1.

• If A is a vector, then B is a vector of the same size containing the cumulative sum ofA.
• If A is a matrix, then B is a matrix of the same size containing the cumulative sum in each column ofA.
• If A is a multidimensional array, thenB is an array of the same size containing the cumulative sum along the first array dimension of A whose size does not equal 1.
• If A is a table or timetable, then M is a table or timetable of the same size containing the cumulative sum in each variable ofA. (since R2023a)

The class of B is the same as the class of A except if A is logical, in which caseB is double.

example

`B` = cumsum([A](#btrgrnv-1-A),[dim](#btrgrnv-1-dim)) returns the cumulative sum of the elements along dimension dim. For example, if A is a matrix, thencumsum(A,2) returns the cumulative sum along the rows ofA.

example

`B` = cumsum(___,[direction](#mw%5F72d66b65-243c-4524-96b1-9fa36114c21c)) specifies the direction for any of the previous syntaxes. For example,cumsum(A,2,"reverse") returns the cumulative sum within the rows of A by working from end to beginning of the second dimension.

example

`B` = cumsum(___,[nanflag](#mw%5F4b90c89c-a098-41cb-a8ca-aa79ac840c9c)) specifies whether to include or omit NaN values inA. For example, cumsum(A,"omitnan") ignores NaN values when computing each sum. By default,cumsum includes NaN values.

example

Examples

collapse all

Find the cumulative sum of the integers from 1 to 5. The element B(2) is the sum of A(1) and A(2), while B(5) is the sum of elements A(1) through A(5).

Create a 3-by-3 matrix whose elements correspond to their linear indices.

A = [1 4 7; 2 5 8; 3 6 9]

A = 3×3

 1     4     7
 2     5     8
 3     6     9

Find the cumulative sum of the columns of A. The element B(5) is the sum of A(4) and A(5), while B(9) is the sum of A(7), A(8), and A(9).

B = 3×3

 1     4     7
 3     9    15
 6    15    24

Define a 2-by-3 matrix whose elements correspond to their linear indices.

Find the cumulative sum of the rows of A. The element B(3) is the sum of A(1) and A(3), while B(5) is the sum of A(1), A(3), and A(5).

Create an array of logical values.

A = [true false true; true true false]

A = 2×3 logical array

1 0 1 1 1 0

Find the cumulative sum of the rows of A.

The output has type double.

Create a 3-by-3 matrix of random integers between 1 and 10.

rng default; A = randi([1,10],3)

A = 3×3

 9    10     3
10     7     6
 2     1    10

Calculate the cumulative sum along the rows. Specify the "reverse" option to work from right to left in each row. The result is the same size as A.

B = cumsum(A,2,"reverse")

B = 3×3

22    13     3
23    13     6
13    11    10

Create a matrix containing NaN values.

A = [3 5 NaN 4; 2 6 NaN 9; 1 3 5 NaN]

A = 3×4

 3     5   NaN     4
 2     6   NaN     9
 1     3     5   NaN

Compute the cumulative sums of the matrix, excluding NaN values. For matrix columns that contain leading NaN values, the cumulative sum is 0 until a non-NaN value is encountered.

B = 3×4

 3     5     0     4
 5    11     0    13
 6    14     5    13

Input Arguments

collapse all

Input array, specified as a vector, matrix, multidimensional array, table, or timetable.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | duration | table | timetable
Complex Number Support: Yes

Dimension to operate along, specified as a positive integer scalar. If you do not specify the dimension, then the default is the first array dimension whose size does not equal 1.

Consider a two-dimensional input array, A:

• cumsum(A,1) works on successive elements in the columns of A and returns the cumulative sums of each column.
• cumsum(A,2) works on successive elements in the rows of A and returns the cumulative sums of each row.

cumsum returns A if dim is greater than ndims(A).

Direction of cumulation, specified as one of these values:

• "forward" — Work from1 to end of the operating dimension.
• "reverse" — Work fromend to 1 of the operating dimension.

Missing value condition, specified as one of these values:

• "includemissing" or"includenan" — IncludeNaN values in A when computing the cumulative sums. Elements in B areNaN as soon as the firstNaN value in A is encountered. "includemissing" and"includenan" have the same behavior.
• "omitmissing" or "omitnan" — Ignore NaN values inA when computing the cumulative sums. IfA has consecutive leadingNaN values, then the corresponding elements in B are 0. "omitmissing" and"omitnan" have the same behavior.

Tips

• The "reverse" option in many cumulative functions allows quick directional calculations without requiring a flip or reflection of the input array.

Extended Capabilities

expand all

This function supports tall arrays with the limitations:

The "reverse" direction is not supported.

For more information, see Tall Arrays.

Usage notes and limitations:

• Logical inputs are not supported. Cast input todouble first.
• Code generation does not support sparse matrix inputs for this function.

Usage notes and limitations:

• Logical inputs are not supported. Cast input todouble first.
• Code generation does not support sparse matrix inputs for this function.

The cumsum function supports GPU array input with these usage notes and limitations:

• The order of the additions within the cumsum operation is not defined. Therefore, the cumsum operation on a gpuArray might not return exactly the same answer as the cumsum operation on the corresponding numeric array. The differences might be significant whenA is a signed integer type.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Usage notes and limitations:

• The order of the additions within the cumsum operation is not defined. Therefore, the cumsum operation on a distributed array might not return exactly the same answer as the cumsum operation on the corresponding numeric array. The differences might be significant when A is a signed integer type.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

expand all

Include or omit missing values in the input array when computing cumulative sums by using the "includemissing" or "omitmissing" options. These options have the same behavior as the "includenan" and "omitnan" options, respectively.

The cumsum function can calculate on all variables within a table or timetable without indexing to access those variables. All variables must have data types that support the calculation. For more information, see Direct Calculations on Tables and Timetables.