cov.spatial: Computes Value of the Covariance Function

Description

Computes the covariances for pairs variables, given the separation distance of their locations. Options for different correlation functions are available. The results can be seen as a change of metric, from the Euclidean distances to covariances.

Usage

cov.spatial(obj, cov.model=c("matern", "exponential", "gaussian",
            "spherical", "circular", "cubic", "wave",
            "power", "powered.exponential", "cauchy", 
            "gneiting", "gneiting.matern", "pure.nugget"),
            cov.pars=stop("no cov.pars argument provided"),
            kappa = 0.5)

Arguments

obj

a numeric object (vector or matrix), typically with values of distances between pairs of spatial locations.

cov.model

a string indicating the type of the correlation function. See section DETAILS for available options and expressions of the correlation functions.

cov.pars

a vector with 2 elements or an $ns \times 2$ matrix with the covariance parameters. The first element (if a vector) or first column (if a matrix) corresponds to the variance parameter $\sigma^2$. The second element or column corresponds to the

kappa

numerical value for the additional smoothness parameter of the correlation function. Only required by the following correlation functions: "matern", "powered.exponential", "cauchy" and "gneiting

Value

The function returns values of the covariances corresponding to the given distances. The type of output is the same as the type of the object provided in the argument obj, typically a vector, matrix or array.

Details

Covariance functions return the value of the covariance $C(h)$ between a pair variables located at points separated by the distance $h$. The covariance function can be written as a product of a variance parameter $\sigma^2$ times a positive definite correlation function $\rho(h)$: $$C(h) = \sigma^2 \rho(h).$$ The expressions of the covariance functions available in geoR are given below. We recommend the LaTeX (and/or the corresponding .dvi, .pdf or .ps) version of this document for better visualization of the formulas. Denote $\phi$ the basic parameter of the correlation function and name it the range parameter. Some of the correlation functions will have an extra parameter $\kappa$, the smoothness parameter. $K_\kappa(x)$ denotes the modified Bessel function of the third kind of order $\kappa$. See documentation of the function besselK for further details. In the equations below the functions are valid for $\phi>0$ and $\kappa>0$, unless stated otherwise. exponential $$\rho(h) = \exp(-\frac{h}{\phi})$$

wave $$\rho(h) = \frac{\phi}{h}\sin(\frac{h}{\phi})$$

matern $$\rho(h) = \frac{1}{2^{\kappa-1}\Gamma(\kappa)}(\frac{h}{\phi})^\kappa K_{\kappa}(\frac{h}{\phi})$$

gaussian $$\rho(h) = \exp[(-\frac{h}{\phi})^2]$$

spherical $$\rho(h) = \left{ \begin{array}{ll} 1 - 1.5\frac{h}{\phi} + 0.5(\frac{h}{\phi})^3 \mbox{ , if $h$ < $\phi$} \cr 0 \mbox{ , otherwise} \end{array} \right.$$ circular Let $\theta = \min(\frac{h}{\phi},1)$ and $$g(h)= 2\frac{(\theta\sqrt{1-\theta^2}+ \sin^{-1}\sqrt{\theta})}{\pi}.$$ Then, the circular model is given by: $$\rho(h) = \left{ \begin{array}{ll} 1 - g(h) \mbox{ , if $h < \phi$}\cr 0 \mbox{ , otherwise} \end{array} \right.$$

cubic $$\rho(h) = \left{ \begin{array}{ll} 7(\frac{h}{\phi})^2-8.75(\frac{h}{\phi})^3+ 3.5(\frac{h}{\phi})^5-0.75(\frac{h}{\phi})^7 \mbox{ , if $h<\phi$} 0="" \cr="" \mbox{="" ,="" otherwise}="" \end{array}="" \right.$$<="" p="">

power For the power model the parameters $\sigma^2$ and $\phi$ of the covariance function will no longer have the interpretation as partial sill and range as for the other models. $$\rho(h) = {h}^{\phi}$$ powered.exponential $$\rho(h) = \exp[-(\frac{h}{\phi})^\kappa] \mbox{ , } 0 < \kappa \leq 2$$

cauchy $$\rho(h) = [1+(\frac{h}{\phi})^2]^{-\kappa}$$

gneiting Let $\theta = \min(\frac{h}{\phi},1)$. The Gneiting model is given by: $$\rho(h) = (1+8\theta+25\theta^2+32\theta^3)(1-\theta)^8$$

gneiting.matern Let $\alpha=\phi\kappa_2$, $\rho_m(\cdot)$ denotes the $\mbox{Mat\'{e}rn}$ model and $\rho_g(\cdot)$ the Gneiting model. Then the $\mbox{Gneiting-Mat\'{e}rn}$ is given by $$\rho(h) = \rho_g(h|\phi=\alpha) \, \rho_m(h|\phi=\phi,\kappa=\kappa_1)$$

References

For a review on correlation functions: Schlather, M. (1999) An introduction to positive definite functions and to unconditional simulation of random fields. Technical report ST 99-10, Dept. of Maths and Statistics, Lancaster University.

Further information about geoR can be found at: http://www.maths.lancs.ac.uk/~ribeiro/geoR.

Examples

Run this code

#
# Variogram models with the same "practical" range:
#
v.f <- function(x, ...){1-cov.spatial(x, ...)}
#
curve(v.f(x, cov.pars=c(1, .2)), from = 0, to = 1,
      xlab = "distance", ylab = expression(gamma(h)),
      main = "variograms with equivalent "practical range"")
curve(v.f(x, cov.pars = c(1, .6), cov.model = "sph"), 0, 1,
      add = TRUE, lty = 2)
curve(v.f(x, cov.pars = c(1, .6/sqrt(3)), cov.model = "gau"),
      0, 1, add = TRUE, lwd = 2)
legend(0.5,.3, c("exponential", "spherical", "gaussian"),
       lty=c(1,2,1), lwd=c(1,1,2))
#
# Matern models with equivalent "practical range"
# and varying smoothness parameter
#
curve(v.f(x, cov.pars = c(1, 0.25), kappa = 0.5),from = 0, to = 1,
      xlab = "distance", ylab = expression(gamma(h)), lty = 2,
      main = "models with equivalent "practical" range")
curve(v.f(x, cov.pars = c(1, 0.188), kappa = 1),from = 0, to = 1,
      add = TRUE)      
curve(v.f(x, cov.pars = c(1, 0.14), kappa = 2),from = 0, to = 1,
      add = TRUE, lwd=2, lty=2)      
curve(v.f(x, cov.pars = c(1, 0.117), kappa = 2),from = 0, to = 1,
      add = TRUE, lwd=2)      
legend(0.4,.4, c(expression(paste(kappa == 0.5, "and  ",
       phi == 0.250)),
       expression(paste(kappa == 1, "and  ", phi == 0.188)),
       expression(paste(kappa == 2, "and  ", phi == 0.140)),
       expression(paste(kappa == 3, "and  ", phi == 0.117))),
       lty=c(2,1,2,1), lwd=c(1,1,2,2))

Run the code above in your browser using DataLab