corMatern: Matern Correlation Structure as a corSpatial object

Description

This implements the Matérn correlation structure for use with lme or glmmPQL. Usage is as for others corSpatial objects such as corGaus or corExp, except that the Matérn family has an additional parameter. This function was defined for comparing results obtained with corrHLfit to those produced by lme and glmmmPQL. There are problems in fitting (G)LMMs in the latter way, so it is not a recommended practice.

Usage

corMatern(value = c(1, 0.5), form = ~1, nugget = FALSE, nuScaled = FALSE,  metric = c("euclidean", "maximum", "manhattan"), fixed = FALSE)

Arguments

value

An optional vector of parameter values, with serves as initial values or as fixed values depending on the fixed argument. It has either two or three elements, depending on the nugget argument.

If nugget is FALSE, value should have two elements, corresponding to the "range" and the "smoothness" $\nu$ of the Matérn correlation structure. If value has zero length, the default is a range of 90% of the minimum distance and a smoothness of 0.5 (exponential correlation). Warning: the range parameter used in corSpatial objects is the inverse of the scale parameter used in MaternCorr and thus they have opposite meaning despite both being denoted $\rho$ elsewhere in this package or in nlme literature. If nugget is TRUE, meaning that a nugget effect is present, value can contain two or three elements, the first two as above, the third being the "nugget effect" (one minus the correlation between two observations taken arbitrarily close together). If value has length zero or two, the nugget defaults to 0.1. The range and smoothness must be greater than zero and the nugget must be between zero and one.

form

(Pasted from corSpatial) a one sided formula of the form ~ S1+...+Sp, or ~ S1+...+Sp | g, specifying spatial covariates S1 through Sp and, optionally, a grouping factor g. When a grouping factor is present in form, the correlation structure is assumed to apply only to observations within the same grouping level; observations with different grouping levels are assumed to be uncorrelated. Defaults to ~ 1, which corresponds to using the order of the observations in the data as a covariate, and no groups.

nugget

an optional logical value indicating whether a nugget effect is present. Defaults to FALSE.

nuScaled

If nuScaled is set to TRUE the "range" parameter $\rho$ is divided by $2 \sqrt\nu$. With this option and for large values of $\nu$, corMatern reproduces the calculation of corGaus. Defaults to FALSE, in which case the function compares to corGaus with range parameter $2(\sqrt\nu)\rho$ when $\nu$ is large.

metric

(Pasted from corSpatial) an optional character string specifying the distance metric to be used. The currently available options are "euclidean" for the root sum-of-squares of distances; "maximum" for the maximum difference; and "manhattan" for the sum of the absolute differences. Partial matching of arguments is used, so only the first three characters need to be provided. Defaults to "euclidean".

fixed

an optional logical value indicating whether the coefficients should be allowed to vary in the optimization, or kept fixed at their initial value. Defaults to FALSE, in which case the coefficients are allowed to vary.

Value

an object of class corMatern, also inheriting from class corSpatial, representing a Matérn spatial correlation structure.

Details

This function is a constructor for the corMatern class, representing a Matérn spatial correlation structure. See MaternCorr for details on the Matérn family.

References

Mixed-Effects Models in S and S-PLUS, José C. Pinheiro and Douglas M. Bates, Statistics and Computing Series, Springer-Verlag, New York, NY, 2000.

Examples

Run this code

## LMM
data(blackcap)
blackcapD <-cbind(blackcap,dummy=1) ## obscure, isn't it? 
## With method= 'ML' in lme, The correlated random effect is described 
##  as a correlated residual error and no extra residual variance is fitted:
nlme::lme(fixed = migStatus ~ means, data = blackcapD, random = ~ 1 | dummy, 
    correlation = corMatern(form = ~ longitude+latitude  | dummy), 
    method = "ML")

## Binomial GLMM
## ~54s. on a laptop
if (spaMM.getOption("example_maxtime")>50) {
 data(Loaloa)
 LoaloaD <-cbind(Loaloa,dummy=1) 
 MASS::glmmPQL(fixed =cbind(npos,ntot-npos)~elev1+elev2+elev3+elev4+maxNDVI1+seNDVI, 
        data = LoaloaD, random = ~ 1 | dummy,family=binomial, 
        correlation = corMatern(form = ~ longitude+latitude | dummy))
}

Run the code above in your browser using DataCamp Workspace