GeoModels (version 2.2.8)

GeoCorrFct_Cop: Correlation, Covariance, and Variogram Functions for Spatial Copula Models

Description

Computes the observed-scale correlation, covariance, or semivariogram of a univariate spatial or spatio-temporal random field constructed with a Gaussian, Clayton-like, or skew-Gaussian copula. The function uses the same numerical second-order covariance engines as GeoCovmatrix(), GeoCovariogram(), and GeoKrig().

Usage

GeoCorrFct_Cop(x, t = NULL, corrmodel,
model = "Gaussian", copula = "Gaussian",
distance = "Eucl", param, radius = 6371,
n = 1, covariance = FALSE, variogram = FALSE)

Value

An object of class GeoCorrFct. Its corr component contains the requested correlation, covariance, or semivariogram values. The object also contains the spatial distances, temporal distances, marginal model, copula, parameters, and flags describing the requested scale.

Arguments

x

Numeric vector of non-negative spatial distances.

t

Optional numeric vector of non-negative temporal distances for a spatio-temporal correlation model.

corrmodel

String giving the latent Gaussian correlation model. See GeoCovmatrix for implemented correlation models.

model

String giving the marginal distribution. Copula covariance is implemented for Gaussian, StudentT, LogGaussian, Gamma, Weibull, Beta, Beta2, Kumaraswamy, Kumaraswamy2, Logistic, SkewLaplace, Tukeyh, Tukeyh2, and SinhAsinh.

copula

String giving the copula. Supported values are Gaussian, Clayton, and SkewGaussian. For the Clayton-like copula, param$nu must be a positive integer. For the skew-Gaussian copula, param$nu is the asymmetry parameter and must belong to \((-1,1)\).

distance

String giving the spatial distance. The default is Eucl. The supplied x values are already distances; this argument is retained for consistency with the other GeoModels functions.

param

List of correlation, marginal, nugget, and copula parameters. Since this is a lag-only function and has no design matrix, location-dependent margins use an intercept-only marginal predictor mean.

radius

Numeric radius of the sphere when great-circle distances are used. The default is 6371 km.

n

Numeric number of trials, retained for interface compatibility.

covariance

Logical. If TRUE and variogram=FALSE, return observed-scale covariance. If FALSE, return observed-scale correlation.

variogram

Logical. If TRUE, return a semivariogram. With covariance=TRUE, this is the observed-scale semivariogram \(V_Y-C_Y(h)\). With covariance=FALSE, it is the normalized semivariogram \(1-\rho_Y(h)\).

Author

Moreno Bevilacqua, ,https://sites.google.com/view/moreno-bevilacqua/home, Víctor Morales Oñate, , https://sites.google.com/site/moralesonatevictor/, Christian Caamaño-Carrillo, ,https://www.researchgate.net/profile/Christian-Caamano

Details

The spatial dependence supplied by corrmodel is interpreted as the correlation \(\rho(h)\) of the latent Gaussian random field underlying the copula. The marginal covariance is then obtained on the observed scale using the selected copula and marginal quantile transformation.

For Gaussian copulas, the implementation uses the Gaussian-copula covariance engine. The Tukeyh, Tukeyh2, and SinhAsinh margins are monotone transforms of one Gaussian field, so their Gaussian-copula covariance is evaluated with the corresponding exact transformed-Gaussian covariance rather than a truncated Hermite expansion. Clayton-like covariances use the cached deterministic quadrature/interpolation engine, avoiding adaptive two-dimensional integration at every lag. Skew-Gaussian covariances use the cached bivariate Hermite representation. Consequently, repeated calls with the same copula and marginal parameters can reuse cached numerical objects.

The nugget is applied to the latent correlation for non-zero lags. At the exact zero spatial and temporal lag, the function represents the same random variable and therefore returns correlation one, the marginal variance for covariance, and zero for the semivariogram.

Examples

library(GeoModels)

################################################################
### Correlation of a mean-reparametrized Beta random field
### with a Matern latent correlation model.
################################################################

x <- seq(0, 0.4, 0.02)

param <- list(smooth = 0.5, scale = 0.2 / 3, nugget = 0,
              mean = 0, min = 0, max = 1, shape = 2)

corr_gauss <- GeoCorrFct_Cop(
    x = x, corrmodel = "Matern", param = param,
    copula = "Gaussian", model = "Beta2"
)
plot(corr_gauss, ylab = "Correlation", lwd = 2)

## Clayton-like and skew-Gaussian copulas are selected through param$nu.
## Their fast covariance engines are also used by GeoCovmatrix and GeoKrig.