# cumsum

Symbolic cumulative sum

## Syntax

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

## 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. 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.```

## Examples

collapse all

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

```syms x A = (1:5)*x```
`A = $\left(\begin{array}{ccccc}x& 2 x& 3 x& 4 x& 5 x\end{array}\right)$`

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 = $\left(\begin{array}{ccccc}x& 3 x& 6 x& 10 x& 15 x\end{array}\right)$`

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

`A = sym(ones(3))`
```A =  $\left(\begin{array}{ccc}1& 1& 1\\ 1& 1& 1\\ 1& 1& 1\end{array}\right)$```

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

`B = cumsum(A)`
```B =  $\left(\begin{array}{ccc}1& 1& 1\\ 2& 2& 2\\ 3& 3& 3\end{array}\right)$```

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

`B = cumsum(A,2)`
```B =  $\left(\begin{array}{ccc}1& 2& 3\\ 1& 2& 3\\ 1& 2& 3\end{array}\right)$```

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) =  $\left(\begin{array}{ccc}x& y& 3\\ 3& x& y\\ y& 2& x\end{array}\right)$```
```A(:,:,2) =  $\left(\begin{array}{ccc}x& y& \frac{1}{3}\\ 1& y& x\\ \frac{1}{3}& x& 2\end{array}\right)$```

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) =  $\left(\begin{array}{ccc}x+y+3& y+3& 3\\ x+y+3& x+y& y\\ x+y+2& x+2& x\end{array}\right)$```
```B(:,:,2) =  $\left(\begin{array}{ccc}x+y+\frac{1}{3}& y+\frac{1}{3}& \frac{1}{3}\\ x+y+1& x+y& x\\ x+\frac{7}{3}& x+2& 2\end{array}\right)$```

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) =  $\left(\begin{array}{ccc}2 x& 2 y& \frac{10}{3}\\ 4& x+y& x+y\\ y+\frac{1}{3}& x+2& x+2\end{array}\right)$```
```B(:,:,2) =  $\left(\begin{array}{ccc}x& y& \frac{1}{3}\\ 1& y& x\\ \frac{1}{3}& x& 2\end{array}\right)$```

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

`A = [sym('a') sym('b') 1 NaN 2]`
`A = $\left(\begin{array}{ccccc}a& b& 1& \mathrm{NaN}& 2\end{array}\right)$`
`B = cumsum(A)`
`B = $\left(\begin{array}{ccccc}a& a+b& a+b+1& \mathrm{NaN}& \mathrm{NaN}\end{array}\right)$`

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

`B = cumsum(A,'omitnan')`
`B = $\left(\begin{array}{ccccc}a& a+b& a+b+1& a+b+1& a+b+3\end{array}\right)$`

## 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` 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`.

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