covStruct: Specifying correlation structures

Description

covStruct is a formal argument of HLCor, also handled by fitme and corrHLfit, that allows one to specify the correlation structure for different types of random effects, It is an alternative to other ad hoc formal arguments such as corrMatrix or adjMatrix. It replaces the deprecated function Predictor(...) which has served as an interface for specifying the design matrices for random effects in early versions of spaMM.

It is assumed that the design matrices for the random effects take the form ZL or ZAL where the L factor can be determined from the covStruct argument (or from the model formula; see Details), the Z factor is determined from the model formula, and the optional A factor is given by the optional "AMatrices" attribute of covStruct.

covStruct is a list of matrices with names specifying the type of matrix considered: covStruct=list(corrMatrix=<some matrix>) or covStruct=list(adjMatrix=<some matrix>), where the “corrMatrix” or “adjMatrix” labels are used to specify the type of information provided (accordingly, the names can be repeated: covStruct=list(corrMatrix=<.>,corrMatrix=<.>)).

The covariance structure of a corrMatrix(1|<grouping factor>) formula term can be specified in two ways (see Examples): either by a correlation matrix factor (covStruct=list(corrMatrix=<some matrix>)), or by a precision matrix factor Q such that the covariance factor is \(\lambda\)Q\(^{-1}\), using the type name "precision": covStruct=list(precision=<some matrix>). In this case, an algorithm efficient for sparse precision matrices is used to fit the model. The function as_precision can be used to perform the conversion from correlation information to precision factor (using a crude solve() that may not always be efficient).

NULL list members may be necessary, e.g. covStruct=list(corrMatrix=<.>,"2"=NULL,corrMatrix=<.>)) when correlations matrices are required only for the first and third random effect.

"AMatrices" is a list of matrices. The names of elements of the list does not matter, but the ith A matrix, and its row names, should match the ith Z matrix, and its column names. This implies that NULL list members may be necessary, as for the covStruct list.

Usage

as_precision(corrMatrix)

Arguments

corrMatrix

Correlation matrix, specified as matrix or as dist object

Value

as_precision returns a list with addition class precision and with single element a symmetric matrix of class dsCMatrix.

Details

covStruct can also be specified as a list with an optional "types" attribute, e.g. structure(list(<some matrix>,types="corrMatrix"))

In a spatial model, a vector of correlated random effects Lv can be constructed from uncorrelated ones, v, for some matrix L (this may be meaningful only for Gaussian random effects). Typically L is the Cholesky “square root” of a correlation matrix determined by the random effect specification (e.g., Matern(...)), or given by the covStruct argument.

If there is one response value par location, L is thus a square matrix which dimension is the number of observations. Alternatively, several observations may be taken in the same location, and a matrix Z automatically constructed) tells which element of Lv affects each observation. The linear predictor then contains a term of the form ZLv, where dim(Z) is (number of observations,number of locations).

Finally, in some applications the realized random effects in response locations may be viewed as linear combinations ALv of random effects Lv in distinct locations. In that case the dimension of L is the number of such distinct locations, A maps them to the observed locations, and Z again maps them to possibly repeated observations in observed locations.

Thus, in general the random term in the linear predictor is written Mv, where M=ZAL is reconstructed from the element matrices (usually automatically constructed if needed).

attr(covStruct,"AMatrices") should be used to specify A matrices, and the other matrices are automatically constructed from the various arguments of a fit.

Examples

Run this code

# NOT RUN {
data("blackcap") 
# a 'dist' object can be used to specify a corrMatrix:  
MLdistMat <- MaternCorr(proxy::dist(blackcap[,c("latitude","longitude")]),
                        nu=0.6285603,rho=0.0544659) # a 'dist' object!
blackcap$name <- as.factor(rownames(blackcap))     
HLCor(migStatus ~ means + corrMatrix(1|name), data=blackcap,
      corrMatrix=MLdistMat, HLmethod="ML")
#### Same result by different input and algorithm:
HLCor(migStatus ~ means + corrMatrix(1|name), data=blackcap,
      covStruc=list(precision=as_precision(MLdistMat)), HLmethod="ML")
# Manual version of the same:
m <- proxy::as.matrix(MLdistMat, diag=1) 
prec_mat <- solve(m) ## precision factor matrix
HLCor(migStatus ~ means + corrMatrix(1|name), data=blackcap,
      covStruc=list(precision=prec_mat), HLmethod="ML")
# }