Covariance-class: Virtual Class 'Covariance' of Covariance Matrices

In lme4: Linear Mixed-Effects Models using 'Eigen' and S4

Virtual Class ‘Covariance’ of Covariance Matrices

Description

An S4 class that describes the within-group variance-covariance structures available for the lme4 package. The syntax for use is similar to the glmmTMB package. See the Examples section on how to use.

There are four main covariance classes: Covariance.us (unstructured), Covariance.diag (diagonal), Covariance.cs (compound symmetry), and Covariance.ar1 (autoregressive order 1).

Usage

getPar(object)
getParLength(object)
getParNames(object, cnm, gnm, prf = NULL, old = TRUE)
setPar(object, value, pos = 0L)
getTheta(object)
getThetaLength(object)
getThetaNames(object, cnm, gnm, prf = NULL, old = TRUE)
getThetaIndex(object)
getThetaIndexLength(object)
setTheta(object, value, pos = 0L)
getLower(object)
getUpper(object)
getLambda(object)
getLambdat.dp(object)
getLambdat.i(object)
getVC(object)
getVCNames(object, cnm, gnm, prf = NULL, old = TRUE)
setVC(object, vcomp, ccomp)
getProfPar(object, profscale, sc = NULL)
setProfPar(object, profscale, sc = NULL, value, pos = 0L)
getProfLower(object, profscale, sc = NULL)
getProfUpper(object, profscale, sc = NULL)

Details

In matrix notation, a linear mixed model can be represented as:

\mathbf{y} = X \beta + Z \mathbf{b} + \boldsymbol{\epsilon}

Where \mathbf{b} represents an unknown vector of random effects. The Covariance class helps define the structure of the variance-covariance matrix as specified as Var(\mathbf{b}). Typically, we denote the variance-covariance matrix as \Sigma.

Proper details can be found in vignette("lmer"). Our main focus is the restriction on \Sigma. Let q represent the number of columns of the random-effects model matrix Z. \Sigma can be expressed in terms of a relative cofactor \Lambda_{\theta} which is a q \times q block diagonal matrix that depends on the variance-component parameter \theta:

\mathbf{\Sigma}_{\mathbf{\theta}} = \sigma^{2} \Lambda_{\theta} \Lambda_{\theta}^{T}.

Where \sigma is a scale parameter of the variance of a linear mixed model.

If the within-group variance-covariance structure is unspecified, the default is unstructured (Covariance.us), meaning we only ensure that the variance-covariance matrix \Sigma is positive semidefinite.

Objects from the Class

Available standard classes:

Covariance.us

Unstructured (general positive definite). This is the default version.

Covariance.diag

Diagonal; only the diagonal entries are nonzero, indicating no covariances between variables.

Covariance.cs

Compound symmetry.

Covariance.ar1

Autoregressive process of order 1.

Besides Covariance.us, the remaining classes contain a logical slot called hom, described in the Slots section.

Slots

nc

An integer value giving the number of columns (or components).

par

A double vector that stores the covariance parameters for the model. (See lmer and vignette("covariance_structures", package = "lme4") for more details on parameterization.)

hom

A logical value which represents whether the variance-covariance matrix has a homogeneous structure - that is, whether the variances are equal across groups.

S4 Methods

vcomp contains parameters of the variance component of the covariance matrix (typically standard deviations). ccomp contains parameters of the correlation component of the covariance matrix. That is,

• Covariance.us: the entries of the lower triangle of the correlation matrix in column-major order.

• diag: should be empty; we only care about the standard deviations.

• cs, ar1: \rho

Methods that obtain names (i.e., getParNames, getThetaNames, and getVCNames), cnm represents the column (of the model matrix) name, and gnm represents the group name.

For methods that involve getProf (i.e., getProfPar, setProfPar, getProfLower, getProfUpper), the user may set the argument profscale = "varcor", which transforms the variance components and correlation components into the corresponding variance-covariance matrix. Furthermore, the user may scale the standard deviations by a factor of the sc argument.

getPar:

The vector of parameters that the optimizer cares about; contains c(vcomp, ccomp).

getParLength:

Obtains the length of par.

getParNames:

Obtains the names of par in terms of cnm and gnm.

setPar:

Sets the value of par.

getTheta:

Obtains the variance-component parameter. These are also the column-wise elements of Lambda, or the row-wise elements of t(Lambda).

getThetaLength:

Obtains the length of the variance-component parameter theta.

getThetaNames:

Obtains the names of theta in terms of cnm and gnm.

getThetaIndex:

A mapping of the elements of theta into Lambda in column-major order.

getThetaIndexLength:

Obtains the length of getThetaIndex; which corresponds to the number of non-zero entries of Lambda.

setTheta:

Sets the value of the variance-component parameter.

getLower:

Retrieves the lower bound for vcomp and ccomp, in that order.

getUpper:

Retrieves the upper bound for vcomp and ccomp, in that order.

getLambda:

The relative covariance factor.

getLambdat.dp:

Returns a vector of length nc where each element contains the count of nonzero entries in the corresponding column. Together with Lambdat.i, defines the compressed sparse column representation of t(Lambda).

getLambdat.i:

Returns a vector of 0-based row indices (length <= nc*(n+1)/2) for nonzero entries in t(Lambda), stored in column-major order. Together with Lambdat.dp, defines the compressed sparse column representation of t(Lambda).

getVC:

Retrieves both vcomp and ccomp.

getVCNames:

Obtains the names of the values associated with vcomp and ccomp in terms of cnm and gnm.

setVC:

Sets the values for VC, which is composed of vcomp and ccomp.

getProfPar:

Converting the values from vcomp and ccomp (or getVC) to extract parameters from the object and translates them to a different parameterization suitable for profiling. If profscale = "varcov" then the variance-covariance matrix is returned.

setProfPar:

Sets the parameters to use for profiling.

getProfLower:

Obtains the lower bounds of the values obtained by getProfPar for profiling.

getProfUpper:

Obtains the upper bounds of the values obtained by getProfPar for profiling.

Examples

## Unstructured
fm1.us <- lmer(Reaction ~ Days + us(Days | Subject), sleepstudy)
## Diagonal
fm1.diag <- lmer(Reaction ~ Days + diag(Days | Subject), sleepstudy)
fm1.diag.hom <- lmer(Reaction ~ Days + diag(Days | Subject, hom = TRUE), 
  sleepstudy)
## Compound symmetry
fm1.cs <- lmer(Reaction ~ Days + cs(Days | Subject), sleepstudy)
fm1.cs.hom <- lmer(Reaction ~ Days + cs(Days | Subject, hom = TRUE), 
  sleepstudy)
## Auto-regressive order 1
sleepstudy$Daysf <- factor(sleepstudy$Days, ordered = TRUE)
fm1.ar1 <- lmer(Reaction ~ Daysf + ar1(0 + Daysf | Subject, hom = TRUE), 
                sleepstudy, REML = FALSE)

lme4 documentation built on March 6, 2026, 1:07 a.m.