R/random-effects-marginal-covariance.R
random_effects_marginal_vcov.RdConstructs posterior-draw marginal covariance matrices implied by BayesTools formula random effects. For each included random-effect block and posterior draw, the helper builds the observation-level contribution \(Z_b G_b Z_b'\) and sums contributions across blocks.
random_effects_marginal_vcov(
fit,
parameter = NULL,
data = NULL,
posterior_samples = NULL,
prior_list = NULL,
blocks = NULL,
new_levels = NULL,
diagonal_only = FALSE,
fitted_rows = NULL,
...
)a fitted object returned by JAGS_fit(), an object carrying
formula_design metadata, or a BayesTools_formula_design object.
formula parameter name. Required when fit stores more than
one formula design.
optional data frame defining the observation rows. When NULL,
the fitted formula design rows are used. New random-effect grouping levels
require an explicit new_levels policy unless allowed by block metadata.
optional posterior sample matrix, data frame,
mcmc, or mcmc.list. When NULL, samples are extracted from fit.
optional named prior list used to materialize fixed point
hyperparameters. When NULL, priors are taken from fit or the formula
design.
optional character vector of random-effect block names to include. The default includes all formula random-effect blocks.
optional new-level policy. Use a random_new_levels()
object or one of "error", "zero", or "sample". "zero" assigns
zero covariance contribution to unseen grouping levels. "sample" treats
unseen grouping levels as independent draws from the block covariance G.
Grouping levels declared in the fitted grouping factor but without rows in
the fitting data are unseen levels, except in blocks with a known group
covariance; see prior_random().
whether to return only observation-level marginal
variances. This avoids allocating a draw x row x row array when callers
need only diag(Z G Z').
CAR blocks still reconstruct a draw x column x column factor. Their
admission estimate includes conservative factor and contraction work;
diagonal output may not resolve a factor-dominated refusal. This estimate
is not a measured peak or success guarantee: live inputs and uncollected
garbage can require additional memory.
optional integer vector mapping supplied prediction rows
to fitted observation indices. It is required whenever data is supplied
and a selected block uses a posterior-indexed row source. Reordering and
duplicate indices are supported. Callback-computed row sources do not use
this mapping. The entries of rows of new random-effect levels with
new_levels = "zero" are ignored, because those rows have zero
covariance; they must still be valid fitted observation indices.
reserved for future extensions. Unused arguments are rejected.
A list of class
BayesTools_random_effects_marginal_vcov with fields:
A dense array with dimensions draw x row x row, or a
draw x row matrix when diagonal_only = TRUE.
A list describing row ordering, included blocks,
skipped blocks, structures, dimensions, and memory size. With
diagonal_only = TRUE, it additionally identifies the "diagonal"
variance representation, its sample dimensions, and the equivalent
dense entry count. The default covariance metadata schema is
unchanged.
Invalid supplied variance-allocation coordinates can signal
BayesTools_random_effect_allocation_out_of_support, inheriting from
BayesTools_random_effects_error, error, and condition, with message
and call fields. This is an input support error, distinct from structural
factor unavailability. JAGS_bridgesampling() converts this support leaf
to BayesTools_marglik_out_of_support during likelihood reconstruction.
Unavailable new rows for a posterior-indexed row source raise
BayesTools_prediction_new_rows_unavailable (parent
BayesTools_prediction_unavailable), with
reason = "posterior_indexed_row_source", block, displayed source
label, affected prediction rows, and caller context. It applies where
the source of the new rows is needed, under new_levels = "sample"; with
new_levels = "zero" the new rows have zero covariance and need no source.
Mapping, source value, and monitoring errors retain their existing
conditions.