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 identifying individuals and parents. Columns are resolved by name using the synonyms id/animal, sire/father, and dam/mother; if none match, column 1 is id, column 2 is sire, and column 3 is dam. Unknown parents may be NA, "", or "0". Converted internally to a sparse inverse relationship matrix \(\mathbf A^{-1}\) by pedigree_to_Ainv_sparse() (Henderson/Quaas), not to a dense \(\mathbf A\). Must be passed by name (pedigree = ped). If several of pedigree, A, and Ainv are given, pedigree wins, then A, then Ainv.

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 the relatedness input. Pass one named argument: pedigree = (converted to a sparse inverse relationship matrix \(\mathbf A^{-1}\) via Henderson/Quaas), A = (dense \(n \times n\) relatedness matrix), or Ainv = (precision matrix). Sparse Ainv inputs use the sparse precision route. A positional pedigree such as animal_scalar(id, ped) is not recognised. If more than one of pedigree, A, and Ainv is supplied, the first match wins in that order.

See also

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

Examples

set.seed(1)
## Pedigree: ten founders (five sires, five dams) and 90 offspring.
ped <- data.frame(
  id   = paste0("i", 1:100),
  sire = c(rep(NA, 10), sample(paste0("i", 1:5), 90, replace = TRUE)),
  dam  = c(rep(NA, 10), sample(paste0("i", 6:10), 90, replace = TRUE))
)
A <- pedigree_to_A(ped)
## Two traits sharing one additive-genetic variance: the breeding values
## bv (individuals x traits) have vec(bv) ~ N(0, G %x% A) with G = 0.5 I.
## Residual noise is added and the data stacked one row per
## (individual, trait); the individual column also fills the `cluster`
## slot, which carries the relatedness matrix.
G <- diag(0.5, 2)
bv <- t(chol(A)) %*% matrix(rnorm(100 * 2), 100, 2) %*% chol(G)
df <- data.frame(
  individual = factor(rep(ped$id, each = 2), levels = ped$id),
  trait      = factor(rep(c("t1", "t2"), times = 100)),
  value      = as.vector(t(bv)) + rnorm(100 * 2, sd = 0.6)
)
fit <- gllvmTMB(
  value ~ 0 + trait + animal_scalar(individual, pedigree = ped),
  data = df, trait = "trait", unit = "individual",
  cluster = "individual"
)
#> Warning: ! Formula keyword `animal_scalar()` is soft-deprecated as of gllvmTMB 0.5.0
#>   (compatibility syntax).
#> ℹ The covariance grid now has three modes: `indep()`, `dep()`, `latent()`. The
#>   one-shared-variance case is `common = TRUE`.
#> → Use `animal_indep(..., common = TRUE)`; it fits the same model.
fit
#> Stacked-trait gllvmTMB fit
#>   Traits = 2, individual = 100 
#>   Covstructs: propto 
#>   Fixed effects (b_fix): 2
#>   ML log L = -253.726   convergence = 0   engine = Laplace
#>   Run gllvmTMB_diagnose(fit) for a full health check, or summary(fit) for parameter estimates.
## The recommended spelling, animal_indep(..., common = TRUE), fits the
## same model:
fit2 <- gllvmTMB(
  value ~ 0 + trait +
    animal_indep(0 + trait | individual, pedigree = ped, common = TRUE),
  data = df, trait = "trait", unit = "individual",
  cluster = "individual"
)
c(logLik(fit), logLik(fit2))
#> [1] -253.7261 -253.7261