GeoCovmatrix {GeoModels}R Documentation

Spatial and Spatio-temporal Covariance Matrix of (non) Gaussian random fields

Description

The function computes the covariance matrix associated to a spatial or spatio(-temporal) or a bivariate spatial Gaussian or non Gaussian randomm field with given underlying covariance model and a set of spatial location sites (and temporal instants).

Usage

GeoCovmatrix(coordx, coordy=NULL, coordt=NULL, coordx_dyn=NULL, corrmodel,
          distance="Eucl", grid=FALSE, maxdist=NULL, maxtime=NULL,
          model="Gaussian", n=1, param, anisopars=NULL, radius=6371, sparse=FALSE,
          taper=NULL, tapsep=NULL, type="Standard",copula=NULL,X=NULL,spobj=NULL)

Arguments

coordx

A numeric (d \times 2)-matrix (where d is the number of spatial sites) giving 2-dimensions of spatial coordinates or a numeric d-dimensional vector giving 1-dimension of spatial coordinates. Coordinates on a sphere for a fixed radius radius are passed in lon/lat format expressed in decimal degrees.

coordy

A numeric vector giving 1-dimension of spatial coordinates; coordy is interpreted only if coordx is a numeric vector or grid=TRUE otherwise it will be ignored. Optional argument, the default is NULL then coordx is expected to be numeric a (d \times 2)-matrix.

coordt

A numeric vector giving 1-dimension of temporal coordinates. At the moment implemented only for the Gaussian case. Optional argument, the default is NULL then a spatial random field is expected.

coordx_dyn

A list of T numeric (d_t \times 2)-matrices containing dynamical (in time) coordinates. Optional argument, the default is NULL

corrmodel

String; the name of a correlation model, for the description see the Section Details.

distance

String; the name of the spatial distance. The default is Eucl, the euclidean distance. See GeoFit.

grid

Logical; if FALSE (the default) the data are interpreted as spatial or spatial-temporal realisations on a set of non-equispaced spatial sites (irregular grid). See GeoFit.

maxdist

Numeric; an optional positive value indicating the marginal spatial compact support in the case of tapered covariance matrix. See GeoFit.

maxtime

Numeric; an optional positive value indicating the marginal temporal compact support in the case of spacetime tapered covariance matrix. See GeoFit.

n

Numeric; the number of trials in a binomial random fields. Default is 1.

model

String; the type of RF. See GeoFit.

param

A list of parameter values required for the covariance model.

anisopars

A list of two elements "angle" and "ratio" i.e. the anisotropy angle and the anisotropy ratio, respectively.

radius

Numeric; a value indicating the radius of the sphere when using covariance models valid using the great circle distance. Default value is the radius of the earth in Km (i.e. 6371)

sparse

Logical; if TRUE the function return an object of class spam. This option should be used when a parametric compactly supporte covariance is used. Default is FALSE.

taper

String; the name of the taper correlation function if type is Tapering, see the Section Details.

tapsep

Numeric; an optional value indicating the separabe parameter in the space-time non separable taper or the colocated correlation parameter in a bivariate spatial taper (see Details).

type

String; the type of covariance matrix Standard (the default) or Tapering for tapered covariance matrix.

copula

String; the type of copula. It can be "Clayton" or "Gaussian"

X

Numeric; Matrix of space-time covariates.

spobj

An object of class sp or spacetime

Details

In the spatial case, the covariance matrix of the random vector

[Z(s_1),\ldots,Z(s_n,)]^T

with a specific spatial covariance model is computed. Here n is the number of the spatial location sites.

In the space-time case, the covariance matrix of the random vector

[Z(s_1,t_1),Z(s_2,t_1),\ldots,Z(s_n,t_1),\ldots,Z(s_n,t_m)]^T

with a specific space time covariance model is computed. Here m is the number of temporal instants.

In the bivariate case, the covariance matrix of the random vector

[Z_1(s_1),Z_2(s_1),\ldots,Z_1(s_n),Z_2(s_n)]^T

with a specific spatial bivariate covariance model is computed.

The location site s_i can be a point in the d-dimensional euclidean space with d=2 or a point (given in lon/lat degree format) on a sphere of arbitrary radius.

A list with all the implemented space and space-time and bivariate correlation models is given below. The argument param is a list including all the parameters of a given correlation model specified by the argument corrmodel. For each correlation model one can check the associated parameters' names using CorrParam. In what follows \kappa>0, \beta>0, \alpha, \alpha_s, \alpha_t \in (0,2] , and \gamma \in [0,1]. The associated parameters in the argument param are smooth, power2, power, power_s, power_t and sep respectively. Moreover let 1(A)=1 when A is true and 0 otherwise.

Remarks:
In what follows we assume \sigma^2,\sigma_1^2,\sigma_2^2,\tau^2,\tau_1^2,\tau_2^2, a,a_s,a_t,a_{11},a_{22},a_{12},\kappa_{11},\kappa_{22},\kappa_{12},f_{11},f_{12},f_{21},f_{22} positive.

The associated names of the parameters in param are sill, sill_1,sill_2, nugget, nugget_1,nugget_2, scale,scale_s,scale_t, scale_1,scale_2,scale_12, smooth_1,smooth_2,smooth_12, a_1,a_12,a_21,a_2 respectively.

Let R(h) be a spatial correlation model given in standard notation. Then the covariance model applied with arbitrary variance, nugget and scale equals to \sigma^2 if h=0 and

C(h)=\sigma^2(1-\tau^2 ) R( h/a,,...), \quad h > 0

with nugget parameter \tau^2 between 0 and 1. Similarly if R(h,u) is a spatio-temporal correlation model given in standard notation, then the covariance model is \sigma^2 if h=0 and u=0 and

C(h,u)=\sigma^2(1-\tau^2 )R(h/a_s ,u/a_t,...) \quad h>0, u>0

Here ‘...’ stands for additional parameters.

The bivariate models implemented are the following :

  1. Bi_Matern defined as:

    C_{ij}(h)=\rho_{ij} (\sigma_i \sigma_j+\tau_i^2 1(i=j,h=0)) Matern(h/a_{ij},\kappa_{ij}) \quad i,j=1,2.\quad h\ge 0

    where \rho=\rho_{12}=\rho_{21} is the correlation colocated parameter and \rho_{ii}=1. The model Bi_Matern_sep (separable matern) is a special case when a=a_{11}=a_{12}=a_{22} and \kappa=\kappa_{11}=\kappa_{12}=\kappa_{22}. The model Bi_Matern_contr (constrained matern) is a special case when a_{12}=0.5 (a_{11} + a_{22}) and \kappa_{12}=0.5 (\kappa_{11} + \kappa_{22})

  2. Bi_GenWend defined as:

    C_{ij}(h)=\rho_{ij} (\sigma_i \sigma_j+\tau_i^2 1(i=j,h=0)) GenWend(h/a_{ij},\nu_{ij},\kappa_ij) \quad i,j=1,2.\quad h\ge 0

    where \rho=\rho_{12}=\rho_{21} is the correlation colocated parameter and \rho_{ii}=1. The model Bi_GenWend_sep (separable Genwendland) is a special case when a=a_{11}=a_{12}=a_{22} and \mu=\mu_{11}=\mu_{12}=\mu_{22}. The model Bi_GenWend_contr (constrained Genwendland) is a special case when a_{12}=0.5 (a_{11} + a_{22}) and \mu_{12}=0.5 (\mu_{11} + \mu_{22})

  3. Bi_LMC defined as:

    C_{ij}(h)=\sum_{k=1}^{2} (f_{ik}f_{jk}+\tau_i^2 1(i=j,h=0)) R(h/a_{k})

    where R(h) is a correlation model. The model Bi_LMC_contr is a special case when f=f_{12}=f_{21}. Bivariate LMC models, in the current version of the package, is obtained with R(h) equal to the exponential correlation model.

Value

Returns an object of class GeoCovmatrix. An object of class GeoCovmatrix is a list containing at most the following components:

bivariate

Logical:TRUE if the Gaussian random field is bivariaete otherwise FALSE;

coordx

A d-dimensional vector of spatial coordinates;

coordy

A d-dimensional vector of spatial coordinates;

coordt

A t-dimensional vector of temporal coordinates;

coordx_dyn

A list of t matrices of spatial coordinates;

covmatrix

The covariance matrix if type isStandard. An object of class spam if type is Tapering or Standard and sparse is TRUE.

corrmodel

String: the correlation model;

distance

String: the type of spatial distance;

grid

Logical:TRUE if the spatial data are in a regular grid, otherwise FALSE;

nozero

In the case of tapered matrix the percentage of non zero values in the covariance matrix. Otherwise is NULL.

maxdist

Numeric: the marginal spatial compact support if type is Tapering;

maxtime

Numeric: the marginal temporal compact support if type is Tapering;

n

The number of trial for Binomial RFs

namescorr

String: The names of the correlation parameters;

numcoord

Numeric: the number of spatial coordinates;

numtime

Numeric: the number the temporal coordinates;

model

The type of RF, see GeoFit.

param

Numeric: The covariance parameters;

tapmod

String: the taper model if type is Tapering. Otherwise is NULL.

spacetime

TRUE if spatio-temporal and FALSE if spatial covariance model;

sparse

Logical: is the returned object of class spam? ;

Author(s)

Moreno Bevilacqua, moreno.bevilacqua89@gmail.com,https://sites.google.com/view/moreno-bevilacqua/home, Víctor Morales Oñate, victor.morales@uv.cl, https://sites.google.com/site/moralesonatevictor/, Christian", Caamaño-Carrillo, chcaaman@ubiobio.cl,https://www.researchgate.net/profile/Christian-Caamano

References

Alegria, A.,Cuevas-Pacheco, F.,Diggle, P, Porcu E. (2021) The F-family of covariance functions: A Matérn analogue for modeling random fields on spheres. Spatial Statistics 43, 100512

Bevilacqua, M., Faouzi, T., Furrer, R., and Porcu, E. (2019). Estimation and prediction using generalized Wendland functions under fixed domain asymptotics. Annals of Statistics, 47(2), 828–856.

Bevilacqua, M., Caamano-Carrillo, C., and Porcu, E. (2022). Unifying compactly supported and Matérn covariance functions in spatial statistics. Journal of Multivariate Analysis, 189, 104949.

Daley J. D., Porcu E., Bevilacqua M. (2015) Classes of compactly supported covariance functions for multivariate random fields. Stochastic Environmental Research and Risk Assessment. 29 (4), 1249–1263.

Emery, X. and Alegria, A. (2022). The gauss hypergeometric covariance kernel for modeling second-order stationary random fields in euclidean spaces: its compact support, properties and spectral representation. Stochastic Environmental Research and Risk Assessment. 36 2819–2834.

Gneiting, T. (2002). Nonseparable, stationary covariance functions for space-time data. Journal of the American Statistical Association, 97, 590–600.

Gneiting T, Kleiber W., Schlather M. 2010. Matern cross-covariance functions for multivariate random fields. Journal of the American Statistical Association, 105, 1167–1177.

Ma, P., Bhadra, A. (2022). Beyond Matérn: on a class of interpretable confluent hypergeometric covariance functions. Journal of the American Statistical Association,1–14.

Porcu, E.,Bevilacqua, M. and Genton M. (2015) Spatio-Temporal Covariance and Cross-Covariance Functions of the Great Circle Distance on a Sphere. Journal of the American Statistical Association. DOI: 10.1080/01621459.2015.1072541

Gneiting, T. and Schlater M. (2004) Stochastic models that separate fractal dimension and the Hurst effect. SSIAM Rev 46, 269–282.

See Also

GeoKrig, GeoSim, GeoFit

Examples

library(GeoModels)


################################################################
###
### Example 1. Spatial covariance matrix associated to
### the Matern correlation model
###
###############################################################

# Define the spatial-coordinates of the points:
x = runif(500, 0, 1)
y = runif(500, 0, 1)
coords = cbind(x,y)

# Correlation Parameters for Matern model 
CorrParam("Matern")

# Matern Parameters 
param=list(smooth=0.5,sill=1,scale=0.2,nugget=0)

matrix1 = GeoCovmatrix(coordx=coords, corrmodel="Matern", param=param)
dim(matrix1$covmatrix)

################################################################
###
### Example 2. Spatial covariance matrix associated to
### the GeneralizedWendland-Matern correlation model
###
###############################################################

# Correlation Parameters for Gen Wendland model 
CorrParam("GenWend_Matern")
# Gen Wendland Parameters 
param=list(sill=1,scale=0.04,nugget=0,smooth=0,power2=1.5)

matrix2 = GeoCovmatrix(coordx=coords, corrmodel="GenWend_Matern", param=param,sparse=TRUE)

# Percentage of no zero values 
matrix2$nozero


################################################################
###
### Example 3. Spatial covariance matrix associated to
### the Kummer correlation model
###
###############################################################

# Correlation Parameters for kummer model 
CorrParam("Kummer")
param=list(sill=1,scale=0.2,nugget=0,smooth=0.5,power2=1)

matrix3 = GeoCovmatrix(coordx=coords, corrmodel="Kummer", param=param)

matrix3$covmatrix[1:4,1:4]


################################################################
###
### Example 4. Covariance matrix associated to
### the space-time double Matern correlation model
###
###############################################################

# Define the temporal-coordinates:
times = seq(1, 4, 1)

# Correlation Parameters for double Matern model
CorrParam("Matern_Matern")

# Define covariance parameters
param=list(scale_s=0.3,scale_t=0.5,sill=1,smooth_s=0.5,smooth_t=0.5)

# Simulation of a spatial Gaussian random field:
matrix4 = GeoCovmatrix(coordx=coords, coordt=times, corrmodel="Matern_Matern",
                     param=param)

dim(matrix4$covmatrix)

################################################################
###
### Example 5. Spatial Covariance matrix associated to
### a  skew gaussian RF with Matern correlation model
###
###############################################################

param=list(sill=1,scale=0.3/3,nugget=0,skew=4,smooth=0.5)
# Simulation of a spatial Gaussian random field:
matrix5 = GeoCovmatrix(coordx=coords,  corrmodel="Matern", param=param, 
                     model="SkewGaussian")

# covariance matrix
matrix5$covmatrix[1:4,1:4]

################################################################
###
### Example 6. Spatial Covariance matrix associated to
### a  Weibull RF with Genwend correlation model
###
###############################################################

param=list(scale=0.3,nugget=0,shape=4,mean=0,smooth=1,power2=5)
# Simulation of a spatial Gaussian random field:
matrix6 = GeoCovmatrix(coordx=coords,  corrmodel="GenWend", param=param, 
                     sparse=TRUE,model="Weibull")

# Percentage of no zero values 
matrix6$nozero

################################################################
###
### Example 7. Spatial Covariance matrix associated to
### a  binomial gaussian RF with Generalized Wendland correlation model
###
###############################################################

param=list(mean=0.2,scale=0.2,nugget=0,power2=4,smooth=0)
# Simulation of a spatial Gaussian random field:
matrix7 = GeoCovmatrix(coordx=coords,  corrmodel="GenWend", param=param,n=5, 
                     sparse=TRUE,
                     model="Binomial")

as.matrix(matrix7$covmatrix)[1:4,1:4]


################################################################
###
### Example 8.  Covariance matrix associated to
### a bivariate Matern exponential correlation model
###
###############################################################

set.seed(8)
# Define the spatial-coordinates of the points:
x = runif(4, 0, 1)
y = runif(4, 0, 1)
coords = cbind(x,y)

# Parameters 
param=list(mean_1=0,mean_2=0,sill_1=1,sill_2=2,
           scale_1=0.1,  scale_2=0.1,  scale_12=0.1,
           smooth_1=0.5, smooth_2=0.5, smooth_12=0.5,
            nugget_1=0,nugget_2=0,pcol=-0.25)

# Covariance matrix 
matrix8 = GeoCovmatrix(coordx=coords, corrmodel="Bi_matern", param=param)$covmatrix

matrix8


[Package GeoModels version 2.0.1 Index]