Compute Savage-Dickey inclusion Bayes factors — Savage_Dickey

Computes Savage-Dickey (density ratio) inclusion Bayes factors based on the change of height from prior to posterior distribution at the test value.

Savage_Dickey_BF(
  posterior,
  null_hypothesis = 0,
  normal_approximation = FALSE,
  silent = FALSE,
  density_method = c("KDE", "precomputed")
)

Arguments

posterior: marginal posterior distribution generated via the marginal_posterior function
null_hypothesis: point null hypothesis to test. Defaults to 0
normal_approximation: whether the height of the posterior density at the null should be approximated via a normal distribution (rather than kernel density). The prior height is always the structural prior-density ordinate. Defaults to FALSE.
silent: whether warnings should be returned silently. Defaults to FALSE
density_method: density source for the posterior ordinate. "KDE" computes the Gaussian kernel density estimate at the null exactly (the kernel sum over the continuous draws, with bandwidth stats::bw.nrd0() of those draws; no evaluation grid or interpolation), using boundary reflection when exact posterior-support metadata is available. Finite sample ranges are not treated as exact support; Gaussian kernel tails are evaluated at finite null values. "precomputed" requires valid posterior_ordinate metadata when present, or otherwise valid posterior_density metadata (see posterior_metadata()). Posterior atom status must be declared through package-generated atoms metadata or posterior_atom_attribute(). An ordinary Savage-Dickey density ratio is rejected when atom status is unknown or when any positive atom is located exactly at the null. For a scalar marginal posterior, a positive atom at the null is an error; for a list of marginal posteriors (levels), such a level returns NA with the reason in its "warnings" attribute ("fixed at the null hypothesis value" for an atom of mass one, e.g., the reference level of a treatment-coded factor) and the other levels are computed. Declared atoms at other locations are removed from the continuous posterior ordinate and the resulting density is scaled by the remaining continuous mass.

Value

Savage_Dickey_BF returns a Bayes factor. The prior ordinate at the null follows the exactness rule of hypothesis_BF() point hypotheses, with the same condition classes: a prior point mass at the null value stops with an error of class BayesTools_point_mass_at_null, a zero, infinite or undefined ordinate with BayesTools_zero_ordinate, BayesTools_infinite_ordinate or BayesTools_undefined_ordinate, and an ordinate without an exact structural value (a prior-density combination evaluated only on a numerical grid, a quadrature rejected by its diagnostics, or a density grid without recorded provenance) with BayesTools_inexact_ordinate; each also has class BayesTools_hypothesis_ordinate. A declared posterior point mass at the null value of a scalar marginal posterior stops with an error of class BayesTools_posterior_point_mass_at_null (also BayesTools_hypothesis_ordinate). These conditions are errors of a direct scalar call only. For a list of marginal posteriors, and for the marginal posteriors of marginal_inference() and as_marginal_inference() (scalar marginals included), the Bayes factor of the affected parameter or level is NA instead, with the reason in its "warnings" attribute: for a posterior point mass at the null, for each of the five prior-ordinate conditions above (zero and infinite ordinates keep the reason text given in Details; the others, the message of their condition), and for a numerically unavailable posterior ordinate (BayesTools_hypothesis_numerical_unavailable, which the "numerical_diagnostics" attribute retains).

Details

Marginal posterior vectors may carry posterior_ordinate metadata with exact value and ordinate entries. When density_method = "precomputed" and normal_approximation = FALSE, a matching ordinate is used for the Savage-Dickey ratio. If no matching ordinate is available, a valid posterior_density grid with x and y coordinates is used. If neither valid precomputed source is available, an error is thrown. Exact support metadata is also checked before accepting precomputed posterior ordinates or densities; support is used to exclude the null only after it is validated against the posterior samples. A stale precomputed value is ignored when compatible exact support excludes the null; returned Bayes factors label this path as exact support exclusion rather than as a KDE estimate. Support is not inferred from prior-density grids, posterior-density grids, or plotting ranges, which may be finite numerical integration ranges rather than true support boundaries. Exact support metadata is created with posterior_support_attribute() (exact = TRUE); type = "points" support is not treated as a continuous interval for KDE boundary reflection. The same object may be supplied as support of posterior_density metadata. A prior density that is zero or infinite at the null makes the density ratio a 0/0 or singular limit that a kernel estimate of the posterior ordinate cannot estimate (e.g., with a log-singular prior the posterior carries the same singularity and the true ratio is a finite limit): a scalar call stops (see Value), and for a list of marginal posteriors (levels) such a level returns NA with the reason in its "warnings" attribute ("The prior density at the null hypothesis value is zero" or "infinite") and the other levels are computed.

Marginal posteriors created by marginal_posterior() record the mixture component of each draw and each component's exact support: the model for mix_posteriors() ensembles, and, for single fits with mixture or spike-and-slab priors (as_mixed_posteriors()), the combination of the component indicators of the terms entering the parameter or level. When continuous components have different exact supports (for example, a truncated prior in only some models or mixture components), the KDE posterior ordinate is estimated per component and mixed by the components' shares of the continuous draws: each component's ordinate uses its own support (zero when the support excludes the null, the one-sided limit on a support bound, as for the prior ordinate). The "posterior_density_components" attribute of the Bayes factor lists the components. When all continuous components share their support, the pooled KDE is used.

When the null hypothesis lies outside the continuous posterior draws (and is not an exact support bound), the KDE posterior density at the null is an extrapolation from Gaussian kernel tails. The finite Bayes factor is then returned with the warning that the density ratio is likely to be overestimated; for a model mixture, only the draws of models whose support contains the null count. Diagnostic messages are stored in the "warnings" attribute of each Bayes factor and, unless silent = TRUE, emitted once per parameter or level. The warnings of the conditions that are reported as NA (a posterior point mass at the null, a zero or infinite prior ordinate) are prefixed with the rendered label of the level, as in the rows of the marginal summary tables (for example theta[A] or, for a level of the formula parameter mu, (mu) x[A]); the warning table of marginal_estimates_table() prefixes the warnings that 0.3.0 reported with the fitted parameter instead.

The KDE posterior ordinate needs at least two finite continuous draws with positive spread (unless exact support excludes the null). With fewer, or with identical draws, a scalar call stops with BayesTools_hypothesis_numerical_unavailable, and a level of a list, and a parameter or level of marginal inference (a scalar marginal included), gets an NA Bayes factor with the reason. The same holds on the per-component route, for the pooled continuous draws and for each component whose support contains the null and that has several identical draws (a component with a single draw uses the pooled bandwidth).

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.