Known sampling-error term (brms-style, deprecated alias)

A formula keyword for the two-stage meta-regression workflow's stage-2 entry, where the responses are stage-1 estimates (or pre-computed effect sizes such as Hedges' g) and their marginal sampling variances are known. This keyword desugars to equalto(0 + obs | grp_V, V) inside gllvmTMB().

Usage

meta(value, sampling_var)

Arguments

value

The response column name (typically the column called value in a stage-1 summary, or an effect-size column in a meta-analytic dataset).

sampling_var

Either an unquoted column name holding the per-row sampling variance, or a length-1 numeric used for every row. Deprecated in favour of meta_V(V = V).

Value

A formula marker; never evaluated.

Details

Deprecated alias. Use meta_V() in new code: meta_V(V = V).

Diagonal vs block-diagonal V

meta(value, sampling_var = vi) describes the diagonal case – rows independent. For multivariate meta-analyses with multiple effect sizes per study (multiple outcomes, multiple traits per individual, etc.), within-study sampling errors are correlated and V is block-diagonal. The engine supports any positive-definite \(n \times n\) V via solve(V) internally. Build a block-diagonal V with block_V() and pass it to gllvmTMB() as known_V = V_block.

See also

meta_V() (canonical replacement); block_V() for constructing a block-diagonal sampling-V from a study factor; gllvmTMB() for the stage-2 fit.

Examples

# A stage-1 summary: one estimate per site and trait, each with a known
# sampling variance.
set.seed(131)
stage1_summary <- expand.grid(
  site  = factor(seq_len(50)),
  trait = factor(paste0("t", 1:3))
)
n <- nrow(stage1_summary)
stage1_summary$value <- rnorm(n, sd = 0.5)
stage1_summary$sampling_var <- runif(n, min = 0.02, max = 0.08)

# Preferred (canonical) form -- use meta_V():
V    <- diag(stage1_summary$sampling_var)
# \donttest{
fit2 <- gllvmTMB(value ~ 0 + trait +
                   latent(0 + trait | site, d = 1) +
                   meta_V(V = V),
                 data    = stage1_summary,
                 trait   = "trait",
                 unit    = "site",
                 known_V = V)
#> ℹ Auto-suppressing `sigma_eps`: `indep(0 + trait | site)` is at the per-row
#>   level, so it already absorbs the observation residual.
#> • Fixed at 0.000528 (~1/1000 of sd(y)) to keep the Gaussian density
#>   well-defined; the row-level residual variance is fully captured by the
#>   per-row diagonal term.

# Deprecated form (still works, prints a deprecation message):
fit2 <- gllvmTMB(value ~ 0 + trait +
                   latent(0 + trait | site, d = 1) +
                   meta(value, sampling_var = sampling_var),
                 data    = stage1_summary,
                 trait   = "trait",
                 unit    = "site",
                 known_V = V)
#> ! Formula keyword `meta()` is a deprecated alias; use `meta_V()` for new code.
#> ℹ `meta_V(V = V)` =/=> `meta(V = V)`
#> → Aliases will be dropped at the next minor release. See `?meta_V`.
#> ℹ Auto-suppressing `sigma_eps`: `indep(0 + trait | site)` is at the per-row
#>   level, so it already absorbs the observation residual.
#> • Fixed at 0.000528 (~1/1000 of sd(y)) to keep the Gaussian density
#>   well-defined; the row-level residual variance is fully captured by the
#>   per-row diagonal term.
# }