Multivariate Random Regression of Treatment BLUPs Within Environments

Uses the G-matrix from an ASReml-R V4 model to decompose variety BLUPs into efficiency and responsiveness components within each environment, supporting four conditioning schemes via the type argument.

For any treatment $j$ with conditioning set $A_j$, the multivariate conditional normal distribution gives:

$$ \boldsymbol{\beta}_j = \boldsymbol{G}_{A_j A_j}^{-1}\, \boldsymbol{G}_{A_j j} \qquad \tilde{u}_j = u_j - \boldsymbol{\beta}_j^\top \boldsymbol{u}_{A_j} $$

The four built-in conditioning schemes differ only in how $A_j$ is chosen for each treatment:

"baseline" (default): Every non-first treatment is conditioned on levs[1] alone. Responsiveness BLUPs are orthogonal to the baseline but may be correlated with each other. The transformed G-matrix TGmat is block-diagonal.
"sequential": Treatment $j$ is conditioned on all preceding treatments levs[1:(j-1)]. This is the Gram-Schmidt orthogonalisation of the BLUPs, equivalent to the $LDL^\top$ Cholesky decomposition of the G-matrix. All components are mutually orthogonal and TGmat is diagonal, with the Schur complements on the diagonal. Treatment ordering matters.
"partial": Each treatment is conditioned on all other treatments simultaneously. The diagonal of TGmat gives the partial genetic variances; off-diagonals are generally non-zero.
"custom": The conditioning set for each treatment is specified explicitly via the cond argument.

Usage

randomRegress(
  model,
  term = "us(TSite):Variety",
  levs = NULL,
  type = "baseline",
  cond = NULL,
  sep = "-",
  pev = TRUE,
  ...
)

Arguments

model

An ASReml-R V4 model object containing a random Treatment $\times$ Site $\times$ Variety term.

term

Character string giving the full random-effect interaction term exactly as it appears in the model formula, written as "<struct>(<Group>):<Variety>". The function parses the structure keyword, group factor name, and variety factor name automatically, so the correct strings are used for predict.asreml().

Supported variance structures on the left-hand side:

us(TSite): Unstructured G-matrix — the most general form.
fa(TSite, k): Factor-analytic of order $k$.
corgh(TSite): Heterogeneous correlation — one correlation parameter shared across groups with group-specific variances.
corh(TSite): Correlation and variance structure for two-group (two-treatment-level) models.
diag(TSite): Diagonal — independent genetic variances per group, zero between-group covariances.

Supported wrappers on the right-hand side (variety factor):

vm(Variety, giv1): Genomic or pedigree relationship matrix via asreml::vm(). Only the bare factor name is used for predict.asreml().
ide(Variety): Identity-scaled term via asreml::ide().
Variety (no wrapper): Plain factor — the default.

Examples:


  term = "us(TSite):Variety"
  term = "fa(TSite, 2):Variety"
  term = "corgh(TSite):Variety"
  term = "corh(TSite):Variety"
  term = "us(TSite):vm(Variety, giv1)"
  term = "us(TSite):ide(Variety)"

levs

Character vector of length $\ge 2$ giving the treatment labels. For type = "baseline" and type = "sequential" the first element is the baseline (efficiency) treatment. For type = "partial" the ordering does not affect results. For type = "custom" the ordering determines which element of cond applies to which treatment.

type

Character string selecting the conditioning scheme. One of "baseline" (default), "sequential", "partial", or "custom". See Description for full details of each scheme.

cond

Named list required when type = "custom". Each element name must be a treatment label from levs; each element value is either NULL (treatment is unconditional / efficiency) or a character vector of treatment labels from levs that form the conditioning set. Treatments absent from cond are treated as unconditional. Example for a three-treatment sequential-style custom scheme:


  cond = list(T0 = NULL,
              T1 = "T0",
              T2 = c("T0", "T1"))

sep

Character separator used inside the composite Treatment-Site factor labels. Defaults to "-".

pev

Logical. If TRUE (default) the variance used for HSD computation is the prediction error variance (PEV) of each responsiveness BLUP. If FALSE it is the posterior variance $\sigma_{j|A_j}^2 - \text{PEV}$. Ignored for FA models (HSD is always NA).

...

Additional arguments forwarded to asreml::predict.asreml() (non-FA terms only).

Value

A named list:

blups: Data frame with columns: Site, Variety, one raw BLUP column per treatment in levs, one resp.<lev> column per conditioned treatment, and one HSD.<lev> column per conditioned treatment (Tukey's HSD on the responsiveness scale; NA for FA models or absent treatment combinations).
TGmat: Transformed G-matrix $\boldsymbol{T}\boldsymbol{G} \boldsymbol{T}^\top$. Unconditional treatments are labelled eff.<lev>; conditioned treatments are labelled resp.<lev>. Diagonal for type = "sequential".
Gmat: Original G-matrix.
beta: Named list of length equal to the number of conditioned treatments. Each element beta[["<lev>"]] is an $n_s \times |A_j|$ matrix of site-specific regression coefficients, with column names equal to the conditioning treatment labels. NA where a treatment combination is absent in a site.
sigmat: Numeric matrix of dimensions $n_s \times n_{\text{cond}}$ containing the scalar conditional genetic variances $\sigma_{j|A_j}^2$ for each conditioned treatment at each site. NA where absent.
tmat: Full transformation matrix $\boldsymbol{T}$. Lower-triangular for type = "sequential"; sparse (one non-trivial column per site) for type = "baseline"; dense for type = "partial".
cond_list: The resolved conditioning structure as a named list, one element per treatment in levs.
type: The type argument used.

Examples

if (FALSE) { # \dontrun{
## Baseline scheme — unstructured G-matrix
res_base <- randomRegress(model, term = "us(TSite):Variety",
                          levs = c("N0","N1","N2"))

## Sequential (Cholesky) — fully orthogonal components; TGmat is diagonal
res_seq  <- randomRegress(model, term = "fa(TSite, 2):Variety",
                          levs = c("N0","N1","N2"), type = "sequential")

## Heterogeneous correlation structure
res_cor  <- randomRegress(model, term = "corgh(TSite):Variety",
                          levs = c("N0","N1","N2"))

## Genomic relationship matrix (vm wrapper on Variety)
res_vm   <- randomRegress(model, term = "us(TSite):vm(Variety, giv1)",
                          levs = c("N0","N1","N2"))

## Custom conditioning
res_cust <- randomRegress(model, term = "us(TSite):Variety",
                          levs = c("N0","N1","N2"),
                          type = "custom",
                          cond = list(N0 = NULL,
                                      N1 = "N0",
                                      N2 = c("N0","N1")))
} # }

Multivariate Random Regression of Treatment BLUPs Within Environments

Usage

Arguments

Value

See also

Examples