fam: Factor-analytic covariance structure

In sommer: Solving Mixed Model Equations in R

Factor-analytic covariance structure

Description

Factor-analytic covariance structure. The returned dimensionless covariance shape is intended for use inside vsm, which supplies the single overall variance scale.

Usage

fam(x, k = 1L, loadings = NULL, specific = NULL, fixed = NULL,
    variance = c("heterogeneous", "homogeneous"), shared = NULL)

Arguments

x	Variable defining q covariance levels.
k	Factor-analytic rank, satisfying 1 <= k < q.
loadings	Optional finite q by k starting loading matrix.
specific	Optional q positive starting specific variances. With variance="homogeneous", supply either one positive value or q equal values. The default is 0.5 for every level.
fixed	Logical vector controlling all loading and specific-variance-ratio parameters.
variance	Whether to estimate separate specific variances for each level ("heterogeneous", the default) or a common specific variance ("homogeneous").
shared	Optional non-empty loading-group name. Matching names on the single random and residual FA terms request common trait loadings with source-specific diagonal factor variances. Requires mmes_control(representation=list(equations="conditional")) for AI, or conditional EM through update=list(method="em") with that representation. The earlier update=list(method="conditional-fa") selector still selects EM. Ordinary equations reject shared tags rather than fitting independent loadings.

Details

The factor-analytic shape is based on

M=\Lambda\Lambda^{\mathsf T}+\Psi,

where \Psi is diagonal positive, followed by K=M/M_{11}. For rotational identification, the leading k\times k loading block is lower triangular and its diagonal loadings are positive. The first specific variance is an internal reference; remaining specific variances are positive ratios. This removes the otherwise redundant internal scale because vsm supplies the overall \sigma^2.

With variance="heterogeneous", fixed has length qk-k(k-1)/2+q-1: triangular loadings followed by q-1 specific-variance ratios. With variance="homogeneous", all specific ratios are one, \Psi=I_q internally, and fixed has length qk-k(k-1)/2. The common specific variance on the fitted scale is estimated, not fixed at one, and is reported as common_specific_variance. This homogeneous model reproduces the covariance family previously fitted by rrm(). For a genuine reduced-rank model with all specific variances fixed at zero, use rrm.

With matching shared groups, the conditional engine fits G=L D_g L^\mathsf{T}+\Psi_g and R=L D_e L^\mathsf{T}+\Psi_e, with diagonal positive factor variances normalized to D_g+D_e=I. Both sources must be entirely free and have the same trait levels and rank. Starting loading columns, after applying each term's variance scale, must be positive scalar multiples across sources. The common loading matrix and factor variance allocations are returned in fit$conditionalFA$state. Marginal loading reports use independent triangular rotations of each source, not the common basis.

Value

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

See Also

rrm, usm, vsm.

Examples

## Not run: 
vsm(fam(environment, k=2), ism(genotype))
vsm(fam(environment, k=2, variance="homogeneous"), ism(genotype))

## End(Not run)

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