spaMM (version 4.1.20)

MaternCorr: Matern correlation function and Matern formula term.

Description

The Maté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érn function at the scaled Euclidean distance between coordinates specified in <...>, using “+” as separator (e.g., Matern(1|longitude+latitude)). 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).

A syntax of the form Matern(1|longitude+latitude %in% grp) can be used to specify a Matern random effect with independent realizations (but identical correlation parameters) for each level of the grouping variable grp. Alternatively, the Matern(<T/F factor>|longitude+latitude) may be used to specify Matern effects specific to individuals identified by the <T/F factor> (see Example with females and males). In that case distinct correlation parameters are fitted for each such Matern term.

When group-specific autocorrelated random effects are fitted, it may be wise to allow for different means for each group in the Intercept (a message will point this out if the fit results for Matern or Cauchy terms suggest so).

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|...)

Value

Scalar/vector/matrix depending on input.

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|longitude+latitude)

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

## 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|longitude+latitude %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|longitude+latitude)+ 
                         Matern(male|longitude+latitude),data=fm)
 # Although the results of these fits do not explicitly call for it,
 # adding a group-specific intercept may make more sense, as in e.g. 
   fitme(migStatus ~ sex + Matern(1|longitude+latitude %in% sex), data=fm)
}