WeightedMean {ClimProjDiags}

Calculate spatial area-weighted average of multidimensional arrays

Description

This function computes a spatial area-weighted average of n-dimensional arrays being possible to select a region and to add a mask to be applied when computing the average.

Usage

WeightedMean(
  data,
  lon,
  lat,
  region = NULL,
  mask = NULL,
  londim = "lon",
  latdim = "lat",
  na.rm = TRUE,
  ncores = NULL
)

Arguments

data

A numeric array with named dimensions, representing the data to be applied the weights. It should have at least the latitude dimension and it can have more other dimensions.

lon

A numeric vector of longitude locations of the cell centers of the grid of data. This vector must be of the same length as the longitude dimension in the parameter data (in degrees).

lat

A numeric vector of latitude locations of the cell centers of the grid of data. This vector must be of the same length as the latitude dimension in the parameter data (in degrees).

region

A vector of length four indicating the minimum longitude, the maximum longitude, the minimum latitude and the maximum latitude of the region to be averaged.

mask

A matrix with the same spatial dimensions of data. It can contain either a) TRUE where the value at that position is to be accounted for and FALSE where not, or b) numeric values, where those greater or equal to 0.5 are to be accounted for, and those smaller are not. Attention: if the longitude and latitude dimensions of the data and mask coincide in length, the user must ensure the dimensions of the mask are in the same order as the dimensions in the array provided in the parameter data.

londim

A character string indicating the name of the longitudinal dimension. The default value is 'lon'.

latdim

A character string indicating the name of the latitudinal dimension. The default value is 'lat'.

na.rm

A logical value indicating whether missing values should be stripped before the computation proceeds, by default it is set to TRUE.

ncores

An integer indicating the number of cores to use for parallel computation. The default value is NULL.

Value

An array, matrix or vector containig the area-weighted average with the same dimensions as data, except for the spatial longitude and latitude dimensions, which disappear.

Examples

# Example 1:
data <- 1:(2 * 3 * 4 * 5)
dim(data) <- c(lon = 2, lat = 3, time = 4, model = 5)
lat <- c(1, 10, 20)
lon <- c(1, 10)
a <- WeightedMean(data = data, lon = lon, lat = lat, region = NULL)

mask <- c(0, 1, 0, 1, 0, 1)
dim(mask) <- c(lon = 2, lat = 3)
a <- WeightedMean(data = data, lon = lon, lat = lat, mask = mask)

region <- c(1, 10, 1, 10)
a <- WeightedMean(data = data, lon = lon, lat = lat, region = region, 
                 mask = mask)

# Example 2:
data <- 1:(2 * 3 * 4)
dim(data) <- c(lon = 2, lat = 3, time = 4)
lat <- c(1, 10, 20)
lon <- c(1, 10)
a <- WeightedMean(data = data, lon = lon, lat = lat)