R/JAGS-parameter-catalog.R
parameter_catalog.Rdparameter_catalog() returns the semantic quantities and aliases from the
fitted object's versioned parameter_map(). The catalog contains only
metadata: selectable quantities, exact aliases, and serializable extraction
keys. Square brackets after a factor term always hold a level label, never a
coordinate position. Fixed factor terms, including ordinary factor priors
whose levels are labelled 1, ..., K, expose every level or interaction cell
as a quantity named <parameter>[<level>], so term[level],
<parameter>[level], and term plus component = "level" all select the
level with that label. Treatment and independent cells and the first ordered
coordinate are structurally the fitted coordinate; reference cells are
structural zeroes; and the remaining cells are reconstructed from the
persisted term-only design matrix. A coordinate that is not a level cell (a
mean-difference or orthonormal coefficient, or a later ordered increment) is
coefficient j of the contrast coding, named <parameter>{j} and displayed
as term{j}. The total of an ordered term (prior_ordered()) is the
quantity <parameter>_ordered_total displayed as term{total} (term{total}:g{1}
for the slice of an ordinary factor; the inclusion indicator of a mixture
total is displayed as term{total} (inclusion)), and the labels of earlier
versions (term_ordered_total) remain aliases. Each share of a random
allocation of an ordered term is a derived quantity,
<parameter>_ordered_allocation[<level>] displayed as term[share: level]
(support [0, 1], the Beta marginal of the Dirichlet prior); its earlier
labels (term_ordered_allocation[level]) are aliases. The level names of transformed summaries,
<parameter>[dif: level], and the row labels those summaries display,
(formula) term[dif: level] and term[dif: level], are aliases of the
level quantity. JAGS
coordinate names such as mu_g[1] remain backend columns, used by
JAGS_materialize_draws(), and do not select factor quantities. Ordinary
level labels remain unchanged; syntax-sensitive characters (including curly
braces) are percent-escaped and ambiguous interaction tokens are quoted so
that every component remains hypothesis-safe and injective. These are
coefficient-level quantities, distinct from estimated marginal means based
on full predictions.
Continuous coefficients retain their ordinary, canonical and fitted backend
selectors; their backend names are not factor-level labels, so selectors such
as x[mu_x] and intercept[mu_intercept] are unavailable. Parameter-map
schema 10 requires refitting older maps rather than retaining their aliases.
parameter_coordinates() is the linked concrete posterior-coordinate view;
the catalog is the semantic view of the same fitted map. Random-effect
canonical names follow (formula) owner: quantity(arguments), with owner:
omitted for a bare or unnamed one-entry random formula, retained for an
explicitly named one-entry list, and required when multiple blocks need
disambiguation. Parentheses contain parameter or
coefficient names, while square brackets inside an argument contain its
factor or index level. Examples include (mu) study: sd(intercept),
(mu) study: cor(group[sensitivity],group[specificity]), and
(mu) var_prop(study). A mean-difference or orthonormal factor term of a
block is one exchangeable unit (see prior_random()) with one SD quantity,
sd(f); its correlations are reported by level, cor(x,f[a]), together
with the multiple correlation cor_total(x,f) (support [0, 1]), and its
coefficient coordinates f{j} appear only in raw tables: a selector such
as sd(f{1}) stops with class BayesTools_selector_unavailable, naming the
unit's quantity. Formula-prefix omission is accepted as an alias.
Additional aliases are limited to genuine semantic equivalences, such as a
CS/HCS pairwise correlation referring to its shared cor.
Random-effect quantities also carry centrally generated simplified aliases.
These remove a sole intercept argument and may omit a redundant owner, but
are considered by resolvers only when simplify_names = TRUE.
For a log-intercept formula, exp(intercept) is an alias of the fitted
coefficient quantity. Selecting that alias does not itself unscale the
coefficient. RoBMA's standardized_coefficients setting selects the display
scale independently of the alias.
Identity random-effect summaries reuse their sampled or structural
coordinate. Summaries requiring a scale or covariance transformation expose
only the transformed quantity; their fitted-scale inputs and all other
private implementation coordinates remain dependencies rather than public
catalog rows. A public coordinate that a variance allocation reads through
random_sd_source() (a model parameter such as tau) is not a private
coordinate of the allocation: it stays its own catalog quantity. Raw
estimates tables
(JAGS_estimates_table(random_effects_summary = "raw")) show these backend
coordinates for inspection; their row labels are not catalog aliases.
Each random extraction key records whether its source mapping
is an identity, one-to-one transform, or composite, together with the source
coordinate, prior, and transform when those are defined.
Constructing or resolving the catalog never accesses posterior draws.
parameter_catalog_extend() adds plain-data quantities and aliases owned by
another provider; the "BayesTools" provider name is reserved for native
quantities. parameter_catalog_resolve() applies optional namespace
and component filters and returns a versioned selection only when the match
is unique. Otherwise it stops with an error of class
BayesTools_parameter_not_found or BayesTools_parameter_ambiguous (both
also BayesTools_parameter_resolution_error; the condition names the
matching quantities). A rendered label that is also the label of another
quantity (e.g. the transformed label g[dif: b] of level b and the label of
a level named dif: b) is ambiguous, while a rendered label never replaces
the canonical name of another quantity. A contrast-coefficient
selector term{j} whose coordinate is a level (the coordinates of treatment
and independent contrasts and the first ordered coordinate have no
coefficient quantity) stops with class BayesTools_selector_unavailable
(also BayesTools_hypothesis_target and
BayesTools_parameter_resolution_error), whose message and field level
name the level in the same form, e.g. g[10] for g{1} of a treatment
factor with levels 5, 10, and 20. A selection that is malformed, stale, or
does not belong to the catalog it is used with (for example one resolved
from another fit) stops with an error of class
BayesTools_parameter_resolution_error; resolve the parameter again from
the fit's catalog.
parameter_catalog(fit, transform_scaled = FALSE) is the catalog of the
fitted scale of the predictors. It has the quantities, identifiers, names,
and aliases of the default catalog (transform_scaled = TRUE), with the
fitted-coordinate support, status, fixed_value, source_type, and
extraction_key of the random-effect SDs, variances, and correlations of
blocks with scaled predictors (a bounded SD prior keeps its bounds, an SD
that the original scale combines from several fitted coefficients is the
fitted coefficient itself, and an SD fixed on the fitted scale is
structural). It is the default catalog for a fit without scaled predictors
and for quantities that the scales do not affect. A selection resolved from
either catalog is accepted by parameter_draws(), parameter_prior_density(),
parameter_transform(), parameter_gate_states(),
random_effects_marginal_update_plan(), and parameter_mixed_posterior(),
which use the matching scale: a selection of the fitted-scale catalog is
extracted from the fit without its predictor scales, a selection of the
default catalog from the fit as it is (so blanking the formula_scale of the
fit is not needed to extract the fitted scale). A selection that belongs to
neither catalog stops as described above, and
parameter_mixed_posterior() stops for a selection of the fitted-scale
catalog with transform_scaled = TRUE.
parameter_draws() is the deferred extraction boundary. The BayesTools fit
method reads only the coordinates declared by the selected
extraction key; a quantity whose source coordinates were not monitored
(catalog status "unavailable") stops with an error of class
BayesTools_refit_monitoring (also BayesTools_refit_required).
Downstream packages can provide methods for package-owned
derived quantities. For gated total-variance allocations, realized
sd_total and var_total draws include the all-off zero branch.
var_prop(...) draws are normalized over active components and are NA on
draws where the realized allocation total is zero. Random-effect
correlations (cor(...) of LKJ blocks; original-scale correlations in a
block with scaled columns) are NA on draws where the correlation is
undefined, i.e. where one of the SDs of its pair is zero; a correlation
whose SD draws are not available (a row-indexed or unmonitored external SD
source) cannot be masked and keeps its fitted draws.
Each catalog quantity declares its definedness ("always", or the reason
of possibly undefined draws: "correlation", "multiple_correlation" for a
cor_total, or "allocation_active" for the variance shares of gated
total-variance allocations) and its exact
support from the prior provenance of its source coordinates (NULL when
it is not derivable). A quantity with point masses in its prior density
(an SD, variance, total, or variance share of an allocation with inclusion
gates, or whose scale prior has a point component) lists exactly the
locations of those atoms as the points of a "mixed" support; where the
atoms cannot be derived (an external SD source without a BayesTools prior, a
composite SD outside its allocation component), its hull is declared inexact
(exact = FALSE). The
mcmc.list returned by parameter_draws()
carries these as draw metadata (posterior_metadata()): support, keyed by
canonical name, and undefined_draws, a character vector named by the
canonical names of the possibly undefined quantities with their reasons.
Summaries such as ensemble_estimates_table() accept missing draws only for
columns carrying this declaration: callers that extract a numeric vector
keep it by copying the element with
posterior_metadata(x, "undefined_draws") <- .
parameter_prior_density() constructs a deterministic
prior_linear_density for supported map-defined quantities: fitted
coordinates and factor levels (the weighted sum of their fitted
coordinates under the fitted prior, whose multiply_by scales enter only
the linear predictor; structural levels are point masses at their fixed
value), one-to-one transformations, Dirichlet allocation marginals, and
allocation-derived component SDs. Variance proportions are conditional on
positive allocation variance. A shared parent inclusion gate cancels from
that conditional law, leaving the Dirichlet marginal
Beta(alpha_i, sum(alpha) - alpha_i). Independently gated components keep the mixed measure
over the realized active set: atoms at 0 and 1, and a Beta mixture over
nonempty sets of other active components. It returns
NULL when the fitted map does
not declare a supported deterministic prior composition; for fitted
coordinates and factor levels, only when no fitted prior owns their
coordinates (an owning prior-list entry that is not a BayesTools prior
stops) or when an owning prior has parameters given as expression()s
(JAGS-only support: the prior has no R-side law, and
parameter_mixed_posterior() returns the draws and atoms without a prior
density). The density records
the source prior and transform it was built from, so its heights and region
probabilities are evaluated on that prior's structural route (bounded-logit
correlations on the refined numerical grid). Allocated SDs are the scale
prior T times an independent multiplier of the fitted model, whose
Dirichlet weights w span all components of the allocation: a component
SD is T sqrt(k w_i) (k the number of components of a mean-variance
allocation, 1 otherwise) while the gates of its allocation chain are on and
0 otherwise, and an allocation total (sd_total, var_total) is
T sqrt(sum of w over the active components), 0 without an active
component and T with all of them, times the allocation chain of its parents
(their gates and Dirichlet shares) for a nested allocation. Their densities
(and those of the variances) are exact: the atoms at zero, and the
continuous parts as mixtures over the gate configurations of the scale prior
and of the one-dimensional integrals over the Beta share margins (e.g., the
total of an ungated allocation that splits the component of a gate-only
allocation is the scale prior times the gate). SD
components and totals of nested allocations with two or more allocation
shares are products of density grids without such provenance, returned for
plotting only (heights, region probabilities and point hypotheses are
unavailable, and their ordinates name the reason). The SD of a gate-only
allocation (one term with an inclusion gate) is the scale prior times its
gate, and an inclusion indicator (of an allocation gate, or
inclusion(...) of a component of a spike-and-slab or mixture SD prior) has
the Bernoulli prior of its marginal inclusion probability (points at 0 and
1; the prior weight of the component, or the expected inclusion probability
of a spike-and-slab prior) and the exact support {0, 1}.
A pairwise correlation of an unstructured random-effect block with K
columns and an LKJ(eta) prior has the exact LKJ marginal: 2 B - 1 with
B ~ Beta(eta - 1 + K/2, eta - 1 + K/2) (Lewandowski et al. 2009)
.
This is its prior on the fitted scale, also when the SDs of the block have
inclusion gates or point masses (the correlation matrix is a priori
independent of them), and on the original scale of scaled predictors when
each coefficient of the pair is one rescaled fitted coefficient (e.g. two
scaled slopes; the correlation is then the fitted one wherever both SDs are
positive). An original-scale correlation that mixes fitted coefficients,
such as that of the intercept and a slope of a centred predictor, combines
the correlation with the SDs and returns NULL.
parameter_transform() returns the one-to-one map from the selected source
coordinate to its public semantic quantity when that map exists. Composite
quantities return NULL. The forward, inverse, and Jacobian helpers are the
authoritative evaluators for these serializable descriptors, so downstream
consumers do not need to reproduce backend correlation, allocation, or
formula-scale transformations.
parameter_catalog(object, ...)
# S3 method for class 'BayesTools_fit'
parameter_catalog(object, transform_scaled = TRUE, ...)
parameter_catalog_schema()
parameter_catalog_extend(catalog, quantities, aliases, provider)
parameter_catalog_resolve(
catalog,
alias,
namespace = NULL,
component = NULL,
simplify_names = FALSE
)
parameter_draws(object, selection, ...)
parameter_prior_density(object, selection, ...)
# S3 method for class 'BayesTools_fit'
parameter_draws(object, selection, model_samples = NULL, ...)
# S3 method for class 'BayesTools_fit'
parameter_prior_density(
object,
selection,
n_grid = .prior_linear_density_default_grid(),
tail_prob = .prior_linear_density_tail_prob(),
...
)
parameter_transform(object, selection)
parameter_transform_forward(values, transform)
parameter_transform_inverse(values, transform)
parameter_transform_jacobian(values, transform)fitted object.
arguments for methods.
for the catalog of a fitted model, whether the
random-effect quantities of blocks with scaled predictors are those of the
original scale (TRUE, the default) or of the fitted scale of the
standardized predictors (FALSE), as for parameter_mixed_posterior().
a BayesTools_parameter_catalog object.
quantity rows matching the quantity schema.
alias rows matching the alias schema.
scalar provider name owning every added quantity.
scalar exact canonical name or alias.
optional exact namespace filter.
optional exact component filter.
whether to accept centrally generated simplified
random-effect aliases. Defaults to FALSE.
a BayesTools_parameter_selection returned by
parameter_catalog_resolve().
optional numeric matrix containing the declared fitted
source coordinates. This lets downstream summaries evaluate a selected semantic
quantity on an already materialized posterior sample.
A single coda::mcmc matrix retains its recorded sampling timing;
plain matrices use the default timing.
Ordered quantities also require the total, Gamma allocation and component
indicator sources listed by JAGS_ordered_parameter_spec() in each term's
source_coordinates; increment-only columns do not establish their
semantic values or structural measure. Include those primitive sources, or
omit model_samples to read the complete fitted draws. Missing supplied
ordered sources raise BayesTools_ordered_coordinates_unavailable.
number of grid points used for deterministic induced prior densities.
probability omitted from each continuous source-prior tail when constructing a finite numerical grid.
numeric values on the source scale for
parameter_transform_forward() and parameter_transform_jacobian(), or
on the public quantity scale for parameter_transform_inverse().
a serializable transform descriptor returned by
parameter_transform().
parameter_catalog() and parameter_catalog_extend() return a
BayesTools_parameter_catalog. parameter_catalog_schema() returns schema
descriptions. parameter_catalog_resolve() returns a
BayesTools_parameter_selection. parameter_draws() returns a
coda::mcmc.list for BayesTools-owned quantities.
parameter_prior_density() returns a prior_linear_density or NULL.
parameter_transform() returns a serializable transform descriptor or
NULL; the transform helpers return numeric values.
Lewandowski D, Kurowicka D, Joe H (2009). “Generating random correlation matrices based on vines and extended onion method.” Journal of Multivariate Analysis, 100(9), 1989–2001. doi:10.1016/j.jmva.2009.04.008 .