NCL Home > Documentation > Functions > General applied math

wgt_volave

Calculates the volume average of a quantity using weights.

Prototype

	function wgt_volave (
		q        : numeric,  
		wgtz [*] : numeric,  
		wgty [*] : numeric,  
		wgtx [*] : numeric,  
		opt      : integer   
	)

	return_val  :  float or double

Arguments

An array of 3 or more dimensions containing the data to be averaged. The rightmost dimensions should correspond to "level" (lev), "latitude" (lat), and "longitude" (lon) when dealing with quantities on a sphere ([...,],lev,lat,lon), and "z", "y", and "x" otherwise ([...,],z,y,x).

wgtz

A scalar (typically 1.0) or 1-dimensional array of size "level" (z) containing the weights.

wgty

A scalar (typically 1.0) or 1-dimensional array of size "lat" (y) containing the weights.

wgtx

A scalar (typically 1.0) or 1-dimensional array of size "lon" (x) containing the weights.

opt

If opt = 0, the area average is calculated using available non-missing data. If opt = 1, then if any point in q is missing, the area average is not computed. In this case, it will be set to the missing value, which is indicated by q@_FillValue, or the default missing value if q@_FillValue is not set.

Return value

Returns a scalar if q is a two dimensional array. Otherwise, the output dimensionality is the same as the leftmost dimensions of the input q.

The return type is floating point if the input is floating point, and double if the input is of type double.

Description

This function computes a volume average of a quantity using weights. It ignores missing values (q@_FillValue).

Examples

Example 1

Let q(time, lev, lat, lon) be a global array with dimension sizes ktime = 120, nlev = 28, nlat = 64, mlon = 128 and wgtz(klev) be a 1-dimensional array containing the log of pressure or "delta-pressures" and wgty(nlat) be a 1-dimensional array containing gaussian or cosine weights. Assume that no special weighting is applied in the longitude (x) direction. Then:

   glAve = wgt_volave(q, wgtz, wgty, 1.0, 0)   ; glAve(ktime)

will calculate the volume (global) average for each time. glAve will be a 1-dimensional array with dimension (ktime = 120). If a missing value is encountered at any of the rightmost dimension, then the result will be set to q@_FillValue (opt = 0).

Example 2

   nhAve = wgt_volave (q(:, :, 33:nlat - 1, :), wgtz, wgty(33:nlat), 1.0, 1)

will calculate the volume (northern hemisphere) average for each time and level. Standard subscripting is used to subset the input global array. nlAve will be a 1-dimensional array with dimension (ktime = 120). If a missing value is encountered at any of the rightmost dimension, it is ignored (equivalent to a weight of 0.0) and the average is calculated using available non-missing data (opt = 1).

Example 3

   shAve = wgt_volave(q(:, 5:7, {lat | -90:0}, :), wgtz(5:7), wgty({lat | -90:0}), 1.0,0)