Fits the same model as lmm_animal or lm_phen_cov
and returns a Gaussian approximation at the posterior mode instead of
posterior draws. It can be much faster than sampling, but has no MCMC
diagnostics: there is no Rhat, divergence count or effective sample
size, because there are no chains.
Usage
lmm_animal_laplace(
Y,
X = NULL,
A,
parametrization = c("variance", "h2"),
lkj_prior = 2,
beta_prior = c(1, 1),
blend_A = FALSE,
model_file = NULL,
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,
draws = 2000,
seed = NULL,
correlation_prior = c("lkj", "size", "shared_size"),
...
)
lm_phen_cov_laplace(
Y,
X = NULL,
lkj_prior = 2,
covariance_structure = c("unstructured", "factor"),
n_factors = NULL,
hs_global_scale = 1,
hs_slab_scale = 1,
column_decay = 0.8,
model_file = NULL,
draws = 2000,
seed = NULL,
...
)Arguments
- Y, X, A
Relationship matrix and data, as in
lmm_animal.lmm_animal_laplace()needsA;lm_phen_cov_laplace()does not take one.- 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".- 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.- blend_A
If TRUE, replace A with 0.99 * A + 0.01 * I before fitting, making singular A positive definite.
- model_file
Optional path to a custom Stan file replacing the default model.
- 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.- draws
Number of draws from the approximation used for its reported means, standard deviations and median absolute deviations. A whole number.
- seed
Optional seed for optimization and approximation draws. If omitted, a seed is drawn from R's random-number generator and recorded in the result.
- 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
- covariance_structure
Covariance structure for
lm_phen_cov_laplace, as inlm_phen_cov:"unstructured"(default) or"factor".
Value
An object of class stanimal_laplace, a list with
summarya data frame of posterior means and standard deviations for the covariance quantities the model reports, on the original data scale. Quantities are labelled with the column names ofY(andXforbeta), e.g.G[wing,tail]andh2[tail], asfit_draws()names sampler fits; an unnamedYkeeps Stan's indices (G[2,1]).drawsthe draws from the approximation, for inspection only, with the same labels.y_names,x_namesthe column names ofYandX.elapsedseconds the fit took.callthe matched call.
It is not a posterior sample and the draw-based functions refuse it. Use it to check that the sampler and a Laplace approximation find the same region, to screen many trait sets quickly, or to get a covariance when a full fit is too slow, and not to report a heritability with an interval.
Details
The approximation is Gaussian on the unconstrained parameter scale, centred on the mode, with covariance taken from the curvature there. Quantities on their reported scales are transformations of those draws. The approximation is poor wherever the posterior is skewed, and the diagonal of a covariance matrix is the first place that happens, so a standard deviation for a variance or a heritability is the least trustworthy number these functions return. In bivariate animal models with 120 individuals the means came out systematically below the sampler's, by up to 0.18 on entries of order one, because the mode sits below the mean when the posterior is skewed, and the standard deviation of the smallest variance was about 40% too wide.
Only cmdstanr can run the approximation; there is no rstan
equivalent, so the functions error when it is not installed rather than
falling back to sampling.
Optimization and CmdStan failures and warnings are surfaced; there is no
automatic retry. If the Laplace stage fails, its CmdStan output is included
in the error. The mode is written with high precision to avoid loss of
precision when CmdStan reads a correlation Cholesky factor back in.
