Main Content

cumsum

Symbolic cumulative sum

Description

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. The output B has the same size as A.

  • 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 of each column of A.

  • If A is a multidimensional array, then cumsum(A) acts along the first nonsingleton dimension.

example

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

example

B = cumsum(___,direction) specifies the direction using any of the previous syntaxes. 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.

example

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.

example

Examples

collapse all

Create a symbolic vector. Find the cumulative sum of its elements.

syms x
A = (1:5)*x
A = (x2x3x4x5x)

In the vector of cumulative sums, 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).

B = cumsum(A)
B = (x3x6x10x15x)

Create a 3-by-3 symbolic matrix A whose elements are all equal to 1.

A = sym(ones(3))
A = 

(111111111)

Compute the cumulative sum of elements of A. By default, cumsum returns the cumulative sum of each column.

B = cumsum(A)
B = 

(111222333)

To compute the cumulative sum of each row, set the value of the dim option to 2.

B = cumsum(A,2)
B = 

(123123123)

Create a 3-by-3-by-2 symbolic array.

syms x y
A(:,:,1) = [x y 3; 3 x y; y 2 x];
A(:,:,2) = [x y 1/3; 1 y x; 1/3 x 2];
A
A(:,:,1) = 

(xy33xyy2x)

A(:,:,2) = 

(xy131yx13x2)

Compute the cumulative sum along the rows by specifying dim as 2. 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(:,:,1) = 

(x+y+3y+33x+y+3x+yyx+y+2x+2x)

B(:,:,2) = 

(x+y+13y+1313x+y+1x+yxx+73x+22)

To compute the cumulative sum along the third (page) dimension, specify dim as 3. Specify the 'reverse' option to work from largest page index to smallest page index.

B = cumsum(A,3,'reverse')
B(:,:,1) = 

(2x2y1034x+yx+yy+13x+2x+2)

B(:,:,2) = 

(xy131yx13x2)

Create a symbolic vector containing NaN values. Compute the cumulative sums.

A = [sym('a') sym('b') 1 NaN 2]
A = (ab1NaN2)
B = cumsum(A)
B = (aa+ba+b+1NaNNaN)

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

B = cumsum(A,'omitnan')
B = (aa+ba+b+1a+b+1a+b+3)

Input Arguments

collapse all

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

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 sum of each column.

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

cumsum(A,1) column-wise operation and cumsum(A,2) row-wise operation

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

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

NaN condition, specified as:

  • '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

collapse all

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

More About

collapse all

First Nonsingleton Dimension

The first nonsingleton dimension is the first dimension of an array whose size is not equal to 1.

For example:

  • If X is a 1-by-n row vector, then the second dimension is the first nonsingleton dimension of X.

  • If X is a 1-by-0-by-n empty array, then the second dimension is the first nonsingleton dimension of X.

  • If X is a 1-by-1-by-3 array, then the third dimension is the first nonsingleton dimension of X.

Version History

Introduced in R2013b

expand all

See Also

| | | |