R/random-effects-marginal-update.R
random_effects_marginal_update_plan.RdResolves a selected public random-effect quantity to the exact scalar
dependence of its marginal covariance contribution. The result is compiled
exclusively from the fitted parameter map and formula random-effect
metadata; posterior draws are neither inspected nor used to infer an update
form. An unsupported plan can include a conditional entry containing
required_active and plan. The nested plan applies only to posterior rows
where every named inclusion indicator equals one. It does not declare an
unconditional update for the selected public quantity.
random_effects_marginal_update_plan(fit, selection)a fitted object carrying a BayesTools parameter map and formula design metadata.
a one-quantity selection returned by
parameter_catalog_resolve().
A list of class
BayesTools_random_effects_marginal_update_plan. Field family is one of
"affine", "factor", "markov", or "unsupported". An affine plan
additionally records the scalar covariance coefficient transform and the
affected random-effect blocks. For a plan in a source coordinate
(coefficient_input = "source"), the blocks include every block whose SD
binding uses that source, also through another variance allocation.
Fields shared by the supported families are update (the kind of
update, below), blocks, structure and component_index (the
covariance structure and the column of a per-column quantity),
coefficient_input, source_parameter, source_transform and
source_transform_spec (the fitted coordinate and its transform to the
public quantity), quantity_id, canonical_name, formula_parameter and
dependencies. Affine plans add coefficient_transform and, for the
Dirichlet-weight updates of an allocation, allocation (weight_name,
index, n_targets, and the allocation scale when the plan comes from
the conditional route). invariant_covariance holds the
covariance that does not depend on the selected coordinate when it is
structurally available, and NULL otherwise. Factor plans of
allocation-derived SDs add coefficient_scale_transform. An unsupported
plan carries reason and message instead.
update is "scale" when the contribution of the affected blocks is
scaled by one coefficient, "column_scale" when the SDs of some columns of
a block change (component_index, the first column of the selected SD;
the other column SDs of a direct per-column SD are held fixed, a direct SD
shared by several columns lists them in driven_columns, and so do the
driven columns of an allocation-derived SD), "allocation" when
a Dirichlet weight of a variance allocation changes, and "correlation"
for a correlation coordinate. A direct per-column SD with unequal column
SDs reports "column_scale".
The plan of an allocation-derived component SD or variance, and of an
aggregate allocation SD or variance (sd_common, var_common, sd_total,
var_total) that is a quantity-scale plan, has the field
held_fixed = "allocation_weights": whatever the covariance structure,
setting the selected SD to v holds the allocation weights and every
non-allocation coordinate (correlations included) fixed and moves the
allocation scale tau of the SD SD_k = tau * m_k(w) to v / m_k(w),
where m_k(w) is the product of the square roots of the weights on the
path from tau to the SD (sqrt(w_j) for a total-variance allocation,
sqrt(K_j w_j) for a mean-variance one, over the nested allocations).
This is the conditional of the variance prior declared on (tau, w),
which are independent a priori. For an SD value v the prior of the moved
coordinate is the tau prior evaluated at v / m_k(w) with the Jacobian
1 / m_k(w); for a variance value u the SD is sqrt(u) and the Jacobian
is 1 / m_k(w)^2 on the variance parameterization of the scale
(tau^2, equivalently 1 / (2 m_k(w) sqrt(u)) from tau). The scale
reaches every block whose SD binding uses it, also through nested
allocations (a split root with one <block>_components allocation per
block) or a shared random_sd_source(): blocks lists all of them, the
selected block first. Every column SD that derives from tau is
multiplied by the same factor c = v / SD_k, so a reached block whose
columns are all driven by tau has its covariance contribution multiplied
by c^2 on every covariance structure: the plan is then the affine
update = "scale" plan of the summed contribution of blocks. If tau
drives only some columns of the selected block, which is the only block it
reaches, the plan is the factor "column_scale" plan with
driven_columns and the grid factor column_factor for them, when the
selected column is among the driven ones (otherwise the plan is
unsupported with the reason "selected_column_not_driven"); a scale
that reaches several blocks and only part of their columns, or an
aggregate whose scale drives only part of a block, has no exact scalar
update and is unsupported with the reason "partial_scale_reach". An
aggregate of a nested allocation moves the root scale of its allocation
chain as well, so its blocks are those of every sibling allocation of
the root, not only its own.
Plans of direct per-column SDs have no held_fixed field.
family = "affine" means that, conditional on every non-selected posterior
coordinate, the row covariance has the exact form A + h(value) * B, where
value is the coordinate declared by coefficient_input ("source" or
"quantity") and h is recorded in coefficient_transform.
family = "factor" identifies an exact candidate-dependent covariance
factor, while family = "markov" identifies a compiled structured Markov
state. Allocation-derived component SDs are affine on every covariance
structure when the allocation scale drives all columns of every block it
reaches (A + h(v) B with h the square of the SD or the identity of the
variance, B the summed covariance of blocks per unit of h); they are
factor column_scale updates only when it drives part of the columns of the
one block it reaches. All of them hold the allocation weights fixed and scale
every driven column SD by the same factor (held_fixed, above), so the
column_scale plan of an allocation-derived SD differs from that of a direct
SD, which replaces the scale of its own columns only (one column, or every
column in driven_columns for an SD shared by several columns). Their
coefficient_scale_transform converts a selected variance to its square
root and leaves a selected SD unchanged. These
quantity-scale plans require the public SD to be on the fitted coefficient
scale; after formula scaling that changes it, the plan is unsupported.
Unsupported plans carry a structural reason. The accessor
never estimates affineness from evaluated covariance matrices.
The invariant covariance of a block with several coefficient columns is a
dense rows x rows matrix of the fitted data. Its estimated peak memory is
checked against the BayesTools.random_effects_memory_limit_bytes option
(see BayesTools) before it is formed; above the ceiling the accessor stops
with an error of class BayesTools_random_effects_memory_limit (also
BayesTools_random_effects_error).
The conditional entry of an unsupported plan is compiled only for a
variance allocation with exactly two single-column block targets, a scalar
total-variance source and inclusion gates on the blocks; an allocation with
more than two targets has no conditional plan and stays unsupported.