GeoCovmatrix: Spatial and Spatio-temporal Covariance Matrix of...
In GeoModels: Procedures for Gaussian and Non Gaussian Geostatistical (Large) Data Analysis
GeoCovmatrix 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 random field
with given underlying covariance model and a set of spatial location sites (and temporal instants).
Usage
GeoCovmatrix(estobj = NULL, coordx, coordy = NULL, coordz = NULL, coordt = NULL,
coordx_dyn = NULL, corrmodel, distance = "Eucl", grid = FALSE,
model = "Gaussian", n = 1, param, anisopars = NULL, radius = 1,
sparse = FALSE, copula = NULL, X = NULL, spobj = NULL)
Arguments
estobj
An object of class Geofit that includes information about data, model and estimates.
coordx
A numeric (d \times 2)-matrix or (d \times 3)-matrix.
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; optional argument, the default is NULL.
coordz
A numeric vector giving 1-dimension of spatial coordinates; optional argument, the default is NULL.
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.
n
Numeric; the number of trials in a binomial random field. 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 for the great circle distance. Default value is 1.
sparse
Logical; if TRUE the function returns an object of class spam.
This option should be used when a parametric compactly supported covariance is
used. Default is FALSE.
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 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 d=3
or a point (given in lon/lat degree format) on a sphere of arbitrary radius.
A list with all implemented spatial, 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.
Spatial correlation models:
-
GenCauchy (generalised Cauchy in Gneiting and Schlather 2004) defined as:
R(h) = ( 1+h^{\alpha} )^{-\beta / \alpha}
If h is the geodesic distance then \alpha \in (0,1].
-
Matern defined as:
R(h) = 2^{1-\kappa} \Gamma(\kappa)^{-1} h^\kappa K_\kappa(h)
If h is the geodesic distance then \kappa \in (0,0.5].
-
Kummer (Kummer hypergeometric in Ma and Bhadra 2022) defined as:
R(h) = \Gamma(\kappa+\alpha) U(\alpha,1-\kappa,0.5 h^2 ) / \Gamma(\kappa+\alpha)
where U(.,.,.) is the Kummer hypergeometric function.
If h is the geodesic distance then \kappa \in (0,0.5].
-
Kummer_Matern It is a rescaled version of the Kummer model,
i.e. h must be divided by (2(1+\alpha))^{0.5}. When \alpha goes to infinity it is the Matern model.
-
Wave defined as:
R(h)=\sin(h)/h
This model is valid only for dimensions less than or equal to 3.
-
GenWend (Generalized Wendland in Bevilacqua et al. 2019) defined as:
R(h) = A (1-h^2)^{\beta+\kappa} F(\beta/2,(\beta+1)/2,2\beta+\kappa+1,1-h^2) 1(h \in [0,1])
where \mu \ge 0.5(d+1)+\kappa
and A=(\Gamma(\kappa)\Gamma(2\kappa+\beta+1))/(\Gamma(2\kappa)\Gamma(\beta+1-\kappa)2^{\beta+1}) and F(.,.,.)
is the Gaussian hypergeometric function.
The cases \kappa=0,1,2 correspond to the Wend0, Wend1 and Wend2 models respectively.
-
GenWend_Matern (Generalized Wendland Matern in Bevilacqua et al. 2022).
It is defined as a rescaled version of the Generalized Wendland, i.e.
h must be divided by (\Gamma(\beta+2\kappa+1)/\Gamma(\beta))^{1/(1+2\kappa)}.
When \beta goes to infinity it is the Matern model.
-
GenWend_Matern2 (Generalized Wendland Matern second parametrisation).
It is defined as a rescaled version of the Generalized Wendland, i.e.
h must be multiplied by \beta and the smoothness parameter is \kappa-0.5.
When \beta goes to infinity it is the Matern model.
-
Hypergeometric (Hypergeometric model in Bevilacqua et al. 2025).
-
Hypergeometric_Matern (Hypergeometric model first parametrisation).
-
Hypergeometric_Matern2 (Hypergeometric model second parametrisation).
-
Multiquadric defined as:
R(h) = (1-\alpha 0.5)^{2\beta}/(1+(\alpha 0.5)^2-\alpha \cos(h))^{\beta}, \quad h \in [0,\pi]
This model is valid on the unit sphere and h is the geodesic distance.
-
Sinpower defined as:
R(h) = 1-(\sin(h/2))^{\alpha},\quad h \in [0,\pi]
This model is valid on the unit sphere and h is the geodesic distance.
-
F_Sphere (F family in Alegria et al. 2021) defined as:
R(h) = K F(1/\alpha,1/\alpha+0.5,2/\alpha+0.5+\kappa),\quad h \in [0,\pi]
where K =(\Gamma(a)\Gamma(i))/(\Gamma(i)\Gamma(o)).
This model is valid on the unit sphere and h is the geodesic distance.
Spatio-temporal correlation models:
Non-separable models:
-
Gneiting defined as:
R(h, u) = \exp(-h^{\alpha_s}/((1+u^{\alpha_t})^{0.5 \gamma \alpha_s}))/(1+u^{\alpha_t})
-
Gneiting_GC defined as:
R(h, u) = \exp(-u^{\alpha_t}/((1+h^{\alpha_s})^{0.5 \gamma \alpha_t}))/(1+h^{\alpha_s})
where h can be either Euclidean or geodesic distance.
-
Iacocesare defined as:
R(h, u) = (1+h^{\alpha_s}+u^{\alpha_t})^{-\beta}
-
Porcu defined as:
R(h, u) = (0.5 (1+h^{\alpha_s})^\gamma + 0.5 (1+u^{\alpha_t})^\gamma)^{-\gamma^{-1}}
-
Porcu1 defined as:
R(h, u) = \exp(-h^{\alpha_s}(1+u^{\alpha_t})^{0.5 \gamma \alpha_s})/((1+u^{\alpha_t})^{1.5})
-
Stein defined as:
R(h, u) = (h^{\psi(u)}K_{\psi(u)}(h))/(2^{\psi(u)}\Gamma(\psi(u)+1))
where \psi(u)=\nu+u^{0.5\alpha_t}.
-
Gneiting_mat_S defined as:
R(h, u) = \phi(u)^{\tau_t} \mathrm{Mat}(h \phi(u)^{-\beta},\nu_s)
where \phi(u)=(1+u^{0.5\alpha_t}), \tau_t \ge 3.5+\nu_s, \beta \in [0,1].
-
Gneiting_mat_T defined by interchanging h with u in Gneiting_mat_S.
-
Gneiting_wen_S defined as:
R(h, u) = \phi(u)^{\tau_t} \mathrm{GenWend}(h \phi(u)^{\beta},\nu_s,\mu_s)
where \phi(u)=(1+u^{0.5\alpha_t}), \tau_t \ge 2.5+2\nu_s, \beta \in [0,1].
-
Gneiting_wen_T defined by interchanging h with u in Gneiting_wen_S.
-
Matern_Matern_nosep defined as:
R(h, u) = \frac{\mathrm{Matern}(h;\nu_s)\,\mathrm{Matern}(u;\nu_t)}
{1+\lambda\,h^{2}u^{2}/(1+\lambda)}
with \nu_s,\nu_t>0 and \lambda\in[0,1].
-
GenWend_GenWend_nosep defined as:
R(h, u) = \frac{\mathrm{GenWend}(h;\nu_s,\delta_s)\,\mathrm{GenWend}(u;\nu_t,\delta_t)}
{1+\lambda\,h^{2}u^{2}/(1+\lambda)}
with \nu_x \geq -0.5, \delta_x>(d+1)/2+\nu_x for x=s,t, and \lambda\in[0,1].
-
Multiquadric_st defined as:
R(h, u)= ((1-0.5\alpha_s)^2/(1+(0.5\alpha_s)^2-\alpha_s \psi(u) \cos(h)))^{a_s},\quad h \in [0,\pi]
where \psi(u)=(1+(u/a_t)^{\alpha_t})^{-1}.
This model is valid on the unit sphere and h is the geodesic distance.
-
Sinpower_st defined as:
R(h, u)=(\exp(\alpha_s \cos(h) \psi(u)/a_s)(1+\alpha_s \cos(h) \psi(u)/a_s))/k
where \psi(u)=(1+(u/a_t)^{\alpha_t})^{-1} and k=(1+\alpha_s/a_s)\exp(\alpha_s/a_s), h \in [0,\pi].
This model is valid on the unit sphere and h is the geodesic distance.
Separable models:
Space-time separable correlation models are easily obtained as the product of a spatial and a temporal correlation model, that is
R(h,u)=R(h) R(u)
Several combinations are possible:
-
Exp_Exp defined as:
R(h, u) = \exp(-h)\exp(-u)
-
Matern_Matern defined as:
R(h, u) = \mathrm{Matern}(h;\kappa_s)\mathrm{Matern}(u;\kappa_t)
-
GenWend_GenWend defined as:
R(h, u) = \mathrm{GenWend}(h;\kappa_s,\mu_s)\mathrm{GenWend}(u;\kappa_t,\mu_t)
-
Stable_Stable defined as:
R(h, u) = \exp(-h^{\alpha_s})\exp(-u^{\alpha_t})
Note that some models are nested (e.g. Exp_Exp within Matern_Matern).
Spatial bivariate correlation models:
-
Bi_Matern (Bivariate full Matern model)
-
Bi_Matern_contr (Bivariate Matern model with constraints)
-
Bi_Matern_sep (Bivariate separable Matern model)
-
Bi_LMC (Bivariate linear model of coregionalization)
-
Bi_LMC_contr (Bivariate LMC with constraints)
-
Bi_Wendx (Bivariate full Wendland model)
-
Bi_Wendx_contr (Bivariate Wendland model with constraints)
-
Bi_Wendx_sep (Bivariate separable Wendland model)
-
Bi_F_Sphere (Bivariate full F model on the unit sphere)
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,\ldots), \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,\ldots), \quad h>0, u>0
Here ‘...’ stands for additional parameters.
The bivariate models implemented are the following:
-
Bi_Matern defined as:
C_{ij}(h)=\rho_{ij}(\sigma_i\sigma_j+\tau_i^2 1(i=j,h=0))\mathrm{Matern}(h/a_{ij},\kappa_{ij}), \quad i,j=1,2,\; h\ge 0
where \rho=\rho_{12}=\rho_{21} is the colocated correlation 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}).
-
Bi_GenWend defined as:
C_{ij}(h)=\rho_{ij}(\sigma_i\sigma_j+\tau_i^2 1(i=j,h=0))\mathrm{GenWend}(h/a_{ij},\nu_{ij},\kappa_{ij}), \quad i,j=1,2,\; h\ge 0
where \rho=\rho_{12}=\rho_{21} is the colocated correlation 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}).
-
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, are 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 bivariate, 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 is Standard. 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 on a regular grid, otherwise FALSE.
nozero
In the case of tapered matrix the percentage of non-zero values in the
covariance matrix; otherwise NULL.
n
The number of trials for binomial RFs.
namescorr
String: the names of the correlation parameters.
numcoord
Numeric: the number of spatial coordinates.
numtime
Numeric: the number of temporal coordinates.
model
The type of RF, see GeoFit.
param
Numeric: the covariance parameters.
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. and 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., Caamaño-Carrillo, C. and Porcu, E. (2022).
Unifying compactly supported and Matérn covariance functions in spatial statistics.
Journal of Multivariate Analysis 189, 104949.
Daley, D. J., Porcu, E. and 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. and Schlather, M. (2010).
Matérn cross-covariance functions for multivariate random fields.
Journal of the American Statistical Association 105, 1167–1177.
Ma, P. and 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 Schlather, M. (2004).
Stochastic models that separate fractal dimension and the Hurst effect.
SIAM Review 46, 269–282.
See Also
GeoKrig,
GeoSim,
GeoFit
Examples
library(GeoModels)
################################################################
###
### Example 1. Estimated spatial covariance matrix associated to
### a WCL estimates using the Matern correlation model
###
###############################################################
set.seed(3)
N <- 300 # number of location sites
x <- runif(N, 0, 1)
y <- runif(N, 0, 1)
coords <- cbind(x, y)
# Set the covariance model's parameters:
corrmodel <- "Matern"
mean <- 0.5
sill <- 1
nugget <- 0
scale <- 0.2/3
smooth <- 0.5
param <- list(mean = mean, sill = sill, nugget = nugget, scale = scale, smooth = smooth)
data <- GeoSim(coordx = coords, corrmodel = corrmodel, param = param)$data
fixed <- list(nugget = nugget, smooth = smooth)
start <- list(mean = mean, scale = scale, sill = sill)
fit0 <- GeoFit(data = data, coordx = coords, corrmodel = corrmodel,
neighb = 3, likelihood = "Conditional", optimizer = "BFGS",
type = "Pairwise", start = start, fixed = fixed)
print(fit0)
# estimated covariance matrix using Geofit object
mm <- GeoCovmatrix(fit0)$covmatrix
# estimated covariance matrix
mm1 <- GeoCovmatrix(coordx = coords, corrmodel = corrmodel,
param = c(fit0$param, fit0$fixed))$covmatrix
sum(mm - mm1)
################################################################
###
### Example 2. Spatial covariance matrix associated to
### the Generalized Wendland-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/1.5)
matrix2 <- GeoCovmatrix(coordx = coords, corrmodel = "GenWend_Matern",
param = param, sparse = TRUE)
# Percentage of non-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 non-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
GeoModels documentation built on Sept. 1, 2025, 1:09 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| GeoCovmatrix | 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 random field with given underlying covariance model and a set of spatial location sites (and temporal instants).
Usage
GeoCovmatrix(estobj = NULL, coordx, coordy = NULL, coordz = NULL, coordt = NULL,
coordx_dyn = NULL, corrmodel, distance = "Eucl", grid = FALSE,
model = "Gaussian", n = 1, param, anisopars = NULL, radius = 1,
sparse = FALSE, copula = NULL, X = NULL, spobj = NULL)
Arguments
estobj |
An object of class |
coordx |
A numeric ( |
coordy |
A numeric vector giving 1-dimension of spatial coordinates; optional argument, the default is |
coordz |
A numeric vector giving 1-dimension of spatial coordinates; optional argument, the default is |
coordt |
A numeric vector giving 1-dimension of temporal coordinates.
At the moment implemented only for the Gaussian case. Optional argument, the default is |
coordx_dyn |
A list of |
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 |
grid |
Logical; if |
n |
Numeric; the number of trials in a binomial random field. Default is |
model |
String; the type of RF. See |
param |
A list of parameter values required for the covariance model. |
anisopars |
A list of two elements |
radius |
Numeric; a value indicating the radius of the sphere
when using covariance models valid for the great circle distance. Default value is |
sparse |
Logical; if |
copula |
String; the type of copula. It can be |
X |
Numeric; matrix of space-time covariates. |
spobj |
An object of class |
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 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 d=3
or a point (given in lon/lat degree format) on a sphere of arbitrary radius.
A list with all implemented spatial, 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.
Spatial correlation models:
-
GenCauchy(generalised Cauchy in Gneiting and Schlather 2004) defined as:R(h) = ( 1+h^{\alpha} )^{-\beta / \alpha}If
his the geodesic distance then\alpha \in (0,1]. -
Materndefined as:R(h) = 2^{1-\kappa} \Gamma(\kappa)^{-1} h^\kappa K_\kappa(h)If
his the geodesic distance then\kappa \in (0,0.5]. -
Kummer(Kummer hypergeometric in Ma and Bhadra 2022) defined as:R(h) = \Gamma(\kappa+\alpha) U(\alpha,1-\kappa,0.5 h^2 ) / \Gamma(\kappa+\alpha)where
U(.,.,.)is the Kummer hypergeometric function. Ifhis the geodesic distance then\kappa \in (0,0.5]. -
Kummer_MaternIt is a rescaled version of theKummermodel, i.e.hmust be divided by(2(1+\alpha))^{0.5}. When\alphagoes to infinity it is the Matern model. -
Wavedefined as:R(h)=\sin(h)/hThis model is valid only for dimensions less than or equal to 3.
-
GenWend(Generalized Wendland in Bevilacqua et al. 2019) defined as:R(h) = A (1-h^2)^{\beta+\kappa} F(\beta/2,(\beta+1)/2,2\beta+\kappa+1,1-h^2) 1(h \in [0,1])where
\mu \ge 0.5(d+1)+\kappaandA=(\Gamma(\kappa)\Gamma(2\kappa+\beta+1))/(\Gamma(2\kappa)\Gamma(\beta+1-\kappa)2^{\beta+1})andF(.,.,.)is the Gaussian hypergeometric function. The cases\kappa=0,1,2correspond to theWend0,Wend1andWend2models respectively. -
GenWend_Matern(Generalized Wendland Matern in Bevilacqua et al. 2022). It is defined as a rescaled version of the Generalized Wendland, i.e.hmust be divided by(\Gamma(\beta+2\kappa+1)/\Gamma(\beta))^{1/(1+2\kappa)}. When\betagoes to infinity it is the Matern model. -
GenWend_Matern2(Generalized Wendland Matern second parametrisation). It is defined as a rescaled version of the Generalized Wendland, i.e.hmust be multiplied by\betaand the smoothness parameter is\kappa-0.5. When\betagoes to infinity it is the Matern model. -
Hypergeometric(Hypergeometric model in Bevilacqua et al. 2025). -
Hypergeometric_Matern(Hypergeometric model first parametrisation). -
Hypergeometric_Matern2(Hypergeometric model second parametrisation). -
Multiquadricdefined as:R(h) = (1-\alpha 0.5)^{2\beta}/(1+(\alpha 0.5)^2-\alpha \cos(h))^{\beta}, \quad h \in [0,\pi]This model is valid on the unit sphere and
his the geodesic distance. -
Sinpowerdefined as:R(h) = 1-(\sin(h/2))^{\alpha},\quad h \in [0,\pi]This model is valid on the unit sphere and
his the geodesic distance. -
F_Sphere(F family in Alegria et al. 2021) defined as:R(h) = K F(1/\alpha,1/\alpha+0.5,2/\alpha+0.5+\kappa),\quad h \in [0,\pi]where
K =(\Gamma(a)\Gamma(i))/(\Gamma(i)\Gamma(o)). This model is valid on the unit sphere andhis the geodesic distance.
-
Spatio-temporal correlation models:
Non-separable models:
-
Gneitingdefined as:R(h, u) = \exp(-h^{\alpha_s}/((1+u^{\alpha_t})^{0.5 \gamma \alpha_s}))/(1+u^{\alpha_t}) -
Gneiting_GCdefined as:R(h, u) = \exp(-u^{\alpha_t}/((1+h^{\alpha_s})^{0.5 \gamma \alpha_t}))/(1+h^{\alpha_s})where
hcan be either Euclidean or geodesic distance. -
Iacocesaredefined as:R(h, u) = (1+h^{\alpha_s}+u^{\alpha_t})^{-\beta} -
Porcudefined as:R(h, u) = (0.5 (1+h^{\alpha_s})^\gamma + 0.5 (1+u^{\alpha_t})^\gamma)^{-\gamma^{-1}} -
Porcu1defined as:R(h, u) = \exp(-h^{\alpha_s}(1+u^{\alpha_t})^{0.5 \gamma \alpha_s})/((1+u^{\alpha_t})^{1.5}) -
Steindefined as:R(h, u) = (h^{\psi(u)}K_{\psi(u)}(h))/(2^{\psi(u)}\Gamma(\psi(u)+1))where
\psi(u)=\nu+u^{0.5\alpha_t}. -
Gneiting_mat_Sdefined as:R(h, u) = \phi(u)^{\tau_t} \mathrm{Mat}(h \phi(u)^{-\beta},\nu_s)where
\phi(u)=(1+u^{0.5\alpha_t}),\tau_t \ge 3.5+\nu_s,\beta \in [0,1]. -
Gneiting_mat_Tdefined by interchanginghwithuinGneiting_mat_S. -
Gneiting_wen_Sdefined as:R(h, u) = \phi(u)^{\tau_t} \mathrm{GenWend}(h \phi(u)^{\beta},\nu_s,\mu_s)where
\phi(u)=(1+u^{0.5\alpha_t}),\tau_t \ge 2.5+2\nu_s,\beta \in [0,1]. -
Gneiting_wen_Tdefined by interchanginghwithuinGneiting_wen_S. -
Matern_Matern_nosepdefined as:R(h, u) = \frac{\mathrm{Matern}(h;\nu_s)\,\mathrm{Matern}(u;\nu_t)} {1+\lambda\,h^{2}u^{2}/(1+\lambda)}with
\nu_s,\nu_t>0and\lambda\in[0,1]. -
GenWend_GenWend_nosepdefined as:R(h, u) = \frac{\mathrm{GenWend}(h;\nu_s,\delta_s)\,\mathrm{GenWend}(u;\nu_t,\delta_t)} {1+\lambda\,h^{2}u^{2}/(1+\lambda)}with
\nu_x \geq -0.5,\delta_x>(d+1)/2+\nu_xforx=s,t, and\lambda\in[0,1]. -
Multiquadric_stdefined as:R(h, u)= ((1-0.5\alpha_s)^2/(1+(0.5\alpha_s)^2-\alpha_s \psi(u) \cos(h)))^{a_s},\quad h \in [0,\pi]where
\psi(u)=(1+(u/a_t)^{\alpha_t})^{-1}. This model is valid on the unit sphere andhis the geodesic distance. -
Sinpower_stdefined as:R(h, u)=(\exp(\alpha_s \cos(h) \psi(u)/a_s)(1+\alpha_s \cos(h) \psi(u)/a_s))/kwhere
\psi(u)=(1+(u/a_t)^{\alpha_t})^{-1}andk=(1+\alpha_s/a_s)\exp(\alpha_s/a_s),h \in [0,\pi]. This model is valid on the unit sphere andhis the geodesic distance.
-
Separable models:
Space-time separable correlation models are easily obtained as the product of a spatial and a temporal correlation model, that is
R(h,u)=R(h) R(u)Several combinations are possible:
-
Exp_Expdefined as:R(h, u) = \exp(-h)\exp(-u) -
Matern_Materndefined as:R(h, u) = \mathrm{Matern}(h;\kappa_s)\mathrm{Matern}(u;\kappa_t) -
GenWend_GenWenddefined as:R(h, u) = \mathrm{GenWend}(h;\kappa_s,\mu_s)\mathrm{GenWend}(u;\kappa_t,\mu_t) -
Stable_Stabledefined as:R(h, u) = \exp(-h^{\alpha_s})\exp(-u^{\alpha_t})
Note that some models are nested (e.g.
Exp_ExpwithinMatern_Matern).-
Spatial bivariate correlation models:
-
Bi_Matern(Bivariate full Matern model) -
Bi_Matern_contr(Bivariate Matern model with constraints) -
Bi_Matern_sep(Bivariate separable Matern model) -
Bi_LMC(Bivariate linear model of coregionalization) -
Bi_LMC_contr(Bivariate LMC with constraints) -
Bi_Wendx(Bivariate full Wendland model) -
Bi_Wendx_contr(Bivariate Wendland model with constraints) -
Bi_Wendx_sep(Bivariate separable Wendland model) -
Bi_F_Sphere(Bivariate full F model on the unit sphere)
-
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,\ldots), \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,\ldots), \quad h>0, u>0
Here ‘...’ stands for additional parameters.
The bivariate models implemented are the following:
-
Bi_Materndefined as:C_{ij}(h)=\rho_{ij}(\sigma_i\sigma_j+\tau_i^2 1(i=j,h=0))\mathrm{Matern}(h/a_{ij},\kappa_{ij}), \quad i,j=1,2,\; h\ge 0where
\rho=\rho_{12}=\rho_{21}is the colocated correlation parameter and\rho_{ii}=1. The modelBi_Matern_sep(separable Matern) is a special case whena=a_{11}=a_{12}=a_{22}and\kappa=\kappa_{11}=\kappa_{12}=\kappa_{22}. The modelBi_Matern_contr(constrained Matern) is a special case whena_{12}=0.5(a_{11}+a_{22})and\kappa_{12}=0.5(\kappa_{11}+\kappa_{22}). -
Bi_GenWenddefined as:C_{ij}(h)=\rho_{ij}(\sigma_i\sigma_j+\tau_i^2 1(i=j,h=0))\mathrm{GenWend}(h/a_{ij},\nu_{ij},\kappa_{ij}), \quad i,j=1,2,\; h\ge 0where
\rho=\rho_{12}=\rho_{21}is the colocated correlation parameter and\rho_{ii}=1. The modelBi_GenWend_sep(separable GenWendland) is a special case whena=a_{11}=a_{12}=a_{22}and\mu=\mu_{11}=\mu_{12}=\mu_{22}. The modelBi_GenWend_contr(constrained GenWendland) is a special case whena_{12}=0.5(a_{11}+a_{22})and\mu_{12}=0.5(\mu_{11}+\mu_{22}). -
Bi_LMCdefined 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 modelBi_LMC_contris a special case whenf=f_{12}=f_{21}. Bivariate LMC models, in the current version of the package, are obtained withR(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: |
coordx |
A |
coordy |
A |
coordt |
A |
coordx_dyn |
A list of |
covmatrix |
The covariance matrix if |
corrmodel |
String: the correlation model. |
distance |
String: the type of spatial distance. |
grid |
Logical: |
nozero |
In the case of tapered matrix the percentage of non-zero values in the
covariance matrix; otherwise |
n |
The number of trials for binomial RFs. |
namescorr |
String: the names of the correlation parameters. |
numcoord |
Numeric: the number of spatial coordinates. |
numtime |
Numeric: the number of temporal coordinates. |
model |
The type of RF, see |
param |
Numeric: the covariance parameters. |
spacetime |
|
sparse |
Logical: is the returned object of class |
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. and 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., Caamaño-Carrillo, C. and Porcu, E. (2022). Unifying compactly supported and Matérn covariance functions in spatial statistics. Journal of Multivariate Analysis 189, 104949.
Daley, D. J., Porcu, E. and 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. and Schlather, M. (2010). Matérn cross-covariance functions for multivariate random fields. Journal of the American Statistical Association 105, 1167–1177.
Ma, P. and 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 Schlather, M. (2004). Stochastic models that separate fractal dimension and the Hurst effect. SIAM Review 46, 269–282.
See Also
GeoKrig,
GeoSim,
GeoFit
Examples
library(GeoModels)
################################################################
###
### Example 1. Estimated spatial covariance matrix associated to
### a WCL estimates using the Matern correlation model
###
###############################################################
set.seed(3)
N <- 300 # number of location sites
x <- runif(N, 0, 1)
y <- runif(N, 0, 1)
coords <- cbind(x, y)
# Set the covariance model's parameters:
corrmodel <- "Matern"
mean <- 0.5
sill <- 1
nugget <- 0
scale <- 0.2/3
smooth <- 0.5
param <- list(mean = mean, sill = sill, nugget = nugget, scale = scale, smooth = smooth)
data <- GeoSim(coordx = coords, corrmodel = corrmodel, param = param)$data
fixed <- list(nugget = nugget, smooth = smooth)
start <- list(mean = mean, scale = scale, sill = sill)
fit0 <- GeoFit(data = data, coordx = coords, corrmodel = corrmodel,
neighb = 3, likelihood = "Conditional", optimizer = "BFGS",
type = "Pairwise", start = start, fixed = fixed)
print(fit0)
# estimated covariance matrix using Geofit object
mm <- GeoCovmatrix(fit0)$covmatrix
# estimated covariance matrix
mm1 <- GeoCovmatrix(coordx = coords, corrmodel = corrmodel,
param = c(fit0$param, fit0$fixed))$covmatrix
sum(mm - mm1)
################################################################
###
### Example 2. Spatial covariance matrix associated to
### the Generalized Wendland-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/1.5)
matrix2 <- GeoCovmatrix(coordx = coords, corrmodel = "GenWend_Matern",
param = param, sparse = TRUE)
# Percentage of non-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 non-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
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.