NCL Home > Documentation > Functions > General applied math, Statistics

# dim_cumsum_n_Wrap

Calculates the cumulative sum along the given dimension(s) and retains metadata.

Available in version 5.1.1 and later.

## Prototype

```load "\$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"

function dim_cumsum_n_Wrap (
x        : numeric,
opt      : integer,
dims [*] : integer
)

return_val [dimsizes(x)] :  float or double
```

## Arguments

x

A variable of numeric type and any dimensionality.

opt

Option for how to treat _FillValue:

• opt = 0 ; when _FillValue is encountered no additional summing will be performed.
• opt = 1 ; when _FillValue is encountered set element to _FillValue and resume summing
• opt = 2 ; treat _FillValue as numeric zero when summing

dims

The dimension(s) of x on which to do the cumulative sum across.

## Return value

The same type and dimensionality as x.

## Description

This function calculates the cumulative sum of all elements of dimensions indicated by dims for each index of the remaining dimensions. A wrapper function. Missing values are treated differently as specified by opt

## Examples

Example 1: When no _FillValue are encountered all three options return the same result.

```  x        = (/1,2,3,4,5/)
x_sum    = sum(x)            ; result 15
x_cumsum = dim_cumsum_n_Wrap(x, 0, 0)  ; result (/1  3  6  10  15/)
x_cumsum = dim_cumsum_n_Wrap(x, 1, 0)  ; result (/1  3  6  10  15/)
x_cumsum = dim_cumsum_n_Wrap(x, 2, 0)  ; result (/1  3  6  10  15/)
```
Note: for a 1D array, it is simpler to use dim_cumsum_Wrap.

Example 2: When one or more _FillValue are encountered, each option yields a different answer.

```  x        = (/1,2,-999,4,5/)
x@_FillValue = -999
x_sum    = sum(x)            ; result 12
x_cumsum = dim_cumsum_n_Wrap(x, 0, 0)  ; result (/1  3 -999 -999 -999/)
x_cumsum = dim_cumsum_n_Wrap(x, 1, 0)  ; result (/1  3 -999    7   12/)
x_cumsum = dim_cumsum_n_Wrap(x, 2, 0)  ; result (/1  3    3    7   12/)
```
Example 3: Let p(time,lat,lon) and calculate cumulative sums at each time. The opt argument can be set by the user.
```  p_cumsum = dim_cumsum_n_Wrap(p,opt,0)
```