spaMM (version 3.5.0)

MaternCorr: Matern correlation function and Matern formula term.

Description

The Mat<U+00E9>rn correlation function describes realizations of Gaussian spatial processes with different smoothnesses (i.e. either smooth or rugged surfaces, controlled by the \(\nu\) parameter). It also includes a \(\rho\) scaling parameter and an optional 'nugget' parameter. A random effect specified in a model formula as Matern(1|<...>) has pairwise correlations given by the Mat<U+00E9>rn function at the scaled Euclidean distance between coordinates specified in <...>, using “+” as separator (e.g., Matern(1|latitude + longitude)). A syntax of the form Matern(1|latitude + longitude %in% grp) can be used to specify a Matern random effect with independent realizations for each level of the grouping variable grp. The Matern family can be used in Euclidean spaces of any dimension; and also for correlations on a sphere (with maximum smoothness nu=0.5).

By default, fitme and corrHLfit performs optimization over the \(\rho\) and \(\nu\) parameters. It is possible to estimate different scaling parameters for the different Euclidean dimensions: see examples in make_scaled_dist.

The MaternCorr function may be used to vizualise these correlations, using distances as input.

Usage

# S3 method for default
MaternCorr(d, rho = 1, smoothness, nu = smoothness, Nugget = NULL)
# Matern(1|...)

Arguments

d

A distance or a distance matrix.

rho

A scaling factor for distance. The 'range' considered in some formulations is the reciprocal of this scaling factor

smoothness

The smoothness parameter, >0. \(\nu=0.5\) corresponds to the exponential correlation function, and the limit function when \(\mu\) goes to \(\infty\) is the squared exponential function (as in a Gaussian).

nu

Same as smoothness

Nugget

(Following the jargon of Kriging) a parameter describing a discontinuous decrease in correlation at zero distance. Correlation will always be 1 at \(d=0\), and from which it immediately drops to (1-Nugget)

…

Names of coordinates, using “+” as separator (e.g., Matern(1|latitude + longitude)

Value

Scalar/vector/matrix depending on input.

Details

The correlation at distance \(d>0\) is $$(1-\textrm{Nugget}) \frac{(\rho d)^\nu K_\nu(\rho d)}{2^{(\nu - 1)} \Gamma(\nu)}$$ where \(K_\nu\) is the besselK function of order \(\nu\).

By default the Nugget is set to 0. See one of the examples on data set Loaloa for a fit including the estimation of the Nugget.

References

Stein, M.L. (1999) Statistical Interpolation of Spatial Data: Some Theory for Kriging. Springer, New York.

See Also

See corMatern for an implementation of this correlation function as a corSpatial object for use with lme or glmmPQL.

Examples

# NOT RUN {
## See examples in help("HLCor"), help("Loaloa"),  help("make_scaled_dist"), etc.
## Matern correlations in 4-dimensional space:
set.seed(123)
randpts <- matrix(rnorm(20),nrow=5)
distMatrix <- as.matrix(proxy::dist(randpts))
MaternCorr(distMatrix,nu=2)

## Group-specific random effects
if (spaMM.getOption("example_maxtime")>1.6) {
   data("blackcap")
 # grouped effect using the '%in%' syntax:
   fm <- cbind(blackcap,sex=c(rep(TRUE,7),rep(FALSE,7))) 
   fitme(migStatus ~ 1 + Matern(1|latitude+longitude %in% sex),data=fm)
    
 # Superficially similar aim for distinct random effects for each sex,
 # but here with distinct covariance parameters for each of them:
   fm$female <- fm$sex; fm$male <- ! fm$female
   fitme(migStatus ~ 1 + Matern(female|latitude+longitude)+ 
                         Matern(male|latitude+longitude),data=fm)
} 
# }