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,
  rho = 1
)

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.

rho

Source strength: a number in [0,1] fixes rho * K + (1-rho) * diag(diag(K)) on the legacy-resolved source scale. Omitted or explicit 1 preserves the existing model. NULL estimates strength for one Gaussian structured trait-intercept block with complete replicated multivariate observations and no competing ordinary covariance. Estimated latent terms require rank one and at least four traits. The same strength applies to the entire latent-plus-Psi covariance. This parameter is not a variance-share summary. Fixed attenuation and the admitted Gaussian estimator have implementation checks; recovery is regime-specific.

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, unit = "species", family = gaussian()
)
} # }