cumsum

B = cumsum(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 cumsum(A) returns a vector containing the cumulative sum of the elements of A.
If A is a matrix, then cumsum(A) returns a matrix containing the cumulative sums for each column of A.
If A is a multidimensional array, then cumsum(A) acts along the first nonsingleton dimension.

B = cumsum(A,dim) returns the cumulative sum of the elements along dimension dim. For example, if A is a matrix, then cumsum(A,2) returns the cumulative sum of each row.

B = cumsum(___,direction) optionally specifies the direction using any of the previous syntaxes. You must specify A, and optionally can specify dim. For instance, cumsum(A,2,'reverse') returns the cumulative sum within the rows of A by working from end to beginning of the second dimension.

B = cumsum(___,nanflag) specifies whether to include or omit NaN values from the calculation for any of the previous syntaxes. cumsum(A,'includenan') includes all NaN values in the calculation while cumsum(A,'omitnan') ignores them.

Examples

Cumulative Sum of Vector

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).

A = 1:5;
B = cumsum(A)

B = 1×5

     1     3     6    10    15

Cumulative Sum of Each Column in Matrix

Define 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 = cumsum(A)

B = 3×3

     1     4     7
     3     9    15
     6    15    24

Cumulative Sum of Each Row in Matrix

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

A = [1 3 5; 2 4 6]

A = 2×3

     1     3     5
     2     4     6

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).

B = cumsum(A,2)

B = 2×3

     1     4     9
     2     6    12

Cumulative Sum of Logical Input

Create an array of logical values.

A = [true false true; true true false]

A = 2x3 logical array

   1   0   1
   1   1   0

Find the cumulative sum of the rows of A.

B = cumsum(A,2)

B = 2×3

     1     1     2
     1     2     2

The output has type double.

class(B)

ans = 
'double'

Reverse Cumulative Sum

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

Vector with `NaN` Values

Create a vector containing NaN values and compute the cumulative sums. By default, cumsum includes NaN values. When you include NaN values in the calculation, the cumulative sum becomes NaN as soon as the first NaN value in A is encountered.

A = [3 5 NaN 9 0 NaN];
B = cumsum(A)

B = 1×6

     3     8   NaN   NaN   NaN   NaN

You can ignore NaN values in the cumulative sum calculation using the 'omitnan' option.

B = cumsum(A,'omitnan')

B = 1×6

     3     8     8    17    17    17

Input Arguments

`A` — Input array
vector | matrix | multidimensional array

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

`dim` — Dimension to operate along
positive integer scalar

Dimension to operate along, specified as a positive integer scalar. If no value is specified, 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` — Direction of cumulation
`'forward'` (default) | `'reverse'`

Direction of cumulation, specified as 'forward' (default) or 'reverse'.

'forward' works from 1 to end of the active dimension.
'reverse' works from end to 1 of the active dimension.

Data Types: char

`nanflag` — `NaN` condition
`'includenan'` (default) | `'omitnan'`

NaN condition, specified as one of the following values:

'includenan' — Include NaN values from the input when computing the cumulative sums, resulting in NaN values in the output.
'omitnan' — Ignore all NaN values in the input. The sum of elements containing NaN values is the sum of all non-NaN elements. If all elements are NaN, then cumsum returns 0.

Data Types: char

Output Arguments

`B` — Cumulative sum array
vector | matrix | multidimensional array

Cumulative sum array, returned as a vector, matrix, or multidimensional array of the same size as the input array A.

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

More About