dsumm: Direct sum of residual covariance structures across sections

In sommer: Solving Mixed Model Equations in R

Direct sum of residual covariance structures across sections

Description

dsumm replicates a residual vsm structure independently for every level (section) of a grouping variable, such as a trial, location, or experiment. Each section receives its own variance and its own copy of every covariance parameter of the inner structure.

Usage

dsumm(x, by, levels = NULL)

Arguments

x	A residual vsm() term, for example vsm(ar1m(range), ar1m(row), ism(units)). Its covariance-shaping factors define the structure fitted within each section.
by	Observation-level grouping variable defining the sections. Missing values of by exclude the observation.
levels	Optional character vector of by levels that receive the structured covariance of x. All other levels receive an independent and identically distributed residual with their own variance. The default NULL applies the structure to every level.

Details

Direct sum versus Kronecker product. A vsm() term is a Kronecker product with a single overall variance. Including a diagonal section factor,

\mathrm{vsm}(\mathrm{dsm}(t), \mathrm{ar1m}(r), \mathrm{ar1m}(c), \mathrm{ism}(units)):\quad R = \sigma^2\, D_t \otimes K_r(\rho_r) \otimes K_c(\rho_c),

gives each section its own variance, but a single correlation shared by all sections, because each factor of a Kronecker product appears only once. In contrast, dsumm builds the block-diagonal direct sum

R = \bigoplus_{t} \sigma^2_t\, K_r(\rho_{r,t}) \otimes K_c(\rho_{c,t}),

so every section has its own variance and its own correlations. Sections are mutually independent, so their parameters are estimated only from their own observations; with section-specific fixed effects the joint fit reproduces separate per-section fits.

Choosing between the two. Use the vsm() form when trials are small or similar and a common spatial correlation is adequate (fewer parameters). Use dsumm when correlations are expected to differ between trials. With T sections and p inner covariance parameters, dsumm estimates T(p+1) residual parameters.

Unlisted levels. Levels omitted from levels are modelled as \sigma^2_t I. Their observations are retained even when the variables of the inner structure (for example row or range) are missing, so trials without spatial coordinates can be analysed together with spatially designed trials.

Computation. Each section is embedded in the rectangle spanned by its observed levels of the inner factors. Covariance applications use the small factor inverses, and missing cells (e.g. plots with a missing response) are absorbed exactly by a Schur complement, so the dense observation-level covariance matrix is never formed. This requires sections that are close to complete rectangles and no W weights.

Reporting. covparams_mmes returns one row per parameter and section, with the section in the section column. The variance rows belong to the by factor; correlation rows are labelled by their inner factor, e.g. ar1m(range).

Value

A residual covariance structure, in the same form as a residual vsm() term, for use in the rcov argument of mmes.

Limitations

dsumm is currently available only for residual (rcov) structures, without W weights, and cannot be nested.

See Also

vsm, ar1m, dsm, mmes, covparams_mmes.

Examples

## Not run: 

mix <- mmes(yield ~ trial,
            rcov = ~ dsumm(vsm(ar1m(range), ar1m(row), ism(units)), by = trial),
            data = dat)
covparams_mmes(mix)

# Spatial structure only for two trials; remaining trials are iid.
mix2 <- mmes(yield ~ trial,
             rcov = ~ dsumm(vsm(ar1m(range), ar1m(row), ism(units)),
                            by = trial, levels = c("T1", "T2")),
             data = dat)

# Site-specific unstructured covariance among environments.
mix3 <- mmes(y ~ site,
             rcov = ~ dsumm(vsm(usm(env), ism(units)), by = site),
             data = dat2)

## End(Not run)

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