corgm: General positive-definite correlation structure

In sommer: Solving Mixed Model Equations in R

General positive-definite correlation structure

Description

General positive-definite correlation structure. The returned dimensionless covariance shape is intended for use inside vsm, which supplies the single overall variance scale.

Usage

corgm(x, theta = NULL, fixed = NULL,
      variance = c("homogeneous", "heterogeneous"), values = NULL)

Arguments

x	Variable defining q covariance levels.
theta	Optional positive-definite q by q starting covariance or correlation matrix. With variance="heterogeneous" its diagonal is used as starting variances when values is not given.
fixed	Logical vector flagging parameters held at their starting value: length q(q-1)/2 (correlations) for the homogeneous mode and q(q-1)/2 + q-1 (correlations, then variance ratios of levels 2..q) for the heterogeneous mode.
variance	"homogeneous" (default) gives a pure correlation matrix scaled by the single variance of vsm. "heterogeneous" adds one variance per level.
values	Optional positive starting variances (length q) for the heterogeneous mode. Only their ratios to the first level matter; the first level's variance is the vsm scale. When omitted, the starting ratios are taken from the data.

Details

An unrestricted SPD correlation matrix is represented using a unit-diagonal lower factor A. The intermediate matrix S=AA^{\mathsf T} is standardized to correlation scale,

K_{ij}=S_{ij}/\sqrt{S_{ii}S_{jj}}.

The unrestricted working parameters are the strict lower-triangular entries of A.

With variance="heterogeneous" the shape is K = DRD with D=\mathrm{diag}(1, \sqrt{r_2}, \ldots, \sqrt{r_q}), where r_l=\sigma^2_l/\sigma^2_1 = \exp(\phi_l) are variance ratios relative to the first level; the vsm scale is \sigma^2_1. The model is the same as usm but parameterized as correlations and variances, which allows individual variances to be fixed. This is what mixed-family multi-trait models (familym) need: the residual variance of a binomial or Poisson trait is fixed to one while the correlations and the variances of Gaussian traits are estimated. Reported parameters (covparams_mmes) are the correlations and the variances of each level.

Value

A list containing the incidence/design matrix in Z and a compiled CovarianceFactor v2 descriptor in covFactor, for use inside vsm.

See Also

csm, usm, vsm, covmatrix_mmes, familym.

Examples

data(DT_example, package = "enhancer")
DT <- DT_example
# genetic correlations between environments with a homogeneous variance
m1 <- mmes(Yield ~ Env,
  random = ~ vsm(corgm(Env), ism(Name)),
  rcov = ~ units,
  data = DT,
  control = mmes_control(diagnostics = list(verbose = FALSE)))
covparams_mmes(m1, 1)

# heterogeneous variances (equivalent to usm, parameterized as corr/var)
m2 <- mmes(Yield ~ Env,
  random = ~ vsm(corgm(Env, variance = "heterogeneous"), ism(Name)),
  rcov = ~ units,
  data = DT,
  control = mmes_control(diagnostics = list(verbose = FALSE)))
covparams_mmes(m2, 1)
covmatrix_mmes(m2, 1)$correlation

sommer documentation built on Oct. 24, 2026, 1:08 a.m.