Animal-model structured-effect marker

animal() marks pedigree or additive-relatedness animal-model syntax. It is the biological front door for questions such as whether among-individual additive genetic variance appears in the location mu, residual scale sigma, shape or skewness, inflation, or a bivariate covariance. The fitted routes are univariate Gaussian mu and sigma random intercepts from a small pedigree data frame, precomputed additive relationship matrix A, or inverse relationship matrix Ainv, for example animal(1 | id, pedigree = pedigree) or animal(1 | id, Ainv = Ainv). Matching univariate mu and sigma intercept terms estimate one animal-model mean-scale correlation. The first bivariate Gaussian q=2 location covariance comes from matching labelled terms in mu1 and mu2, and the constant all-four q=4 location-scale block comes from matching labelled terms in mu1, mu2, sigma1, and sigma2, for example animal(1 | p | id, pedigree = pedigree). The pedigree route builds a dense additive relationship matrix from id, dam, and sire columns. The univariate Gaussian mu path also supports one numeric slope, for example animal(1 + x | id, pedigree = pedigree), as independent intercept and slope fields with separate SDs and no intercept-slope correlation. Large-pedigree sparse precision construction, multiple structured slopes, slope correlations, predictor-dependent corpair() regression, residual-scale structured slopes, and animal-model sd*() direct-SD grammar remain planned.

Usage

animal(term, pedigree = NULL, A = NULL, Ainv = NULL)

Arguments

term

Structured random-effect term, such as 1 | id or 1 + x | id.

pedigree

Pedigree data frame with columns id, dam, and sire. Unknown parents can be NA, "", or "0". The first fitted route builds a dense additive relationship matrix for Gaussian mu animal effects.

A

Additive relatedness or covariance matrix for the first fitted univariate Gaussian mu path.

Ainv

Sparse or dense inverse additive relatedness matrix for the first fitted univariate Gaussian mu path.

Value

A formula marker; never evaluated by users.

Examples

# Fitted: additive genetic variance in body size from a precomputed Ainv.
bf(body_size ~ age + sex + animal(1 | id, Ainv = Ainv),
  sigma ~ habitat
)
#> <drm_formula>
#> body_size ~ age + sex + animal(1 | id, Ainv = Ainv)
#> sigma ~ habitat

# Fitted: the same route can build a small additive matrix from a pedigree.
bf(activity ~ treatment + animal(1 | id, pedigree = pedigree),
  sigma ~ treatment
)
#> <drm_formula>
#> activity ~ treatment + animal(1 | id, pedigree = pedigree)
#> sigma ~ treatment