Main Content

cumsum

Cumulative sum

collapse all in page

Syntax

B = cumsum(A)
B = cumsum(A,dim)
B = cumsum(___,direction)
B = cumsum(___,nanflag)

Description

example

B= cumsum(A)returns the cumulative sum ofAstarting at the beginning of the first array dimension inAwhose size does not equal 1.

  • IfAis a vector, thencumsum(A)returns a vector containing the cumulative sum of the elements ofA.

  • IfAis a matrix, thencumsum(A)returns a matrix containing the cumulative sums for each column ofA.

  • IfAis a multidimensional array, thencumsum(A)acts along thefirst nonsingleton dimension.

example

B= cumsum(A,dim)returns the cumulative sum of the elements along dimensiondim. For example, ifAis a matrix, thencumsum(A,2)returns the cumulative sum of each row.

example

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

example

B= cumsum(___,nanflag)specifies whether to include or omitNaNvalues from the calculation for any of the previous syntaxes.cumsum(A,'includenan')includes allNaNvalues in the calculation whilemitnan')ignores them.

Examples

collapse all

Open Live Script

Find the cumulative sum of the integers from1to5. The elementB(2)is the sum ofA(1)andA(2), whileB(5)is the sum of elementsA(1)throughA(5).

A = 1:5; B = cumsum(A)
B =1×51 3 6 10 15
Open Live Script

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×31 4 7 2 5 8 3 6 9

Find the cumulative sum of the columns ofA. The elementB(5)is the sum ofA(4)andA(5), whileB(9)is the sum ofA(7),A(8), andA(9).

B = cumsum(A)
B =3×31 4 7 3 9 15 6 15 24
Open Live Script

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

A = [1 3 5; 2 4 6]
A =2×31 3 5 2 4 6

Find the cumulative sum of the rows ofA. The elementB(3)is the sum ofA(1)andA(3), whileB(5)is the sum ofA(1),A(3), andA(5).

B = cumsum(A,2)
B =2×31 4 9 2 6 12
Open Live Script

Create an array of logical values.

A = [true false true; true true false]
A =2x3 logical array1 0 1 1 1 0

Find the cumulative sum of the rows ofA.

B = cumsum(A,2)
B =2×31 1 2 1 2 2

The output has typedouble.

class(B)
ans = 'double'
Open Live Script

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

rngdefault; A = randi([1,10],3)
A =3×39 10 3 10 7 6 2 1 10

沿着行计算累计总和。Specify the“反向”option to work from right to left in each row. The result is the same size asA.

B = cumsum(A,2,“反向”)
B =3×322 13 3 23 13 6 13 11 10
Open Live Script

Create a vector containingNaNvalues and compute the cumulative sums. By default,cumsumincludesNaNvalues. When you includeNaNvalues in the calculation, the cumulative sum becomesNaNas soon as the firstNaNvalue inAis encountered.

A = [3 5 NaN 9 0 NaN]; B = cumsum(A)
B =1×63 8 NaN NaN NaN NaN

You can ignoreNaNvalues in the cumulative sum calculation using the'omitnan'option.

B = cumsum(A,'omitnan')
B =1×63 8 8 17 17 17

Input Arguments

collapse all

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

Data Types:double|single|int8|int16|int32|int64|uint8|uint16|uint32|uint64|logical|duration
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 of size greater than 1.

Consider a two-dimensional input array,A:

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

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

cumsumreturnsAifdimis greater thanndims(A).

Direction of cumulation, specified as'forward'(default) or“反向”.

  • 'forward'works from1toendof the active dimension.

  • “反向”works fromendto1of the active dimension.

Data Types:char

NaNcondition, specified as one of the following values:

  • 'includenan'— IncludeNaNvalues from the input when computing the cumulative sums, resulting inNaNvalues in the output.

  • 'omitnan'— Ignore allNaNvalues in the input. The sum of elements containingNaNvalues is the sum of all non-NaNelements. If all elements areNaN, thencumsumreturns 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 arrayA.

The class ofBis the same as the class ofAexcept ifAislogical, in which caseBisdouble.

More About

collapse all

First Nonsingleton Dimension

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

For example:

  • IfXis a 1-by-n row vector, then the second dimension is the first nonsingleton dimension ofX.

  • IfXis a 1-by-0-by-n empty array, then the second dimension is the first nonsingleton dimension ofX.

  • IfXis a 1-by-1-by-3 array, then the third dimension is the first nonsingleton dimension ofX.

Tips

  • Many cumulative functions in MATLAB®support the“反向”option. This option allows quick directional calculations without needing a flip or reflection of the input array.

Extended Capabilities

版本历史

Introduced before R2006a

See Also

||||||