Package {BayesTools}

Title:	Tools for Bayesian Analyses
Version:	0.4.0
Description:	Provides tools for conducting Bayesian analyses and Bayesian model averaging (Kass and Raftery, 1995, <doi:10.1080/01621459.1995.10476572>, Hoeting et al., 1999, <doi:10.1214/ss/1009212519>). The package contains functions for creating a wide range of prior distribution objects, mixing posterior samples from 'JAGS' and 'Stan' models, plotting posterior distributions, and etc... The tools for working with prior distribution span from visualization, generating 'JAGS' and 'bridgesampling' syntax to basic functions such as rng, quantile, and distribution functions.
Maintainer:	František Bartoš <f.bartos96@gmail.com>
URL:	https://fbartos.github.io/BayesTools/
BugReports:	https://github.com/FBartos/BayesTools/issues
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
SystemRequirements:	JAGS (>= 4.3.0, < 5.0.0) (https://mcmc-jags.sourceforge.io/)
NeedsCompilation:	yes
Depends:	R (≥ 4.3.0), stats
Imports:	graphics, grid, extraDistr, mvtnorm, coda, bridgesampling, parallel, ggplot2, Rdpack, rlang (≥ 0.4.10), reformulas (≥ 0.2.0)
Suggests:	R6, scales, testthat (≥ 3.3.0), waldo, tibble, withr, vdiffr, covr, digest, knitr, pkgload, rstan, brms, rjags, runjags, lme4 (≥ 2.0-1), BayesFactor, RoBMA, rmarkdown
RdMacros:	Rdpack
VignetteBuilder:	knitr
Config/testthat/edition:	3
Packaged:	2026-11-03 13:43:22 UTC; fbart
Author:	František Bartoš [aut, cre]
Repository:	CRAN
Date/Publication:	2026-11-03 23:00:37 UTC

BayesTools

Description

BayesTools: Provides tools for conducting Bayesian analyses. The package contains functions for creating a wide range of prior distribution objects, mixing posterior samples from JAGS and Stan models, plotting posterior distributions, and etc... The tools for working with prior distribution span from visualization, generating JAGS and bridgesampling syntax to basic functions such as rng, quantile, and distribution functions.

Details

Random-effect operations use the BayesTools.random_effects_memory_limit_bytes option as a deterministic pre-allocation guard. The default is 16 * 1024^3 bytes (16 GiB). The estimate includes the primary numeric payload, simultaneous working copies, row maps, group state, and covariance state known before allocation. Set a different positive byte ceiling with options(BayesTools.random_effects_memory_limit_bytes = value). Experts may explicitly use Inf to disable the guard after verifying the operation's memory budget. Passing the guard does not promise that an allocation will succeed because R, JAGS, and the operating system have additional memory requirements. An operation above the ceiling stops with an error of class BayesTools_random_effects_memory_limit (also BayesTools_random_effects_error) whose fields operation, peak_bytes, and limit_bytes report the estimate.

Author(s)

František Bartoš f.bartos96@gmail.com

See Also

Useful links:

• https://fbartos.github.io/BayesTools/

• Report bugs at https://github.com/FBartos/BayesTools/issues

Remove the carrier attributes of a Bayes factor

Description

Removes the private attributes with which a Bayes-factor carrier (see format_BF_from_log()) retains its canonical logarithms, so that the values can be stored in a plain data frame or compared as ordinary numbers.

Usage

BF_carrier_drop(x)

Arguments

Details

The names and the public attributes name, logBF, BF01, and bound_operator are kept. The class BayesTools_BF is kept only while a non-missing bound operator remains, as for the result of format_BF() on a plain vector. A numeric vector without carrier attributes is returned with the same rule applied to its class.

Value

BF_carrier_drop() returns x without its carrier attributes.

See Also

format_BF_from_log() format_BF()

Examples

BF <- format_BF_from_log(c(a = 2, b = 800))
names(attributes(BF))
names(attributes(BF_carrier_drop(BF)))

Create BayesTools ensemble summary tables

Description

Creates 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).

Usage

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
)

Arguments

Value

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.

See Also

ensemble_inference mix_posteriors BayesTools_model_tables

Load the BayesTools JAGS module

Description

Loads the package-shipped JAGS extension module that provides compiled distributions and helper functions used by generated BayesTools JAGS syntax.

Usage

BayesTools_load_JAGS_module(quiet = TRUE, warn = TRUE)

Arguments

Value

Invisibly returns TRUE when the module is loaded and FALSE otherwise.

Create BayesTools model tables

Description

Creates model summary based on a model objects or provides estimates table for a runjags fit.

Usage

model_summary_table(
  model,
  model_description = NULL,
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  remove_spike_0 = TRUE,
  short_name = FALSE,
  formula_prefix = TRUE,
  remove_parameters = NULL
)

runjags_estimates_table(
  fit,
  transformations = NULL,
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  conditional = FALSE,
  probs = c(0.025, 0.5, 0.975),
  remove_spike_0 = TRUE,
  transform_factors = FALSE,
  formula_prefix = TRUE,
  remove_inclusion = FALSE,
  remove_parameters = NULL,
  remove_formulas = NULL,
  keep_parameters = NULL,
  keep_formulas = NULL,
  return_samples = FALSE,
  transform_scaled = FALSE,
  remove_diagnostics = FALSE,
  diagnostic_columns = getOption("BayesTools.JAGS_estimates_diagnostic_columns", if
    (remove_diagnostics) "none" else "all"),
  random_effects_summary = c("standard", "full", "raw", "none"),
  simplify_names = FALSE,
  random_effects_metadata = FALSE,
  remove_random_effects = NULL,
  keep_random_effects = NULL,
  remove_random_structures = NULL,
  keep_random_structures = NULL
)

runjags_inference_table(
  fit,
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  formula_prefix = TRUE,
  logBF = FALSE,
  BF01 = FALSE,
  BF_diagnostics = FALSE,
  BF_diagnostic_columns = getOption("BayesTools.JAGS_BF_diagnostic_columns", if
    (BF_diagnostics) "all" else "none")
)

JAGS_estimates_table(
  fit,
  transformations = NULL,
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  conditional = FALSE,
  probs = c(0.025, 0.5, 0.975),
  remove_spike_0 = TRUE,
  transform_factors = FALSE,
  formula_prefix = TRUE,
  remove_inclusion = FALSE,
  remove_parameters = NULL,
  remove_formulas = NULL,
  keep_parameters = NULL,
  keep_formulas = NULL,
  return_samples = FALSE,
  transform_scaled = FALSE,
  remove_diagnostics = FALSE,
  diagnostic_columns = getOption("BayesTools.JAGS_estimates_diagnostic_columns", if
    (remove_diagnostics) "none" else "all"),
  random_effects_summary = c("standard", "full", "raw", "none"),
  simplify_names = FALSE,
  random_effects_metadata = FALSE,
  remove_random_effects = NULL,
  keep_random_effects = NULL,
  remove_random_structures = NULL,
  keep_random_structures = NULL
)

JAGS_inference_table(
  fit,
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  formula_prefix = TRUE,
  logBF = FALSE,
  BF01 = FALSE,
  BF_diagnostics = FALSE,
  BF_diagnostic_columns = getOption("BayesTools.JAGS_BF_diagnostic_columns", if
    (BF_diagnostics) "all" else "none")
)

JAGS_summary_table(
  model,
  model_description = NULL,
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  remove_spike_0 = TRUE,
  short_name = FALSE,
  formula_prefix = TRUE,
  remove_parameters = NULL
)

model_summary_empty_table(
  model_description = NULL,
  title = NULL,
  footnotes = NULL,
  warnings = NULL
)

runjags_estimates_empty_table(
  probs = c(0.025, 0.5, 0.975),
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  remove_diagnostics = FALSE,
  diagnostic_columns = getOption("BayesTools.JAGS_estimates_diagnostic_columns", if
    (remove_diagnostics) "none" else "all")
)

runjags_inference_empty_table(
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  logBF = FALSE,
  BF01 = FALSE,
  BF_diagnostics = FALSE,
  BF_diagnostic_columns = getOption("BayesTools.JAGS_BF_diagnostic_columns", if
    (BF_diagnostics) "all" else "none")
)

JAGS_estimates_empty_table(
  probs = c(0.025, 0.5, 0.975),
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  remove_diagnostics = FALSE,
  diagnostic_columns = getOption("BayesTools.JAGS_estimates_diagnostic_columns", if
    (remove_diagnostics) "none" else "all")
)

JAGS_inference_empty_table(
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  logBF = FALSE,
  BF01 = FALSE,
  BF_diagnostics = FALSE,
  BF_diagnostic_columns = getOption("BayesTools.JAGS_BF_diagnostic_columns", if
    (BF_diagnostics) "all" else "none")
)

stan_estimates_table(
  fit,
  transformations = NULL,
  title = NULL,
  footnotes = NULL,
  warnings = NULL
)

Arguments

Details

For product-space JAGS inclusion Bayes factors, posterior inclusion probabilities of exactly 0 or 1 cannot produce a finite point estimate of the model odds ratio. In that case, inclusion BFs marked with "<" or ">" are finite-sample bounds: posterior inclusion probabilities of 0 or 1 were replaced by 1/S or (S - 1)/S, where S is the number of posterior samples. This is a reporting convention, not an unbiased finite Bayes-factor estimate. If the prior inclusion probability is exactly 0 or 1, the inclusion Bayes factor is undefined and reported as NA, because the corresponding inclusion/exclusion comparison was not tested.

The inference table has a row for every spike-and-slab and mixture prior, for the spike-and-slab total of an ordered-factor prior (reported under the term label), and for every random-effect inclusion gate.

An original-scale random-effect correlation is defined in a posterior draw whenever both of its SDs are positive, including draws with a singular covariance (for example, a zero scaled intercept SD with a nonzero scaled slope SD gives an intercept-slope correlation of \pm 1). It is missing in draws with a zero SD (for example, an excluded spike-and-slab SD of a scaled slope). The affected rows are summarized over the defined draws, and a table footnote reports the share of defined draws for each affected row. Raw Cholesky and LKJ-primitive coordinates (random_effects_summary = "raw") exist only for positive-definite correlation matrices and are also missing in singular draws.

Value

model_summary_table returns a table with overview of the fitted model, runjags_estimates_table returns a table with MCMC estimates, and runjags_estimates_empty_table returns an empty estimates table. All of the tables are objects of class 'BayesTools_table'. The estimates table carries 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 of the quantity the row's label names, its canonical name or an exact alias such as a transformed factor level <parameter>[dif: level]; "" for rows that are not catalog quantities, such as inclusion rows, mixture components, backend coordinates, fitted random-effect summaries whose catalog quantity is on the original scale, ordered-factor allocation shares, and rows whose values transformations changed, whose label parts record the transformation as "custom"), and label_parts (the label parts the row label is rendered from; parameter_labels() renders them, also with another formula parameter or random-effect quantity names). With transform_scaled = TRUE, the rows of standardized coefficients (including the exponentiated log intercept, an alias of the intercept) show their catalog quantity on the original predictor scale. Subsetting the table subsets its quantity table.

See Also

BayesTools_ensemble_tables

Add 'JAGS' prior

Description

Adds priors to a 'JAGS' syntax.

Usage

JAGS_add_priors(syntax, prior_list)

Arguments

Details

Syntax containing moment, inverse-moment, or inverse-gamma priors (dbt_invgamma) uses the BayesTools JAGS module. JAGS_fit() loads this module automatically; users running syntax returned by JAGS_add_priors() directly in JAGS need to load the module first.

Value

JAGS_add_priors returns a JAGS syntax.

Compute marginal likelihood of a 'JAGS' model

Description

A wrapper around bridge_sampler that automatically computes likelihood part dependent on the prior distribution and prepares parameter samples. log_posterior must specify a function that takes a named parameter list, the data, and any additional arguments, and returns the log likelihood of the model part.

Usage

JAGS_bridgesampling(
  fit,
  log_posterior,
  data = NULL,
  prior_list = NULL,
  formula_list = NULL,
  formula_data_list = NULL,
  formula_prior_list = NULL,
  formula_scale_list = NULL,
  add_parameters = NULL,
  add_bounds = NULL,
  maxiter = 10000,
  silent = TRUE,
  formula_random_prior_list = NULL,
  formula_random_effects_compile_list = NULL,
  formula_random_effects_marginalize_list = NULL,
  bridge_context = FALSE,
  bridge_context_node_names = NULL,
  repetitions = 1L,
  method = c("normal", "warp3"),
  nonfinite = c("error", "drop"),
  cores = 1,
  seed = NULL,
  ...
)

Arguments

Details

Row-shaped external random-effect SD sources, such as random_sd_source("tau", shape = "row"), must be reconstructable during bridge sampling. A source computed from other parameters, for example tau[i] <- s * tau_data[i], is deterministic and must be supplied as parameter_source("tau", shape = "row", values = function(parameters, data, n_rows) ..., inputs = ...). The values function is evaluated from the parameters it declares in inputs and the original-scale formula data stored at fit time; it must return finite, non-negative row values on the support of the model. Any callback data must therefore be included in formula_data_list when fitting. Data supplied only to JAGS_bridgesampling() do not extend or replace the fitted source snapshot. Posterior columns named tau[1], ..., tau[n] with non-negative lower bounds in add_bounds are valid only when every tau[i] is a free stochastic node whose prior density log_posterior adds. Supplying deterministic nodes as bridge coordinates makes the target improper; such rank-deficient bridge coordinate draws are rejected with an error. Rank is checked both on the supplied coordinates before bound transformations and on the transformed coordinates used by the proposal. Each rank check rescales a local diagnostic copy of finite, nonzero columns before standardization to avoid variance overflow or underflow. Supplied coordinates and sampler bounds retain their original values. Constant columns retain their existing sampler handling.

If every bridge coordinate is fixed by a point prior, JAGS_bridgesampling() evaluates log_posterior once at the reconstructed fixed parameter values. The returned marginal likelihood is exact and uses the aggregation rule "exact_zero_dimensional"; no bridge repetitions are performed. A target that declares no coordinate at all (no non-formula prior, formula prior, or add_parameters entry, for example raw draws with prior_list omitted) is an error of class BayesTools_marglik_input, not an exact evaluation.

use_neff is passed to bridge_sampler as the logical flag that upstream defines. bridgesampling computes the effective sample size itself, from the merged integrand matrix, and accepts no caller-supplied value: a numeric use_neff is a length-⁠>1⁠ condition upstream and aborts the sampler. Per-chain effective sample sizes therefore cannot be injected here; the merged-chain ESS is conservative, because concatenating chains that have not mixed inflates the estimated autocorrelation and so lowers the ESS.

When bridge_context = TRUE, the callback receives an object of class BayesTools_bridge_context with fields state, state_matrix, nodes, prior_parameters, formula_prior_parameters, formula_parameters, add_parameters, random, marginalized_random, node_info, and metadata. The state field contains the independent bridge coordinates and the completed fixed-zero random-effect latents (latent coordinates of fixed-zero blocks, which are not bridge dimensions). The add_parameters field contains only the add_parameters supplied by the caller: the coordinates BayesTools adds for formula random effects (standardized latent effects and correlation primitives) are not additional parameters, so a callback that adds densities for additional parameters does not count them twice. They are part of state and nodes, and node_info labels them source = "random_latent", owner = "formula", role = "random_latent". The nodes field is a flat named numeric vector that also includes deterministic BayesTools-resolved nodes such as normalized Dirichlet allocation weights reconstructed from ⁠prior_par_eta_*⁠ coordinates. The node_info field records the owner and role of each exposed node. The random field contains structured random-effect block state including resolved SDs, allocation weights, correlations, Cholesky factors, covariance matrices where row-invariant, and row-indexed SD source values where applicable. Each random block is keyed by formula parameter and block name, and contains block_name, compile_mode, dimensions, levels, scale, allocation, correlation, covariance, latent, and nodes fields.

When bridge_context = "nodes", the callback receives an object inheriting from BayesTools_bridge_context with only the nodes field. Its values and names are identical to the nodes field in the complete context for the same bridge state. Random-effect replay metadata that is invariant across states is compiled once before bridge sampling.

When bridge_context = "marginal", the callback receives the same exact nodes vector plus marginalized_random. If bridge_context_node_names is supplied, nodes is the requested exact subset in the requested order. The latter is keyed by formula parameter and contains representation, blocks, structures, row_names, and dimension. Without row_blocks, representation = "dense" and the covariance field equals the sum of ZGZ' over exactly the requested random-effect blocks. With validated row_blocks, representation = "factor"; row_blocks gives the exact observation partition and factors contains dense, ordinary grouped Z_b G_b Z_b', or known-group covariance factors. This avoids materializing zero cross-block entries. For requests with factor_state = TRUE, the marginal context instead reports representation = "factor_state", with invariant factor_plans and draw-varying factor_states; the complete context and direct covariance evaluator retain the full representation. All representations define the same covariance without approximation.

Value

A BayesTools_marglik object that also has the class bridge of released versions, so that bridgesampling::bf(), post_prob() and logml() apply to it. For a single repetition, niter and method of the upstream result are kept at the top level, and the result prints as that object did (one line added when maxiter was exceeded). Failed, manual, exact and repeated results print a BayesTools summary. summary() and bridgesampling::error_measures() of a result forward to the sampler result stored in diagnostics$upstream (the bridge summary and error measures of one repetition, the bridge_list ones of repetitions); a failed, manual or exact result stores none and stops with an error of class BayesTools_marglik_sampler_result_unavailable (parent BayesTools_marglik_unavailable). logml is one scalar natural-log marginal likelihood, aggregated as the median of finite repetition-level log marginal likelihoods. repetitions contains one diagnostic row per bridge repetition, aggregation records the aggregation and failure policy, and diagnostics$upstream retains the original bridgesampling result. Top-level success records estimate availability. The separate logical iteration_limit_exceeded is TRUE when any known repetition count exceeds maxiter, FALSE when all counts are known and none exceeds it, and NA when counts are unavailable or partly unknown without a known excess. Manual/imported and exact zero-dimensional results have NA; historical schema-1 objects may omit the field, meaning unavailable telemetry. This flag does not assert convergence: counts can include upstream retries, including a successful retry whose total count exceeds maxiter.

The columns of repetitions are repetition, logml, niter (iterations used), mcse (Monte Carlo standard error of logml), finite (whether logml is finite), within_maxiter (whether niter did not exceed maxiter; TRUE when the iteration count is unknown), success (finite and within_maxiter), warning and error (the description of an exceeded iteration limit or of a non-finite estimate, NA otherwise), method, n_chains, and n_draws. Only non-finite repetitions are excluded from the aggregate, so aggregation$n_included counts the finite repetitions: a finite repetition that exceeded maxiter has success = FALSE and is still aggregated. Known excess counts always warn with class BayesTools_marglik_iteration_limit (parent BayesTools_marglik_diagnostic; fields repetitions, the affected diagnostic rows, maxiter, and upstream_warnings). A flagged result also prints a visible iteration-count diagnostic. Finite aggregation and top-level success availability are unchanged; legacy repetition success and within_maxiter retain their unknown-count convention.

Rank refusals have class BayesTools_marglik_rank_deficiency (parent BayesTools_marglik_input), with fields reason, rank, n_coordinates, n_draws, and dependent_coordinates. These describe the finite, varying diagnostic sample checked by the existing QR tolerance. The reason "insufficient_draws" means that n_draws <= n_coordinates prevents full centered rank; "dependent_coordinates" means observed numerical rank loss despite a sufficient raw row count. These observations are nonexclusive and neither certifies a structural cause or a guaranteed remedy. Duplicate rows remain counted. Coordinate names are the complete, basis-dependent QR-pivot tail when available, otherwise character(0); they do not identify uniquely faulty or deterministic nodes.

Condition classes: a non-finite repetition under nonfinite = "error", and the absence of any finite repetition under "drop", stop with an error of class BayesTools_marglik_repetition_failure (fields repetitions, the failed rows, and upstream_warnings). Errors of the likelihood callback keep their own classes and fields, with the ⁠Bridge sampling failed:⁠ context in the message and the muffled warnings in upstream_warnings. A state outside the support of the model (for example an out-of-support row-indexed random-effect SD source value) signals an error of class BayesTools_marglik_out_of_support while the parameters are reconstructed; the bridge target treats it as zero density, and the direct reconstruction functions (such as JAGS_marglik_parameters_formula()) let it escape. The two classes belong to no shared parent class; callers match the class, not the message.

A NA returned by log_posterior on the sampler route is no density. At a posterior draw the model cannot be evaluated where it was sampled: the call stops with an error of class BayesTools_marglik_callback_na (parent class BayesTools_marglik_input; field n_posterior_na, the number of affected posterior draws, and upstream_warnings). At a proposal draw the NA is evaluated as -Inf (zero density) and the call signals a warning of the same classes that reports the share of proposal draws (fields n_proposal_na and n_proposal); the estimate and its success are not otherwise affected. The counts are those that bridgesampling reports for the replaced evaluations. The exact zero-dimensional evaluation and NA priors keep their own errors.

This policy is defined for method = "normal"; method = "warp3" is outside it. bridgesampling evaluates the callback at warped draws and takes their exponentials in extended-range arithmetic, which stops on an NA with the unclassed upstream error "Bridge sampling failed: NAs are not allowed in subscripted assignments" (no BayesTools_marglik_callback_na), and the warnings that it words for warp3 evaluations are not classified either. A callback used with warp3 must not return NA.

Examples

## Not run: 
# simulate data
set.seed(1)
data <- list(
  x = rnorm(10),
  N = 10
)
data$x

# define priors
priors_list <- list(mu = prior("normal", list(0, 1)))

# define likelihood for the data
model_syntax <-
  "model{
    for(i in 1:N){
      x[i] ~ dnorm(mu, 1)
    }
  }"

# fit the models
fit <- JAGS_fit(model_syntax, data, priors_list, seed = 1)

# define log posterior for bridge sampling
log_posterior <- function(parameters, data){
  sum(dnorm(data$x, parameters$mu, 1, log = TRUE))
}

# get marginal likelihoods
marglik <- JAGS_bridgesampling(
  fit, log_posterior, data, priors_list, seed = 1
)

## End(Not run)

Prepare 'JAGS' posterior for 'bridgesampling'

Description

prepares posterior distribution for 'bridgesampling' by removing unnecessary parameters and attaching lower and upper bounds of parameters based on a list of prior distributions.

Usage

JAGS_bridgesampling_posterior(
  posterior,
  prior_list,
  add_parameters = NULL,
  add_bounds = NULL
)

Arguments

Value

JAGS_bridgesampling_posterior returns a matrix of posterior samples with 'lb' and 'ub' attributes carrying the lower and upper boundaries.

Check and list 'JAGS' fitting settings

Description

Checks and lists settings for the JAGS_fit function.

Usage

JAGS_check_and_list_fit_settings(
  chains,
  adapt,
  burnin,
  sample,
  thin,
  autofit,
  parallel,
  cores,
  silent,
  seed,
  check_mins = list(chains = 1, adapt = 50, burnin = 50, sample = 100, thin = 1),
  call = ""
)

JAGS_check_and_list_autofit_settings(
  autofit_control,
  skip_sample_extend = FALSE,
  call = ""
)

Arguments

Value

JAGS_check_and_list_fit_settings invisibly returns a list of checked fit settings. JAGS_check_and_list_autofit_settings invisibly returns a list of checked autofit settings.

Assess convergence of a runjags model

Description

Checks whether the supplied runjags-package model satisfied convergence criteria. Derived-draw views are refused with BayesTools_draws_view_inference_unavailable (also BayesTools_draws_view_unavailable); assess fit$original_fit.

Usage

JAGS_check_convergence(
  fit,
  prior_list = NULL,
  max_Rhat = 1.05,
  min_ESS = 500,
  max_error = 0.01,
  max_SD_error = 0.05,
  add_parameters = NULL,
  fail_fast = FALSE,
  check_indicators = FALSE,
  monitor = NULL,
  allow_not_assessable = FALSE
)

Arguments

Details

JAGS_fit() assigns every fitted coordinate one convergence role, stored in the convergence_role column of parameter_coordinates() and derived from the declared model, never from the draws:

"sampled"

stochastic parameters, including the user's add_parameters that depend on a stochastic node; checked by default.

"indicator"

declared model indicators of mixture, spike-and-slab, and variance-allocation priors; checked with check_indicators = TRUE.

"structural"

declared constants: point priors, one-state indicators, reference and fixed publication-weight bins, a p-hacking kind shared by every mixture branch, the point total of an ordered prior and the coefficients it fixes, unit correlation diagonals and Cholesky constants, monitored fully observed data, and monitored deterministic nodes (<- or =) whose ancestors in the model syntax are all data or constants. They are reported as "structural_constant".

"derived"

deterministic functions of sampled nodes that BayesTools generates for formulas (such as random-effect correlation matrices, their Cholesky factors, and derived latent effects or SDs) and point priors whose location is an expression; checked only when named in monitor.

"auxiliary"

inclusion probabilities and the backend anchor of models without monitored parameters, checked only when named in monitor, and private implementation nodes that the summary tables hide (such as Dirichlet gamma draws), which are never checked.

Mirrored two-sided publication-weight bins are hidden in the same way. The default selection (monitor = NULL) consists of the sampled and structural parameters, and of the indicators when check_indicators is set. Automatic fitting in JAGS_fit() and JAGS_extend() uses the same selection.

Value

JAGS_check_convergence returns a boolean indicating whether all requested, assessable parameters satisfy the enabled criteria. An explicitly empty monitor returns logical(0) rather than claiming convergence. When no parameters remain available (empty sample columns and no structural parameters) or the selection is empty, the function returns TRUE: there is nothing assessable, which is treated as vacuously satisfied. The diagnostics attribute contains one row per available parameter and classifies it as "assessable", "structural_constant", "not_assessable", "not_requested", or "not_checked" when fail_fast = TRUE stops before reaching that parameter. Its Rhat column is the larger of the point estimate and the upper confidence limit of the potential scale reduction factor (see max_Rhat). The errors attribute carries the failed checks: one message per failed criterion, with the most extreme value, as in BayesTools 0.3.0 (for example "R-hat 1.234 is larger than the set target (1.05)."), followed by the sentence "Failing parameters: 'mu', 'tau'." that names the failing parameters (the first five and the number of the others), and one message for every parameter whose enabled diagnostics are not assessable.

See Also

JAGS_fit() parameter_coordinates()

Examples

## Not run: 
# simulate data
set.seed(1)
data <- list(
  x = rnorm(10),
  N = 10
)
data$x

# define priors
priors_list <- list(mu = prior("normal", list(0, 1)))

# define likelihood for the data
model_syntax <-
  "model{
    for(i in 1:N){
      x[i] ~ dnorm(mu, 1)
    }
  }"

# fit the models
fit <- JAGS_fit(model_syntax, data, priors_list)
JAGS_check_convergence(fit)

## End(Not run)

Generated deterministic nodes

Description

JAGS_deterministic_nodes() lists the deterministic nodes that BayesTools generates in the JAGS model of a fit (other than the internal intermediates of random-effect blocks, which the random-effect reconstruction recomputes), with the family that defines them, the coordinates they produce, and the coordinates they are computed from. JAGS_evaluate_deterministic() recomputes their values from draws of those coordinates. JAGS_deterministic_evaluator() resolves the nodes of a fit once and returns a function that evaluates them on draws, for repeated evaluations (e.g. one draw at a time).

Usage

JAGS_deterministic_nodes(fit)

JAGS_evaluate_deterministic(fit, draws = NULL, nodes = NULL)

JAGS_deterministic_evaluator(fit, nodes = NULL)

Arguments

Details

Each generated node belongs to one family, which defines both the JAGS syntax of the node and the R evaluator used everywhere BayesTools needs its value (prior draws, parameter-catalog quantities, bridge sampling, marginal-likelihood parameters, prediction, marginal posteriors of formula parameters, random-effect unscaling, and convergence roles):

"random_sd"

random-effect SDs derived from a variance allocation (random_variance_allocation()): the source SD (the allocation's own SD or an external scalar SD source) times the chain of allocation factors from the root allocation, sqrt(w[i]) (total variance) or sqrt(K * w[i]) (mean variance) of the Dirichlet weights and the inclusion gates. The family also contains the parent allocation components that a child allocation splits further.

"random_rho"

scalar correlations of structured random-effect blocks sampled on the Fisher-z (rho = tanh(z)) or logit scale (rho = lower + (upper - lower) * plogis(z)).

"lkj"

the Cholesky factor L, the correlation matrix R = L L^T (with an exact unit diagonal), and the monitored partial correlations cpc = 2 u - 1 of an LKJ-Cholesky block, computed from its primitives u with the kernel of the BayesTools JAGS module.

"omega"

the publication weights of a weight-function prior (alone, as the selection of prior_bias(), or as branches of a publication-bias mixture) on the one-sided global p-value bins, with the bins of two-sided weight functions mirrored. The dependencies are the free coordinates of the weights (eta, the monitored omega[2] of a binary cumulative weight function, or the independent omega or log_omega); mixture branches are read from their own component nodes and the bias_indicator.

"phacking"

the nodes of the p-hacking branches of a prior_phacking(), prior_bias(), or publication-bias mixture prior (experimental): the form code phack_kind, the null masses pi_null = alpha * a and beta_null = alpha * b with the constants of the form, the z geometry phack_z_source and phack_z_dest, and the sel_vector_rule of the selection kernel. A publication-bias mixture composes them from its branches (zeros for a branch without p-hacking) and the bias_indicator, and adds the severity alpha composed from the component severities alpha_component_k. pi_null and beta_null are computed from the coordinate alpha, so a fit that monitors it needs no component severities.

"prior_mixture"

parameters with spike-and-slab (p = p_variable * p_indicator) or mixture priors (p = sum_k p_component_k * (p_indicator == k)), and the PET and PEESE terms of publication-bias mixtures (PET <- PET_1 * equals(bias_indicator, k)), per coefficient of factor priors. Only the components that are active in some draw need to be available; literal point components are constants. Multi-slice ordered spike totals use indexed slab sources and one shared inclusion state.

"prior_dirichlet"

the coordinates of an ordinary Dirichlet prior, theta[i] = eta[i] / sum(eta), from its gamma auxiliaries eta. The Dirichlet weights of a variance allocation belong to the allocation family.

"prior_mt"

the coordinates of a multivariate-t prior (also of an orthonormal or meandif multivariate-t factor, or of a component of a mixture), theta[i] = z[i] / sqrt(s) + location, from the normal coordinates z and the scale coordinate s. A location that is an expression leaves the node unavailable to the evaluator.

"ordered_allocation"

normalized Gamma coordinates of an ordered allocation. Gamma values take precedence over supplied normalized weights. Replay accepts nonnegative Gamma values with a positive row sum; bridge stochastic-source checks retain their positive-coordinate rule.

"ordered_coefficient"

each ordered increment from its declared total slice and factor allocations. Shared allocation keys have one node.

"point_expression"

scalar expression-valued formula point coefficients and their declared expression-point parents. Replay uses the retained location AST, owned data, and available declared parents. It replaces stale coefficient monitors before dependent formula replay. A coefficient monitor can supply a formula when its parents are absent; that coefficient is then unavailable for explicit recomputation.

"linear_predictor"

the linear predictor of a formula parameter on the fitted rows: the intercept (or its logarithm), the continuous and factor terms with their multiply_by multipliers, the expression() terms, and the contributions of the sampled random-effect blocks, evaluated with JAGS_evaluate_formula(). It is evaluated only by JAGS_evaluate_deterministic(), and only when the standardized latent effects of the sampled blocks are among the draws. A block whose SDs come from a row-shaped external source (random_sd_source(..., shape = "row")) depends on the source rows source[1], ..., source[N], or, when the source's values function reconstructs them, on the inputs that function declares (parameter_source(inputs = )), and on the Dirichlet weights and inclusion gates of its allocation.

Nodes are evaluated with the arithmetic of the R evaluator, which reproduces the JAGS monitors exactly or to the last bits of floating-point rounding. Successful parent outputs replace stale derived columns before dependent nodes are evaluated, for every family. Point coefficient replay uses the bounded formula-expression arithmetic subset, requires one finite scalar per draw, and does not bind the loop index i. Unsupported replay syntax retains valid fitting and monitored-value routes, and reports BayesTools_formula_point_unavailable when replay is requested. Missing affected declaration ownership requires refitting.

Value

JAGS_deterministic_nodes() returns a data frame with one row per node and the columns node (node name), family, parameter (the formula parameter or prior name the node belongs to), block (the random-effect block, NA otherwise), coordinates and dependencies (list columns of coordinate names), and monitored (whether all coordinates of the node are monitored in fit).

JAGS_evaluate_deterministic() returns a numeric matrix with one row per draw and one column per coordinate of the evaluated nodes.

JAGS_deterministic_evaluator() returns a function with one argument, draws (in the forms accepted by JAGS_evaluate_deterministic(); a named numeric vector for one draw), that returns the matrix JAGS_evaluate_deterministic(fit, draws, nodes) returns, with the nodes of fit resolved when the evaluator is created. JAGS_evaluate_deterministic() is this evaluator applied once.

See Also

JAGS_fit() parameter_coordinates() transform_prior_samples()

Plot diagnostics of a 'JAGS' model

Description

Creates density plots, trace plots, and autocorrelation plots for a given parameter of a JAGS model.

Usage

JAGS_diagnostics(
  fit,
  parameter,
  type,
  plot_type = "base",
  xlim = NULL,
  ylim = NULL,
  lags = 30,
  n_points = 1000,
  transformations = NULL,
  transform_factors = FALSE,
  short_name = FALSE,
  parameter_names = FALSE,
  formula_prefix = TRUE,
  ...
)

JAGS_diagnostics_density(
  fit,
  parameter,
  plot_type = "base",
  xlim = NULL,
  n_points = 1000,
  transformations = NULL,
  transform_factors = FALSE,
  short_name = FALSE,
  parameter_names = FALSE,
  formula_prefix = TRUE,
  ...
)

JAGS_diagnostics_trace(
  fit,
  parameter,
  plot_type = "base",
  ylim = NULL,
  transformations = NULL,
  transform_factors = FALSE,
  short_name = FALSE,
  parameter_names = FALSE,
  formula_prefix = TRUE,
  ...
)

JAGS_diagnostics_autocorrelation(
  fit,
  parameter,
  plot_type = "base",
  lags = 30,
  transformations = NULL,
  transform_factors = FALSE,
  short_name = FALSE,
  parameter_names = FALSE,
  formula_prefix = TRUE,
  ...
)

Arguments

Details

The trace shows the retained MCMC iteration of every draw on its x axis (thinned chains keep their original positions). Autocorrelation uses the retained original iteration positions. Requested lags without finite observation pairs, beyond the retained chain, or with nonfinite autocorrelation are retained as NA. One warning per parameter and chain has classes BayesTools_autocorrelation_unavailable and BayesTools_plot_condition, with parameter, chain, unavailable_lags, pair_count and reason fields. Computed x/y objects retain full-length pair_count and unavailability_reason attributes; both renderers display finite bars only. No iteration compression, replacement estimate or confidence band is introduced.

Coordinates whose convergence role is "structural" (see JAGS_check_convergence()) are constants of the prior: the weight bins that the prior fixes (for example by wf_fixed()) or the coefficients of an ordered prior with a point total and fixed allocation. The density and autocorrelation diagnostics omit them when their draws are constant, and when nothing else remains the call returns NULL with a message, as for a spike prior; the trace is produced as for any other parameter. A parameter with a prior_none() prior is not sampled: the call returns NULL with a message for every type.

Value

diagnostics returns either NULL if plot_type = "base" or an object/list of objects (depending on the number of parameters to be plotted) of class 'ggplot' if plot_type = "ggplot".

See Also

JAGS_fit() JAGS_check_convergence()

JAGS draw geometry and deterministic materialization

Description

JAGS_draw_geometry() returns the retained iteration and chain geometry stored from the actual chains returned by JAGS. Geometry is independent of which coordinates are public.

JAGS_materialize_draws() reconstructs requested coordinates from the fitted parameter map. Sampled coordinates are selected from the fitted chains and structural coordinates are filled with their exact fixed_value. Internal coordinates, including a private backend anchor, are excluded by default.

JAGS_with_draws() returns a derived-draw view with supplied draws and matching geometry, plus the complete untouched fit in original_fit. Views have class BayesTools_draws_view and BayesTools_fit, with only original_fit and mcmc slots. Nonruntime analysis attributes are copied; view-local changes do not modify the original. Replacing a view retains its original fit and current local analysis attributes without nesting views. Fit-level draw metadata and stored posterior densities/ordinates are cleared; attach fresh estimates with posterior_metadata() after replacement. A view supports descriptive estimates, diagnostic plots, mixed-posterior extraction and marginal inference from its supplied draws. It does not support original-model convergence, bridge sampling or sampling extension: use fit$original_fit and regenerate the view after extending that fit. These refusals have common class BayesTools_draws_view_unavailable, with leaves BayesTools_draws_view_sampling_unavailable (also BayesTools_sampling_unavailable) and BayesTools_draws_view_inference_unavailable. Missing requested sampled coordinates signal BayesTools_draws_view_coordinate_unavailable, with a missing field. Views need not contain every original sampled coordinate; prior-draw transformations retain their existing intersection-of-columns policy. coda::as.mcmc.list() preserves chain timing. coda::as.mcmc() pools in chain-major order with indices starting at one and thinning one; pooled indices do not describe a continuous MCMC trajectory.

Usage

JAGS_draw_geometry(fit)

JAGS_draw_geometry_schema()

JAGS_materialize_draws(fit, parameters = NULL, include_internal = FALSE)

JAGS_with_draws(fit, draws)

## S3 method for class 'BayesTools_draws_view'
as.mcmc.list(x, ...)

## S3 method for class 'BayesTools_draws_view'
as.mcmc(x, ...)

## S3 method for class 'BayesTools_draws_view'
print(x, ...)

Arguments

Value

JAGS_draw_geometry() returns a BayesTools_draw_geometry list. JAGS_draw_geometry_schema() returns field descriptions. JAGS_materialize_draws() returns a coda::mcmc.list, including a valid zero-column list when the fit has no public coordinate. JAGS_with_draws() returns a BayesTools_draws_view.

Evaluate JAGS formula using posterior samples

Description

Evaluates a JAGS formula on a posterior distribution obtained from a fitted model, through the formula design that JAGS_fit() stores for the formula parameter (the processed formula, factor levels and contrasts, and the standardization of predictors). Posterior or prior draws without a fit are evaluated through the same design, built by JAGS_formula_draws(). Fits created by BayesTools 0.3.0, which store no design, must be refitted: they stop with an error of class BayesTools_refit_required (see JAGS_validate_fit_contract()). Formula random effects can be evaluated for existing grouping levels when either standardized latent random effects and covariance hyperparameters were monitored via random_monitor(latent = TRUE), or the group-level coefficients were monitored via random_monitor(coefficients = TRUE); otherwise, and for random-effect blocks compiled as marginalized, conditional evaluation stops with an error of class BayesTools_refit_monitoring (also BayesTools_refit_required). In a random-effect block of a scalar-correlation structure (CS, HCS, AR1, HAR, or CAR) compiled group by group, the coefficients of index levels that a group does not have in the fitted data are drawn from their exact Gaussian conditional law given the observed levels. This draw is stochastic and follows set.seed(). Row-indexed external random-effect SD sources, such as random_sd_source("tau", shape = "row"), are evaluated from latent random effects only. Model generation automatically monitors the required latent effects for these blocks. The posterior samples must either contain source columns named tau[1], ..., tau[N]. When prediction data are supplied, fitted_rows must explicitly map each prediction row to its fitted observation index. Alternatively, the source must provide a parameter_source() values function for reconstructing row-wise source values from the posterior samples and supplied prediction data. An unavailable new-row evaluation of a posterior-indexed row source raises BayesTools_prediction_new_rows_unavailable (parent BayesTools_prediction_unavailable), with reason = "posterior_indexed_row_source", block, the displayed source label, affected prediction rows, and caller context. It applies where the source of the new rows is needed, under new_levels = "sample"; with new_levels = "zero" the new rows contribute zero and need no source. Missing or malformed mappings, invalid source values, and missing monitored columns retain their own errors. Literal expression() terms use the replayable subset documented by JAGS_formula() and are evaluated against prediction data using JAGS-style row indexing through i. Array expressions such as X[i, column[i]] pair the coordinates pointwise. Each index must contain finite positive integers within its array dimension; scalar indices repeat across a common nonzero vector length. One-index expressions retain ordinary vector indexing. Sampled parameter references are reconstructed separately for every posterior draw. Replaying a fitted formula restores the stored expression syntax, dependency classification, and fitted data snapshot. Supply an explicit expression-free formula to evaluate a selected subset without those offsets. Inline transformations, offsets, dot expansion, and arbitrary calls are not supported. Create transformed predictors as explicit columns in data. Selected existing terms retain fitted factor coding and variable order, including interactions requested with reversed variable order. Predictors outside the selected terms are not required. Expression-valued scalar point coefficients use valid monitors first, otherwise their retained declaration and owned model data. New prediction rows do not replace that owned data. Unsupported scalar replay, missing parents, cycles, and malformed values raise BayesTools_formula_point_unavailable; absent affected owners require refitting. This replay does not extend bridge prior-expression eligibility or establish a structural point law from constant draws.

Usage

JAGS_evaluate_formula(
  fit,
  formula = NULL,
  parameter,
  data = NULL,
  prior_list = NULL,
  formula_target = NULL,
  blocks = NULL,
  new_levels = NULL,
  fitted_rows = NULL
)

Arguments

Value

JAGS_evaluate_formula returns a matrix of the evaluated posterior samples on the supplied data.

See Also

JAGS_fit() JAGS_formula()

Fits a 'JAGS' model

Description

A wrapper around run.jags that simplifies fitting 'JAGS' models with usage with pre-specified model part of the 'JAGS' syntax, data and list of prior distributions.

Usage

JAGS_fit(
  model_syntax,
  data = NULL,
  prior_list = NULL,
  formula_list = NULL,
  formula_data_list = NULL,
  formula_prior_list = NULL,
  formula_scale_list = NULL,
  chains = 4,
  adapt = 500,
  burnin = 1000,
  sample = 4000,
  thin = 1,
  autofit = FALSE,
  autofit_control = list(max_Rhat = 1.05, min_ESS = 500, max_error = 0.01, max_SD_error =
    0.05, max_time = list(time = 60, unit = "mins"), sample_extend = 1000, restarts = 10,
    max_extend = 10, check_indicators = FALSE, monitor = NULL, allow_not_assessable =
    FALSE),
  parallel = FALSE,
  cores = chains,
  silent = TRUE,
  seed = NULL,
  add_parameters = NULL,
  required_packages = NULL,
  formula_random_prior_list = NULL,
  formula_random_effects_compile_list = NULL,
  jags_modules = NULL,
  runtime_setup = NULL,
  runtime_cache = NULL,
  worker_output = NULL,
  ...
)

JAGS_extend(
  fit,
  autofit_control = list(max_Rhat = 1.05, min_ESS = 500, max_error = 0.01, max_SD_error =
    0.05, max_time = list(time = 60, unit = "mins"), sample_extend = 1000, restarts = 10,
    max_extend = 10, check_indicators = FALSE, monitor = NULL, allow_not_assessable =
    FALSE),
  parallel = FALSE,
  cores = NULL,
  silent = TRUE,
  runtime_setup = attr(fit, "runtime_setup", exact = TRUE),
  runtime_cache = attr(fit, "runtime_cache", exact = TRUE),
  worker_output = NULL
)

Arguments

Value

JAGS_fit returns an object of class 'runjags' and 'BayesTools_fit'. JAGS_extend continues the backend random-number generator state of the existing chains; it does not reseed them. Stored parameter and RNG states initialize reconstruction; recompilation can reset sampler tuning and follows runjags' adaptation policy. The model is always recompiled from these stored states, never continued from a compiled model left in the session, so extending the same object twice, or a saved and reloaded copy of it, gives identical draws. Neither function keeps runjags' compiled rjags model (method.options$rjags) in the returned object; runjags::extend.jags() recompiles a model without it, as after reloading.

See Also

JAGS_check_convergence()

Examples

## Not run: 
# simulate data
set.seed(1)
data <- list(
  x = rnorm(10),
  N = 10
)
data$x

# define priors
priors_list <- list(mu = prior("normal", list(0, 1)))

# define likelihood for the data
model_syntax <-
  "model{
    for(i in 1:N){
      x[i] ~ dnorm(mu, 1)
    }
  }"

# fit the models
fit <- JAGS_fit(model_syntax, data, priors_list)

## End(Not run)

JAGS formula name map and fitted-object contract

Description

JAGS_formula_name_map() returns the persisted mapping between opaque JAGS base names and semantic formula coordinates (kind, formula parameter, term and role), with an injective encoded identifier of those fields. The identifier does not replace the backend column name stored in a fit. Downstream code should use this map or parameter_coordinates() rather than parsing a JAGS name.

JAGS_fit_contract() returns the schema contract attached to a fit. JAGS_validate_fit_contract() checks the components named in requires and requires unsupported objects to be refitted rather than adapted.

Every error that asks to refit the model has class BayesTools_refit_required: these validators, and every function that reads fitted metadata, stop with it on a fit (or stored metadata or draw geometry) created by another version of BayesTools, such as BayesTools 0.3.0, or lacking fitted metadata the request requires. A fit whose posterior samples lack coordinates the request needs because of its monitoring or sampling settings (a quantity whose source coordinates were not monitored in parameter_draws(), random effects without random_monitor(latent = TRUE) or random_monitor(coefficients = TRUE) in JAGS_evaluate_formula() and JAGS_bridgesampling(), or a marginalized random-effect block) stops with the child class BayesTools_refit_monitoring (also BayesTools_refit_required): refitting with this version alone does not resolve it, and the message names the settings to refit with. Callers match these classes, never the message.

Usage

JAGS_formula_name_map(fit, parameter = NULL)

JAGS_fit_contract(fit)

JAGS_validate_fit_contract(fit, requires = character())

JAGS_fit_contract_schema()

Arguments

Value

JAGS_fit_contract_schema() returns a data frame. JAGS_formula_name_map() returns a BayesTools_formula_name_map data frame (or a named list of them). JAGS_fit_contract() returns a named list, and the validator returns it invisibly.

Create JAGS formula syntax and data object

Description

Creates a JAGS formula syntax, prepares data input, and returns modified prior list for further processing in the JAGS_fit function.

Usage

JAGS_formula(
  formula,
  parameter,
  data,
  prior_list,
  formula_scale = NULL,
  prior_random = NULL,
  random_effects_compile = NULL
)

Arguments

Details

When a formula suppresses the intercept with 0 + or -1, the function adds an intercept back to the compiled formula and includes a point prior that contributes zero on the formula scale: spike(0) ordinarily and spike(1) for a log-transformed intercept.

Scaling with formula_scale replaces a continuous predictor x by (x - m) / s in every term, where m and s are its mean and standard deviation in the fitting data. Centering also applies to terms without a free intercept, which is intended: the model is specified on the standardized scale. For example, ~ 0 + x with a scaled x fits \mu = b (x - m) / s, a line through (m, 0) rather than through the origin; on the original scale its slope is b / s and its implied intercept is -b m / s. Original-scale summaries (transform_scaled = TRUE) report that implied intercept although the standardized intercept is fixed at zero. Likewise, a random-effect block without a random intercept, such as (0 + x | g), fits group contributions u (x - m) / s. It implies an original-scale random intercept -u m / s (SD \tau |m| / s for a scaled-slope SD \tau), perfectly correlated with the original-scale slope u / s; random-effect summaries report the block's own coefficients, such as sd(x) = \tau / s, and not this implied intercept. Leave a predictor unscaled when a line or group slope through the origin of x is intended.

Independence of random-effect coefficients is likewise specified on the centered scale. An independent block such as (1 + x || g) (or a diag() block) with a scaled x has independent group coefficients u_0 and u_1 with SDs \tau_0 and \tau_1. On the original scale, the group intercept u_0 - u_1 m / s and slope u_1 / s are correlated with

\rho = -\frac{\tau_1 m / s}{\sqrt{\tau_0^2 + (\tau_1 m / s)^2}},

for example \rho \approx -0.93 for equal SDs and m / s = 2.5. The original-scale summaries of such a block report its SDs, \sqrt{\tau_0^2 + (\tau_1 m / s)^2} and \tau_1 / s, but no correlation, because the block has no correlation parameter. Use a correlated block, such as (1 + x | g), to estimate the correlation, or leave x unscaled for independence on the original scale.

A homogeneous-SD block (id(), random(covariance = "id"), or diag(..., hom = TRUE)) shares one SD among its columns, which cannot carry the different original-scale SDs of the columns. A homogeneous block with more than one column that contains a column of a scaled predictor is therefore refused by JAGS_formula(), whether its shared SD is sampled or fixed by a point prior: use a heterogeneous block, or leave the predictor unscaled. Single-column homogeneous blocks, such as id(0 + x | g), are not affected.

Factor contrasts are owned by prior_factor() and stored formula metadata, not inferred from whether an intercept is present. Thus ~ 0 + group with an independent factor prior means a structural zero intercept plus one coefficient per group level. With treatment or mean-difference contrasts, the same no-intercept expression preserves that selected basis. An interaction without one of its lower-order terms, such as g:x in ~ g + g:x, codes that factor by level indicators, as stats::model.matrix() does, and has one coefficient per level (e.g., one slope per level of g). Such a term does not use the contrast of that factor, so its prior may use a different contrast than the factor's terms that code it by its contrast (e.g., a mean-difference g with an independent g:x). When no term codes the factor by its contrast (e.g., ~ g:x + g:z), its indicator-coded terms must agree on the contrast instead. Mean-difference and orthonormal priors, other than a point mass at zero, are unavailable for such a term; use a treatment or independent prior for per-level coefficients, or add the lower-order term (here ~ g * x) to keep the contrast.

When using default priors ("__default_continuous" or "__default_factor"), explicitly specified priors for individual terms take precedence over the defaults. The defaults are only applied to terms that are not already in the prior list.

Formula random effects require prior_random. Random-effect SD priors in prior_list using "term|group" names are no longer supported. Continuous fixed-effect terms must expand to one design-matrix column. Matrix-valued continuous predictors are not currently supported. Fixed formulas support literal data-column names and standard formula operators, including interaction expansion such as (x + z)^2 with literal whole degrees from 2 through .Machine$integer.max. This is formula expansion, not arithmetic powers; I(x^2) remains unsupported. Degree 0 or 1 and symbolic degrees retain the base-R formula refusal. Dot expansion, offset(), inline transformations, and arbitrary calls are rejected; create explicit data columns for transformed predictors. The BayesTools expression(...) facility accepts finite numeric constants, formula or model data, JAGS-style i indexing, sampled scalar or one-dimensional indexed parameters, arithmetic operators, and abs(), exp(), log(), or sqrt(). Expressions retain literal JAGS indexing: users must write x or x[i] as required by the JAGS data shape. Their parsed syntax and dependencies are persisted and replayed draw by draw during prediction and marginal- likelihood reconstruction. Parameter dependencies must be owned by a prior or declared through add_parameters; opaque deterministic nodes and formula-output dependencies are rejected by JAGS_fit() because their defining JAGS graph is unavailable during replay. Random-effect predictors likewise support literal data-column names and formula operators, but not inline transformations or arbitrary calls. Create transformed random slopes as explicit data columns. Grouping terms support variables, : interactions, and / nesting.

Random-effect structures have two left-side grammars. id(), diag(), and us() / un() use a coefficient formula, so 1, 0, and -1 control the random intercept and slopes or interactions generate coefficient columns. Plain bars default to us() and double bars to diag(). A factor's concrete random basis is inherited from resolved contrast metadata by default and can be set for one block with random_block(contrasts = ...).

cs() / hcs(), ar1() / ar() / har(), and car() instead use a structure-owned index specification. They reject intercept controls and block contrast overrides. See random_effects_formula() and prior_random() for their index and covariance contracts. Categorical predictor and grouping levels must not contain BayesTools' reserved internal tokens, such as __xXx__. The predictor name intercept is reserved for the formula intercept.

Value

JAGS_formula returns a list containing the formula JAGS syntax, JAGS data object, modified prior_list, and (if standardization was applied) a formula_scale list with standardization information for back-transformation.

Conditions

Refusals that callers may need to tell apart are errors of class BayesTools_formula_transform_unavailable (parents error and condition); their reason field names the cause:

• "single_level_factor": a factor with a single level in the data has no contrasts to code (the field predictor names it). The index of a cs(), hcs(), ar1(), or har() block is coded by one indicator per level and may have a single level.

• "logical_factor_interaction": a logical predictor in an interaction with a factor that model.matrix() would code by indicators, in a fixed formula or a random-effect term (see the data argument; the fields predictors and terms name them).

• "unsupported_random_factor_contrast": a factor used only in a random-effect block that carries a contrasts matrix or an unsupported contrast name (the field predictor names it; set the coding with random_block(contrasts = )).

• "homogeneous_scaled_block": a homogeneous-SD random block with a standardized slope (see Details; the fields parameter and coordinates name the formula parameter and the shared SD).

• "basis_dependent_factor_prior": the prior of an interaction term of two or more factors, of which at least one is coded by a mean-difference or orthonormal contrast, depends on the basis of that contrast and would not treat the factor levels exchangeably. Only mean-difference and orthonormal priors, and treatment or independent priors built from zero-mean untruncated normal and zero spike priors, are accepted on such a term; when every coded factor has two levels, treatment and independent priors symmetric about zero are accepted as well. Other treatment and independent priors and every ordered prior are refused (the fields terms and predictors name the term and the coded factors; a refused ordered prior also has class BayesTools_ordered_unavailable).

Other invalid inputs stop with ordinary errors.

See Also

JAGS_fit()

Examples

# simulate data
set.seed(1)
df <- data.frame(
  y      = rnorm(60),
  x_cont = rnorm(60),
  x_bin  = rbinom(60, 1, .5),
  x_fac3 = factor(rep(c("A", "B", "C"), 20), levels = c("A", "B", "C")),
  x_fac4 = factor(rep(c("A", "B", "C", "D"), 15), levels = c("A", "B", "C", "D"))
)

# specify priors with intercept
prior_list <- list(
"intercept"     = prior("normal", list(0, 1)),
"x_cont"        = prior("normal", list(0, .5)),
"x_fac3"        = prior_factor("normal",  list(0, 1),  contrast = "treatment"),
"x_fac4"        = prior_factor("mnormal", list(0, 1),  contrast = "orthonormal"),
"x_fac3:x_fac4" = prior_factor("mnormal", list(0, .5), contrast = "orthonormal")
)

# create the formula object
formula_obj <- JAGS_formula(
  formula = ~ x_cont + x_fac3 * x_fac4,
  parameter = "mu", data = df, prior_list = prior_list)

# using -1 notation (automatically adds spike(0) intercept)
prior_list_no_intercept <- list(
  "x_fac3" = prior_factor("normal", list(0, 1), contrast = "treatment")
)
formula_no_intercept <- JAGS_formula(
  formula = ~ x_fac3 - 1,
  parameter = "mu", data = df, prior_list = prior_list_no_intercept)
# Equivalent to specifying intercept = prior("spike", list(0))

# using default priors for simpler specification
prior_list_defaults <- list(
  "__default_continuous" = prior("normal", list(0, 1)),
  "__default_factor"     = prior_factor("normal", list(0, 0.5), contrast = "treatment")
)
formula_defaults <- JAGS_formula(
  formula = ~ x_cont + x_fac3,
  parameter = "mu", data = df, prior_list = prior_list_defaults)
# intercept and x_cont get the default continuous prior
# x_fac3 gets the default factor prior

Original-scale route of a formula coefficient

Description

Describes how a coefficient of a fitted formula is related to the fitted coordinates on the original scale of the predictors, from the fitted coefficient transform (JAGS_formula_coefficient_transform()): the type of the map, its support, and the weights of the coefficient on the fitted coordinates. Fit-level hypothesis tests use it to evaluate hypotheses on original-scale coefficients (hypothesis_BF()).

Usage

JAGS_formula_coefficient_route(
  fit,
  parameter,
  target,
  caller = "hypothesis_BF()",
  refit_class = NULL
)

Arguments

Value

A list with the formula_parameter, the target, its position target_i in the transform, the type of the map ("identity", "affine", "exp_affine", "state_dependent", or "unsupported"), the weights on the fitted coordinates, the support of the coefficient, and for an unsupported map the reason and its cause ("metadata", "fixed", or "nonlinear").

See Also

JAGS_formula_coefficient_transform(), hypothesis_BF()

Formula coefficient transformations and induced prior densities

Description

JAGS_formula_coefficient_transform() exposes the declared fixed-coefficient transformation used by transform_scale_samples(). It records fitted sources, original-scale targets, named source/output transforms, exact nonzero dependencies, and parameter-map structural metadata.

JAGS_formula_prior_density() constructs the induced marginal prior measure for one target, or for a weighted combination of targets, through BayesTools' deterministic prior-density context and linear-density algebra. The result can be passed directly to prior_density_ordinate(). Fitted coefficient priors are raw; multiply_by belongs to their compiled formula contribution. Original raw coefficients use z'_j = \sum_k A_{jk} z_k m_k / m_j on one immutable fitted state. Identical canonical multipliers cancel before division, including zero; declared zero contributions require no irrelevant state. A different needed zero denominator refuses the requested numeric vector, without row repair. The numerical grid of a weighted combination resolves its narrowest continuous component (64 knots per robust scale of its prior times its absolute weight), except that a simple component whose demanded spacing is below .Machine$double.eps times the largest absolute coordinate of the combination's range cannot be represented on that grid. Such a component, e.g. the weight of a centered predictor equal to its mean, is a point at its mean and does not set the grid spacing; a component whose spacing the grid can resolve does.

Finite matrix rows are static raw maps. Dynamic rows are entirely NA and retain finite basis_matrix, canonical multipliers, true state dependencies, and a raw_affine, contribution_affine, or unavailable prior recipe. Compatible weighted requests share one context; declared point siblings may add a constant offset. Incompatible recipes refuse with "incompatible_prior_recipes"; unsupported stochastic denominators refuse with "state_dependent_map". Unsupported dependence/products remain explicit. Uncanceled subnormal static ratio weights retain their static classification, but draw and declared-point evaluation use the original value-aware arithmetic. Continuous laws whose reused scale cannot retain that map have reason numerical_scale_unavailable; usable draws and certified point laws remain.

JAGS_formula_internal_coordinate_priors() returns exact scalar priors for stochastic formula coordinates that are intentionally absent from the ordinary fitted prior_list. Currently these are the independent beta primitives used by compiled LKJ random-effect blocks.

Usage

JAGS_formula_internal_coordinate_priors(fit)

JAGS_formula_coefficient_transform(fit, parameter, target_scale = "original")

JAGS_formula_coefficient_transform_schema()

JAGS_formula_prior_density(
  fit,
  parameter,
  target = NULL,
  target_scale = "original",
  context = NULL,
  weights = NULL
)

Arguments

Value

JAGS_formula_coefficient_transform() returns a BayesTools_formula_coefficient_transform list (schema version 4). Its targets data frame has one row per original-scale target with the structural_status, fixed_value and reason of the target, its map_type ("identity": the target is its own fitted source, including a log-transformed source with an exp output; "affine": a linear combination of fitted sources; "exp_affine": exp of a linear combination of identity and log-transformed sources; "state_dependent": a map requiring fitted multiplier states; "unsupported": any other map), and the support of the map (a list column of c(lower, upper): c(0, Inf) for maps with an exp output and c(-Inf, Inf) otherwise; the prior support of a target can be narrower). JAGS_formula_coefficient_transform_schema() returns field descriptions. JAGS_formula_prior_density() returns a prior_linear_density accepted by prior_density_ordinate(). An unavailable density stops with an error of class BayesTools_formula_prior_density_unavailable (also BayesTools_formula_transform_unavailable) whose field reason names the cause, e.g. "unknown_target", "missing_source_coordinates", or "nonlinear_map" for a weighted combination with a target whose map is not linear in the fitted coefficients. Declared measure limitations additionally inherit BayesTools_formula_measure_unavailable; generic context/program failures and numeric transformation failures retain their strict boundary. Numeric refusal reasons include "zero_multiplier_denominator", "missing_multiplier_state", and "nonfinite_transform". Formula-design 7, unscale-design 2, and transform 4 require refitting older stored formats; readers never reconstruct missing fitted declaration ownership. A requested parameter without a persisted formula design stops with BayesTools_formula_transform_unavailable and reason "missing_formula_design", also when requested through either prior-density route. JAGS_formula_internal_coordinate_priors() returns a uniquely named list of scalar prior() objects keyed by concrete fitted coordinate.

Fitted-formula coordinate dependencies

Description

JAGS_formula_coordinate_dependencies() reports every fitted formula predictor that structurally depends on the supplied posterior coordinates. It uses the persisted formula designs and parameter map, including direct coefficients, formula expressions, coefficient multipliers, the parents of expression-point coefficients and multipliers ("point_expression"), the coordinates a random block samples itself ("random_effect": SDs, latent deviations, group coefficients, correlations, and SD allocations and inclusions), and external random-effect SD sources ("random_sd_source"). A row-source callback is reported as opaque for every queried coordinate: its declared inputs are not used to narrow the dependencies, so a callback source is conservatively treated as depending on every coordinate.

Usage

JAGS_formula_coordinate_dependencies(fit, coordinates)

Arguments

Value

A data frame with coordinate_name, formula_parameter, and dependency_type columns. An empty data frame means that none of the fitted formula predictors depends on the supplied coordinates.

See Also

JAGS_formula_design() parameter_map()

Extract Fitted JAGS Formula Design Metadata

Description

Returns the fitted formula design metadata stored by JAGS_fit(). The design contains the processed formula, fitted model frame, exact model matrix used for JAGS data construction, replayable expression syntax and dependencies, JAGS-safe coefficient names, contrast and factor- level metadata, rank diagnostics, prior metadata, and formula-scale information.

Usage

JAGS_formula_design(fit, parameter = NULL)

Arguments

Value

A named list of formula designs, or one formula design when parameter is supplied. Returns NULL when no formula design metadata is stored on fit.

See Also

JAGS_fit() JAGS_formula()

Formula designs for draws without a fit

Description

Builds the formula design of a formula parameter exactly as JAGS_fit() builds it from its formula_list, formula_data_list, formula_prior_list, and the related arguments (through JAGS_formula()), with its model data as model_data, and attaches it to posterior or prior draws that do not come from such a fit, for example the prior draws of a model that was not fitted. JAGS_evaluate_formula() and JAGS_predict_formula() evaluate the returned draws through this design as they evaluate a fit: on data when their data is NULL, and on new prediction data with the levels, contrasts, and standardization of data.

Usage

JAGS_formula_draws(
  draws,
  formula,
  parameter,
  data,
  prior_list,
  formula_scale = NULL,
  prior_random = NULL,
  random_effects_compile = NULL,
  model_data = NULL
)

Arguments

Value

An mcmc object of the draws carrying the formula design of parameter (see JAGS_formula_design()) and, when predictors are standardized, its formula_scale, which JAGS_evaluate_formula() and JAGS_predict_formula() accept as fit.

See Also

JAGS_formula() JAGS_evaluate_formula() JAGS_formula_design()

Finalize formula designs built outside JAGS_fit()

Description

Completes the formula_design and formula_scale returned by JAGS_formula() in the way JAGS_fit() does before it stores them in a fit. The functions let a caller rebuild the formula design of a fitted model outside JAGS_fit(), for example to replace the design stored with a fit.

Usage

JAGS_formula_point_finalize(
  design,
  prior_list,
  formula_data,
  model_data = NULL,
  parameter_names = character()
)

JAGS_formula_scale_finalize(
  formula_scale,
  design = NULL,
  prior_list = list(),
  model_data = NULL,
  owner_scope = "fit"
)

Arguments

Details

JAGS_formula() returns a fresh design and scale. JAGS_fit() completes them for each formula parameter in this order: first JAGS_formula_point_finalize() and the finalization of the expression() terms of the design, then the JAGS data generated by all the formulas are merged into the model data, and, in a second loop over the formula parameters, JAGS_formula_scale_finalize() completes the scale with that merged model data. The completed scale is stored both as the formula_scale of the parameter and as the formula_scale element of its finalized design.

The finalization of the expression() terms and the merge of the formula-generated data are not exported. A design rebuilt with these two functions alone does not carry the finalization of its expression() terms, and the scale is completed with the model_data that is supplied, without the data generated by the formulas.

JAGS_formula_point_finalize() retains, for each fixed coefficient with an expression() point prior and for each expression() point prior named by a multiply_by attribute of the design, the expression, the parent priors it reads, and the data it reads, in the point_expression_owner element of the design. A design without such a coefficient or multiplier is returned unchanged. Malformed or contradictory declarations stop with an error of class BayesTools_formula_point_unavailable (also BayesTools_formula_transform_unavailable) whose field reason names the cause.

JAGS_formula_scale_finalize() resolves the scalar states that the multipliers and standard deviations of the design need from the point coefficients of the scale, the point priors in prior_list, the scalars in model_data, and the constants the scale already holds, and marks the scale as complete for owner_scope. Contradictory sources of one state stop with an error of class BayesTools_formula_transform_unavailable (field reason "contradictory_state_constants"), and a scale without its declarations stops with an error of class BayesTools_refit_required.

Value

JAGS_formula_point_finalize() returns design, with the point_expression_owner element when it has expression-point coefficients.

JAGS_formula_scale_finalize() returns formula_scale with the completed unscale_design attribute (the resolved state_constants, owner_scope, and complete = TRUE), or NULL for a NULL scale.

See Also

JAGS_formula() JAGS_fit() JAGS_formula_design()

Examples

data <- data.frame(x = c(-1, 0, 1, 2, 4))
prior_list <- list(
  intercept = prior("normal", list(0, 1)),
  x         = prior("normal", list(0, 1))
)
formula <- JAGS_formula(~ x, "mu", data, prior_list, formula_scale = TRUE)

design <- JAGS_formula_point_finalize(
  formula$formula_design, formula$prior_list, data
)
scale <- JAGS_formula_scale_finalize(
  formula$formula_scale, design, formula$prior_list
)
attr(scale, "unscale_design")$complete

Exact fitted-formula predictor update basis

Description

JAGS_formula_predictor_basis() uses the fitted parameter map and persisted formula design to construct the exact observation-level change in a fixed linear predictor for a supplied direction through fitted coefficient coordinates. The result is conditional on all coordinates outside that direction, including fitted random effects.

The accessor reports "affine" only when the stored metadata proves that the selected update is additive on the fitted predictor scale. Coordinates reused by formula expressions, coefficient multipliers, expression-point coefficients, or random-effect scale sources are reported as non-affine or unsupported so callers can retain a generic evaluator.

A logged intercept is additive in its own logarithm rather than in the fitted coordinate: the predictor adds log(new) - log(current) times the intercept's model column. Such a direction is reported as "affine" with coordinate = "log" when the intercept is the only moving coordinate, and the caller must form the update from the logarithms. Every other affine result carries coordinate = "identity". A direction that moves a logged intercept together with ordinary coefficients mixes the two coordinates and remains non-affine.

Usage

JAGS_formula_predictor_basis(fit, directions, posterior_samples = NULL)

Arguments

Value

A BayesTools_formula_predictor_basis list with status, reason, formula parameter, selected coordinates, the coordinate the update is additive in ("identity" or "log"), and an S by N numeric basis. basis is present only when status is "affine".

See Also

JAGS_formula_design() parameter_map()

Compile formula random effects as marginal JAGS covariance nodes

Description

Compiles sampled or marginalized formula random-effect metadata into deterministic JAGS nodes containing observation-level covariance contributions. The compiler is intentionally likelihood agnostic: callers provide dependency-preserving row blocks and choose which terms contribute by subsetting the formula design. Sampling latent coordinates does not change their population covariance.

Usage

JAGS_formula_random_marginal_covariance(
  formula_design,
  row_blocks,
  prefix = "random_marginal_covariance",
  representation = c("dense", "auto")
)

Arguments

Value

A list of class BayesTools_JAGS_random_marginal_covariance with syntax (the JAGS model syntax as one string), data (the named list of data the syntax reads), row_blocks (the validated integer row vectors), representation ("dense", or the diagonal-plus-factor representation that "auto" returns when it is structurally certified), term_names (the compiled random-effect block names), and the node names per row block. Dense results contain one lower-triangle covariance node name per row block in lower_names and NA in diagonal_names and loading_names. Diagonal-plus-factor results instead contain diagonal_names, loading_names (NA for a block without loading columns), and structural loading_ranks. A formula design without random effects returns empty syntax and data.

Create initial values for 'JAGS' model

Description

Creates initial values for priors in a 'JAGS' model.

Usage

JAGS_get_inits(prior_list, chains, seed)

Arguments

Value

JAGS_get_inits returns a list with one element per chain, containing the chain's JAGS initial values and its .RNG.name and .RNG.seed. The generator is "base::Super-Duper" for up to four chains and "lecuyer::RngStream" for more chains, so the streams of a fit change when it is run with more than four chains. With an empty prior_list, each element contains only .RNG.name and .RNG.seed, so that fits of models whose priors are specified only in the model syntax remain reproducible.

Generate a JAGS LKJ-Cholesky correlation module

Description

Creates JAGS syntax for a Cholesky factor of a correlation matrix with the same target distribution as Stan's lkj_corr_cholesky(eta), using the BayesTools compiled JAGS module.

Usage

JAGS_lkj_corr_cholesky(
  name,
  K,
  eta = 1,
  include_correlation = TRUE,
  include_primitives = FALSE
)

Arguments

Value

A list with JAGS syntax, monitor names, primitive bridge coordinate names and bounds, and metadata for the generated LKJ-Cholesky block.

Extract parameters for 'JAGS' priors

Description

Extracts transformed parameters from the prior part of a 'JAGS' model inside of a 'bridgesampling' function (returns them as a named list)

Usage

JAGS_marglik_parameters_formula(
  samples,
  formula_list,
  formula_data_list,
  formula_prior_list,
  prior_list_parameters,
  formula_design_list = NULL,
  model_data = NULL
)

JAGS_marglik_parameters(samples, prior_list)

Arguments

Value

JAGS_marglik_parameters returns a named list of (transformed) posterior samples. Samples that lack monitored coordinates the priors require stop with an error of class BayesTools_missing_monitored_columns (also BayesTools_marglik_input); callers match the class, not the message. This includes ordinary scalar and vector priors. A named coordinate whose value is NA is present; literal point priors need no monitored coordinate. Formula reconstruction combines decoded ordinary and formula-prior values, genuine additional sampled sources, and retained scalar data before fixed coefficients, multipliers, and random-effect SDs are reconstructed. Natural owned state takes precedence over transformed aliases; malformed supplied owners refuse instead of falling back to a sample column. Expression-point replay is available through a fitted formula owner; generic prior readers without that owner report BayesTools_formula_point_unavailable. A state outside the support of the model (for example a negative row-indexed external random-effect SD value) stops JAGS_marglik_parameters_formula() with an error of class BayesTools_marglik_out_of_support, which JAGS_bridgesampling() treats as zero density.

Compute marginal likelihood for 'JAGS' priors

Description

Computes marginal likelihood for the prior part of a 'JAGS' model within 'bridgesampling' function

Usage

JAGS_marglik_priors(samples, prior_list)

JAGS_marglik_priors_rows(samples, prior_list)

JAGS_marglik_priors_rows_evaluator(prior_list)

JAGS_marglik_priors_formula(samples, formula_prior_list, prior_list = NULL)

Arguments

Details

JAGS_marglik_priors_rows() preserves joint prior boundaries within each posterior row. In particular, auxiliary-gamma contributions for vector and Dirichlet priors are summed separately within each row.

When model and formula priors share an ordered Dirichlet allocation, supply the model priors as prior_list to JAGS_marglik_priors_formula(). Its contribution then excludes allocations already included by JAGS_marglik_priors(samples, prior_list), so the two log prior contributions can be added without counting shared allocations twice. Evaluate the combined contribution as JAGS_marglik_priors(samples, prior_list) + JAGS_marglik_priors_formula(samples, formula_prior_list, prior_list).

Value

JAGS_marglik_priors returns a numeric value of the log prior density evaluated at the current posterior sample. JAGS_marglik_priors_rows returns one numeric value for every row of posterior samples. JAGS_marglik_priors_rows_evaluator returns a function that applies the same row-wise evaluation without recompiling the prior structure on each call. Samples that lack monitored coordinates the priors require stop with an error of class BayesTools_missing_monitored_columns (also BayesTools_marglik_input).

Batched numerical density kernel for ordered primitives

Description

Compiles the active ordered totals and distinct allocation coordinates into a function of a numeric draws matrix.

Usage

JAGS_ordered_density_kernel(prior_list, allocation_chart = NULL)

Arguments

Details

Total mixture components are localized independently for each row; multi-slice spike totals share one inclusion state. Each total slice and allocation key contributes once. Mixture-state probabilities, inactive component sources, and nuisance-only chart factors are omitted because they are constant along the conditional chart. This is a numerical conditional kernel, not a bridge density. Expression totals raise BayesTools_ordered_expression_unavailable, missing coordinates raise BayesTools_ordered_coordinates_unavailable, and invalid indicators or missing (NA) total values of a sampled total raise BayesTools_ordered_invalid_state; all inherit BayesTools_ordered_unavailable. Ordinary values outside numeric support return -Inf. Refit when bound ordered metadata are unavailable.

Value

A function of samples, a numeric matrix with named coordinate columns, returning one log density or log probability per row.

Fitted ordered parameter specifications

Description

Reads the persisted total, allocation and coefficient recipes of ordered terms. The recipes are backend specifications; the totals and the shares of random allocations they describe are catalog quantities of the fit (parameter_catalog()).

Usage

JAGS_ordered_parameter_spec(
  fit,
  parameters = NULL,
  weights = NULL,
  draws = NULL
)

Arguments

Details

Missing fitted numeric provenance raises BayesTools_ordered_metadata_unavailable and BayesTools_refit_required: refit with this version. Missing source draws raise BayesTools_ordered_coordinates_unavailable; invalid component states raise BayesTools_ordered_invalid_state. Continuous total families remain structurally continuous with expression parameters. Bernoulli totals retain their declared support even with an expression probability. Expression point locations can supply fitted snapshot values but have an unavailable scalar measure with a BayesTools_ordered_expression_unavailable reason. Without a registered certified ancestor recipe, expression totals cannot supply numerical charts or correct replay after changing an ancestor. These coordinate/expression conditions inherit BayesTools_ordered_unavailable. Missing or inconsistent fitted provenance reports: "Fitted ordered numeric provenance is unavailable. Refit the model with this version of BayesTools." Missing projection totals report: "Ordered total sources for '⁠<term>⁠' are unavailable in 'draws'. Include its declared source coordinates." Invalid total states report: "Ordered total indicator '⁠<coordinate>⁠' does not select a declared component."

Value

With no weights, a named list of term specifications containing the bound prior, coefficient names and grid, slice indices, total names and prior, deterministic total recipe, allocation records (key, factor, slice, id, normalized and gamma coordinates, alpha or fixed weights), and label parts. source_coordinates combines total monitors, total primitive dependencies, and Gamma monitors; total_auxiliary_coordinates lists the total's other monitored coordinates, including indicators, inclusion probabilities and slab sources. Some total-component dependencies are optional unmonitored sources; the monitored total is their fitted snapshot alternative. No supplied draws means no values field. With weights = NULL and supplied draws, each term also contains sampled_parameters: values is the fitted total/share matrix (its columns keep the backend names of the sources), label_parts holds the rendered labels (f{total}, f[share: mid], see parameter_labels()), and allocation_names identifies its sampled share columns. Fixed totals materialize every slice; fixed allocations produce no sampled share columns.

An empty named list is returned when no ordered terms are present. With weights, the result is a BayesTools_ordered_projection containing bound specs, fitted weights, original requested_weights, static tensor contractions, and ordinary_weights. With resolved draws it also contains row-aligned values, atom (point location, otherwise NA), state ("point", "continuous", or "unavailable"), and exact (a full-simplex identity). total_contraction_weights holds the per-term matrices of total slopes, and allocation_contractions holds complete coordinate contractions per allocation key, including totals and every retained other factor. reason is a typed condition when the scalar measure is structurally unavailable. Total-coordinate weights expand to the corresponding complete coefficient slice, so a total target uses its declared full-simplex identity. Available ordered semantic values in mixed posteriors, factor levels and marginal views use these primitive projections, including continuous cumulative effects. Declared view transformations and undefined rows are kept.

Build fingerprints of loaded packages

Description

Identifies the builds of packages as loaded in the running session. Two processes run the same build of a package when its fingerprints are identical; parallel BayesTools computation (e.g., JAGS_fit() and JAGS_runtime_cluster()) requires this of every worker, and packages can use it to key caches by build.

Usage

JAGS_package_builds(packages)

Arguments

Value

A list named by packages. An element is NULL when the package cannot be loaded, and otherwise a list with the package version, r_code (a hash of the functions and immutable constants defined in the loaded namespace, so an installed package and an equivalent development load agree), and dll (MD5 sums of the package's loaded native libraries).

See Also

JAGS_runtime_cluster()

Examples

JAGS_package_builds("stats")$stats$version

Formula prediction with explicit random-effect target

Description

Returns formula-scale predictions from fitted BayesTools formula metadata. Unlike JAGS_evaluate_formula(), this helper can return structured prediction output for marginal random-effect targets, including marginal random-effect covariance or simulated random-effect draws. Unavailable new rows for a posterior-indexed row source raise BayesTools_prediction_new_rows_unavailable (parent BayesTools_prediction_unavailable), with reason = "posterior_indexed_row_source", block, displayed source label, affected prediction rows, and caller context. This applies to conditional and both marginal targets where the source of the new rows is needed, under new_levels = "sample"; with new_levels = "zero" the new rows contribute zero and need no source. Mapping, source-value, and monitoring errors retain their existing conditions.

Usage

JAGS_predict_formula(
  fit,
  parameter,
  formula = NULL,
  data = NULL,
  prior_list = NULL,
  formula_target = c("conditional", "fixed", "marginal"),
  blocks = NULL,
  new_levels = NULL,
  marginal_method = c("covariance", "sample"),
  seed = NULL,
  components = FALSE,
  fitted_rows = NULL
)

Arguments

Value

A list of class BayesTools_formula_prediction with fields value, mean, random, vcov, components, and metadata.

See Also

JAGS_evaluate_formula() random_effects_marginal_vcov()

Worker clusters with the running package builds

Description

JAGS_runtime_cluster() starts a PSOCK cluster for parallel computation whose workers run the package builds of the calling session, as the workers of parallel JAGS_fit() do. Packages built on BayesTools use it for their own parallel computation. JAGS_runtime_cluster_stop() stops such a cluster.

Usage

JAGS_runtime_cluster(
  cores,
  packages = "BayesTools",
  runtime_setup = NULL,
  options = list(),
  operation = "Parallel computation"
)

JAGS_runtime_cluster_stop(cl)

Arguments

Details

Workers start with Rscript --vanilla, so no user or site startup file runs, and with the library paths of the calling session. Setting the options precedes loading the packages. If the start fails, the workers are stopped (and a started runtime setup finished) before the error is signalled. JAGS_runtime_cluster_stop() stops the workers first and then finishes the runtime setup in the calling process; further calls have no effect.

Value

JAGS_runtime_cluster() returns the cluster (as created by parallel::makePSOCKcluster()), for use with the functions of the parallel package. JAGS_runtime_cluster_stop() returns NULL invisibly.

See Also

JAGS_fit() JAGS_package_builds()

Examples

## Not run: 
cl <- JAGS_runtime_cluster(2, packages = "BayesTools")
on.exit(JAGS_runtime_cluster_stop(cl), add = TRUE)
parallel::parLapply(cl, 1:2, function(i) i^2)

## End(Not run)

Create list of monitored parameters for 'JAGS' model

Description

Creates a vector of parameter names to be monitored in a 'JAGS' model.

Usage

JAGS_to_monitor(prior_list)

Arguments

Value

JAGS_to_monitor returns a character vector of parameter names.

Compute Savage-Dickey inclusion Bayes factors

Description

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

Usage

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

Arguments

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.

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).

Adds column to BayesTools table

Description

Adds column to a BayesTools table while not breaking formatting, attributes, etc...

Usage

add_column(
  table,
  column_title,
  column_values,
  column_position = NULL,
  column_type = NULL
)

Arguments

Value

returns an object of 'BayesTools_table' class.

Model-average marginal posterior distributions and marginal Bayes factors based on BayesTools JAGS model via marginal_inference

Description

Creates marginal model-averaged and conditional posterior distributions based on a BayesTools JAGS model, vector of parameters, formula, and a list of conditional specifications for each parameter. Computes inclusion Bayes factors for each marginal estimate via a Savage-Dickey density approximation.

Usage

as_marginal_inference(
  model,
  marginal_parameters,
  parameters,
  conditional_list,
  conditional_rule,
  formula,
  null_hypothesis = 0,
  normal_approximation = FALSE,
  n_samples = 10000,
  silent = FALSE,
  force_plots = FALSE,
  density_method = "KDE",
  compute_BF = TRUE
)

Arguments

Details

For as_marginal_inference(), conditional_list is applied separately to each output marginal or level. A requested conditional parameter is active only for levels whose linear combination has a nonzero weight for that parameter. Requested conditionals with zero weight are ignored for that level; if no requested conditionals are active, the level uses the fully averaged posterior and prior context. Level comparisons require the compared levels to use the same effective conditional subset and rule. As in marginal_inference(), a parameter or level whose conditional posterior has a declared point mass at the null hypothesis gets an NA inclusion Bayes factor with the reason in its "warnings" attribute. Known prior-ordinate refusals and a numerically unavailable posterior ordinate also produce NA plus the original reason, including scalar marginal table results; direct scalar Savage_Dickey_BF() remains strict. A level whose effective conditional subset is non-empty and leaves no draws is unavailable: it gets the warning "No samples left after conditioning." (once per distinct conditioning event) and is absent from the conditional and inference entries of its parameter, while the other levels and the averaged marginals are kept. A parameter without an available level has no conditional or inference entry.

Value

as_marginal_inference returns an object of class 'marginal_inference'.

See Also

marginal_inference as_mixed_posteriors

Export BayesTools JAGS model posterior distribution as model-average posterior distributions via mix_posteriors

Description

Creates a model-averages posterior distributions on a single model that allows mimicking the mix_posteriors functionality. This function is useful when the model-averaged ensemble is based on prior_spike_and_slab or prior_mixture priors - the model-averaging is done within the model.

Usage

as_mixed_posteriors(
  model,
  parameters,
  conditional = NULL,
  conditional_rule = "AND",
  force_plots = FALSE,
  transform_scaled = FALSE,
  n_prior_samples = 10000
)

Arguments

Value

as_mix_posteriors returns a named list of mixed posterior distributions (either a vector of matrix).

See Also

mix_posteriors

Create a BayesTools marginal-likelihood object

Description

Creates a marginal-likelihood result from a supplied scalar natural-log marginal likelihood. This is useful for analytically known or deliberately zero-evidence models that were not evaluated by bridge sampling.

Usage

bridgesampling_object(logml = -Inf)

Arguments

Value

A BayesTools_marglik object (with the class bridge of released versions, so that bridgesampling::bf(), post_prob() and logml() apply) with no repetition rows and the "supplied_scalar" aggregation rule, or the "supplied_failure" rule for a failed computation (logml = NA).

Check input

Description

A set of convenience functions for checking objects/arguments to a function passed by a user.

Usage

check_bool(
  x,
  name = deparse(substitute(x)),
  check_length = 1,
  allow_NULL = FALSE,
  allow_NA = FALSE,
  call = ""
)

check_char(
  x,
  name = deparse(substitute(x)),
  check_length = 1,
  allow_values = NULL,
  allow_NULL = FALSE,
  allow_NA = TRUE,
  call = ""
)

check_real(
  x,
  name = deparse(substitute(x)),
  lower = -Inf,
  upper = Inf,
  allow_bound = TRUE,
  check_length = 1,
  allow_NULL = FALSE,
  allow_NA = TRUE,
  call = ""
)

check_int(
  x,
  name = deparse(substitute(x)),
  lower = -Inf,
  upper = Inf,
  allow_bound = TRUE,
  check_length = 1,
  allow_NULL = FALSE,
  allow_NA = TRUE,
  call = ""
)

check_list(
  x,
  name = deparse(substitute(x)),
  check_length = 0,
  check_names = NULL,
  all_objects = FALSE,
  allow_other = FALSE,
  allow_NULL = FALSE,
  call = ""
)

Arguments

Value

returns NULL, called for the input check.

NA values

allow_NA defaults to TRUE for check_char, check_int, and check_real, but to FALSE for check_bool: a missing value cannot be used as a switch, so an NA flag is rejected unless allow_NA = TRUE is requested.

Examples

# check whether the object is logical
check_bool(TRUE, name = "input")

# will throw an error on any other type
## Not run: 
  check_bool("TRUE", name = "input")

## End(Not run)

BayesTools Contrast Matrices

Description

BayesTools provides several contrast matrix functions for Bayesian factor analysis. These functions create different types of contrast matrices that can be used with factor variables in Bayesian models.

Usage

contr.orthonormal(n, contrasts = TRUE)

contr.meandif(n, contrasts = TRUE)

contr.independent(n, contrasts = TRUE)

contr.ordered_cumulative(n, contrasts = TRUE)

contr.ordered_cumulative_levels(n, contrasts = TRUE)

Arguments

Details

The package includes the following contrast functions:

contr.orthonormal

Return a matrix of orthonormal contrasts: a normalised Helmert basis, whose columns have unit length and sum to zero and which is identical on every platform. Any orthonormal basis of the centred space implies the same exchangeable prior on the factor level effects under a spherical prior on the coefficients, which corresponds to the description by Rouder et al. (2012). Returns a matrix with n rows and k columns, with k = n - 1 if contrasts = TRUE and k = n if contrasts = FALSE.

contr.meandif

Return a matrix of mean difference contrasts. This is an adjustment to the contr.orthonormal that ascertains that the prior distributions on difference between the gran mean and factor level are identical independent of the number of factor levels (which does not hold for the orthonormal contrast). Furthermore, the contrast is re-scaled so the specified prior distribution exactly corresponds to the prior distribution on difference between each factor level and the grand mean – this is approximately twice the scale of contr.orthonormal. Returns a matrix with n rows and k columns, with k = n - 1 if contrasts = TRUE and k = n if contrasts = FALSE.

contr.independent

Return a matrix of independent contrasts – a level for each term. Returns a matrix with n rows and k columns, with k = n if contrasts = TRUE and k = n if contrasts = FALSE.

contr.ordered_cumulative

Return a cumulative increment basis for ordered factors, with the first level fixed to zero and the last level equal to the full total effect.

contr.ordered_cumulative_levels

Return a cumulative level basis for ordered factors, where the first level receives the first allocation share and the last level equals the full total effect.

References

Rouder JN, Morey RD, Speckman PL, Province JM (2012). “Default Bayes factors for ANOVA designs.” Journal of Mathematical Psychology, 56(5), 356–374. doi:10.1016/j.jmp.2012.08.001.

Examples

# Orthonormal contrasts
contr.orthonormal(c(1, 2))
contr.orthonormal(c(1, 2, 3))

# Mean difference contrasts
contr.meandif(c(1, 2))
contr.meandif(c(1, 2, 3))

# Independent contrasts
contr.independent(c(1, 2))
contr.independent(c(1, 2, 3))

# Ordered cumulative contrasts
contr.ordered_cumulative(c("low", "mid", "high"))
contr.ordered_cumulative_levels(c("low", "mid", "high"))

Prior density

Description

Computes density of a prior distribution across a range of values.

Usage

## S3 method for class 'prior'
density(
  x,
  x_seq = NULL,
  x_range = NULL,
  x_range_quant = NULL,
  n_points = 1000,
  n_samples = 10000,
  force_samples = FALSE,
  individual = FALSE,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  truncate_end = TRUE,
  ...
)

Arguments

Details

Sample-based density estimates for continuous priors with finite support use boundary-reflected kernel density estimates. The plotting range controls the evaluation grid, while reflection is based on the prior's true truncation bounds. Automatic transformed prior-coordinate ranges keep the existing source range and equally spaced source grid. Where the existing marginal and transformed density route supports it, a source display endpoint with an infinite transformed image uses the prior's existing marginal tail quantile, controlled by x_range_quant. Prior-list plots use the union of participating component marginal quantiles. This is a finite display window; the prior support, density, probability masses and mixture weights are unchanged. Invalid atom images remain unavailable. When an endpoint quantile is unavailable or its transformed image is still not finite (for example the 0.995 quantile of a very wide prior under "exp"), the automatic display range of the transformed prior is unavailable: density() stops with BayesTools_prior_range_unavailable, parent BayesTools_transformation_domain and BayesTools_transformation, with call = NULL, and the message names the remedy of explicit display limits (x_range or x_seq; xlim in the plotting functions). In plot_posterior() only the prior curve is omitted, with a warning of class BayesTools_prior_curve_unavailable (see there), and the posterior is drawn alone. Explicit source or transformed coordinates keep their supplied interpretation. Individual weightfunction and ordered routes retain their existing transformation behavior and conditions. Nonindividual PET/PEESE standard-error axes and weightfunction p-value axes retain their specialized interpretation. Declared point locations and finite builtin support bounds must have representable images. Finite-source exponential underflow, tanh saturation, positive-power underflow and nonfinite point images stop with BayesTools_transformation_image_unavailable, parent BayesTools_transformation, with call = NULL and fields transformation, source_values, and images for the matched failing finite sources. True zero under positive powers and infinite mathematical support limits retain their meaning. Continuous display grids retain their existing handling. Direct ordered Dirichlet-product densities use stable log-share arithmetic for literal, untruncated Normal totals with mean zero and finite positive SD, retaining the existing quadrature budget and tolerances. This guarded route does not certify tiny or nonrepresentable ranges. Every other total takes the same quadrature at each display value and accepts it when it converges within its tolerances and exceeds the absolute tolerance (the integral of a total concentrated away from zero can miss the band where the integrand is positive and give zero); the display values it does not accept take the structural route of the level (its total times a Beta share), built without a numerical grid. A quadrature that does not converge is not repeated for the rest of the level. Small second Beta shapes remain a numerical risk of the quadrature. A display value whose density neither the quadrature nor the route resolves (an NA height inside the support) is left out of the level and reported by a warning of class BayesTools_prior_curve_unavailable with the fields unresolved_values, structural_values (the limits at support ends without a structural classification, which are not warned about) and levels.

Value

density.prior returns an object of class 'density'. For Dirichlet simplex priors it returns a named list of beta-marginal density objects, one for each simplex coordinate. Ordered priors return one component per factor level. When a level has both discrete and continuous probability, its atoms table stores exact location and mass values, while its continuous table stores a density already weighted to integrate to the remaining continuous mass over its full support. A clipped plotting grid preserves density heights; diagnostics$continuous_integral reports its numerical trapezoid integral, which can differ from the exact continuous mass because of clipping and grid discretization. Nonfinite continuous ordinates are omitted by the structural mixed-measure route; the curve is not renormalized. A supported scalar point total times a random allocation share has a continuous scaled-Beta distribution at intermediate levels, with declared atoms retained for zero-total branches, reference levels, fixed shares, and the full-total level. A spike-and-slab prior returns a list of class density.prior.spike_and_slab with the slab density (variable) and the density of the spike at zero (inclusion), each scaled by its prior mass. Under a transformation, a prior with inclusion probability 1 has no prior mass in the spike, returns inclusion = NULL, and does not require a representable image of the spike location (for example log(0)); any other inclusion probability does.

See Also

prior()

Compute posterior probabilities and inclusion Bayes factors

Description

Computes prior probabilities, posterior probabilities, and inclusion Bayes factors based either on (1) a list of models, vector of parameters, and a list of indicators the models represent the null or alternative hypothesis for each parameter, (2) on prior model odds, marginal likelihoods, and indicator whether the models represent the null or alternative hypothesis, or (3) list of models for each model.

Usage

compute_inference(
  prior_weights,
  margliks,
  is_null = NULL,
  conditional = FALSE,
  on_failure = c("error", "drop", "zero")
)

ensemble_inference(
  model_list,
  parameters,
  is_null_list,
  conditional = FALSE,
  on_failure = c("error", "drop", "zero")
)

models_inference(model_list, on_failure = c("error", "drop", "zero"))

Arguments

Details

Dropping every positive-prior-probability model stops because no finite marginal likelihood is available; it does not renormalize an empty model space. Original positive model odds retain their logarithmic declaration even when the visible probability rounds to zero. Evidence is centered before model probabilities and inclusion Bayes factors are evaluated. Finite evidence differences outside the logarithmic range stop with BayesTools_numerical_condition. The returned numeric fields remain ordinary probabilities; passing a visible zero to inclusion_BF() retains that function's exact supplied-zero meaning.

Value

compute_inference returns a named list of prior probabilities, posterior probabilities, and Bayes factors. ensemble_inference gives a list of named lists of inferences for each parameter, and models_inference returns a list of models, each expanded by the inference list.

See Also

mix_posteriors BayesTools_ensemble_tables

Fingerprint the loaded BayesTools fitting backend

Description

Returns a deterministic fingerprint of the BayesTools implementation that owns the currently loaded namespace. Downstream packages can store this value with serialized fits and invalidate caches when the generic fitting backend changes.

Usage

fit_backend_fingerprint()

Details

The fingerprint covers the package's executable R and native surface and an explicit fit-backend schema version. It is captured when the namespace loads and memoized for the R session so source files edited afterward cannot silently restamp fits produced by the already loaded implementation. Development workflows should reload BayesTools after changing its backend.

The scope is intentionally conservative: any executable R/native or package build artifact change can change the fingerprint. Installed lazy-load databases and native libraries make the value build- and platform-local; it is not a cross-platform cache key. External runtimes and dependencies such as JAGS are outside this BayesTools implementation fingerprint.

Value

A length-one 32-character hexadecimal fingerprint, or NA_character_ when the loaded implementation cannot be resolved.

Format Bayes factor

Description

Formats Bayes factor

Usage

format_BF(BF, logBF = FALSE, BF01 = FALSE, inclusion = FALSE)

Arguments

Details

Valid live Bayes-factor carriers retain their canonical BF10 logarithms when reformatted into either direction and scale. This preserves finite logs and representable reciprocals when the natural display is zero or infinite. Replaced or arithmetically modified vectors follow ordinary numeric formatting.

Value

format_BF returns a formatted Bayes factor.

Format Bayes factors from natural-log values

Description

Builds a Bayes factor from natural-logarithm BF10 values without passing them through exp(). Output on the logarithmic scale (logBF = TRUE) and in the inverse orientation (BF01 = TRUE) is computed in log space, so Bayes factors beyond the double range (an exp(log_BF) equal to 0 or Inf) keep finite logarithms and representable reciprocals. format_BF() cannot recover them from the natural-scale numbers.

Usage

format_BF_from_log(
  log_BF,
  logBF = FALSE,
  BF01 = FALSE,
  inclusion = FALSE,
  bound_operator = NULL,
  diagnostics = NULL
)

Arguments

Details

The result is the Bayes-factor carrier that format_BF() returns when it receives such a carrier: reformatting it with format_BF() keeps the canonical logarithms. A plain numeric vector given to format_BF() returns an unclassed vector (it has the class BayesTools_BF only while a non-missing bound operator is present). The carrier stores the logarithms in private attributes; BF_carrier_drop() removes them. Subsetting keeps the logarithms of the selected values, arithmetic on the carrier returns ordinary numbers, and replacing values removes the carrier attributes.

Value

format_BF_from_log() returns a numeric vector of class c("BayesTools_BF", "numeric") with the names of log_BF. Its public attributes are name (for example "BF", "1/BF", "Inclusion BF", "Exclusion BF", wrapped in log() when logBF = TRUE), logBF, BF01, and bound_operator.

See Also

format_BF() BF_carrier_drop() invert_BF_bound_operator()

Examples

# a Bayes factor beyond the double range keeps its finite logarithm
BF <- format_BF_from_log(c(a = 2, b = 800))
format_BF(BF, logBF = TRUE)
format_BF(BF, BF01 = TRUE, logBF = TRUE)

Add an Intercept to a Formula

Description

Converts a no-intercept formula to the corresponding formula with an intercept while preserving the formula environment. Additive, parenthesized, and unary-plus no-intercept encodings such as - 1, + 0, and 0 + are removed without editing transformed calls such as I(x - 1) or offset(x - 1).

Usage

formula_add_intercept(formula)

Arguments

Value

A formula object with an intercept.

Add prior object to a ggplot

Description

Add prior object to a ggplot

Usage

geom_prior(
  x,
  xlim = NULL,
  x_seq = NULL,
  x_range_quant = NULL,
  n_points = 1000,
  n_samples = 10000,
  force_samples = FALSE,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  show_parameter = if (individual) 1 else NULL,
  individual = FALSE,
  rescale_x = FALSE,
  scale_y2 = NULL,
  ...
)

Arguments

Value

geom_prior returns a ggplot2 layer for a continuous density (a list of layers for a weight function), and an overlay of class BayesTools_prior_overlay for a point mass, a mixture, or a spike and slab prior. Both are added to a prior plot with +; the overlay takes the scaling of the probability axis of the plot it is added to.

See Also

plot.prior() lines.prior()

Add list of prior objects to a plot

Description

Add list of prior objects to a plot

Usage

geom_prior_list(
  prior_list,
  xlim = NULL,
  x_seq = NULL,
  x_range_quant = NULL,
  n_points = 500,
  n_samples = 10000,
  force_samples = FALSE,
  individual = FALSE,
  show_figures = if (individual) 1 else NULL,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  rescale_x = FALSE,
  scale_y2 = NULL,
  prior_list_mu = NULL,
  effect_direction = "positive",
  ...
)

Arguments

Value

geom_prior_list returns an overlay of class BayesTools_prior_overlay, which is added to a prior plot with + and takes the scaling of the probability axis of that plot.

See Also

plot_prior_list() lines_prior_list()

Harrell-Davis quantiles of posterior draws

Description

Estimates quantiles of equally weighted draws with the Harrell-Davis estimator (Harrell and Davis 1982), a weighted average of all order statistics. Applied pointwise to the columns of a draws-by-grid matrix, it gives smooth credible bands: the kinks that the empirical quantile (stats::quantile()) shows when the draws that define the quantile change from one grid point to the next are attenuated. The estimand is the same as that of the empirical quantile; in simulations of smooth curves the accuracy was similar (see the details).

Usage

harrell_davis_quantile(x, probs, names = FALSE)

Arguments

Details

For m draws with order statistics ⁠y(1), ..., y(m)⁠ and a probability p in ⁠(0, 1)⁠, the estimate is the sum of w_i * y(i) with weights w_i = I_(i/m)(a, b) - I_((i-1)/m)(a, b), where I is the regularized incomplete beta function, a = p * (m + 1), and b = (1 - p) * (m + 1). The weights depend only on the number of draws and p and are computed once for all columns that need them. The estimate is exact for constant columns and does not overflow for finite draws. The probabilities 0 and 1 return the minimum and the maximum, and a single draw is returned as it is.

Caveats of the estimator:

• The quantiles of the columns are pointwise: the result is not a simultaneous band of the underlying curve.

• Smoothness gives no general accuracy guarantee relative to the empirical quantile, including at extreme probabilities (e.g., 0.0005). Increasing the number of draws reduces Monte Carlo error; smoothing alone does not remove it. In simulations of smooth curves (lines with normal coefficients, probability 0.025, 1,000 and 10,000 draws), the root mean squared error was about as large as that of the empirical quantile (median ratios of 0.92 and 0.97) and the roughness of the error along the grid was several times smaller; this is no guarantee for other draws or settings.

• The input draws have equal weights (there are no importance weights), but the estimator gives every draw a positive and unequal weight that depends on its rank and is largest for the draws closest to the target rank. A small number of draws (below roughly 200) and heavy tails can therefore move the estimate far from the empirical quantile.

• Draws with a point mass (an atom, e.g., a parameter fixed at zero in part of a model-averaged posterior) are not treated separately: within about two Monte Carlo standard errors (in probability) of the edge of a point mass, the estimate blends the point mass and the continuous draws.

• The weighted sum is computed in double precision. Its rounding error is of the order of the machine precision times the largest absolute draw. Where the sorted draws jump close to the target rank (e.g., at the edge of a point mass or in a sparse tail), the rounding of the cell boundaries i/m can make it larger by a factor that grows roughly in proportion to sqrt(m * p / (1 - p)). Measured binary-step examples with zeros and the top r draws equal to one give about 40 with m = 10000, r = 249, p = 0.975, and about 1,400 with m = 100000, r = 50, p = 0.9995. Differences between draws that are much smaller than this error (e.g., the middle draw of c(-1e16, 1, 1e16)) are not resolved.

An infinite draw has a positive weight at every probability strictly between 0 and 1, which makes the weighted average infinite (or undefined for infinite draws of both signs). A column that contains an infinite draw is therefore summarized by the empirical quantile of that column (stats::quantile(), type 7). If that quantile is NaN (an interpolation between draws of -Inf and Inf), or if the weights of a probability cannot be computed numerically (at tiny probabilities, with a limit that depends on the draw count and distribution-function implementation), the function stops with an error of class BayesTools_harrell_davis_undefined (also of the family class BayesTools_harrell_davis). The weights are computed only when a column with finite draws needs them, so columns of infinite draws never raise the second error.

Value

a numeric vector of the same length as probs for a vector x, and a matrix with length(probs) rows and one column per column of x (keeping its column names) for a matrix x.

References

Harrell FE, Davis CE (1982). “A new distribution-free quantile estimator.” Biometrika, 69(3), 635–640. doi:10.1093/biomet/69.3.635.

See Also

stats::quantile()

Examples

set.seed(1)
draws <- rnorm(500)
harrell_davis_quantile(draws, c(.025, .5, .975))
quantile(draws, c(.025, .5, .975), names = FALSE)

# pointwise credible band of a line from draws of its intercept and slope
intercept <- rnorm(500)
slope     <- rnorm(500, sd = .5)
x_grid    <- seq(-1, 1, length.out = 5)
line      <- outer(intercept, rep(1, 5)) + outer(slope, x_grid)
harrell_davis_quantile(line, c(.025, .5, .975), names = TRUE)

Hypothesis Bayes Factors

Description

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.

Usage

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, ...)

Arguments

Details

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.

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.

Value

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.

Fitted models

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.

References

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.

Hypothesis Bayes factors of a fitted model

Description

hypothesis_BF_model() is the engine behind hypothesis_BF() of a BayesTools_fit, exported for packages that test hypotheses on the parameters of their own models. It parses the statements with the parameter catalog of the model, resolves each to one tested parameter, plans how it can be evaluated (the draws and the prior density of the tested quantity, the classification of its point values), checks every plan against the requested density backend, evaluates the statements in groups that share a tested quantity, and binds the results into one table in the order of the statements. What the engine needs to know about the model comes from its provider (hypothesis_provider()); the methods to evaluate a point hypothesis are the density backends (hypothesis_density_backend()).

Usage

hypothesis_BF_model(
  object,
  hypothesis,
  namespace = NULL,
  component = NULL,
  transform_scaled = FALSE,
  conditional = FALSE,
  logBF = FALSE,
  BF01 = FALSE,
  seed = NULL,
  density_method = NULL,
  density_control = NULL,
  n_samples = 10000,
  columns = "default",
  parameter = NULL,
  conditional_omitted = FALSE
)

Arguments

Details

Every statement is planned before any is evaluated: the plan records the tested target (its weights on the fitted coefficients, its prior density and declared atoms), the classification of each point value by prior_ordinate_status(), and what refuses it. A statement that the requested density backend cannot evaluate stops with its refusal before anything is computed. The refusals are classed conditions; callers match the class and never the message:

BayesTools_hypothesis_statement

a statement that has to be restated, or an argument that has to change: point expressions that are no direct reference (for example "2 * mu = 0"), nonlinear expressions of factor levels, one quantity named by several names, and references that BayesTools refuses (BayesTools_parameter_resolution_error, for example BayesTools_parameter_not_found for an unknown name or level, which keeps its fields alias and available). BayesTools_hypothesis_ambiguous (parent BayesTools_hypothesis_statement) marks a statement whose references still name several model parameters, and BayesTools_hypothesis_component_mismatch a statement whose parameters belong to another component than the requested one; BayesTools_hypothesis_parameter_mismatch a marginal-means statement that refers to another parameter than parameter.

BayesTools_hypothesis_unavailable

a test that cannot be computed, with the more specific BayesTools_hypothesis_fixed (the quantity is fixed by the fitted model), BayesTools_hypothesis_target (no supported target or prior density), or BayesTools_hypothesis_method (the density backend is unavailable for the target). A point hypothesis whose prior ordinate is not exact, finite, and regular stops with the class of prior_ordinate_status() (for example BayesTools_point_mass_at_null) and BayesTools_hypothesis_ordinate.

A density backend owns its own conditions (a failed ordinate, a model it does not support).

Random numbers: the draws of every statement are extracted while it is planned, without seed; seed only reaches the evaluation of the Bayes factors of the draws (hypothesis_BF()) and the prior draws of random-effect quantities that have no prior density.

Value

A BayesTools_hypothesis_BF table, as returned by hypothesis_BF(), with the rows labelled as the statements were written. When an ordinate backend computed ordinates, the table can carry the density_diagnostics attribute of the backend.

References

There are no references for Rd macro ⁠\insertAllCites⁠ on this help page.

See Also

hypothesis_BF(), hypothesis_provider(), hypothesis_density_backend(), hypothesis_quantities()

Helpers of hypothesis tables

Description

Small helpers that the entry points of a package share with hypothesis_BF_model(). hypothesis_alias_label() is the name under which the rows of a hypothesis table show a tested parameter: the first alias of the parameter other than its own name, or the parameter. hypothesis_unique_named_warnings() drops repeated warnings of a table (the same text for the same row).

Usage

hypothesis_alias_label(aliases, parameter)

hypothesis_unique_named_warnings(warnings)

Arguments

Value

hypothesis_alias_label() returns a string. hypothesis_unique_named_warnings() returns the unique, nonempty warnings, or NULL without any.

See Also

hypothesis_BF_model()

Versioned hypothesis syntax trees

Description

hypothesis_parse() parses the restricted language used by hypothesis_BF() into a validated, serializable syntax tree. An explicit vs comparison requires two nonempty statements. hypothesis_render() renders that tree with token-safe quoting. hypothesis_symbols() returns exact parameter roots or an occurrence table. Quoted reserved names and ordinary identifiers retain their exact identity; numeric labels preserve the parsed values when rendered and parsed again.

hypothesis_rewrite() replaces only exact symbol roots. Function names, literals, level labels, and longer identifiers are never edited. hypothesis_resolve() resolves every occurrence through parameter_catalog_resolve() without accessing posterior draws. A bracketed symbol such as mu_f[b] or ⁠(mu) f[b]⁠ is first resolved as an exact catalog name or alias; otherwise its bracketed level is used as the catalog component of the parameter before the bracket. The bracket always holds a level label: mu_f[2] selects the level labelled "2", never the second fitted coordinate. A symbol that does not resolve uniquely stops with the classed errors of parameter_catalog_resolve(), a hypothesis without parameter symbols (e.g. "1 > 0") stops with an error of class BayesTools_hypothesis_no_parameters, and a level-qualified symbol whose level differs from component stops with an error of class BayesTools_hypothesis_component_mismatch (fields symbol and component); both are also BayesTools_parameter_resolution_error.

Usage

hypothesis_parse(
  hypothesis,
  catalog = NULL,
  namespace = NULL,
  component = NULL,
  simplify_names = FALSE
)

hypothesis_ast_schema()

hypothesis_render(ast)

hypothesis_symbols(ast, occurrences = FALSE)

hypothesis_rewrite(ast, mapping)

hypothesis_resolve(
  ast,
  catalog,
  namespace = NULL,
  component = NULL,
  simplify_names = FALSE
)

Arguments

Value

hypothesis_parse() and hypothesis_rewrite() return a BayesTools_hypothesis_ast. hypothesis_render() returns character text. hypothesis_symbols() returns unique roots or an occurrence data frame. hypothesis_resolve() returns a versioned BayesTools_hypothesis_resolution containing one row per occurrence.

Drop the caches of the hypothesis engine

Description

Drops the cached plans of hypothesis_BF_model() and hypothesis_quantities() (draws, selections, and plans are kept per model object for the session) and the caches of the registered density backends (hypothesis_density_backend()). A package calls it when a function the plans are built with has been replaced (for example after reloading).

Usage

hypothesis_cache_clear()

Value

NULL, invisibly.

Density backends of fit-level hypothesis Bayes factors

Description

The density backend of a point hypothesis (the density_method of hypothesis_BF() and hypothesis_BF_model()) decides how the posterior ordinate at the null value is obtained. The built-in backends "KDE" and "normal" estimate it from the posterior draws, and "precomputed" uses ordinates that are stored on the draws (it is for draw inputs only, not for fitted models). A package that computes posterior ordinates itself, for example by a likelihood-aware estimator that cannot be written as a function of the draws, registers an ordinate backend. hypothesis_density_backend() creates a backend object, register_hypothesis_density_backend() adds it to the registry (a package registers its backends in .onLoad() and removes them with unregister_hypothesis_density_backend() in .onUnload()), and hypothesis_density_backends() lists the registered backends.

Usage

hypothesis_density_backend(
  name,
  type = c("ordinate", "draws", "stored"),
  available = NULL,
  control = NULL,
  attach = NULL,
  reuse = NULL,
  warnings = NULL,
  diagnostics = NULL,
  bind_diagnostics = NULL,
  rescale_failure = NULL,
  refusal_classes = NULL,
  clear_cache = NULL,
  method = NULL,
  policy = list(),
  advertised = TRUE,
  package = NULL
)

register_hypothesis_density_backend(backend, overwrite = FALSE)

unregister_hypothesis_density_backend(name)

hypothesis_density_backends()

Arguments

Details

A backend has a type: "draws" (evaluated from the posterior draws by hypothesis_BF() with the density method method), "ordinate" (the backend attaches the posterior ordinates of the tested values to the draws; they are then evaluated as "precomputed" ordinates), or "stored" (the ordinates are already attached to the draws). Matching of density_method to the registered names ignores case and accepts unambiguous partial names.

The engine calls the callbacks of a backend as follows; each is optional except attach of an ordinate backend.

available(object, plan, control)

whether the backend can evaluate the statement plan of the model object (the capability_object of the provider) with the normalized control, the settings that control() returns for the call (for the stored marginal means of a model, for the settings of the call or the stored settings that the provider inherits). For the stored marginal means, settings that control() refuses reach available() as they were supplied, and the engine stops with the failure of control() after the plans are checked; for a fitted model, the failure of control() stops the call before any plan is checked. It is evaluated on every call and never cached. It returns NULL when the backend can, and otherwise a refusal: a list with the reason (a string) and optionally class (additional condition classes appended to BayesTools_hypothesis_method and BayesTools_hypothesis_unavailable) and fields (a named list of further fields of the condition). The engine stops with the refusal before any statement is evaluated.

control(control)

the normalized density_control of the backend (defaults filled in), stopping on invalid settings. It is called with the settings of the call (or the stored settings of the provider) on every call with an ordinate backend, and for the settings that a call supplies to another backend, after the check_density_control() of the provider (hypothesis_provider()). The default accepts no settings: NULL and an empty list give NULL, anything else is an error.

attach(posterior, request, control, cache)

the whole ordinate step of an ordinate backend. posterior is the marginal posterior of the tested quantity (a vector, or for the request of a factor level the list of the posteriors of the levels of the factor term); it returns it with the ordinates of the requested values stored in its posterior_ordinate metadata (posterior_metadata(), posterior_ordinate_attribute(), posterior_ordinate_append()), one entry per value, and the parameter, conditional, conditional_rule, and condition_key metadata of the draws, or stops with its own typed condition when an ordinate cannot be constructed. cache is an environment that lives for the evaluation of one group of statements, for objects that the requests of the group share. The request is a list with the elements kind ("scalar": the values of the vector posterior; "level": the values of the level level), route (the kind of the statement plan: "scalar", "linear", "random", "exp_affine", or "marginal_mean"), object (the model object, or the object that the provider names as its capability_object), model (the object of the provider), parameter, label (the tested quantity, as the table names it), level, values (the point values to compute), conditional (the conditioning of the draws: the parameter whose inclusion event the draws are conditioned on, or NULL), condition (the declared conditioning of the draws that the ordinates belong to, read from their metadata (posterior_metadata(), "condition"): the elements conditional (the effective conditioning, a character vector that is empty for averaged draws), conditional_rule, condition_key, condition_event, and resolved_condition_event, those the draws declare; an empty list for draws without a declaration), spec (the structure of the tested quantity that the provider declares: for example type = "primitive" or "linear" with the weights on the fitted coordinates and the prior_density), display_transform (the transformation from the evaluated to the tested scale, or NULL), density_method (the name of the backend), and inference_type (marginal means: the marginal inference the draws belong to).

reuse(entry, request, control, posterior)

whether the ordinate entry that is stored on the draws posterior at a requested value is current for the request (the method, control, source of the fit, target, and conditioning agree), so that it is not computed again. posterior are the draws that carry entry (for the request of a factor level, the draws of that level), with their metadata; request$condition is their declared conditioning. The default reuses nothing: stored ordinates at the requested values are replaced.

warnings(posterior, request)

the warnings of the ordinates stored on posterior (recursively over the levels of a list), as a data frame with the columns warning, parameter, level, label, and value. The engine puts each warning on the rows of the statements it belongs to. The default reads the warning element of the diagnostics of each stored ordinate. The request is the request that attach received for the group of statements, before the values whose stored ordinates reuse accepted were left out of values; for a group that is attached level by level (the levels of a factor term, marginal means) it is the request of the first level, and the requests of the group differ in their level, values, label, spec, and condition only.

diagnostics(posterior, request)

the public diagnostics of the stored ordinates (a data frame; request as for warnings), stored as the density_diagnostics attribute of the table, and bind_diagnostics(list), which combines the diagnostics of several groups of statements. Without diagnostics the table has no such attribute; the default of bind_diagnostics row-binds the data frames.

rescale_failure(condition, requested, evaluated, label, density_method)

restates a condition that attach raised for the evaluated values evaluated of a request for the values requested of a quantity that is evaluated through a transformation of itself (a variance through its standard deviation); it returns the condition to signal, or NULL to signal the original one.

refusal_classes(cause)

additional condition classes for the refusals of the ordinate backends for a generic cause ("original_scale", "conditional_random", or "random_target"); they follow the classes of the refusal of the engine (for example BayesTools_hypothesis_target and BayesTools_hypothesis_unavailable). A provider names the cause of the refusal of a random-effect quantity (hypothesis_provider()).

clear_cache()

drops the caches of the backend; the engine calls it when it drops its own caches.

policy is a list of the settings that the backend declares for its acceptance of ordinates (thresholds on its error estimates, for example). It is reported by hypothesis_density_backends() and not used by the engine: the backend applies its own acceptance rules in attach, and the engine only checks that the attached ordinates are valid (posterior_ordinate_supports_bf()).

Value

hypothesis_density_backend() returns an object of class BayesTools_hypothesis_density_backend. register_hypothesis_density_backend() returns the backend invisibly, and unregister_hypothesis_density_backend() returns whether a backend was removed (invisibly). hypothesis_density_backends() returns a data frame with one row per registered backend in the order of registration: name, type, package, advertised, and the list column policy.

See Also

hypothesis_BF(), hypothesis_BF_model(), hypothesis_provider()

Examples

hypothesis_density_backends()

# a toy backend that evaluates the ordinate of a normal posterior exactly
normal_ordinate <- hypothesis_density_backend(
  name   = "exactNormal",
  type   = "ordinate",
  attach = function(posterior, request, control, cache) {
    draws    <- as.numeric(posterior)
    ordinate <- stats::dnorm(request$values, mean(draws), stats::sd(draws))
    posterior_metadata(posterior, "posterior_ordinate") <-
      posterior_ordinate_attribute(
        value = request$values, ordinate = ordinate,
        method = "exact normal", density_method = "exactNormal",
        parameter = attr(posterior, "parameter")
      )
    posterior
  }
)
register_hypothesis_density_backend(normal_ordinate)
hypothesis_density_backends()$name
unregister_hypothesis_density_backend("exactNormal")

Compile a hypothesis linear in the levels of one parameter

Description

When structured quantity labels are available, hypothesis tables display the compiled combination's label rather than its internal scalar name. Compiles point and simple region statements that all refer to one linear combination t = \sum_l c_l L_l of levels L_l of the same parameter of one marginal posterior, e.g. a difference of two levels, a scaled level, or a weighted average of several levels. The returned scalar marginal posterior of t retains the exact joint-prior density and the structural conditioning metadata needed by downstream inference methods (e.g. precomputed posterior-ordinate estimators that need the combined linear weights).

Every referenced level must have one fixed named linear-weight row over the fitted coordinates and a declared posterior-atom status, and the levels must share a joint prior context and conditioning event. The prior density of t is the joint-context density at the combined weights \sum_l c_l w_l shifted by the combined level offsets: on the fitted scale it equals parameter_prior_density() at those coordinate weights, and on the original scale of scaled formula coefficients JAGS_formula_prior_density() with the corresponding weights. It must be atom-free; by absolute continuity the posterior of t is then atom-free as well. Affine transformations already applied to the marginal levels retain their scale and offset; nonlinear transformed marginal levels, nonlinear expressions, row-varying level weights, and statements about different combinations are rejected.

Usage

hypothesis_linear_target(posterior, hypothesis, parameter)

Arguments

Value

A list with posterior, hypothesis, parameter, and weights. posterior is a scalar marginal_posterior of the linear combination whose draw metadata (posterior_metadata()) hold the combined linear_weights and linear_offset, its prior_density and prior_context, declared (empty) atoms, the condition of the levels, and, when the levels carry label parts, quantities labelling the target by the combination of the levels' labels (e.g. ⁠(mu) 2*f[A] - f[C]⁠, see parameter_labels()); hypothesis is an equivalent AST written against that scalar target, parameter its name, and weights the combined linear weights. A target that cannot be certified stops with an error of class BayesTools_linear_target_unavailable (also BayesTools_hypothesis_target) whose field reason is "posterior_atoms" (the target's prior is not structurally atom-free), "atom_declarations" (a level lacks its posterior-atom declaration), "prior_context" (no valid joint prior context, including level weights on columns the joint prior context does not contain), "weight_space" (the levels' linear weights are in different weight spaces), or "component_alignment" (the repeated mixture component keys of the levels do not match the original posterior rows). A reference to a level that posterior does not contain stops with an error of class BayesTools_parameter_not_found (also BayesTools_parameter_resolution_error), as in hypothesis_BF(). A translated threshold is the correctly rounded quotient of the statement's value and divisor. Numerical loss in coefficients, or a threshold quotient that is not finite, underflows or is subnormal, stops with BayesTools_hypothesis_numerical_unavailable (also BayesTools_hypothesis_ordinate, BayesTools_numerical_unavailable, and BayesTools_numerical_condition). Unrepresentable target units are unavailable; the compiler does not round or clamp them into a valid target.

Linear form of one side of a hypothesis statement

Description

Reads one side of a statement of a hypothesis syntax tree as a linear combination of the levels of one parameter, \sum_l c_l L_l, compared with a value by the operator of the side. It is the per-side reading that hypothesis_linear_target() uses, and it identifies the combination of levels that a statement is about without a posterior: statements with identical coefficients refer to the same linear combination, however their level expressions are written. The coefficients are not normalized, so a multiple of a combination has other coefficients.

Usage

hypothesis_linear_target_side(side, parameter)

Arguments

Details

The side is a left or right element of a statement of a BayesTools_hypothesis_ast (see hypothesis_parse() and hypothesis_ast_schema()): a point side (=, !=), or a region side with a simple comparison (<, <=, >, >=). In a comparison the right expression is subtracted from the left expression. The expressions are linear in the level references of parameter (for example f[A]) and numbers: sums and differences, level references multiplied or divided by numbers, and parentheses. Levels of other parameters, other terms, and other kinds of sides stop with an error. The value is the correctly rounded quotient of the statement's constant and divisor. Numerical loss in the coefficients, or a value that is not finite, underflows or is subnormal, stops with an error of class BayesTools_hypothesis_numerical_unavailable, as in hypothesis_linear_target().

Value

hypothesis_linear_target_side() returns a list with

operator

the operator of the side: "=" or "!=" for point sides, and the comparison operator for region sides.

coefficients

a named numeric vector of the coefficients of the levels divided by divisor, named by level, sorted by level, without zero coefficients.

numerator_coefficients

the coefficients of the levels before the division by divisor.

value

the value that the combination is compared with, in the unit of coefficients (the value after moving the constants of the expressions to it and dividing by divisor).

divisor

the divisor of the expression.

See Also

hypothesis_linear_target() hypothesis_parse()

Examples

side <- hypothesis_parse("f[A] - 2*f[B] > 0.5")$statements[[1]]$left
hypothesis_linear_target_side(side, "f")

side <- hypothesis_parse("(f[A] + f[B])/2 = 0")$statements[[1]]$left
hypothesis_linear_target_side(side, "f")

Hypothesis parser helpers

Description

Utilities for parsing point-null hypothesis references and level references in the same syntax accepted by hypothesis_BF.

Usage

hypothesis_parse_point_reference(hypothesis, allow_compound = TRUE)

hypothesis_parse_level_reference(text)

hypothesis_normalize_level_references(text)

Arguments

Value

hypothesis_parse_point_reference() returns a data frame with columns hypothesis, side, symbol, parameter, level, value, operator, and direct. hypothesis_parse_level_reference() returns a data frame with columns input, symbol, parameter, level, and direct. hypothesis_normalize_level_references() returns a character vector.

Hypothesis provider of a fitted model

Description

hypothesis_provider() is the single hook through which hypothesis_BF_model() reaches a model. Its method returns a provider, a list of the callbacks and values that the engine needs for the statements it plans: the parameter catalog and its entries, the draws of the tested quantities, the random-effect quantities, and the density backends that can evaluate them. The method for a BayesTools_fit returns the default provider, which implements every callback with the functions of BayesTools (parameter_catalog(), as_mixed_posteriors(), marginal_posterior(), parameter_mixed_posterior(), JAGS_formula_coefficient_transform(), and JAGS_formula_prior_density()). A downstream model class that wraps a fit starts from hypothesis_provider(<its fit>) and replaces the callbacks that differ with utils::modifyList(), so that it overrides only what is specific to its model.

Usage

hypothesis_provider(object, ...)

## Default S3 method:
hypothesis_provider(object, ...)

## S3 method for class 'BayesTools_fit'
hypothesis_provider(object, ...)

Arguments

Details

A provider is a list of class BayesTools_hypothesis_provider; the engine checks it before use. Its elements are the following. The callbacks close over the model object.

kind

"model" (default) or "marginal_means".

object

the model object. It is hashed for the cache of plans and passed to the density backends.

fit

its BayesTools_fit, from which the transforms of formula coefficients and their prior densities are read.

capability_object

the object the density backends receive in available() and in their requests (default object).

build, refit_class

the name of the build in the requests to refit a model with outdated metadata ("Refit the model with the current ⁠<build>⁠ build."), and classes that precede BayesTools_refit_required in those conditions.

caller, random_point_mass_advice, transform_scaled_default

the name of the entry point in the reasons of refusals (default "hypothesis_BF()"); the sentence that ends the reason of a refused point null at a prior point mass of a random-effect quantity; and the scale of hypothesis_quantities() when transform_scaled is NULL.

ordinate_label

how the messages of refusals name the ordinate backends (default "ordinate density methods").

component_argument

the name of the argument through which the caller selects a value of components (default "namespace", the argument of hypothesis_BF_model() and of the method of hypothesis_BF() for a BayesTools_fit). The messages of the engine that name that argument ("The 'hypothesis' argument selects namespace = 'mu' but 'namespace' was set to 'random'.") use it; a model class that passes the selection under another name sets it, for example "component".

density_methods

the names that density_method can match, in order (default: the registered backends that are not of type "stored").

components

the selection vocabulary of the namespace argument as data: values (the accepted values, in the order of the error message), synonyms (a named character vector, for example c(location = "mods")), default ("auto"), refused (a named character vector of the reasons for which a component cannot be tested), random (the value that selects the random-effect quantities), and advice (the sentence that follows the message of an ambiguous statement).

metadata()

a list with the catalog (a parameter_catalog(), possibly extended with parameter_catalog_extend(); the engine parses and resolves with it) and the entries: a data frame with one row per tested parameter and the columns quantity_id, parameter (the name of the tested parameter), component (a value of components$values), term, source, formula_parameter, role ("formula_coefficient_group" for a whole factor term, whose levels are its member_quantity_ids), quantity, status, fixed_value, aliases (a list column), and member_quantity_ids (a list column). The alias rows of the catalog of the entries carry the component as their namespace and component.

uncovered(resolution, quantity_ids, symbol, metadata)

the refusal for resolved quantities that no entry covers: a list with reason and either type ("target" or "statement") or the complete condition class.

sample_parameters(parameter), mixed_posteriors(parameters, conditional, conditional_rule, transform_scaled, n_prior_samples), density_parameter(samples, parameter, sample_parameters), formula_name_map(formula_parameter)

the draws of a fixed coefficient: the prior-list names whose draws are mixed (the parameter and the owners of the fitted coordinates that its prior density combines), the mixed posteriors (as_mixed_posteriors()), the element of the samples that is the tested parameter, and the map of the formula coefficients to the fitted names.

random

the callbacks for the random-effect quantities: select(parameter, transform_scaled) (a list with the element spec, a list with the label and status of the quantity, and any elements the other callbacks need), mixed_posterior(parameter, transform_scaled, conditional, selected) (the mixed posterior as the one-element list returned by as_mixed_posteriors()), support(selected) (the exact bounds on the scale requested from select(), which are those of the draws), density_target(parameter, transform_scaled, operation) (a list with the quantity that a density backend evaluates, its parameter_spec, and display_transform, or the refusal of a quantity without one: its reason, and optionally its type ("target", the default, "method", or "fixed": the engine's refusal BayesTools_hypothesis_<type> and its parent BayesTools_hypothesis_unavailable) and its cause ("random_target", the default, or "original_scale"), for which the density backend appends its classes (refusal_classes(cause))), sd_pair(selected) (the standard deviation of which a variance is the square, or NULL), zero_boundary(selected) (NULL, or a list with the statement that tests the omission of a component), defined_share(values, selected, conditional), defined_footnote(label, samples, posterior_defined, prior_defined), defined_draws(values, samples, label) (the treatment of the draws at which a quantity is undefined), and prior_draws(parameter, selected, transform_scaled, n_samples, seed) (prior draws of a quantity without a prior density with provenance).

point_mass_reason()

NULL, or the text that replaces the reason of a point hypothesis at a prior point mass.

full_ensemble(parameter)

whether omitting conditional tests the parameter within the full ensemble, including the models in which it is fixed by its null component (the engine then warns); combination_hint(plan): NULL, or text appended to the refusal of a linear combination of the levels of such a term.

check_plans(plans)

NULL, or a function that validates the plans of all statements of a request and stops with a refusal.

check_density_control(density_method, density_control)

NULL, or a function that checks the density_control of a call before the control() of the density backend sees it. It receives the name of the selected backend and the settings as supplied (a list, possibly empty, or NULL) wherever control() is called: on every call with an ordinate backend, and on every call that supplies settings to another backend (for stored marginal means also where the stored settings are normalized). It stops with the condition that refuses the settings; its value is ignored. Without it the built-in backends accept NULL and an empty list and refuse other settings with the message 'density_control' is not used by density_method = 'KDE'., and the control() of a backend validates its own settings.

A provider of kind = "marginal_means" describes the stored marginal means of a model instead: inference (the marginal inference with the elements averaged and conditional), model_averaged (logical; model-averaged point statements are tested on the conditional draws and cannot mix with region statements), capability_object (the fit that the backends compute ordinates from, or NULL), select(hypothesis, parameter) (the marginal-means parameter and its aliases that a statement names), density_method_default() and density_control_default(density_method) (used when the arguments are NULL), and metadata() for hypothesis_quantities().

Value

A provider, a list of class BayesTools_hypothesis_provider.

See Also

hypothesis_BF_model(), hypothesis_density_backend()

Available Hypothesis Quantities

Description

Lists the parameter names and aliases that hypothesis_BF() accepts for a fitted model, with the tests that it runs on each of them.

Usage

hypothesis_quantities(object, ...)

## Default S3 method:
hypothesis_quantities(object, transform_scaled = NULL, ...)

## S3 method for class 'BayesTools_fit'
hypothesis_quantities(object, transform_scaled = NULL, ...)

Arguments

Details

The eligibility columns render the plans that hypothesis_BF_model() executes (see its details) for the statements <q> = <null> (point tests), <q> > <null> (directional and interval tests), and, for factor terms, <level> = <other level> (level contrasts) of every quantity q. The null value is 0; when 0 is a prior point mass, a support boundary without a regular prior ordinate, or outside the support (for example, a gated random-effect standard deviation or a variance proportion), the point test is rendered at an interior value of the support instead (the midpoint of a bounded support, one unit inside a half-bounded support, and 1 otherwise): point hypotheses at such values follow the per-value rules of hypothesis_BF_model(). A factor term lists the point-test methods available for all of its levels that the contrast does not fix, and the contrast-test methods available for all pairs of its levels. Region tests do not use a density method. The methods are the registered density backends that are advertised (hypothesis_density_backends(); the normal approximation is a rough check and is not listed).

Value

A data frame with the columns alias (a name that hypothesis_BF() resolves to the row's quantity when the row's component is passed as the argument that selects the component of the model, which the provider names in its component_argument: the namespace argument for a BayesTools_fit; a name shared by several quantities of a component is not listed), parameter, component, term, bracket (a parameter[level] template for fitted factor terms, or a concrete level selector for each marginal-mean row), point_test, direction_test, contrast_test (NA for quantities without levels), point_test_methods, contrast_test_methods, and reason (the refusals of the rendered statements).

See Also

hypothesis_BF(), hypothesis_BF_model()

Stop with a refusal of a hypothesis

Description

Raises the error with which the hypothesis engine (hypothesis_BF_model()) refuses a statement or a test that it cannot compute, so that other entry points of a package refuse the same cause with the same condition classes.

Usage

hypothesis_stop(
  reason,
  type = c("target", "fixed", "method", "statement", "ambiguous"),
  class = NULL,
  fields = NULL
)

Arguments

Value

Does not return; it signals the error.

See Also

hypothesis_BF_model()

Compute inclusion Bayes factors

Description

Computes inclusion Bayes factors based on prior model probabilities, posterior model probabilities (or natural-log marginal likelihoods), and an indicator of whether the models represent the null or alternative hypothesis.

Usage

inclusion_BF(
  prior_probs,
  post_probs,
  margliks,
  is_null,
  on_failure = c("error", "drop", "zero")
)

Arguments

Details

Supplying margliks as the input is preferred since it is better at dealing with under/overflow (posterior probabilities are very close to either 0 or 1). In case that both the post_probs and margliks are supplied, the results are based on margliks. If the prior probability of either the null or alternative hypothesis is zero, the Bayes factor is undefined and NA is returned.

Value

inclusion_BF returns a Bayes factor.

Interpret ensemble inference and estimates

Description

Provides textual summary for posterior distributions created by mix_posteriors and ensemble inference created by ensemble_inference.

Usage

interpret(inference, samples, specification, method)

interpret2(specification, method = NULL)

Arguments

Value

interpret returns character.

See Also

ensemble_inference mix_posteriors BayesTools_model_tables BayesTools_ensemble_tables

Normalize structured interpretation sources

Description

interpret_records normalizes interpretation inputs from one or more structured sources into traceable evidence, estimate, header, note, prior, and footnote records. It is intended for downstream packages that already own the domain-specific ordering and wording of an interpretation, but want BayesTools to consistently extract table rows, preserve Bayes-factor metadata, and carry traceability information.

Usage

interpret_records(
  sources,
  plan,
  output = c("records", "text"),
  missing = c("error", "skip", "warn"),
  method = NULL,
  digits = 3
)

interpret_tables(sources, spec, ...)

Arguments

Value

interpret_records returns a data frame with class "BayesTools_interpret_records" when output = "records", or a character vector when output = "text". Evidence records keep the supplied BF_value and BF_scale; BF_canonical_value is the Bayes factor on the natural scale in the canonical orientation (0 or Inf for a log-scale value beyond the double range). The text rendering classifies and prints a log-scale value from its logarithm, so such values keep their evidence strength and are printed as exp(<log>). interpret_tables is a convenience wrapper around interpret_records.

Invert the orientation of Bayes factor bound operators

Description

Swaps "<" and ">": the bound operators of a Bayes factor in the BF10 orientation become those of its reciprocal in the BF01 orientation, and the other way round. Missing operators (exact values) are kept.

Usage

invert_BF_bound_operator(operator)

Arguments

Value

invert_BF_bound_operator() returns a character vector of the length of operator (without names) with the operators swapped.

See Also

format_BF_from_log() format_BF()

Examples

invert_BF_bound_operator(c("<", ">", NA))

Reports whether x is a a prior object

Description

Reports whether x is a a prior object. Note that point priors inherit the prior.simple property

Usage

is.prior(x)

is.prior.point(x)

is.prior.none(x)

is.prior.simple(x)

is.prior.discrete(x)

is.prior.vector(x)

is.prior.simplex(x)

is.prior.PET(x)

is.prior.PEESE(x)

is.prior.weightfunction(x)

is.prior.factor(x)

is.prior.ordered(x)

is.prior.orthonormal(x)

is.prior.treatment(x)

is.prior.independent(x)

is.prior.spike_and_slab(x)

is.prior.meandif(x)

is.prior.mixture(x)

Arguments

Value

returns a boolean indicating whether the test object is a prior (of specific type).

Examples

# create some prior distributions
p0 <- prior(distribution = "point",  parameters = list(location = 0))
p1 <- prior_PET(distribution = "normal", parameters = list(mean = 0, sd = 1))

is.prior(p0)
is.prior.simple(p0)
is.prior.point(p0)
is.prior.PET(p0)

is.prior(p1)
is.prior.simple(p1)
is.prior.point(p1)
is.prior.PET(p1)

Reports whether x is a composed publication-bias prior

Description

Reports whether x is a composed publication-bias prior

Usage

is_prior_bias(x)

Arguments

Value

A logical value.

Reports whether x is a p-hacking prior

Description

Reports whether x is a p-hacking prior

Usage

is_prior_phacking(x)

Arguments

Value

A logical value.

Kitchen Rolls data from Wagenmakers et al. (2015) replication study.

Description

The data set contains mean NEO PI-R scores for two groups of students. Each of them filled a personality questionnaire while rotating a kitchen roll either clock or counter-clock wise. See Wagenmakers et al. (2015) for more details about the replication study and the https://osf.io/uszvx/ for the original data.

Usage

kitchen_rolls

Format

A data.frame with 2 columns and 102 observations.

Value

a data.frame.

References

Wagenmakers E, Beek TF, Rotteveel M, Gierholz A, Matzke D, Steingroever H, Ly A, Verhagen J, Selker R, Sasiadek A, others (2015). “Turning the hands of time again: a purely confirmatory replication study and a Bayesian analysis.” Frontiers in Psychology, 6, 1–6. doi:10.3389/fpsyg.2015.00494.

Add prior object to a plot

Description

Add prior object to a plot

Usage

## S3 method for class 'prior'
lines(
  x,
  xlim = NULL,
  x_seq = NULL,
  x_range_quant = NULL,
  n_points = 1000,
  n_samples = 10000,
  force_samples = FALSE,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  show_parameter = if (individual) 1 else NULL,
  individual = FALSE,
  rescale_x = FALSE,
  scale_y2 = NULL,
  ...
)

Arguments

Details

For ordered and Dirichlet simplex priors, show_parameter is a single figure between 1 and the number of figures; other values stop with an error. The default draws the default selection of plot.prior().

Value

lines.prior returns NULL.

See Also

plot.prior() geom_prior()

Add list of prior objects to a plot

Description

Add list of prior objects to a plot

Usage

lines_prior_list(
  prior_list,
  xlim = NULL,
  x_seq = NULL,
  x_range_quant = NULL,
  n_points = 500,
  n_samples = 10000,
  force_samples = FALSE,
  individual = FALSE,
  show_figures = if (individual) 1 else NULL,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  rescale_x = FALSE,
  scale_y2 = NULL,
  prior_list_mu = NULL,
  effect_direction = "positive",
  ...
)

Arguments

Details

For base plots, the default scale_y2 = NULL reuses the probability mapping established by the initial mixed-distribution plot. This keeps separately added prior and posterior point masses comparable.

Value

lines_prior_list returns NULL.

See Also

plot_prior_list() geom_prior_list()

Model-average marginal posterior distributions and marginal Bayes factors

Description

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.

Usage

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

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.

Value

marginal_inference returns an object of class 'marginal_inference'.

See Also

ensemble_inference mix_posteriors BayesTools_ensemble_tables

Model-average marginal posterior distributions

Description

Creates marginal model-averages posterior distributions for a given parameter based on model-averaged posterior samples and parameter name (and formula with at specification).

Usage

marginal_posterior(
  samples,
  parameter,
  formula = NULL,
  at = NULL,
  prior_samples = FALSE,
  use_formula = TRUE,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  n_samples = 10000,
  ...
)

Arguments

Details

When the mixed posterior samples carry deterministic posterior_density, posterior_ordinate, or support metadata (posterior_metadata()), marginal_posterior() propagates matching metadata to the returned marginal posterior. Matching uses the parameter name, list/level names such as theta[A], and conditional metadata when present. Exact support metadata is propagated even when prior_samples = FALSE; requesting prior samples adds prior-density metadata but does not replace already attached posterior support. A transformation is applied by posterior_transform() to the marginal posterior with all its metadata (supports, atoms, prior densities, stored posterior densities and ordinates, and component supports); the mixed posterior samples themselves must be untransformed (samples transformed with posterior_transform() whose prior is their prior_list are refused). If support metadata is absent, support is inferred from prior metadata only when the posterior samples are on the raw, unconditioned prior scale; otherwise the deterministic prior-density context is used so formula-scale transformations and conditional model restrictions are respected. Marginal posteriors with prior samples also record each draw's mixture component and each component's exact support (components metadata): the model of mix_posteriors() ensembles, or the combination of the mixture and spike-and-slab component indicators of a single fit (as_mixed_posteriors()). Savage_Dickey_BF() uses them when the components' supports differ. With log(intercept) formula scaling, the unscaled intercept (transform_scaled samples) is the exp of a linear combination of the fitted coefficients with the log of the fitted intercept: its simple marginal posterior (use_formula = FALSE) takes its prior density and support from the exp of that combination, and the linear predictors of a formula marginal posterior are linear in the same coefficients. Ordered formula projections reuse retained fitted coefficients, totals and allocations, with aligned model and draw rows, from the contributing formula prefixes. Every provided source of a contributing prefix is used; unrelated prefixes are excluded. Scaling is determined separately for each prefix; an unscaled prefix keeps its fitted draws when another prefix is scaled. Scaled mixed posteriors that lack the fitted ordinary coefficients needed by a formula stop with class BayesTools_ordered_coordinates_unavailable (parent BayesTools_ordered_unavailable); recreate the mixed posteriors from the source fits with this version of BayesTools.

Value

marginal_posterior returns a named list of mixed marginal posterior distributions (either vectors or matrices).

Prior mean

Description

Computes mean of a prior distribution. (In case of orthonormal prior distributions for factors, the mean of for the deviations from intercept is returned.)

Usage

## S3 method for class 'prior'
mean(x, ...)

Arguments

Details

The mean of a truncated non-normal prior is the integral of its truncated quantile function over the probability interval (0, 1). It is refused with BayesTools_numerical_unavailable when the quantile function is unavailable or the integral's estimated error exceeds 1e-6 of the interquartile range. Untruncated priors use closed forms and truncated normal priors their closed form.

Value

a mean of an object of class 'prior'.

See Also

prior()

Examples

# create a standard normal prior distribution
p1 <- prior(distribution = "normal", parameters = list(mean = 1, sd = 1))

# compute mean of the prior distribution
mean(p1)

Model-average posterior distributions

Description

Model-averages posterior distributions based on a list of models, vector of parameters, and a list of indicators of the null or alternative hypothesis models for each parameter.

Usage

mix_posteriors(
  model_list,
  parameters,
  is_null_list,
  conditional = FALSE,
  seed = NULL,
  n_samples = 10000,
  on_failure = c("error", "drop", "zero")
)

Arguments

Details

For simplex parameters such as Dirichlet priors, absent model parameters are not filled with an implicit spike at zero because the all-zero vector is off the simplex. Every model with positive prior or posterior probability must provide an explicit compatible simplex prior or point prior on the simplex.

Mixture draws are aligned across parameters by restarting from one shared sampling seed and requiring identical posterior model probabilities for every requested parameter. That holds for unconditional averaging even when is_null_list differs by parameter. Conditional averaging (conditional = TRUE) with different null indicators per parameter produces different post_probs and therefore different mixture allocations; mix_posteriors() hard-errors in that case. Mix each conditional parameter in a separate call instead.

With on_failure = "drop" or "zero", one warning is emitted for the model list, and every mixed parameter carries the marglik_failure attribute that ensemble_inference() returns for that parameter.

For an ordered total with a declared inclusion event, conditional averaging also conditions within each model. Posterior model probabilities are multiplied by the event's fraction of fitted draws; prior probabilities are multiplied by its declared prior probability. Resampling uses eligible original draw indices, and conditional prior contexts preserve the original fitted source specifications. A parameterized total without an inclusion event, including a Bernoulli total, retains every state. A compound event must be applied once to full aligned sources; separately conditioned ordered parameters cannot be combined as joint draws by this function.

Positive model declarations remain active when their visible probability rounds to zero. Numeric mixed draws remain usable. A prior law or atom law requiring model probabilities unavailable at full precision is explicitly refused with BayesTools_formula_measure_unavailable and the cause numerical_model_probability_unavailable; structured model/log diagnostics are retained in posterior_metadata(). Descriptive marginal_posterior(use_formula = FALSE, prior_samples = FALSE) remains available. An ordered projection with no allocated rows for a positive model requires a complete declared atom certificate; otherwise that measure has cause structural_target_law_unavailable. Independently known support and valid sibling measures remain available.