# Documentation

### This is machine translation

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

To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

# cumsum

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. 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 = 2x3 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`.

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.