Fits a univariate or multivariate linear mixed animal model using a known relatedness matrix
Usage
lmm_animal(
Y,
X = NULL,
A,
lkj_prior = 2,
beta_prior = c(1, 1),
parametrization = c("variance", "h2"),
iter = 3000,
warmup = floor(iter/2),
chains = 4,
cores = chains,
model_file = NULL,
control = NULL,
cmd_stan = TRUE,
blend_A = FALSE,
residual_structure = c("unstructured", "diagonal", "shared_factor"),
genetic_structure = c("unstructured", "factor"),
n_factors = NULL,
hs_global_scale = 1,
hs_slab_scale = 1,
column_decay = 0.8,
eigen_A = NULL,
correlation_prior = c("lkj", "size", "shared_size"),
...
)Arguments
- Y
response variable, univariate or multivariate. Every trait must vary: constant traits cannot be standardized and are an error. Missing values (
NA) are allowed and are not discarded: see Details.- X
Optional finite numeric fixed-effects matrix with the same rows as Y and full column rank. The default
NULLfits an intercept-only model: one column of ones, named"(Intercept)". A matrix must be able to represent a constant (an intercept column, or the 0/1 indicators of every level of a factor), so that the mean of the response can be reported. Continuous columns are centered and scaled internally; returned beta draws use original X units.- A
Finite symmetric positive-definite relationship matrix matching the rows of Y. A matrix that is only positive semidefinite (duplicated individuals, for example) is rejected; set
blend_A = TRUEto regularize it. WhenAandYboth have row names, they are used to putAin the order ofY; names that disagree are an error. Without names the rows are matched by position.- lkj_prior
Positive shape parameter of the LKJ prior.
1is uniform over correlation matrices, not over each pairwise correlation: their marginal distribution concentrates increasingly around zero as dimension increases. Larger shapes add shrinkage toward zero. For multivariate models it applies to unstructuredG, including with diagonalE, and to unstructuredE, including with factorG. It is unused for factorGwith diagonalE, shared-factor and univariate models; explicitly supplying it there warns.- beta_prior
Parameters of the beta prior on h2. Used by the univariate model with
parametrization = "h2", by the unstructured multivariate model withparametrization = "h2", by the ordinary factor model for the trait heritabilities, and by the shared-factor model for the factor heritabilities. The defaultc(1, 1)is flat on h2 and on each factor heritability. It is validated for every model; explicitly supplying it where it is not used warns that it is ignored.- parametrization
Which parameters carry the prior.
"variance"(default) estimates the genetic and residual standard deviations with half-normal priors and derives h2."h2"estimates a phenotypic standard deviation and a heritability per trait, and puts the beta prior (beta_prior) on h2. It is available for the univariate models and for the unstructured multivariate model, and the two differ only in the prior they imply on h2: because the response is standardized trait by trait, \(s_G^2 + s_E^2\) is the phenotypic variance, so the half-normal priors of"variance"are priors on a circle and they induce \(p(h^2) \propto 1/\sqrt{h^2(1-h^2)}\), a density whose mass sits at the two ends. The two parameterizations agree when the data are informative and separate when they are not, so prefer"h2"when there are few individuals relative to the number of traits, when h2 is the object of inference rather thanG, or when a"variance"fit puts its heritabilities against 0 or 1. No sample-size threshold has been validated, so treat that as a reason to check rather than a rule. The ordinary factor model has no switch: its scales are locked to the phenotypic scale and it always puts the beta prior on the trait heritabilities. Supplying this argument for the factor or shared-factor model warns that it is ignored, and a univariate"variance"fit with low E-BFMI already warns and suggests"h2".- iter
Number of MCMC iterations, a whole number.
- warmup
Number of warmup iterations, a whole number smaller than
iter.- chains
Number of chains to run, a whole number.
- cores
Number of chains to run in parallel (cmdstanr only), a whole number.
- model_file
Optional path to a custom Stan file replacing the default model.
- control
Named list of sampler controls, passed to whichever engine runs:
adapt_delta,adapt_engaged,max_treedepth,step_size(rstan'sstepsizeis accepted),init_buffer,term_buffer,windowandmetric. Any other name is an error, so a control is never silently ignored. The defaultNULLuseslist(adapt_delta = 0.9)forgenetic_structure = "factor"with an unstructured or diagonal residual, andlist(adapt_delta = 0.99)otherwise: unstructuredGon small samples and shared-factor fits diverge at 0.9. A list you supply replaces the default entirely.- cmd_stan
Logical, use cmdstanr. If FALSE, uses rstan. Both engines are suggested packages: when cmdstanr is not installed the fit falls back to rstan with a warning, and when neither is installed the fit errors.
- blend_A
If TRUE, replace A with 0.99 * A + 0.01 * I before fitting, making singular A positive definite.
- residual_structure
Residual covariance for multivariate fits: "unstructured" (default, full covariance between traits), "diagonal", or "shared_factor". With a diagonal residual, environmental covariances between traits are absorbed into the genetic covariance and inflate heritability, so "unstructured" is recommended when estimating G without a factor model. "shared_factor" requires
genetic_structure = "factor"and fits the shared-factor model \(G = \Lambda \mathrm{diag}(h^2_\text{factor}) \Lambda^T + \Psi_G\), \(E = \Lambda \mathrm{diag}(1 - h^2_\text{factor}) \Lambda^T + \Psi_E\), so the same latent factors explain genetic and residual covariance and each factor has a heritability.- genetic_structure
Genetic covariance for multivariate fits: "unstructured" (default, direct scales and LKJ correlation) or "factor", which uses the sparse factor model \(G = \mathrm{diag}(s_G)(\Lambda\Lambda^T + \Psi)\mathrm{diag}(s_G)\) on the correlation scale. The factor model gives loadings regularized-horseshoe priors for automatic shrinkage; loadings are not exactly zero. The ordinary factor model reports
loadings,factor_magnitude,uniqueness,communalityands_G. Withresidual_structure = "shared_factor"the same loadings also structure E, and the fit reportsloadings,factor_magnitude,factor_heritability,genetic_uniqueness,residual_uniqueness,uniquenessandcommunality. It is available only for multivariate fits and is not compatible withmodel_file.- n_factors
Number of factors when
genetic_structure = "factor"; forresidual_structure = "shared_factor"these are shared byGandE. It is a whole number between 1 and the number of traits minus one. IfNULL, the factor model falls back tomin(K - 1, max(2, floor(sqrt(K))), 20)and warns with the value; that fallback depends only on the number of traits, so usesuggest_n_factorsto choose it from the data when the factors themselves are meant to be interpreted. Ignored otherwise.- hs_global_scale, hs_slab_scale
Positive scales of the regularized-horseshoe prior on factor loadings: the global half-Cauchy scale and the slab scale, which limits the loading's prior standard deviation rather than bounding its realized value. For ordinary factor G, communality is \(q/(1+q)\), where \(q\) is the random sum of squared unnormalized loadings. Its prior distribution depends on both scales, the local scales, the number of factors and column decay; it is not determined by the slab alone. The shared-factor model does not row-normalize its loadings, so its communality is a sum of squares on the standardized response scale, not a correlation-scale proportion. Report the settings, especially where data are weak. These arguments are only used by
genetic_structure = "factor"; explicitly supplying them elsewhere warns. See Piironen and Vehtari (2017) on choosing the global scale.- column_decay
Standard-deviation multiplier for successive factor columns, between 0 and 1. Column
mis multiplied bycolumn_decay^(m - 1), so values below 1 favour decreasing factor magnitudes and make the factor labels interpretable. The default 0.8 orders the columns without forcing a strict hierarchy; withcolumn_decay = 1the columns are exchangeable a priori and their labels are free to swap between chains. How strong the decay needs to be depends on how many columns have to be told apart: with two columns of comparable size 0.8 is often too mild and 0.5 is what separates them, while a strong decay works against a model with many columns, because0.5^(m - 1)cuts the prior of the fifth column to a sixteenth of the first. This is a deterministic prior on the column order, not a learned decay parameter; it is used by both factor structures, including the shared-factor model. Explicitly supplying it outsidegenetic_structure = "factor"warns that it is ignored.- eigen_A
Optional eigendecomposition of
A, a list with elementsQ(the \(N \times N\) orthonormal eigenvectors, as columns) andlambda(theNmatching eigenvalues), for examplee <- eigen(A, symmetric = TRUE); list(Q = e$vectors, lambda = e$values). The models never decomposeAthemselves: withouteigen_Ait is decomposed once per fit in R. Supplying it skips that step, so a caller that fits many models on the same relationship matrix (one per trait subset, say) pays theO(N^3)decomposition once. It must be the decomposition ofAin the row order ofAas passed; rows are reordered along withAwhenAandYare matched by name, andblend_Ais applied to the eigenvalues. Eigenvalues and eigenvectors need only be consistently paired, not in any particular order, though the order sets the order of the rotated records thatlog_likrefers to. The pair is checked againstA(reconstruction and orthonormality, on two probe vectors) before fitting. Works with every structure and parametrization.- correlation_prior
Prior on the genetic and residual correlation matrices of the unstructured multivariate model.
"lkj"(default) is LKJ(lkj_prior), which shrinks every correlation toward zero."size"writes each correlation matrix as one dense size factor plus an LKJ remainder, \(\Omega = D(ll^T + R)D\) with \(R \sim\) LKJ(lkj_prior) and \(D\) the row normalisation, and estimates where the correlations are shrunk to: the size loadings \(l_k = \mu + \sigma z_k\) are pooled around a mean loading with \(\rho = \mu^2/(1+\mu^2) \sim\) Beta(1, 1), \(\sigma \sim\) half-normal(0, 1) and \(z_k \sim N(0, 1)\).GandEeach get their own."shared_size"is the same with one standardized pattern \(z\) shared byGandE, so the genetic and residual size axes deviate from equal loadings in the same direction, each with its own mean loading and spread; it needsresidual_structure = "unstructured". Neither lowers the rank: the factor moves the point the prior shrinks toward, and with \(\rho = \sigma = 0\) the prior is the LKJ one. Use them for traits that share a size axis (many measurements of one structure), where LKJ pulls large correlations, and with them the heritabilities, toward zero. Both needgenetic_structure = "unstructured", cannot be combined withmodel_file, and useparametrization = "h2": leavingparametrizationunset selects it, and asking for"variance"is an error. The fits addrho_G,rho_E,sigma_size_G,sigma_size_E, the size loadings on the correlation scalesize_loadings_Gandsize_loadings_E, andintegration_Gandintegration_E, the relative eigenvalue variance of each correlation matrix (0 for no correlation, 1 for a single axis). Sampling is slower than with"lkj", about three times in the tests.- ...
additional parameters for stan sampling
Value
With cmd_stan = TRUE, a CmdStanMCMC object from cmdstanr: use fit$draws() (a posterior draws array) and fit$summary(), and pass these, or the fit itself, to bayesplot (e.g. bayesplot::mcmc_trace(fit$draws("h2")), bayesplot::nuts_params(fit)). Fixed effects are beta[j] (univariate) or beta[trait,j] for column j of X; use rename_beta to get draws named after the columns of X. Use fit_draws to reshape the draws into trait by trait by draw arrays, and draws_mean or draws_quantile for posterior summaries that are already matrices. Factor fits also expose loadings, factor_magnitude, uniqueness and communality; shared-factor fits add factor_heritability, genetic_uniqueness and residual_uniqueness. With cmd_stan = FALSE, a stanfit object whose beta draws are named after the columns of X.
Multivariate fits report G, E, P = G + E, corrG,
sigma_G, sigma_E and h2 = diag(G) / diag(P), plus the
fixed effects beta[trait, j].
Every fit reports log_lik, one term per rotated response record. For
complete data the terms sum to the joint log density, but leave-one-out over
rotated records is not generally leave-one-individual-out. Comparisons need
the same response and predictive units, including the same relationship
matrix and eigenbasis. With missing responses the terms use the completed
data rather than the marginalized observed-data likelihood, so
fit_loo refuses these fits.
Factor fits add quantities that describe the factor decomposition. They come
in two groups. communality, uniqueness and
factor_heritability do not depend on how the factors are oriented, so
the data identify them and their Rhat and effective sample size are
read like any other parameter. loadings and factor_magnitude
do depend on it: two solutions with the same G can differ by a
rotation, a sign flip or a permutation of the columns, and nothing fixes that
choice except the prior. A poor Rhat on those two is therefore not
evidence that the fit failed, and their posterior means describe whichever
orientations the chains visited. Judge convergence on G, E,
P, corrG, communality and uniqueness, and pin
the orientation down by lowering column_decay, which orders the
columns, or by asking for fewer factors.
loadings: the trait by factor loading matrix \(\Lambda\). For the ordinary factor model these are on the correlation scale; for shared-factor fits they are on the standardized phenotype scale.communality: for trait \(k\), \(c_k = \sum_m \lambda_{km}^2\). This is the part of the trait's variance explained by the common factors. In the ordinary factor model it is on the correlation scale, so \(c_k + u_k = 1\); multiplying by \(s_{Gk}^2\) gives the common genetic variance of trait \(k\). In shared-factor fits it is the common phenotypic variance, and \(c_k + u_k\) equals the trait's standardized phenotypic variance.uniqueness: for trait \(k\), the trait-specific variance left after the factors. In the ordinary factor model \(u_k = 1 - c_k\) is the unique genetic variance on the correlation scale; multiply by \(s_{Gk}^2\) for the unique genetic variance. In shared-factor fits \(u_k = \psi_{Gk} + \psi_{Ek}\), withgenetic_uniqueness\(\psi_{Gk}\) andresidual_uniqueness\(\psi_{Ek}\) giving the two parts.factor_magnitude: for factor \(m\), \(\sum_k \lambda_{km}^2\), the variance the factor contributes across traits. It is a factor-level summary, not a per-trait quantity. Ranking the columns only means something once the orientation is fixed, bycolumn_decayor by ann_factorssmall enough to leave the factors identified.factor_heritability: shared-factor fits only. For factor \(m\), \(h^2_m\) is the fraction of that factor's variance that is genetic: the genetic part is multiplied by \(h^2_m\) and the residual part by \(1-h^2_m\).s_G: the genetic standard deviation of each trait on the standardized response scale, which is the diagonal scale that moves the correlation-scale decomposition to the original scale; multiplying it by the response standard deviation gives the genetic standard deviationssigma_Gon the data scale. It is reported by every multivariate fit except the shared-factor model, which scales its factors bysqrt_psi_Gandsqrt_psi_Einstead. In the ordinary factor model it is derived fromh2ands_P.
These are available from fit$summary() and from
fit_draws. The latter returns loadings as a trait by
factor by draw array, factor_heritability and
factor_magnitude as factor by draw matrices, and the uniqueness and
communality vectors as trait by draw matrices.
Details
By default the models estimate the additive genetic and residual standard deviations (sigma_G, sigma_E) directly, with half-normal priors on the standardized response scale, and report h2 as a derived quantity. With parametrization = "h2", and always in the ordinary factor model, the two scales are written as \(s_G = \sqrt{h^2}s_P\) and \(s_E = \sqrt{1-h^2}s_P\) instead, so beta_prior is a prior on the trait heritabilities and \(s_P\) is the phenotypic scale. The multivariate model estimates the additive genetic covariance matrix G and the residual covariance E directly, each as scales times an LKJ-distributed correlation matrix (lkj_prior), with half-normal priors on the scales of the standardized responses. With genetic_structure = "factor", G is instead \(\mathrm{diag}(s_G)(\Lambda\Lambda^T + \Psi)\mathrm{diag}(s_G)\), where the loadings \(\Lambda\) have regularized-horseshoe priors and \(\Psi\) is diagonal on the correlation scale; the default global shrinkage is hs_global_scale = 1. With residual_structure = "shared_factor", the same loadings enter both covariances: \(G = \Lambda\mathrm{diag}(h^2_\text{factor})\Lambda^T + \mathrm{diag}(\psi_G)\) and \(E = \Lambda\mathrm{diag}(1 - h^2_\text{factor})\Lambda^T + \mathrm{diag}(\psi_E)\), with the beta prior on the factor heritabilities controlled by beta_prior. The optional column_decay multiplies the prior standard deviation of factor column \(m\) by column_decay^(m - 1), which favours factors in decreasing order without adding a learned decay parameter. Breeding values are marginalized using the eigendecomposition of A: the response and the design are rotated by its eigenvectors and the likelihood is computed on the rotated records, with the eigenvalues entering through the per-record covariance. No per-individual random effects are needed, which is why a singular A can be fitted once it is regularized with blend_A = TRUE. Returned quantities (original response scale) are G, E, P = G + E, corrG, sigma_G, sigma_E and h2 = diag(G) / diag(P).
With parametrization = "h2", and always in the ordinary factor model, the scales are written as a phenotypic scale and a heritability rather than as two standard deviations, because the response is standardized trait by trait and the two scales are tied to its variance. That makes \(s_G^2 + s_E^2\) the phenotypic variance of the trait and fixes it near 1, so half-normal priors on \(s_G\) and on \(s_E\) are priors on a circle. The density they induce on \(h^2\) is proportional to \(1/\sqrt{h^2(1-h^2)}\), an arcsine prior that puts about 14 percent of its mass below 0.05 and 14 percent above 0.95, which makes a moderate heritability the least likely answer a priori. With few individuals the likelihood is weak enough for that to show through, and a fit can then sit at either end of the interval. Writing the scales as \(s_G = \sqrt{h^2}s_P\) and \(s_E = \sqrt{1-h^2}s_P\) puts beta_prior on \(h^2\) directly, so the prior applied is the one that was asked for, and \(s_P\) is the well-determined quantity that is left.
The per-individual likelihoods are whitened by the residual Cholesky factor and rotated into a single eigendecomposition of E^{-1/2} G E^{-1/2}, so each evaluation costs O(N K^2 + K^3) rather than O(N K^3). This lets the multivariate model scale to dozens of traits without a Cholesky factorization per individual. When the eigenvalues of that matrix are nearly coincident (for example at initialization, or when G is roughly proportional to E) the model automatically falls back to a per-individual Cholesky evaluation, which has a well-behaved gradient.
The cost that grows with the number of individuals is the dense relationship matrix: A is passed in full and each chain eigendecomposes it before sampling (O(N^3) time and O(N^2) memory per chain). That cost is paid once, so with many traits sampling dominates and the decomposition is a small share of the fit, while with few traits and short runs it can be most of it. The models are intended for many traits on hundreds to a few thousand individuals. For cohorts of tens of thousands, where that matrix is the bottleneck, an engine that uses the sparse inverse of A (such as ASReml) is the better tool.
Incomplete records are used rather than dropped. A missing value is not
discarded, because with relatedness it carries information: the value is
informed by every relative's observed traits. The gaps are filled by
parameters on the standardized response scale, drawn with the rest of the
model and reported as Y_mis, and a flat prior on them makes the
posterior over the other parameters the exact marginal over the observed
data. Each gap is one parameter, so the cost grows with the number of gaps;
a record with nothing observed is allowed, since its relatives still inform
it. Dropping incomplete rows instead is the alternative, and it throws away
the rows that are complete for the other traits.
Two configurations are worth avoiding when many values are missing. A
residual_structure = "diagonal" model with a small sample is weakly
identified once gaps loosen the residual structure, and can mix badly:
prefer "unstructured", which is the default and what the missing-data
machinery is tested against. For fits with gaps, log_lik uses the
completed response including imputation parameters, not the marginalized
observed-data likelihood; fit_loo refuses LOO and WAIC for
these fits. Raw log_lik draws remain available, but are not an
observed-data predictive criterion.
The LKJ shape lkj_prior (default 2) deliberately shrinks correlations toward zero. With many traits, an unstructured correlation matrix fit under a flat prior tends to overestimate the magnitude of correlations, especially genetic correlations between traits with limited information, so a shape above 1 acts as a mild regularizer; increase it for stronger shrinkage. Note that fitting many traits remains expensive: the likelihood is cheap, but an unstructured G for K = 40 traits has on the order of 1700 parameters and NUTS needs many leapfrog steps, so a single fit can take an hour or more. Fewer iterations, a larger lkj_prior, or residual_structure = "diagonal" all make fits faster.
Continuous predictors are centered and divided by their sample standard deviation inside Stan. Constant and 0/1 indicator columns are not centered or scaled. Standardized slopes have normal(0, 1) priors; the intercept contribution has a wider normal(0, 2.5) prior. Returned beta coefficients are backtransformed to original predictor and response units, including restoring the response mean to the intercept; beta_scaled draws are also available.
Examples
if (FALSE) { # \dontrun{
set.seed(1)
n <- 40
ped <- data.frame(
id = 1:n,
sire = c(rep(NA, 20), sample(1:10, 20, replace = TRUE)),
dam = c(rep(NA, 20), sample(11:20, 20, replace = TRUE))
)
A <- makeA(ped)
X <- cbind(Intercept = 1, sex = rbinom(n, 1, 0.5))
G <- random_covariance(2, min_var = 0.8, max_var = 1.2,
trait_names = c("t1", "t2"))
E <- random_covariance(2, min_var = 0.8, max_var = 1.2,
trait_names = c("t1", "t2"))
Y <- X %*% rbind(c(10, 9), c(1, -0.5)) +
t(chol(A)) %*% matrix(rnorm(n * 2), n) %*% chol(G) +
matrix(rnorm(n * 2), n) %*% chol(E)
colnames(Y) <- c("t1", "t2")
fit <- lmm_animal(Y, X, A, iter = 1000, warmup = 500,
chains = 2, cores = 2, refresh = 0)
fit$summary(c("G", "E", "h2"))
round(draws_mean(fit, "G"), 2)
# Univariate model with the h2 parametrization
fit_h2 <- lmm_animal(Y[, 1], X, A, parametrization = "h2",
iter = 1000, warmup = 500,
chains = 2, cores = 2)
# Sparse factor G
factor_fit <- lmm_animal(Y, X, A, genetic_structure = "factor",
n_factors = 1, iter = 1000, warmup = 500,
chains = 2, cores = 2)
factor_fit$summary(c("loadings", "factor_magnitude"))
dim(fit_draws(factor_fit)$loadings)
# Shared factors for G and E
shared_fit <- lmm_animal(Y, X, A, genetic_structure = "factor",
residual_structure = "shared_factor",
n_factors = 1, iter = 1000, warmup = 500,
chains = 2, cores = 2)
shared_fit$summary(c("factor_heritability", "genetic_uniqueness"))
} # }
