[TOC]

`cumsum`

Cumulative sum

Usage

`cumsum(A)`

A is a numeric or character array.
The output contains the cumulative sums and has the same size as A.
A cumulative sum is obtained by adding elements in a vector along the first non-singleton dimension of A.

`cumsum(A, dim)`

A is a numeric or character array.
dim should be a positive integer scalar, not equal to inf nor nan.
It obtains the cumulative sums along the dim-th dimension of A.
If size(A, dim) == 1 or dim > ndims(A), then the output is the same as A.

`cumsum(A, option)`

A is a numeric or character array.
option should be either 'reverse', 'forward', 'includenan' or 'omitnan'.
Each of these options controls the operation direction or inclusion of NaN in the operation.
See the table below for the available options.

`cumsum(A, dim, option)`

Same as cumsum(A, dim) above. In addition, an option is specified for controlling the operation direction or inclusion of NaN in the operation.
See the table below for the available options.

`cumsum(A, option1, option2)`

Same as cumsum(A, option) above. In addition, a second option is specified.
option2 will override option1 if they contradict with each other.
See the table below for the available options.

`cumsum(A, dim, option1, option2)`

Same as cumsum(A, dim, option) above. In addition, a second option is specified.
option2 will override option1 if they contradict with each other.
See the table below for the available options.

Option	Meaning	Default
`'forward'`	The cumulative sums are obtained in the forward direction.	Default for `cumsum`, `cumprod`, `cummin`, `cummax`
`'reverse'`	The cumulative sums are obtained in the reverse direction.	Not default for `cumsum`, `cumprod`, `cummin` and `cummax`
`'includenan`'	Include `NaN` in the operation	Default for `cumsum`, `cumprod`
`'omitnan`'	Omit `NaN` in the operation	Default for `cummax`, `cummin`

Examples

The first non-singleton dimension of A is the first dimension. The cumsum operation is performed along the vertical direction. For instance, s(:,1) contains cumulative sums of elements of A(:,1).

Input

% Matrix of size [3,4]
A = reshape(1:12,3,4)

% Cumulative sums
s = cumsum(A)

Output

A = 
 1.0000   4.0000   7.0000   10.000
 2.0000   5.0000   8.0000   11.000
 3.0000   6.0000   9.0000   12.000

s = 
 1.0000   4.0000   7.0000   10.000
 3.0000   9.0000   15.000   21.000
 6.0000   15.000   24.000   33.000

The cumsum operation is performed along the horizontal direction (2nd dimension). For instance, s(1,:) contains cumulative sums of elements of A(1,:).

Input

% Matrix of size [3,4]
A = reshape(1:12,3,4)

% Cumulative sums along 2nd dimension
s = cumsum(A,2)

Output

A = 
 1.0000   4.0000   7.0000   10.000
 2.0000   5.0000   8.0000   11.000
 3.0000   6.0000   9.0000   12.000

s = 
 1.0000   5.0000   12.000   22.000
 2.0000   7.0000   15.000   26.000
 3.0000   9.0000   18.000   30.000

Cumulative sums of the same vector but with different options. Note that cumsum by default includes NaN, therefore NaN appears in the outputs of the 1st and 2nd calls of cumsum. In fact, addition with NaN always returns NaN. In the 3rd call of cumsum, NaN is ignored in the addition operation.

Input

a = [1:5 nan 6]

% Default options
disp('Include nan, forward')
cumsum(a)

% Include nan, forward
disp('Include nan, forward.')
cumsum(a, 'includenan')

% Omit NaN, forward
disp('Omit nan, forward')
cumsum(a, 'omitnan')

% Include nan, forward
disp('Include nan, forward')
cumsum(a, 'forward')

% Include nan, reverse direction
disp('Include nan, reverse')
cumsum(a, 'reverse')

Output

a = 
 1.0000   2.0000   3.0000   4.0000   5.0000   NaN      6.0000

Include nan, forward

ans = 
 1.0000   3.0000   6.0000   10.000   15.000   NaN      NaN   

Include nan, forward.

ans = 
 1.0000   3.0000   6.0000   10.000   15.000   NaN      NaN   

Omit nan, forward

ans = 
 1.0000   3.0000   6.0000   10.000   15.000   15.000   21.000

Include nan, forward

ans = 
 1.0000   3.0000   6.0000   10.000   15.000   NaN      NaN   

Include nan, reverse

ans = 
 NaN      NaN      NaN      NaN      NaN      NaN      6.0000