covm: Covariance Between Two Random Effects

In sommer: Solving Mixed Model Equations in R

Covariance Between Two Random Effects

Description

covm combines two random-effect structures created with vsm into a single correlated random-effect structure. It fits an unstructured 2 \times 2 covariance matrix between the two random effects while allowing them to have different incidence matrices. The two effects must act on the same coefficient space and use the same relationship or precision matrix. The resulting structure can be fitted with the mmes solver.

Usage

covm(ran1, ran2, thetaC = NULL, theta = NULL,
fixed = NULL, fixedSigma2 = FALSE,
labels = c("ran1", "ran2"), tol = 1e-10)

Arguments

ran1	A random-effect structure returned by vsm for the first random effect. Currently, covm requires a simple vsm structure with one covariance-product coordinate, for example vsm(ism(focal)) or vsm(ism(focal), Gu = Ai).
ran2	A random-effect structure returned by vsm for the second random effect. It must have the same coefficient dimension and coefficient levels as ran1, although its incidence matrix may differ.
thetaC	Deprecated and not supported by the current CovarianceFactor parameterization. The former cell-wise constraint matrix cannot in general be translated exactly into the normalized-Cholesky parameterization used by covm. Use fixedSigma2 and fixed instead.
theta	An optional symmetric 2 \times 2 positive-definite matrix containing initial values for the variance-covariance matrix of the two random effects. Values are supplied directly on the natural variance-covariance scale. “' The diagonal elements define the initial variances of the two random effects and the off-diagonal element defines their initial covariance. If theta = NULL, the default starting matrix is ``` diag(2) * 0.15 + matrix(0.015, 2, 2) “' giving initial variances of 0.165 and an initial covariance of 0.015. “'
fixed	An optional logical vector of length two indicating whether the two normalized-Cholesky coordinates describing the covariance structure should be fixed at their starting values. The coordinates correspond to the off-diagonal Cholesky element and the second diagonal Cholesky element, respectively. The default is c(FALSE, FALSE), so both are estimated.
fixedSigma2	Logical value indicating whether the variance scale associated with the first random effect should be fixed at its starting value. The default is FALSE.
labels	Character vector of length two giving labels for the two random effects in the covariance descriptor. The default is c("ran1", "ran2"). The labels must be different and non-empty.
tol	Numerical tolerance used when checking positive definiteness and whether the relationship/precision matrices supplied by the two random effects are equal. The default is 1e-10.

Details

covm is intended for models in which two distinct random effects are expected to be correlated. A common example is the joint modeling of direct and indirect genetic effects.

If the coefficient vector for the first random effect is u_1 and that for the second is u_2, covm represents their covariance structure as

\mathrm{Var}([u_1^\prime, u_2^\prime]^\prime) = \sigma^2 K_{\mathrm{effect}} \otimes A,

where A represents the covariance structure associated with the coefficient levels, and K_{\mathrm{effect}} is a 2 \times 2 unstructured covariance shape describing the relationship between the two random effects.

Internally, covm uses the same CovarianceFactor interface as vsm. The 2 \times 2 effect covariance is represented using a normalized-Cholesky parameterization. This guarantees a positive-definite covariance matrix during optimization.

The variance of the first random effect is represented by the overall scale parameter sigma2. The remaining variance ratio and covariance are represented through the normalized-Cholesky factor.

The two random effects may have different incidence matrices. However, they must refer to identical coefficient levels in the same order and must use the same relationship/precision matrix.

When a relationship matrix is supplied through Gu, the Henderson solver requires it to be an inverse/precision matrix with attr(Gu, "inverse") = TRUE. For example:

attr(Ai, "inverse") <- TRUE

covm(
vsm(ism(focal), Gu = Ai),
vsm(ism(neighbour), Gu = Ai)
)

The current implementation combines simple vsm random effects only. Each input must contain one covariance-product coordinate. More complex covariance-factor products should therefore not currently be supplied independently inside ran1 and ran2.

Value

A list describing a correlated random-effect structure compatible with the CovarianceFactor-v2 interface used by vsm and mmes. The main elements are:

“'

Z

A list containing the two incidence matrices, one for each random effect.

Gu

The common sparse relationship precision matrix associated with the coefficient levels. It is stored with attr(Gu, "inverse") = TRUE for use by the Henderson solver.

covStruct

A CovarianceFactor-v2 descriptor containing the overall variance scale and the normalized-Cholesky representation of the 2 \times 2 unstructured covariance between the two random effects.

residualLocalIndex

NULL, since covm describes a random-effect structure rather than a residual covariance structure.

productDesign

NULL for the current implementation.

partitionsR

NULL for the current implementation.

covm

Logical value equal to TRUE, identifying the object as one constructed by covm.

covm_labels

The two labels used for the correlated random effects.

“'

Author(s)

Giovanny Covarrubias-Pazaran

References

Covarrubias-Pazaran G (2016). Genome assisted prediction of quantitative traits using the R package sommer. PLoS ONE 11(6). \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1371/journal.pone.0156744")}

Bijma, P. (2014). The quantitative genetics of indirect genetic effects: a selective review of modelling issues. Heredity, 112(1), 61–69.

See Also

vsm for constructing random-effect covariance structures and mmes for fitting mixed models using the Henderson solver.

Examples

data(DT_ige, package = "enhancer")
DT <- DT_ige

## Correlate two random effects with identity relationship matrices

covRes <- with(
DT,
covm(
vsm(ism(focal)),
vsm(ism(neighbour))
)
)

str(covRes)

## Custom initial variance-covariance matrix

covRes2 <- with(
DT,
covm(
vsm(ism(focal)),
vsm(ism(neighbour)),
theta = matrix(
c(0.5, 0.1,
0.1, 0.3),
2, 2
)
)
)

## Relationship precision matrix

## Ai must have matching row and column names and be marked as inverse.

##

## attr(Ai, "inverse") <- TRUE

##

## covRes3 <- with(

## DT,

## covm(

## vsm(ism(focal), Gu = Ai),

## vsm(ism(neighbour), Gu = Ai)

## )

## )

## See the DT_ige help page for a complete model-fitting example.

sommer documentation built on Oct. 25, 2026, 5:06 p.m.