Reads and sets the metadata that BayesTools attaches to
posterior draws: the elements and lists returned by mix_posteriors(),
as_mixed_posteriors(), marginal_posterior(), and
random_effects_summary_posterior(), and the draws of parameter_draws().
All metadata are stored in one attribute and validated when they are set;
use this accessor instead of setting attributes.
posterior_metadata(x, field)
posterior_metadata(x, field) <- valueposterior draws (an element or a list of them).
metadata field:
"support"exact support, created with
posterior_support_attribute() (or a list of such objects keyed by
column).
"atoms"declared posterior point masses, created with
posterior_atom_attribute(); point masses are read only from this
field.
"undefined_draws"a character vector naming quantities
whose draws may be NA because the quantity is undefined in those
draws (e.g. "correlation"), as returned by parameter_draws().
"prior_density"the prior density of the quantity.
"prior_densities"a list of prior densities keyed by
parameter, attached to the list returned by as_mixed_posteriors()
with transform_scaled = TRUE for the requested parameters.
"prior_context"the joint prior-density context of the draws.
"posterior_density", "posterior_densities"precomputed posterior densities created with
posterior_density_attribute().
"posterior_ordinate", "posterior_ordinates"precomputed posterior ordinates created with
posterior_ordinate_attribute() or posterior_ordinate_append().
"condition"the conditioning of the draws: a list with
conditional, conditional_rule, condition_key,
condition_event, resolved_condition_event,
averaged (TRUE when the draws are not conditioned on any
event, i.e., the unconditional model-averaged posterior; FALSE
otherwise), and, for levels whose conditioning was resolved per level,
effective_conditional and effective_conditional_rule.
Read averaged instead of comparing condition_key with a
literal key.
"measure_unavailable"a plain data frame with exact columns
column, measure, and reason, with an optional declared
cause enum; absent causes use an already enumerated reason.
An optional diagnostics list column retains compact model probability
diagnostics. Each non-NULL cell is a plain list with model_indices,
log_prior_probabilities, log_posterior_probabilities, and
stage; supplied log vectors align with positive unique integer
model indices. A missing log vector is NULL. Stage identifies prior,
posterior, conditional prior/posterior, event, or component probabilities.
A cell may alternatively contain the existing typed
BayesTools_ordered_expression_unavailable condition, with a NULL
call, retaining that ordered-expression refusal. Other condition objects
are not accepted as diagnostics.
The cause numerical_model_probability_unavailable identifies a
declared law whose active model probabilities cannot be represented at
full precision. The cause missing_source_context identifies a prior
density that a transformation could not rebuild because the source has
neither a declared prior context nor priors (formula marginals of several
models keep none); the transformed values and other metadata remain. The
cause random_sd_prior_law_unavailable identifies the prior density
of a random-effect SD on the original predictor scale that combines several
fitted SDs of its block (e.g., an intercept SD with a non-centered scaled
slope), and random_effect_design_unavailable one whose block has no
fitted design in the prior context; the SD of a block that rescales one
fitted SD has the fitted law rescaled. The cause
expression_prior_law_unavailable identifies the prior density of a
quantity whose prior has parameters given as expression()s (an
expression point or an expression container, including the components of
a mixture or spike-and-slab prior): such priors are evaluated only by JAGS
and have no R-side prior law. The draws are not affected, and the atoms
and the support of a quantity keep their declarations, except on the
routes that build them from the contributing priors (formula marginals,
transform_scaled), where the atoms and the support carry their own
unsupported_contribution_measure marks.
Invalid metadata requires recomputation/refitting.
Human reason text alone does not classify a measure refusal. Tables use
unique column/measure pairs. The measures are prior_density, atoms, or support.
Entries prevent stale prior/density/support fallback while numeric draws
remain usable. Atom/support refusals use
BayesTools_formula_atoms_unavailable and
BayesTools_formula_support_unavailable, inheriting
BayesTools_formula_measure_unavailable.
"linear_weight_space""coefficient" for coefficient
recipes, or "formula_contribution" for fitted design rows and compiled
multipliers. Contribution weights never pass through coefficient C/A again.
Old ambiguous stored contexts must be recreated.
"linear_weights"the weights of the fitted coordinates
that form a level of a marginal_posterior() (a named finite numeric vector,
or a finite matrix: one row per draw for coefficient weights, one row per
fitted design row for the formula contributions of a formula marginal,
where the rows are not draws). Removing weights also removes
their companion weight-space declaration. Unavailable dynamic recipes
remain in the producer's separate transformation/refusal metadata.
"ordered_source"internal retained fitted totals, normalized allocations, model provenance and source-row indices. Producers validate its row count and preserve the primitive values independently of effect transformations. Recreate missing sources from the fitted models; shares are never reconstructed from increments divided by totals.
"quantities"the quantity of every column of mixed and
marginal posterior draws: a data frame with one row per column (one row
for vector draws) and the columns column (the column name),
quantity_id (the parameter_catalog() quantity id, or
"" for columns that are not catalog quantities),
dependencies and weights (the fitted coordinates the
column is a linear function of), and label_parts (the label
parts rendered by parameter_labels()). Set by as_mixed_posteriors(),
mix_posteriors(), transform_factor_samples(), and
marginal_posterior() (whose estimated marginal means are predictions
and declare no fitted coordinates); summaries map columns to fitted
coordinates and render their labels from it.
"output_transformations"the transformations applied to
the values of the draws by posterior_transform() (and
marginal_posterior() with transformation), in the order they
were applied: "lin", "exp_lin", "tanh",
"exp", or "custom" for a transformation given as
functions; absent for untransformed draws.
the new value of the field; NULL removes it.
posterior_metadata() returns the value of the field or
NULL; the replacement form returns x with the field set.
Arithmetic and mathematical functions of posterior draws
(Ops and Math group generics), c(),
as.numeric(), and subsetting return plain numeric draws without
metadata, because supports, atoms, and prior densities do not follow the
transformed values. Functions that need the metadata (e.g.
Savage_Dickey_BF(), plot_posterior(), marginal_posterior()) stop on
such draws; posterior_transform() (and marginal_posterior() with
transformation) transforms the draws together with their metadata.
Operations that replace values but keep the attributes of the draws
(x[] <- , x[i] <- , pmin(), pmax()) leave
metadata that no longer describe the draws. The metadata record a
fingerprint of the values they describe (their number, the number of
missing values, and two sums of the observed values), and reading or
setting the metadata of such draws, here or in any function that uses
them, stops with an error of class BayesTools_stale_metadata
(parent class BayesTools_metadata). Subsetting a list of mixed
posteriors with [ keeps the list's metadata, with the prior
densities of the omitted parameters removed.
The fingerprint cannot detect every change: the two sums are compared within their rounding-error bound, so changes that keep both sums (e.g., adding d, -2d, and d to three consecutive draws), changes of single draws smaller than about \(5.6 \cdot 10^{-17} n^2\) times the draws' mean absolute value for \(n\) draws (about \(6 \cdot 10^{-5}\) for \(10^6\) draws), and reorderings that move draws by only a few positions can keep the metadata. The bound grows with the number of draws: such changes are detected at some positions or for fewer draws (e.g., swapping two adjacent standard-normal draws is typically detected for \(10^5\) draws but not for \(10^6\)).
draws <- stats::rnorm(100)
posterior_metadata(draws, "atoms") <- posterior_atom_attribute()
posterior_metadata(draws, "atoms")
#> $declared
#> [1] TRUE
#>
#> $joint_declared
#> [1] TRUE
#>
#> $locations
#> value
#>
#> $mass
#> numeric(0)
#>
#> $source
#> [1] "user"
#>
#> $component_probabilities
#> NULL
#>
#> attr(,"class")
#> [1] "BayesTools_posterior_atoms" "list"