scores_mmes: Predict factor-analytic scores from a fitted mmes model

In sommer: Solving Mixed Model Equations in R

Predict factor-analytic scores from a fitted mmes model

Description

Predicts latent factor scores for each level of the main random-effect term crossed with a fam() or rrm() covariance-shaping factor, combining the fitted loadings (see loadings_mmes), the fitted covariance matrix, and the BLUPs already stored in object$uList.

Usage

scores_mmes(object, term = NULL, method = c("regression", "bartlett"), 
            varianceScale=TRUE, rotation=TRUE)

Arguments

object	a fitted model of class "mmes".
term	character name of the random term built with a single fam() or rrm() covariance-shaping factor. If NULL, the unique such term in the model is used automatically.
method	"regression" (default) uses the full fitted covariance \Sigma (Thomson's method); "bartlett" uses only the specific (residual) variances \Psi (Bartlett's classic unbiased estimator).
varianceScale	a logical argument to indicate if loadings should be returned in variance scale (multiplied by sqrt(sigma2)).
rotation	a logical value to indicate if loadings should be rotated by its singular vectors.

Details

Let U be the levels-by-levels BLUP matrix in object$uList[[term]] and \Lambda the loadings from loadings_mmes. The regression (Thomson) scores are

F = U\Sigma^{-1}\Lambda,

and the Bartlett scores are

F = U\Psi^{-1}\Lambda(\Lambda^{\mathsf T}\Psi^{-1}\Lambda)^{-1}.

Because U already contains shrunken (BLUP) effects, the resulting scores are similarly regularized. For positive-specific FA covariances, regression uses a Woodbury contraction and a rank-by-rank solve rather than a dense trait-by-trait solve. It also works when the conditional FA engine retains only factorized covariances.

For rrm(), the covariance is singular and the specific variances are zero. Regression scores instead recover the latent BLUP coordinates using

F=U\Lambda(\Lambda^{\mathsf T}\Lambda)^{-1},

so that F\Lambda^{\mathsf T}=U. This uses the returned loading scale and rotation. Bartlett scores are undefined for this zero-specific-variance model and produce an informative error.

Value

A matrix with one row per level of the main random-effect term and one column per latent factor.

See Also

loadings_mmes, fam, rrm, vsm, mmes.

Examples

## Not run: 
mix <- mmes(BLUEs ~ trial,
            random = ~ vsm(fam(trial, 2), ism(genotype)),
            rcov = ~ units, data = dt)
scores_mmes(mix)

## End(Not run)

sommer documentation built on Oct. 25, 2026, 5:06 p.m.