spaMM: HLCor – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

HLCor

Fits a (spatially) correlated mixed model, for given correlation parameters

Description

A fitting function acting as a convenient interface for HLfit, constructing the correlation matrix of random effects from the arguments, then estimating fixed effects and dispersion parameters using HLfit. Various arguments are available to constrain the correlation structure, covStruct and distMatrix being the more general ones (for any number of random effects), and adjMatrix and corrMatrix being alternatives to covStruct for a single correlated random effect. uniqueGeo is deprecated.

Usage

HLCor(formula, data, family = gaussian(), ranPars = NULL, distMatrix,
      adjMatrix, corrMatrix, covStruct=NULL,
      method = "REML", verbose = c(trace=FALSE),
      control.dist = list(), ...)

Arguments

`formula`	A `predictor`, i.e. a formula with attributes (see `Predictor`), or possibly simply a simple `formula` if an offset is not required.
`ranPars`	A list of values for correlation parameters (some of which are mandatory), and possibly also dispersion parameters (optional, but passed to HLfit if present). See `ranPars` for further information.
`data`	The data frame to be analyzed.
`family`	A `family` object describing the distribution of the response variable. See `HLfit` for further information.
`distMatrix`	Either a distance matrix between geographic locations, forwarded to `MaternCorr` or `CauchyCorr`. It overrides the (by default, Euclidean) distance matrix that would otherwise be deduced from the variables in a `Matern(.))` or `Cauchy(.)` term; or a list of such matrices. The list format is useful when there are several Matern/Cauchy terms, to avoid that all of them are affected by the same `distMatrix`. `NULL` list elements may be necessary, e.g. `distMatrix=list("1"=NULL,"2"=<.>)`) when a matrix is specified only for the second random effect.
`adjMatrix`	An single adjacency matrix, used if a random effect of the form `y ~ adjacency(1\|<location index>)` is present. See `adjacency` for further details. If adjacency matrices are needed for several random effects, use `covStruct`.
`corrMatrix`	A matrix C used if a random effect term of the form `corrMatrix(1\|<stuff>)` is present. This allows to analyze non-spatial model by giving for example a matrix of genetic correlations. Each row corresponds to levels of a variable <stuff>. The covariance matrix of the random effects for each level is then λC, where as usual λ denotes a variance factor for the random effects (if C is a correlation matrix, then λ is the variance, but other cases are possible). See `corrMatrix` for further details. If matrices are needed for several random effects, use `covStruct`.
`covStruct`	An interface for specifying correlation structures for different types of random effect (`corrMatrix` or `adjacency`). See `covStruct` for details.
`method`	Character: the fitting method to be used, such as `"ML"`, `"REML"` or `"PQL/L"`. `"REML"` is the default. Other possible values of `HLfit`'s `method` argument are handled.
`verbose`	A vector of booleans. `trace` controls various diagnostic (possibly messy) messages about the iterations.
`control.dist`	A list of arguments that control the computation of the distance argument of the correlation functions. Possible elements are rho.mapping a set of indices controlling which elements of the `rho` scale vector scales which dimension(s) of the space in which (spatial) correlation matrices of random effects are computed. See same argument in `make_scaled_dist` for details and examples. dist.method `method` argument of `proxy::dist` function (by default, `"Euclidean"`, but see `make_scaled_dist` for other distances such as spherical ones.)
`...`	Further parameters passed to `HLfit` or to `mat_sqrt`.

Details

For approximations of likelihood, see method. For the possible structures of random effects, see random-effects, but note that HLCor cannot adjust parameters of correlation models (with the exception of conditional autoregressive ones). Any such parameter must be specified by the ranPars argument. More generally, the correlation matrix for random effects can be specified by various combinations of formula terms and other arguments (see Examples):

Basic Matérn model: Matern(1|<...>), using the spatial coordinates in <...>. This will construct a correlation matrix according to the Matérn correlation function (see MaternCorr);
Basic Cauchy model: Cauchy(1|<...>), as for Matern (see CauchyCorr);
Same models with given distance matrix: as provided by distMatrix (see Examples);
Given correlation matrix: corrMatrix(1|<...>) with corrMatrix argument. See corrMatrix for further details.
CAR model with given adjacency matrix: adjacency(1|<...>) with adjMatrix. See adjacency for further details;
AR1 model: AR1(1|<...>) See AR1 for further details.

Value

The return value of an HLfit call, with the following additional attributes:

`HLCorcall`	the HLCor call
`info.uniqueGeo`	Unique geographic locations.

Examples

# Example with an adjacency matrix (autoregressive model):
# see 'adjacency' documentation page

#### Matern correlation using only the Matern() syntax
data("blackcap")
(fitM <- HLCor(migStatus ~ means+ Matern(1|longitude+latitude),data=blackcap,
      method="ML", ranPars=list(nu=0.6285603,rho=0.0544659)))

#### Using the 'distMatrix' argument
data("blackcap")
#
# Build distance matrix (here equivalent to the default one for a Matern() term)
MLdistMat <- as.matrix(proxy::dist(blackcap[,c("latitude","longitude")]))
#
(fitD <- HLCor(migStatus ~ means+ Matern(1|longitude+latitude),data=blackcap,
      distMatrix=MLdistMat, method="ML", ranPars=list(nu=0.6285603,rho=0.0544659)))
# : result here must be equivalent to the one without the distMatrix.
diff(c(logLik(fitM),logLik(fitD)))

spaMM

Mixed-Effect Models, with or without Spatial Random Effects

v3.10.0

CeCILL-2

Authors

François Rousset [aut, cre, cph] (<https://orcid.org/0000-0003-4670-0371>), Jean-Baptiste Ferdy [aut, cph], Alexandre Courtiol [aut] (<https://orcid.org/0000-0003-0637-2959>), GSL authors [ctb] (src/gsl_bessel.*)

Initial release

2022-02-06