spaMM (version 4.5.0)

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). The coordinates are numeric values found in the data data frame provided to the fitting function. No additional declaration of groups, factors, or other specific formatting is required.

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(Leuca)
  subLeuca <- Leuca[c(1:10,79:88),] # subset of 10 females and 10 males, for faster examples.

  # Independent Matern random effect with different covariance parameters for each sex:
  fitme(fec_div ~ sex + Matern(female|x + y) + Matern(male|x + y),  data = subLeuca) 

  # Independent Matern random effect with the same covariance parameters for each sex:
  fitme(fec_div ~ sex + Matern(1|x+y %in% sex),data=subLeuca)

  # Matern models with random-effects distinct but correlated across sexes 
  # can also be fitted: see Matern examples in help("composite-ranef").   
}