Variance-structure model with arbitrary Kronecker covariance factors

vsm constructs random-effect or residual covariance structures for mmes. Covariance-shaping terms are represented by CovarianceFactor v2 descriptors and may be combined in an arbitrary-depth Kronecker product. A single product-level variance, $\sigma^2$, is owned by vsm, which avoids scale confounding among the individual covariance factors.

Usage

vsm(..., Gu = NULL, sigma2 = NULL, fixedSigma2 = FALSE,
  rotation = FALSE, isFixed = FALSE, verbose = TRUE)

Arguments

...

One or more covariance-constructor terms. The last term supplies the main-effect incidence matrix. All preceding terms are covariance-shaping factors. Examples include dsm(environment), ar1m(row), and ism(genotype).

Gu

Optional known precision matrix for the levels of the final main-effect term. For mmes, Gu must have row and column names matching the main-effect levels and attr(Gu, "inverse") must be TRUE. If omitted, an identity precision matrix is used.

Gu can also be supplied in 3-column (row, column, value) format as a numeric matrix or data frame, e.g. the output of ASReml-R ainverse() or the listAinv element of nadiv::makeAinv(). The first two columns are 1-based level indices and the third the precision values. The level names must be given in attr(Gu, "rowNames"). The lower triangle, the upper triangle, or both may be given (entries present in both must agree), and every level needs a diagonal entry. This format is detected automatically, is always taken to be a precision matrix, and does not require the inverse attribute. Symmetric precision matrices are stored with one triangle only.

sigma2

Positive starting value for the single overall covariance scale of this vsm term. If NULL (the default), mmes replaces it with a data-driven starting value computed from the response and fixed effects; supplying a value here always takes precedence and is never overridden.

fixedSigma2

Logical indicating whether the product-level $\sigma^2$ is fixed at its starting value.

rotation

Logical indicating whether the supplied Gu precision matrix should be eigen-decomposed for Lee–van der Werf rotation in mmes. Rotation is opt-in and currently requires a balanced Gaussian random-effect term and a rotation-invariant residual structure (see mmes).

isFixed

Logical retained for compatibility. If TRUE, return the combined design matrix instead of the structured vsm object.

verbose

Logical controlling messages, including notification when levels present in Gu are appended to the model matrix.

Details

Let $K_1,\ldots,K_m$ be the dimensionless covariance shapes supplied by the covariance constructors. The covariance represented by one vsm term is $$\Sigma = \sigma^2(K_1 \otimes K_2 \otimes \cdots \otimes K_m).$$ For a random effect with known relationship precision Gu, the factor product determines the covariance among the crossed covariance coordinates and Gu determines the relationship structure among the levels of the final main effect.

The final argument in ... is the main-effect incidence term. Every term before it is a covariance-shaping factor. Thus vsm(dsm(location), ar1m(row), ism(genotype), Gu=Ainv) represents a location-by-row covariance shape crossed with genotype. Kronecker ordering is left to right: earlier factors are the slow index and later factors are the fast index.

All optimizer coordinates are stored on unconstrained working scales. Each CovarianceFactor descriptor also carries its evaluator, derivative strategy, reporting transformation, and trust-region caps. Built-in high-use structures may use native C++ covariance primitives, while newer or user-defined structures can use generic R callbacks without requiring changes to ai_mme_sp2.

For residual covariance models, the covariance-shaping factors must define exactly one product coordinate for each observation. mmes combines that local coordinate with an independently constructed residual block index, so a large observation-level identity design is not materialized.

When rotation=TRUE, Gu is decomposed as $$Gu=U\Lambda U',$$ where $\Lambda$ is diagonal. The aligned original precision, diagonal precision, and eigenvectors are retained in the returned descriptor. The mmes front end validates the observation layout and applies the engine-specific rotation after observation filtering. Residual covariance must satisfy $R_{(i,a),(l,b)} = c_{ab}\delta_{il}$, where $i,l$ index relationship levels and $a,b$ index rotation blocks, so that $U'RU = R$; otherwise mmes stops with an error.

Value

A list containing the random-effect design blocks in Z, the precision matrix in Gu, the flattened Kronecker descriptor in covStruct, the product design, and, for residual models, the local covariance-coordinate index. When rotation is requested, GuRot contains the diagonal precision and rotation contains its eigen metadata. The covStruct object contains descriptor version 2 CovarianceFactor objects.

Examples


####=========================================####
#### For CRAN time limitations most lines in the
#### examples are silenced with one '#' mark,
#### remove them and run the examples
####=========================================####

data(DT_example, package="enhancer")
DT <- DT_example
head(DT)


str(with(DT, vsm(dsm(Env),ism(Name))))
str(with(DT, vsm(csm(Env),ism(Name))))
str(with(DT, vsm(toeplitzm(Env),ism(Name))))

## Gu in 3-column (row, column, value) format with level names in rowNames
Ainv <- data.frame(Row=c(1,2,2,3), Column=c(1,1,2,3),
                   Ainverse=c(2,-1,2,1))
attr(Ainv, "rowNames") <- c("a","b","c")
id <- factor(c("a","b","c","a"))
str(vsm(ism(id), Gu=Ainv)$Gu)