R/summary-tables-ensemble.R
BayesTools_ensemble_tables.RdCreates estimate summaries based on posterior distributions created by mix_posteriors, inference summaries based on inference created by ensemble_inference, or ensemble summary/diagnostics based on a list of models_inference models (or marginal_inference in case of marginal_estimates_table).
ensemble_estimates_table(
samples,
parameters,
probs = c(0.025, 0.975),
title = NULL,
footnotes = NULL,
warnings = NULL,
transform_factors = FALSE,
formula_prefix = TRUE,
transform_scaled = FALSE,
formula_scale = NULL
)
ensemble_inference_table(
inference,
parameters,
logBF = FALSE,
BF01 = FALSE,
title = NULL,
footnotes = NULL,
warnings = NULL
)
ensemble_summary_table(
models,
parameters,
logBF = FALSE,
BF01 = FALSE,
title = NULL,
footnotes = NULL,
warnings = NULL,
remove_spike_0 = TRUE,
short_name = FALSE
)
ensemble_diagnostics_table(
models,
parameters,
title = NULL,
footnotes = NULL,
warnings = NULL,
remove_spike_0 = TRUE,
short_name = FALSE
)
ensemble_estimates_empty_table(
probs = c(0.025, 0.975),
title = NULL,
footnotes = NULL,
warnings = NULL
)
ensemble_inference_empty_table(title = NULL, footnotes = NULL, warnings = NULL)
ensemble_summary_empty_table(title = NULL, footnotes = NULL, warnings = NULL)
ensemble_diagnostics_empty_table(
title = NULL,
footnotes = NULL,
warnings = NULL
)
marginal_estimates_table(
samples,
inference,
parameters,
probs = c(0.025, 0.5, 0.975),
logBF = FALSE,
BF01 = FALSE,
title = NULL,
footnotes = NULL,
warnings = NULL,
formula_prefix = TRUE,
transform_scaled = FALSE,
formula_scale = NULL
)posterior samples created by mix_posteriors. For
ensemble_estimates_table(), a sample vector or matrix may contain
missing draws only if it declares them as undefined through its
undefined_draws metadata (posterior_metadata(x,
"undefined_draws") <- ; a single value for a vector, or values named by
column for a matrix), as set by parameter_draws() from the catalog's
definedness ("correlation" for original-scale random-effect
correlations, "multiple_correlation" for their cor_total
multiple correlations, "allocation_active" for variance shares of gated
total-variance allocations). Such a row
is summarized over its defined draws and a table footnote reports their
share, e.g., "summarized over k of n draws where the correlation is
defined, i.e. both SDs are positive". Any other missing draw is an error.
character vector of parameters (or a named list with of character vectors for summary and diagnostics tables) specifying the parameters (and their grouping) for the summary table
quantiles for parameter estimates
title to be added to the table
footnotes to be added to the table
warnings to be added to the table
whether factors with orthonormal/meandif
prior distribution should be transformed to differences from the
grand mean, and factors with prior_ordered() prior distribution to
their level effects (without the reference level of a "cumulative"
contrast, which is fixed at zero). Untransformed ordered factors show the
sampled parameters: runjags_estimates_table() reports the total
effect (<term>{total}) and the allocation shares of the
random allocations (<term>[share: <level>], the share
of the total added when reaching <level>; fixed allocations have no
rows). ensemble_estimates_table() reports retained fitted totals and
the union of allocation shares sampled by any declared ordered model.
Fixed ordered allocations fill that union with their declared constants.
Models without the ordered parameterization have undefined (NA)
shares, with their defined fraction reported in a footnote. Shares remain
defined on zero-total and excluded spike draws of an ordered model. Legacy
mixed objects without retained sources must be recreated from source fits.
whether the parameter prefix from formula should
be printed. Defaults to TRUE.
whether coefficients from standardized
continuous predictors should be transformed back to the original
scale. For runjags_estimates_table(), FALSE keeps fixed and
random effects on the fitted predictor scale, while TRUE transforms
both to the original predictor scale when the fit contains
formula_scale metadata: random-effect SDs and correlations are
computed from the transformed covariance draws. Subtraction-centering can
leave a numerically nonzero predictor mean; its induced effects are retained.
Composite original-scale SDs have available draws but may have unavailable
prior laws. Fitted-scale coefficients and semantic random-effect summaries remain
available without this transformation. A block whose missing-term fallback
mixes categorical coding or omits a representable contribution has no
available original-scale output, with reason
"original_scale_not_representable". Use fitted-scale output or include
the needed lower-order terms in the block. Mixed posterior samples are
transformed through the fitted design of formula_scale: every column
is mapped to its fitted coefficient by its quantities draw metadata
(see posterior_metadata()), and columns that are not fitted coefficients
are refused (a posterior_transform() result, nonlinear or affine with an
offset, stops with reason "transformed_column_not_fitted": unscale
first, then transform), as are random-effect SDs that the random-effect structure of
formula_scale does not cover (SDs it does not contain, blocks it
contains only in part, or blocks it leaves unchanged while the samples'
original-scale SDs differ from the fitted ones). The SDs of a block are
transformed through the fitted block design that the formula state of the
samples carries (as_mixed_posteriors(), and mix_posteriors() when fixed
formula coefficients or random-effect SDs are among its parameters); samples
without it can pair coefficient names only, and the SDs of a block that this
does not map exactly (e.g., a factor in an interaction with a standardized
slope whose margin is not in the block, or the indicator columns of a
logical predictor in such an interaction) are refused. The SD columns of a block
with a standardized random slope are labelled by their fitted coordinates
((mu) g: sd(x)) until they are transformed to the catalog's
original-scale SDs. For a standardized slope that interacts with a factor
whose level effects are not columns of the block (diag(1 + f:x | g):
the level intercepts; diag(1 + z + f:x:z | g): the level slopes of
z), the shifts that centering induces by level are not block
coefficients. The surviving-coordinate transformation retains the shifted
coefficients (here the intercept, or the slope of z) at the predictor
mean; the SDs of the columns that no centering shifts are exact.
runjags_estimates_table() instead reports the unavailable original-scale
quantities of the shifted columns as NA with a row-specific note, and
retains the identifiable summaries. Estimated marginal means of
marginal_estimates_table() are
predictions at the stated predictor values, which do not depend on the
standardization, and are not changed. Defaults to FALSE.
named list containing standardization information
(mean and sd) for each standardized predictor, together with the fitted
design of each formula: the formula_scale attribute of the fitted
model. Required when transform_scaled = TRUE for ensemble/marginal
tables (unless the samples were unscaled by as_mixed_posteriors(); an empty
list means that no predictor is scaled): without it the tables stop with
BayesTools_formula_transform_unavailable (reason
"formula_scale_missing"), as standardization information without the
fitted design does. For
runjags_estimates_table, this is automatically extracted from
the fit object's formula_scale attribute.
model inference created by ensemble_inference.
ensemble_inference_table() refuses conditional inference, of the
whole object or of any of its parameters.
whether the Bayes factor should be on log scale. When model inference objects store log-space inclusion Bayes factors, log-scale values are taken from them, so they remain finite beyond the range of natural-scale Bayes factors.
whether the Bayes factor should be inverted
list of models_inference model objects,
each of which containing a list of priors
and inference object, The inference must be a
named list with information about the model: model number
m_number, marginal likelihood marglik, prior and
posterior probability prior_prob and post_prob,
inclusion Bayes factor inclusion_BF, and fit summary
generated by runjags_estimates_table for the diagnostics
table
whether prior distributions equal to spike
at 0 should be removed from the prior_list. In JAGS estimates
tables with transform_scaled = TRUE, a coefficient with a spike at
0 is kept when it is non-zero on the original scale.
whether the prior distribution names should be
shortened. Defaults to FALSE.
ensemble_estimates_table returns a table with the
model-averaged estimates, ensemble_inference_table returns
a table with the prior and posterior probabilities and inclusion
Bayes factors, ensemble_summary_table returns a table with
overview of the models included in the ensemble, and
ensemble_diagnostics_table returns an overview of the MCMC
diagnostics for the models included in the ensemble. All of the
tables are objects of class 'BayesTools_table'. The estimates tables
(ensemble_estimates_table and marginal_estimates_table)
carry the per-row quantity table attr(table, "quantities"): a data
frame with one row per table row and the columns row (the row
label), quantity_id (the parameter_catalog() quantity id the
summarized draws declare in their quantities metadata, see
posterior_metadata(); "" when they declare none, e.g. for
estimated marginal means), and label_parts (the label parts the row
label is rendered from; see parameter_labels()). Subsetting the table
subsets its quantity table.