spaMM (version 2.0.0)

HLCor:

Description

A convenient interface for HLfit, constructing the correlation matrix of random effects from the arguments, then estimating fixed effects and dispersion parameters using HLfit.

Usage

HLCor(formula, data, family = gaussian(), ranPars = NULL, distMatrix,
      uniqueGeo = NULL, adjMatrix, corrMatrix,
      verbose = c(warn=TRUE,trace=FALSE,summary=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). For the Mat<U+00E9>rn model, the correlation parameters are rho (scale parameter(s)), nu (smoothness parameter), and (optional) Nugget (see Matern). The rho parameter can itself be a vector with different values for different geographic coordinates. For the "adjacency" model, the only correlation parameter is a scalar rho. The dispersion parameters are the random effect variance, lambda, and the residual variance, phi.

data

The data frame to be analyzed.

family

A family object describing the distribution of the response variable. See HLfit for further information.

distMatrix

A distance matrix between geographic locations, forwarded to MaternCorr

uniqueGeo

A matrix of non-redundant geographic locations. This is useful if the rho parameter is a vector with different values for different geographic coordinates, in which case a scaled distance matrix has to be reconstructed from uniqueGeo and rho.

adjMatrix

An adjacency matrix, used if a random effect of the form y ~ adjacency(1|<location index>) is present. Its rows and columns must be ordered as increasing values of the levels of the geographic location index specifying the spatial random effect. For example, if the model formula is y ~ adjacency(1|geo.loc) and <data>$geo.loc is 2,4,3,1,... the first row/column of the matrix refers to the fourth row of the data.

corrMatrix

A arbitrary (valid) correlation matrix, used if a random effect term of the form corrMatrix(1|<stuff>) is present. Each row corresponds to levels of a variable <stuff>. This allows to analyze non-spatial model by giving for example a matrix of genetic correlations. See corrMatrix for details.

verbose

A vector of booleans. trace controls various diagnostic (possibly messy) messages about the iterations. summary controls whether a summary of the fit is called by HLfit. warn is for programming purposes and best ignored.

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 designL.from.Corr.

Value

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

HLCorcall

the HLCor call

info.uniqueGeo

Unique geographic locations.

Details

The correlation matrix for random effects can be specified by various combination of formula terms and other arguments (see Examples):

Basic Mat<U+00E9>rn model

Matern(1|<...>) with ranPars argument, using the spatial coordinates in <...>. This will construct a correlation matrix according to the Mat<U+00E9>rn correlation function (see MaternCorr);

Mat<U+00E9>rn model with given distance matrix

Matern(1|<...>) with distMatrix and ranPars argument;

Given correlation matrix

corrMatrix(1|<...>) with corrMatrix argument. See corrMatrix for further details.

CAR model with given adjacency matrix

adjacency(1|<...>) with adjMatrix and ranPars argument. This will construct the correlation matrix (I\(-\rho\) adjMatrix\()^{-1}\) for a conditional autoregressive (CAR) model. This was implemented for comparison purposes as it is widely used, but is not really recommended for irregular lattices (see Wall, 2004 and Martellosio, 2012 for some insights on the implications of autoregressive models). See adjacency documentation for more information on fitting such models.

References

Wall M.M. (2004) A close look at the spatial structure implied by the CAR and SAR models: Journal of Statistical Planning and Inference 121: 311-324.

Martellosio, F. (2012) The correlation structure of spatial autoregressions, Econometric Theory 28, 1373-1391.

See Also

MaternCorr, HLfit, corrHLfit

Examples

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

#### Mat<U+00E9>rn correlation using only the Matern() syntax
if (spaMM.getOption("example_maxtime")>1.2) {
 data(Loaloa)
 HLCor(cbind(npos,ntot-npos)~elev1+elev2+elev3+elev4+maxNDVI1+seNDVI
              +Matern(1|longitude+latitude),data=Loaloa,
      family=binomial(),ranPars=list(nu=0.5,rho=1/0.7)) 
}
<!-- %- : tested in simulate.HLCor.Rd -->

#### Mat<U+00E9>rn correlation using a distMatrix
data(blackcap)
MLdistMat <- as.matrix(proxy::dist(blackcap[,c("latitude","longitude")]))
HLCor(migStatus ~ means+ Matern(1|latitude+longitude),data=blackcap,
      distMatrix=MLdistMat,HLmethod="ML",ranPars=list(nu=0.6285603,rho=0.0544659))