Model-average marginal posterior distributions and marginal Bayes factors

Source: R/marginal-inference.R

Creates marginal model-averaged and conditional posterior distributions based on a list of models, vector of parameters, formula, and a list of indicators of the null or alternative hypothesis models for each parameter. Computes inclusion Bayes factors for each marginal estimate via a Savage-Dickey density approximation.

marginal_inference(
  model_list,
  marginal_parameters,
  parameters,
  is_null_list,
  formula,
  null_hypothesis = 0,
  normal_approximation = FALSE,
  n_samples = 10000,
  seed = NULL,
  silent = FALSE,
  density_method = "KDE"
)

Arguments

model_list

list of models, each of which contains marginal likelihood estimated with bridge sampling marglik and prior model odds prior_weights

marginal_parameters

parameters for which the the marginal summary should be created

parameters

all parameters included in the model_list that are relevant for the formula (all of which need to have specification of is_null_list) Parameter keys must be unique, nonmissing and nonempty. Unnamed is_null_list entries bind positionally; complete unique names bind by key. Null masks are normalized before conditional model filtering.

is_null_list

list with entries for each parameter carrying either logical vector of indicators specifying whether the model corresponds to the null or alternative hypothesis (or an integer vector indexing models corresponding to the null hypothesis; use 0 or integer(0) when no models are null) Exact matching unique list names bind by parameter name; other ensemble lists retain positional order. Marginal inference requires unnamed lists or unique complete names matching its requested parameters.

formula

model formula (needs to be specified if parameter was part of a formula)

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.

n_samples

controls the numerical grid used for model-averaged prior densities (a grid has at least 16 points). It is not used when the samples carry a stored prior-density context. For a simple parameter, an explicitly attached prior_density is authoritative and is propagated instead of being reconstructed from prior_list.

seed

seed for random number generation. The caller's random-number state (.Random.seed and RNGkind()) is restored afterwards. With NULL, each model-averaging step draws its sampling seed from the caller's random-number stream.

silent

whether warnings should be returned silently. Defaults to FALSE

density_method

posterior density method used for Savage-Dickey Bayes factors. Currently only "KDE" is supported by marginal_inference() and as_marginal_inference() because generic model-averaged marginal posteriors do not have a well-defined precomputed density source.

Value

marginal_inference returns an object of class 'marginal_inference'.

Details

A parameter or level whose conditional marginal posterior has a declared point mass at the null hypothesis (e.g., the reference level of a treatment-coded factor, fixed at zero) gets an NA inclusion Bayes factor with the reason in its "warnings" attribute, which summary tables report; the other parameters and levels are computed. A parameter (scalar marginal) or level whose posterior ordinate is numerically unavailable (for example, a kernel estimate from identical draws) gets an NA inclusion Bayes factor with the reason in the same way.