covStruct: Specifying correlation structures

Description

covStruct is a formal argument of HLCor, also handled by higher level fitting functions such as 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 long-deprecated function Predictor(...) which has served as an interface for specifying the design matrices for random effects in early versions of spaMM.

The main use of covStruct is to specify the correlation matrix of levels of a given random effect term. Assuming that the design matrix of each random effect term follows the structure ZAL described in random-effects, it is thus an indirect way of specifying a “square root” L of the correlation matrix. The optional A factor can also be given by the optional "AMatrices" attribute of covStruct.

The correlation structure of a random effect can be specified directly as a correlation matrix, or by its inverse (a precision matrix Q such that the covariance matrix is \(\lambda\)Q\(^{-1}\)), or by an adjacency matrix. covStruct is a list of matrices with names specifying the type of information provided:
covStruct=list(corrMatrix=<some correlation (or covariance) matrix>) or covStruct=list(adjMatrix=<some adjacency matrix>) or covStruct=list(precision=<some precision matrix>).

When several matrices are provided, these names can be repeated, and 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.

The function as_precision can be used to perform the conversion from correlation information to precision factor in a controlled way (but using a numerical inversion that may not always be efficient). Fitting functions may also perform such a conversion automatically. Do not run as_precision on a matrix which is already the inverse of a correlation or covariance matrix, as the result will no longer be a precision matrix.

"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, condnum=1e12)

Value

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

Arguments

corrMatrix: Correlation matrix, specified as matrix or as dist object.
condnum: Numeric: when a standard Cholesky factorization fails, the matrix is regularized so that the regularized matrix has this condition number (in version 3.10.0 this correction has been implemented more exactly than in previous versions).

Details

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

Examples

Run this code

if (FALSE) {
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))     
fitme(migStatus ~ means + corrMatrix(1|name), data=blackcap,
      corrMatrix=MLdistMat)

#### Same result using precision matrix,
(by_sp <- fitme(migStatus ~ means + corrMatrix(1|name), data=blackcap,
      covStruct=list(precision=as_precision(MLdistMat))))
# This typically induced the use of a distinct fitting algorithm:
how(by_sp) # "...using sparse-precision method..."

# Less controlled specification of precision matrix, 
# but essentially same result again:
as_mat <- proxy::as.matrix(MLdistMat, diag=1) 
prec_mat <- solve(as_mat) ## precision factor matrix
fitme(migStatus ~ means + corrMatrix(1|name), data=blackcap,
      covStruct=list(precision=prec_mat))
# !!! but do *not* use list(precision=as.precision(prec_mat)) !!!
 
# Since no correlation parameter is estimated, 
# HLcor(., method="ML")  is here equivalent to fitme()
}