relmat() marks syntax for a validated user-supplied relatedness matrix. It
is the lower-level route for latent group-level dependence structures that
are not best named as animal(), phylo(), or spatial(): for example a
genomic relationship matrix, a laboratory relatedness kernel, or a graph,
river-network, areal, or Gaussian Markov random-field precision matrix built
outside drmTMB and checked by the analyst. If the matrix is known sampling
covariance among observed estimates, use meta_V() instead.
Arguments
- term
Structured random-effect term, such as
1 | idor1 + x | id.- K
Known relatedness or covariance matrix for the documented fitted univariate and bivariate routes.
- Q
Known precision or inverse covariance matrix for the documented fitted routes. The exact bivariate REML exception requires
K; bivariateQremains available under ML.
Details
Use K for a covariance or relatedness matrix and Q for an inverse
covariance or precision matrix. A correlation matrix with diagonal 1 is a
natural K input because the fitted relatedness SD supplies the latent
variance scale. The fitted known-matrix routes are a univariate Gaussian
mu random intercept, for example
relmat(1 | line, Q = Q), the first bivariate Gaussian q=2 location
covariance from matching labelled terms in mu1 and mu2, matching
univariate Gaussian mu and sigma intercept terms estimate one
relatedness mean-scale correlation, and the constant all-four q=4
location-scale block comes from matching labelled terms in mu1, mu2,
sigma1, and sigma2, for example relmat(1 | p | line, Q = Q). The exact
bivariate Gaussian REML exception requires matching labelled
relmat(1 | p | line, K = K) location intercepts in mu1 and mu2, the
same named supplied covariance K, intercept-only residual formulas,
complete pairs, unit weights, and no additional model layer. This exception
has point-estimate recovery evidence only; bivariate Q, slopes, models
with more than two structured coefficient axes, intervals,
and coverage remain outside it. The
univariate Gaussian mu path also
supports one numeric slope, for example relmat(1 + x | line, Q = Q), as
independent intercept and slope fields with separate SDs and no
intercept-slope correlation. The exact one-axis sigma one-slope route is also
fitted for K and Q. Bivariate labelled maximum-likelihood models are
supported with 2, 4, 6, or 12 structured coefficient axes;
additional structured-slope layouts, structured slope correlations,
predictor-dependent corpair() regression, and relatedness sd*()
direct-SD grammar are not supported.
relmat() is
intentionally separate from meta_V(), which adds known sampling covariance
among observations, and from residual rho12, which models
within-observation bivariate residual correlation.
Examples
# Fitted: a genomic relatedness matrix for among-line genetic variance.
bf(seed_mass ~ temperature + relmat(1 | line, K = G),
sigma ~ temperature
)
#> <drm_formula>
#> seed_mass ~ temperature + relmat(1 | line, K = G)
#> sigma ~ temperature
# Fitted: a user-built sparse precision for another dependence structure.
bf(growth ~ treatment + relmat(1 | plot, Q = Q_plot),
sigma ~ treatment
)
#> <drm_formula>
#> growth ~ treatment + relmat(1 | plot, Q = Q_plot)
#> sigma ~ treatment