Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

cumsum

Cumulative sum

Syntax

Description

example

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.

example

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.

example

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.

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.

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

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

     1     3     6    10    15

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

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

     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 =

     1     4     7
     3     9    15
     6    15    24

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

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

     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 =

     1     4     9
     2     6    12

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.

B = cumsum(A,2)
B =

     1     1     2
     1     2     2

The output has type double.

class(B)
ans =

double

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

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

     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 =

    22    13     3
    23    13     6
    13    11    10

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 =

     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 =

     3     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 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 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 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

collapse all

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

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.

Tips

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

See Also

| | | | | |

Introduced before R2006a

Was this topic helpful?