Skip to contents

Single-shared-variance animal-model random effect: animal_scalar(id)

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

Canonical name for the single-scalar (per-trait) animal-model random intercept. Each trait carries an independent length-n_ids draw \(\mathbf p_t \sim \mathcal{N}(\mathbf{0}, \sigma^{2}_{\text{a}}\,\mathbf{A})\) where \(\mathbf A\) is the additive genetic relatedness matrix (the pedigree-derived numerator-relationship matrix). The variance \(\sigma^{2}_{\text{a}}\) is shared across traits.

Usage

animal_scalar(id, pedigree = NULL, A = NULL, Ainv = NULL)

Arguments

id

Bare column name of the individual factor.

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.

Value

Used inside a gllvmTMB() formula. Returns invisible(NULL) when called outside a formula – the keyword is a syntactic marker that the parser rewrites internally to the canonical phylo_scalar() path (which is family-agnostic at the math level).

Details

Mathematical parallel to phylo_scalar() – same engine path; the only difference is that A is supplied via pedigree = (a 3-column data frame: id, sire, dam), A = (dense \(n \times n\) relatedness matrix), or Ainv = (precision matrix). Sparse Ainv inputs use the sparse precision route.

See also

animal_indep(), animal_latent(), animal_dep(), animal_slope(), phylo_scalar(), meta_V() (sampling variance, distinct from relatedness).

Examples

if (FALSE) { # \dontrun{
# Pedigree-derived additive-genetic relatedness; single shared
# variance across traits. 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_scalar(species, pedigree = ped),
  data = df, family = gaussian()
)
} # }