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(estobj=NULL,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
estobj |
An object of class Geofit that includes information about data, model and estimates. |
coordx |
A numeric ( |
coordy |
A numeric vector giving 1-dimension of
spatial coordinates; |
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 |
maxdist |
Numeric; an optional positive value indicating the
marginal spatial compact support in the case of tapered covariance matrix.
See |
maxtime |
Numeric; an optional positive value indicating the
marginal temporal compact support in the case of spacetime tapered
covariance matrix. See |
n |
Numeric; the number of trials in a binomial random fields.
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 "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 |
taper |
String; the name of the taper correlation
function if type is |
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
|
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.
Spatial correlation models:
-
GenCauchy
(generalisedCauchy
in Gneiting and Schlater (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,\kappa h^2 ) / \Gamma(\kappa+\alpha)
U(.,.,.)
is the Kummer hypergeometric function. Ifh
is the geodesic distance then\kappa \in (0,0.5]
-
Kummer{\_}Matern
It is a rescaled version of theKummer
model that ish
must be divided by2(\kappa(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
andA=(\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 theWend0
,Wend1
andWend2
models respectively. -
GenWend_{\_}Matern
(Generalized Wendland Matern in Bevilacqua et al. (2022)). It is defined as a rescaled version of the Generalized Wendland that ish
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 parametrization. It is defined as a rescaled version of the Generalized Wendland that ish
must be multiplied by\beta
and the smoothness parameter is\kappa-0.5
. When\beta
goes to infinity it is the Matern model. -
Hypergeometric
(Parsimonious Hypegeometric model in Alegria and Emery (2022)) defined as the modelHypergeometric2
with the restriction\beta=\alpha
. -
Multiquadric
defined as:R(h) = (1-\alpha0.5)^{2\beta}/(1+(\alpha0.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. -
Smoke
(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 andh
is the geodesic distance.
-
Spatio-temporal correlation models.
Non-separable models:
-
Gneiting
defined as:R(h, u) = e^{ -h^{\alpha_s}/((1+u^{\alpha_t})^{0.5 \gamma \alpha_s })}/(1+u^{\alpha_t})
-
Gneiting
_
GC
R(h, u) = e^{ -u^{\alpha_t} /((1+h^{\alpha_s})^{0.5 \gamma \alpha_t}) }/( 1+h^{\alpha_s})
where
h
can be both the euclidean and the geodesic distance -
Iacocesare
R(h, u) = (1+h^{\alpha_s}+u^\alpha_t)^{-\beta}
-
Porcu
R(h, u) = (0.5 (1+h^{\alpha_s})^\gamma +0.5 (1+u^{\alpha_t})^\gamma)^{-\gamma^{-1}}
-
Porcu1
R(h, u) =(e^{ -h^{\alpha_s} ( 1+u^{\alpha_t})^{0.5 \gamma \alpha_s}}) / ((1+u^{\alpha_t})^{1.5})
-
Stein
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}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 interchanging h with u inGneiting
_
mat
_
S
-
Gneiting
_
wen
_
S
, defined as:R(h, u) =\phi(u)^{\tau_t}GenWend(h \phi(u)^{\beta},\nu_s,\mu_s)
where
\phi(u)=(1+u^{0.5\alpha_t})
,\tau_t \geq 2.5+2\nu_s
,\beta \in [0,1]
-
Gneiting
_
wen
_
T
, defined interchanging h with u inGneiting
_
wen
_
S
-
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 andh
is the geodesic distance. -
Sinpower
_
st
defined as:R(h, u)=(e^{\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}
andk=(1+\alpha_s/a_s) exp(\alpha_s/a_s), \quad h \in [0,\pi]
This model is valid on the unit sphere andh
is the geodesic distance.
-
Separable models.
Space-time separable correlation models are easly 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) =Matern(h;\kappa_s)Matern(u;\kappa_t)
-
GenWend
_
GenWend
defined asR(h, u) = GenWend(h;\kappa_s,\mu_s) GenWend(u;\kappa_t,\mu_t)
.
-
Stable
_
Stable
defined as:R(h, u) =Stable(h;\alpha_s)Stable(u;\alpha_t)
Note that some models are nested. (The
Exp
_
Exp
withMatern
_
Matern
for instance.)-
Spatial bivariate correlation models (see below):
-
Bi
_
Matern
(Bivariate full Matern model) -
Bi
_
Matern
_
contr
(Bivariate Matern model with contrainsts) -
Bi
_
Matern
_
sep
(Bivariate separable Matern model ) -
Bi
_
LMC
(Bivariate linear model of coregionalization) -
Bi
_
LMC
_
contr
(Bivariate linear model of coregionalization with constraints ) -
Bi
_
Wendx
(Bivariate full Wendland model) -
Bi
_
Wendx
_
contr
(Bivariate Wendland model with contrainsts) -
Bi
_
Wendx
_
sep
(Bivariate separable Wendland model) -
Bi
_
Smoke
(Bivariate full Smoke model on the unit sphere)
-
Spatial taper.
For spatial covariance tapering the taper functions are:-
Bohman
defined as:T(h)=(1-h)(sin(2\pi h)/(2 \pi h))+(1-cos(2\pi h))/(2\pi^{2}h) 1_{[0,1]}(h)
-
Wendlandx, \quad x=0,1,2
defined as:T(h)=Wendx(h;x+2), x=0,1,2
.
-
Spatio-temporal tapers.
For spacetime covariance tapering the taper functions are:-
Wendlandx
_
Wendlandy
(Separable tapers)x,y=0,1,2
defined as:T(h,u)=Wendx(h;x+2) Wendy(h;y+2), x,y=0,1,2.
-
Wendlandx
_
time
(Non separable temporal taper)x=0,1,2
defined as:Wenx
_
time
,x=0,1,2
assuming\alpha_t=2
,\mu_s=3.5+x
and\gamma \in [0,1]
to be fixed usingtapsep
. -
Wendlandx
_
space
(Non separable spatial taper)x=0,1,2
defined as:Wenx
_
space
,x=0,1,2
assuming\alpha_s=2
,\mu_t=3.5+x
and\gamma \in [0,1]
to be fixed usingtapsep
.
-
Spatial bivariate taper (see below).
-
Bi
_
Wendlandx, \quad x=0,1,2
-
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 :
-
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 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
_
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 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
_
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 modelBi
_
LMC
_
contr
is a special case whenf=f_{12}=f_{21}
. Bivariate LMC models, in the current version of the package, is 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 is NULL. |
maxdist |
Numeric: the marginal spatial compact support
if |
maxtime |
Numeric: the marginal temporal compact support
if |
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 |
param |
Numeric: The covariance parameters; |
tapmod |
String: the taper model if |
spacetime |
|
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
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 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