Computes Bayes factors for scalar hypotheses written as
expressions, for example "theta = 0", "theta > 0", or
"theta = 0 vs theta > 0". hypothesis_BF() is a generic: the
default method evaluates posterior draws and marginal posteriors, and the
method for a fitted model (BayesTools_fit) tests the quantities of
its parameter catalog by their public names (see Fitted models). Factor/posterior-list levels can be
referenced as "mu_alloc[alternate] > mu_alloc[random]" when the
marginal posterior carries joint prior information. Level names that
contain brackets, such as the cut() level (0,1], are
referenced by quoting the whole reference in backticks,
"`mu[(0,1]]` > `mu[(1,2]]`", or with the parameter catalog's escaped
level form mu["(0,1%5D"]. Point-null hypotheses use
Savage_Dickey_BF when a marginal_posterior object is
supplied, including precomputed qCMDE/IWMDE posterior ordinates when
density_method = "precomputed". Level-specific
marginal_posterior.* subclass vectors with attached density
metadata are accepted as marginal posterior inputs; parent-level
posterior_density, posterior_densities,
posterior_ordinate, or posterior_ordinates metadata on a
marginal-posterior list is reused for matching level hypotheses.
hypothesis_BF(posterior, ...)
# Default S3 method
hypothesis_BF(
posterior,
prior = NULL,
hypothesis,
parameter = NULL,
logBF = FALSE,
BF01 = FALSE,
seed = NULL,
density_method = c("KDE", "normal", "precomputed"),
columns = "default",
...
)
# S3 method for class 'BayesTools_fit'
hypothesis_BF(
posterior,
hypothesis,
namespace = NULL,
component = NULL,
transform_scaled = FALSE,
conditional = FALSE,
logBF = FALSE,
BF01 = FALSE,
seed = NULL,
density_method = "KDE",
density_control = NULL,
n_samples = 10000,
columns = "default",
...
)
# S3 method for class 'BayesTools_hypothesis_BF'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)posterior draws, a marginal_posterior, a
marginal_inference object, or a data frame/matrix of posterior draws,
or a model fitted with JAGS_fit() (a BayesTools_fit).
Posterior draws must be finite and quantity names must be unique.
for the cbind() method, the tables to bind; unused by the
as.data.frame() method. The method for draws takes no further
arguments and stops on unknown ones; the method for a fitted model warns
about them.
prior draws for numeric/data-frame inputs, or for numeric
draws a scalar BayesTools prior object (including mixture and
spike-and-slab priors). Quantity names in draw tables must be unique.
Ignored when posterior already contains deterministic prior density
information.
character vector with scalar hypothesis statements written
in the restricted grammar described in Details, or, for posterior draws and
marginal posteriors, a validated object from hypothesis_parse(). The method
for a fitted model takes character strings only and stops with the
BayesTools_hypothesis_statement condition for a parsed hypothesis.
optional scalar quantity name for numeric vectors or
marginal_posterior objects.
whether to display the Bayes factor on the log scale.
whether to display the inverse Bayes factor.
optional finite seed used by downstream helpers that sample. The caller's random-number generator state is restored after the call.
posterior density source for point-null tests.
"KDE" uses kernel density estimates. "normal" uses a normal
approximation to the posterior density at the null. "precomputed"
requires valid posterior_ordinate or posterior_density
metadata (posterior_metadata()) and errors if no valid precomputed
source is available. KDE
point-null tests use boundary reflection when exact support metadata is
attached to the marginal posterior or to matched posterior_density
metadata, and, for numeric draws with a prior object, at the bounds that
prior object declares (its truncation, or the support of its family) when
the draws lie within them; other numeric and data-frame expression tests
use standard Gaussian sample KDE. For numeric draws with a prior object that
declares point masses, the posterior ordinate is that of the absolutely continuous part:
the share of the draws not at a declared point-mass location times the KDE
of those draws. A point hypothesis on a linear expression of marginal-posterior
parameters or levels (sums, differences, and constant multiples, e.g.,
mu[B] - mu[A] = 0; functions and powers only of constants) is tested
as a Savage-Dickey ratio of that linear combination: the prior density and
exact support come from the joint prior context and the posterior ordinate
is the normal approximation ("normal") or the KDE with boundary
reflection at bounded supports (per mixture component, see
Savage_Dickey_BF). An affine expression of a numeric quantity with a
prior object uses the exact density of that transformed prior. Only
user-supplied prior draws use the sample KDE of the prior expression draws,
with a classed warning (see Value).
Finite sample and KDE evaluation ranges are not treated as exact support,
so finite point hypotheses outside those ranges use kernel-tail density
estimates.
output columns. "default" returns Alternative,
Null, BF, and BF_error. "all" also returns
prior, posterior, and method columns. The
prior and posterior columns are diagnostics, not always
probabilities: point tests report density heights, region tests report odds,
and transitive point-vs-region tests report NA. The default
BF_error column is printed as error%(BF). Individual columns
are selected by these column names; other spellings are rejected.
arguments of the method for a fitted model, passed to
hypothesis_BF_model(), which documents them: the component of the model
that the statements refer to (namespace: the formula parameter such
as "mu", "model", or "random"), the level of a factor
term that references to the term without a level stand for
(component, which combines with namespace), the scale
(transform_scaled = FALSE, the default, tests the fitted scale as in
JAGS_estimates_table()), the conditioning of the tested quantities on
their inclusion events, the settings of the density backend, and the number
of prior samples.
a hypothesis Bayes factor table.
optional row names for the complete exported frame.
logical; exported column names are always syntactic and unique.
A BayesTools table of class BayesTools_hypothesis_BF. The
BF_error column reports approximate relative Monte Carlo error
percentage when available. Region odds errors are computed on
log(BF) from prior/posterior region indicators using an iid
delta-method approximation on the flattened draws; they do not adjust for
MCMC autocorrelation. Prior region masses computed deterministically from a prior
object's distribution function contribute no Monte Carlo error.
Point-vs-region errors combine the available
point-density and region-mass errors on the log(BF) scale.
Point-null tests require a regular prior ordinate with finite log density at
the null value that prior_density_ordinate() classifies exactly from the
prior's structure, on every route. Otherwise they stop with a classed error
condition, which callers should match by class rather than by message:
BayesTools_point_mass_at_null (a prior point mass at the null),
BayesTools_infinite_ordinate, BayesTools_zero_ordinate,
BayesTools_undefined_ordinate, or BayesTools_inexact_ordinate
(no exact structural ordinate, e.g., a nonlinear expression of a
deterministic prior, a prior-density combination evaluated only on a
numerical grid, a structural quadrature rejected by its diagnostics,
or a density grid without recorded provenance). Each of
these conditions also has class BayesTools_hypothesis_ordinate.
For a whole-factor statement expanded into several quantities, known
ordinate errors produce an NA row with method "unavailable"
and the original reason; valid siblings are computed. Declared formula
measure refusals of class BayesTools_formula_measure_unavailable
behave likewise, preserving their original reason and diagnostics. Only
the declared formula-measure cause allow-list is localized; metadata,
refit, and programming errors propagate. Direct scalar and
explicitly indexed tests remain strict. Known numerical prior-region errors
behave likewise, with classes BayesTools_prior_region_mass_unavailable,
BayesTools_prior_region_route_unavailable,
BayesTools_prior_region_grid_unavailable, or
BayesTools_prior_region_probability_rejected, all also
BayesTools_hypothesis_region. Missing deterministic provenance for a
region remains a metadata error, including in whole-factor tables.
The specific BayesTools_transformation_image_unavailable leaf also
produces an unavailable whole-factor row with its reason; other
transformation and input errors remain strict. Scalar tests retain the
original refusal.
User-supplied prior draws (numeric or data-frame inputs without a prior
object) have no structural prior density: their prior ordinate is the
kernel (or normal) estimate of the prior expression draws, returned with a
warning of classes BayesTools_inexact_ordinate and
BayesTools_hypothesis_ordinate.
Region tests require positive prior mass for every compared region. An
implicit region statement is compared with its complement, which therefore
also needs positive prior mass. Independently evaluated complements remain
valid even when the other natural probability rounds to one. Explicit
comparisons such as
"theta > 0.5 vs theta > 0" accept an encompassing region with prior
mass one. Rows are labelled by quantity; when several statements refer to
the same quantity, the statement number is appended, e.g.
theta (2). A call cannot combine statements that reference explicit
levels of a factor (mu_fac[A] > 0) with statements that reference
the whole factor (mu_fac = 0); it stops with an error naming the
restriction, and the two kinds are evaluated in separate calls.
A symbolic comparison on both sides uses its centered scalar expression:
"theta = phi vs theta > phi" and
"theta - phi = 0 vs theta - phi > 0" are supported. Reversed spelling
"theta = phi vs phi < theta" remains conservatively unavailable;
use the supported orientation or centered spelling.
A reference to a quantity or level that posterior does not contain,
and a parameter that it does not contain, stop with an error of
class BayesTools_parameter_not_found (also
BayesTools_parameter_resolution_error), as unresolved selectors of
parameter_catalog_resolve() do; its fields alias and
available name the unresolved and the available references.
Level combinations require the same complete declared joint prior
context. Fixed reference levels use the shared typed ordinate refusals;
whole-factor requests retain results for eligible sibling levels.
Region Bayes factors are calculated from their canonical log ratios even
when intermediate diagnostic odds are outside the natural-scale range.
A transitive ratio with both a numerically zero posterior point ordinate and
zero posterior region mass is undefined and returns NA with a warning
recorded in the result.
The hypothesis language deliberately accepts only a small, non-programmable subset of R expressions:
hypothesis := statement [ "vs" statement ]
statement := point | region
point := arithmetic ( "=" | "==" | "!=" ) finite_number
region := relation
| "(" region ")"
| "!" region
| region ( "&" | "|" ) region
relation := arithmetic ( "<" | "<=" | ">" | ">=" ) arithmetic
Arithmetic expressions may contain parameter identifiers, finite numeric
literals, parentheses, +, -, *, /, ^,
and the one-argument functions abs(), exp(), log(),
sqrt(), plogis(), and qlogis(). Every constant
arithmetic subexpression must evaluate to one finite number. A point value
may be one finite numeric literal, optionally preceded by one unary sign, or
another parameter expression. Symbolic right-hand sides are normalized to a
difference from zero. Relations with a constant on the left and a parameter
expression on the right are normalized to the equivalent parameter-left
form.
Equality defines a point hypothesis and may appear only as the top-level
relation of a statement. It cannot be parenthesized inside, negated, or
combined as a region. Region relations may be parenthesized, negated, and
combined with the element-wise operators & and |;
&& and || are not supported. Backticks permit
non-syntactic parameter names. In particular, escaped identifiers such as
`Inf` refer to parameters, while unescaped Inf, NaN,
NA, TRUE, and FALSE are reserved literals and are
rejected. Whitespace-delimited vs (in any case) outside backticks is
the separator word of a hypothesis, so a parameter named vs is written
with backticks (`vs`), as hypothesis_render() writes it.
| Form | Status | Reason |
theta = -0.5 | accepted | point with a finite literal |
theta = phi | accepted | normalized to theta - phi = 0 |
0 > theta | accepted | normalized to theta < 0 |
(theta > 0) | accepted | parenthesized region |
!(theta > 0) | accepted | negated region |
theta > 0 & abs(phi) < 2 | accepted | combined regions |
`Inf` > 0 | accepted | escaped parameter identifier |
!(theta == 0) | rejected | point equalities cannot be negated |
theta = 1 + 1 | rejected | constant point value is not one literal |
theta > 0 && phi < 1 | rejected | scalar boolean operator |
sin(theta) > 0 | rejected | function outside the whitelist |
Prior region masses of deterministic prior densities use the structure that
prior_density_ordinate() classifies, for regions whose relations are
linear in the quantity (e.g., theta > 0, 2 * theta < 1, and
their combinations with &, |, and !): point masses
contribute their exact probability, scalar and normal-sum priors their
exact distribution functions, and Gaussian convolutions and
conditional-normal scale mixtures the conditional-normal quadrature of the
ordinate over the other term, split at the same breakpoints, with the
Gaussian peak (where the ordinate uses one) at every finite region bound;
mixture, model, and design-row components are summed with their
probabilities. A quadrature that fails its diagnostics, or evaluates to
exactly zero, stops with an error. Other prior densities and regions use the
prior-density grid, which resolves the region boundaries on that grid: a
boundary is located by bisection within each grid cell where the condition
changes, but region features narrower than the grid spacing may be missed.
Affine expressions retain an unshifted linear numerator and a checked
constant divisor. Point inference evaluates that numerator at the translated
null; diagnostic density heights retain the requested quantity units. Numerical
coefficient, boundary or log-ordinate resolution loss raises
BayesTools_hypothesis_numerical_unavailable (ordinate parent) or
BayesTools_hypothesis_region_numerical_unavailable (region parent), also
BayesTools_numerical_unavailable and BayesTools_numerical_condition.
The log-resolution screen is a conservative floating-point heuristic, not an
estimator or backend error bound. Finite log values may correspond to displayed
natural-scale zero or infinity. raw_log_BF and
numerical_diagnostics retain aligned diagnostics; BF formatting uses the
live column carrier, which replacement, arithmetic and Math operations invalidate.
Supported scalar affine and Boolean regions use deterministic prior laws
even when prior draws are available, as do regions over explicit factor
levels whose comparisons are all of one linear combination of the levels
(e.g., mu_fac[A] > mu_fac[B] + 0.5), which use the exact structural
mass of that combination. Unsupported regions (nonlinear expressions or
comparisons of different combinations, e.g., mu_fac[A] > 0 &
mu_fac[B] > 0) retain their sampled route, or their existing no-draw grid
route. Deterministic prior numerical
diagnostics (method, absolute error and convergence when available) can be
inspected with attr(result, "prior_numerical_diagnostics"); they are
row-aligned through subsetting. BF_error remains Monte Carlo-only and
omits prior Monte Carlo variance only for the actual deterministic route.
Accepted positive scalar prior-region probabilities retain their backend
log probabilities for canonical BF ratios, including positive subnormal
masses. Natural zero or non-finite prior masses remain unavailable.
Data-frame coercion returns a plain long frame with leading
component, parameter (the displayed row identity), and
warning fields. Statistical values retain full precision. Bayes-factor
names are BF10, BF01, logBF10, or logBF01
according to the displayed column attributes; BF_error retains its
existing percent relative-error units. Declared nonmissing bounds are in
BF_bound_operator. Unmatched/global warnings have component
"hypothesis/warnings". Compact printing retains its existing layout.
cbind() binds the displayed columns of hypothesis tables (with their
row names, at full precision) into a plain data frame.
hypothesis_BF(fit, "(mu) cor = 0.9", BF01 = TRUE, seed = 1) tests the
quantities of the parameter catalog (parameter_catalog()) of a fitted
model by the names that JAGS_estimates_table() shows, without backticks
(coefficients such as "x" or "x_fac[B]", random-effect
quantities such as "(mu) sd(intercept)" or "(mu) cor",
scalar parameters such as "sigma", and the total and the allocation
shares of an ordered term, "f{total}" and "f[share: mid]",
also by their earlier names "f_ordered_total" and
"f_ordered_allocation[mid]"), and statements with vs
work as for draws. The total of a spike-and-slab or mixture prior has a point
mass at its null: its point tests need conditional = TRUE, and the
total of a point prior is fixed by the model. On the original scale
(transform_scaled = TRUE) a total is tested when the scaling leaves
the coefficients of its term unchanged; the shares are unitless. A point null on a quantity with a prior point mass at
that value (a spike-and-slab coefficient at its spike) stops with
BayesTools_point_mass_at_null; conditional = TRUE tests the
quantity within its inclusion event, and region hypotheses work without it.
The fit method evaluates the Savage-Dickey density ratio
(Dickey 1971; Wagenmakers et al. 2010)
at the
posterior and prior ordinates of the tested quantity;
hypothesis_BF_model() describes the engine, its refusals, and the density
backends that evaluate point hypotheses (hypothesis_density_backend()).
The result is the same as extracting the quantity
(parameter_mixed_posterior() or as_mixed_posteriors() with
marginal_posterior()) and testing its draws.
Dickey JM (1971).
“The weighted likelihood ratio, linear hypotheses on normal location parameters.”
The Annals of Mathematical Statistics, 204–223.
doi:10.1214/aoms/1177693507
.
Wagenmakers E, Lodewyckx T, Kuriyal H, Grasman R (2010).
“Bayesian hypothesis testing for psychologists: A tutorial on the Savage-Dickey method.”
Cognitive Psychology, 60(3), 158–189.
doi:10.1016/j.cogpsych.2009.12.001
.