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_fit_recovery evidence only; bivariate Q, slopes, q4+, 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 q1 sigma one-slope route is also
fitted for K and Q. Implemented bivariate labelled ML cells extend
through the q2, q4, q6, and q12 layouts recorded in the capability ledger;
additional structured-slope layouts, structured slope correlations,
predictor-dependent corpair() regression, and relatedness sd*()
direct-SD grammar remain planned.
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