Constructs a block-diagonal n x n matrix V suitable for the
meta_known_V() / equalto() covstruct in gllvmTMB(), where
rows belonging to the same study_id are correlated and rows
from different studies are independent. Each block is a compound-
symmetric covariance matrix
\(\mathbf{V}_s = \mathbf{D}_s^{1/2} \mathbf{R}_s \mathbf{D}_s^{1/2}\)
with \(\mathbf{D}_s = \mathrm{diag}(\sigma^2_{s1}, \ldots)\) the
per-row sampling variances within study \(s\) and \(\mathbf{R}_s\)
the within-study correlation matrix (1 on the diagonal,
rho_within on the off-diagonal).
Arguments
- study_id
A factor (or coercible to one) identifying which study each row belongs to. Rows with the same
study_idform a block in V.- sampling_var
Numeric vector of per-row sampling variances, length
length(study_id).- rho_within
Either a single numeric in (-1, 1) used for every study's off-diagonals, or a named numeric vector with one entry per
study_idlevel (allowing study-specific within-study correlations). Default 0.5 - a common ad-hoc choice in ecology meta-analyses when the true rho is unknown but plausibly moderate.
Details
Use this when you have multiple effect sizes per study (multiple
outcomes, multiple traits per individual, etc.) and the within-study
sampling errors share a common cause. The independent-rows / single-
effect-per-study case is block_V(..., rho_within = 0), which
equals diag(sampling_var).
See also
meta_known_V() for the canonical keyword that consumes
the matrix produced here.
Examples
set.seed(1)
df <- data.frame(
study = factor(rep(paste0("s", 1:3), each = 2)),
var = c(0.04, 0.05, 0.06, 0.04, 0.05, 0.07)
)
V <- block_V(df$study, df$var, rho_within = 0.5)
round(V, 3)
#> [,1] [,2] [,3] [,4] [,5] [,6]
#> [1,] 0.040 0.022 0.000 0.000 0.00 0.00
#> [2,] 0.022 0.050 0.000 0.000 0.00 0.00
#> [3,] 0.000 0.000 0.060 0.024 0.00 0.00
#> [4,] 0.000 0.000 0.024 0.040 0.00 0.00
#> [5,] 0.000 0.000 0.000 0.000 0.05 0.03
#> [6,] 0.000 0.000 0.000 0.000 0.03 0.07