Skip to contents

Reduced-rank animal-model latent factors: animal_latent(id, d = K)

Source: R/animal-keyword.R
animal_latent.Rd

Reduced-rank decomposition of the additive-genetic covariance matrix using \(K\) latent factors. Set unique = TRUE to add a per-trait diagonal \(\boldsymbol\Psi\) companion: \(\boldsymbol G = \boldsymbol\Lambda \boldsymbol\Lambda^\top + \boldsymbol\Psi\) with \(\boldsymbol\Lambda\) a \(T \times K\) loadings matrix (\(T\) = number of traits, \(K \le T\)). The latent factors and diagonal companion both carry the same \(\mathbf A\) structure across individuals.

Usage

animal_latent(
  id,
  d = 1,
  pedigree = NULL,
  A = NULL,
  Ainv = NULL,
  unique = FALSE
)

Arguments

id

Bare column name of the individual factor.

d

Number of latent factors (\(K \le T\)). Default 1.

pedigree

A 3-column data frame with columns id, sire, dam (unknown parents encoded as NA). Converted internally to A via Henderson's recursive formula. Only one of pedigree, A, or Ainv should be given.

A

Dense relatedness matrix (\(n \times n\)); rownames / colnames must match levels of id.

Ainv

Precision matrix (inverse of A). Sparse matrix inputs are preserved for the sparse engine route.

unique

Logical; when TRUE, include the per-trait diagonal additive-genetic \(\boldsymbol\Psi\) companion. The default FALSE preserves the loadings-only subset.

Value

See animal_scalar().

Details

This is the canonical "factor-analytic G-matrix" model from quantitative genetics (Kirkpatrick & Meyer 2004; Meyer 2009; the WOMBAT method). Mathematical parallel to phylo_latent() – same engine path with a pedigree-derived relatedness matrix instead of phylogenetic VCV.

See also

animal_scalar(), animal_indep(), phylo_latent().

Examples

if (FALSE) { # \dontrun{
# Factor-analytic G-matrix (d latent factors plus diagonal Psi).
# Grounded in test-animal-keyword.R.
ped <- data.frame(
  id   = paste0("i", 1:12),
  sire = c(rep(NA, 4), rep(c("i1", "i2"), length.out = 8)),
  dam  = c(rep(NA, 4), rep(c("i3", "i4"), length.out = 8))
)
A <- pedigree_to_A(ped)
yvec <- as.numeric(MASS::mvrnorm(
  1, mu = rep(0, 2 * 12),
  Sigma = kronecker(diag(2), A) * 0.5 + diag(2 * 12) * 0.5
))
df <- data.frame(
  species = factor(rep(ped$id, each = 2), levels = ped$id),
  trait   = factor(rep(c("t1", "t2"), times = 12), levels = c("t1", "t2")),
  value   = yvec
)
fit <- gllvmTMB(
  value ~ 0 + trait + animal_latent(species, d = 1, pedigree = ped,
                                   unique = TRUE),
  data = df, family = gaussian()
)
} # }