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

dim_cumsum_n

Calculates the cumulative sum along the given dimension(s).

Prototype

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

	return_val [dimsizes(x)] :  typeof(x)

Arguments

x

A variable of numeric type and any dimensionality.

opt

Option for how to treat _FillValue.

• opt = 0 ; when _FillValue is encountered, set current element and all remaining to _FillValue
• 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 of x on which to do the cumulative sum across. This can only be a single dimension.

Return value

The same type and dimensionality as x.

Description

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

Use the dim_cumsum_n_Wrap function if metadata retention is desired. The interface is identical.

See Also

dim_acumrun_n, dim_cumsum, cumsum, dim_cumsum_n_Wrap, dim_rmvmean_n, dim_rmvmed_n

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(x, 0, 0)  ; result (/1  3  6  10  15/)
  x_cumsum = dim_cumsum_n(x, 1, 0)  ; result (/1  3  6  10  15/)
  x_cumsum = dim_cumsum_n(x, 2, 0)  ; result (/1  3  6  10  15/)

  ; Use dim_cumsum_n_Wrap if metadata retention is desired
  ; 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: when operating across the rightmost dimension, it is simpler to use dim_cumsum.

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(x, 0, 0)  ; result (/1  3 -999 -999 -999/)
  x_cumsum = dim_cumsum_n(x, 1, 0)  ; result (/1  3 -999    7   12/)
  x_cumsum = dim_cumsum_n(x, 2, 0)  ; result (/1  3    3    7   12/)

  ; Use dim_cumsum_n_Wrap if metadata retention is desired
  ; 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). Calculate cumulative sums at each time. The opt argument can be set by the user.

  p_cumsum = dim_cumsum_n(p, opt, 0)  ; (ntim,nlat,mlon)

  ; Use dim_cumsum_n_Wrap if metadata retention is desired
  p_cumsum = dim_cumsum_n_Wrap(p, opt, 0)  

Contact the Webmaster