Package {BayesTools}

Title:	Tools for Bayesian Analyses
Version:	0.3.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 (https://mcmc-jags.sourceforge.io/)
Depends:	R (≥ 4.1.0), stats
Imports:	graphics, grid, extraDistr, mvtnorm, coda, bridgesampling, parallel, ggplot2, Rdpack, rlang
Suggests:	scales, testthat (≥ 3.3.0), vdiffr, covr, knitr, rstan, rjags, runjags, lme4, BayesFactor, RoBMA, rmarkdown
RdMacros:	Rdpack
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-05-05 14:46:53 UTC; fbart
Author:	František Bartoš [aut, cre]
Repository:	CRAN
Date/Publication:	2026-05-06 05:20:02 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.

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

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,
  transform_orthonormal = 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'.

See Also

ensemble_inference mix_posteriors BayesTools_model_tables

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,
  transform_orthonormal = 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")
)

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,
  transform_orthonormal = 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")
)

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.

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

See Also

BayesTools_ensemble_tables

Add 'JAGS' prior

Description

Adds priors to a 'JAGS' syntax.

Usage

JAGS_add_priors(syntax, prior_list)

Arguments

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 two arguments - a named list of samples from the prior distributions and the data, and returns 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,
  ...
)

Arguments

Value

JAGS_bridgesampling returns an object of class 'bridge'.

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)

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

## 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. parameter names.

Assess convergence of a runjags model

Description

Checks whether the supplied runjags-package model satisfied convergence criteria.

Usage

JAGS_check_convergence(
  fit,
  prior_list,
  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
)

Arguments

Value

JAGS_check_convergence returns a boolean indicating whether the model converged or not, with an attribute 'errors' carrying the failed convergence checks (if any).

See Also

JAGS_fit()

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

## End(Not run)

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,
  transform_orthonormal = 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,
  transform_orthonormal = 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,
  transform_orthonormal = 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,
  transform_orthonormal = FALSE,
  short_name = FALSE,
  parameter_names = FALSE,
  formula_prefix = TRUE,
  ...
)

Arguments

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 'ggplot2' if plot_type = "ggplot2".

See Also

JAGS_fit() JAGS_check_convergence()

Evaluate JAGS formula using posterior samples

Description

Evaluates a JAGS formula on a posterior distribution obtained from a fitted model.

Usage

JAGS_evaluate_formula(fit, formula, parameter, data, prior_list)

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),
  parallel = FALSE,
  cores = chains,
  silent = TRUE,
  seed = NULL,
  add_parameters = NULL,
  required_packages = 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),
  parallel = FALSE,
  cores = NULL,
  silent = TRUE,
  seed = NULL
)

Arguments

Value

JAGS_fit returns an object of class 'runjags' and 'BayesTools_fit'.

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)

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)

Arguments

Details

When a formula with -1 (no intercept) is specified, the function automatically removes the -1, adds an intercept back to the formula, and includes a spike(0) prior for the intercept to ensure equivalent model behavior while maintaining consistent formula parsing.

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.

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.

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

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

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_add_priors returns a list of JAGS initial values.

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(samples, prior_list)

JAGS_marglik_parameters_formula(
  samples,
  formula_list,
  formula_data_list,
  formula_prior_list,
  prior_list_parameters
)

Arguments

Value

JAGS_marglik_parameters returns a named list of (transformed) posterior samples.

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_formula(samples, formula_prior_list)

Arguments

Value

JAGS_marglik_priors returns a numeric value of likelihood evaluated at the current posterior sample.

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

Arguments

Value

Savage_Dickey_BF returns a Bayes factor.

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
)

Arguments

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 'bridgesampling' object

Description

prepares a 'bridgesampling' object with a given log marginal likelihood.

Usage

bridgesampling_object(logml = -Inf)

Arguments

Value

JAGS_bridgesampling returns an object of class 'bridge'.

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 = TRUE,
  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.

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)

Arguments

Details

The package includes the following contrast functions:

contr.orthonormal

Return a matrix of orthonormal contrasts. Code is based on stanova::contr.bayes and corresponding to 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.

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

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

Value

density.prior returns an object of class 'density'.

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)

ensemble_inference(model_list, parameters, is_null_list, conditional = FALSE)

models_inference(model_list)

Arguments

Value

compute_inference returns a named list of prior probabilities, posterior probabilities, and Bayes factors, ppoint gives the distribution function, 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

Format Bayes factor

Description

Formats Bayes factor

Usage

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

Arguments

Value

format_BF returns a formatted Bayes factor.

Add an Intercept to a Formula

Description

Converts a no-intercept formula to the corresponding formula with an intercept while preserving the formula environment. Top-level 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 = 1,
  ...
)

Arguments

Value

geom_prior_list returns an object of class 'ggplot'.

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 object of class 'ggplot'.

See Also

plot_prior_list() lines_prior_list()

Compute inclusion Bayes factors

Description

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

Usage

inclusion_BF(prior_probs, post_probs, margliks, is_null)

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". interpret_tables is a convenience wrapper around interpret_records.

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.PET(x)

is.prior.PEESE(x)

is.prior.weightfunction(x)

is.prior.factor(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 = 1,
  ...
)

Arguments

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

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
)

Arguments

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

Value

marginal_posterior returns a named list of mixed marginal posterior distributions (either a vector of matrix). #'

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

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
)

Arguments

Value

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

See Also

ensemble_inference BayesTools_ensemble_tables as_mixed_posteriors

Multivariate point mass distribution

Description

Density, distribution function, quantile function and random generation for multivariate point distribution.

Usage

dmpoint(x, location, log = FALSE)

rmpoint(n, location)

pmpoint(q, location, lower.tail = TRUE, log.p = FALSE)

qmpoint(p, location, lower.tail = TRUE, log.p = FALSE)

Arguments

Value

dpoint gives the density, ppoint gives the distribution function, qpoint gives the quantile function, and rpoint generates random deviates.

Examples

# draw samples from a multivariate point distribution
rmpoint(10, location = c(0, 1))

Clean parameter names from JAGS

Description

Removes additional formatting from parameter names outputted from JAGS.

Usage

format_parameter_names(
  parameters,
  formula_parameters = NULL,
  formula_random = NULL,
  formula_prefix = TRUE,
  formula_scale = NULL
)

JAGS_parameter_names(parameters, formula_parameter = NULL)

Arguments

Value

A character vector with reformatted parameter names.

Examples

format_parameter_names(c("mu_x_cont", "mu_x_fac3t", "mu_x_fac3t__xXx__x_cont"),
                       formula_parameters = "mu")

P-hacking calibration helpers

Description

phack_pi_null() converts the sampled severity alpha to the amount of null probability mass depleted from the source interval. phack_alpha_from_pi_null() applies the inverse calibration. phack_backend_constants() returns the z-scale constants used by the backend.

Usage

phack_pi_null(alpha, form, source, destination, target = 0.025)

phack_alpha_from_pi_null(pi_null, form, source, destination, target = 0.025)

phack_backend_constants(form, source, destination, target = 0.025)

Arguments

Value

Numeric vector for the calibration helpers and a named list for phack_backend_constants().

Plots a prior object

Description

Plots a prior object

Usage

## S3 method for class 'prior'
plot(
  x,
  plot_type = "base",
  x_seq = NULL,
  xlim = NULL,
  x_range_quant = NULL,
  n_points = 1000,
  n_samples = 10000,
  force_samples = FALSE,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  show_figures = if (individual) -1 else NULL,
  individual = FALSE,
  rescale_x = FALSE,
  par_name = NULL,
  ...
)

Arguments

Value

plot.prior returns either NULL or an object of class 'ggplot' if plot_type is plot_type = "ggplot".

See Also

prior() lines.prior() geom_prior()

Examples

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

# a default plot
plot(p0)

# manipulate line thickness and color, change the parameter name
plot(p1, lwd = 2, col = "blue", par_name = bquote(mu))

# use ggplot
plot(p2, plot_type = "ggplot")

# utilize the ggplot prior geom
plot(p2, plot_type = "ggplot", xlim = c(-2, 2)) + geom_prior(p1, col = "red", lty = 2)

# apply transformation
plot(p1, transformation = "exp")

Plot samples from the marginal posterior distributions

Description

Plot samples from the marginal posterior distributions

Usage

plot_marginal(
  samples,
  parameter,
  plot_type = "base",
  prior = FALSE,
  n_points = 1000,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  rescale_x = FALSE,
  par_name = NULL,
  dots_prior = list(),
  legend = TRUE,
  legend_title = NULL,
  legend_labels = NULL,
  legend_position = NULL,
  ...
)

Arguments

Value

plot_marginal returns either NULL or an object of class 'ggplot' if plot_type is plot_type = "ggplot".

See Also

prior() marginal_inference() plot_posterior()

Plot estimates from models

Description

Plot estimates from models

Usage

plot_models(
  model_list,
  samples,
  inference,
  parameter,
  plot_type = "base",
  prior = FALSE,
  conditional = FALSE,
  order = NULL,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  par_name = NULL,
  formula_prefix = TRUE,
  ...
)

Arguments

Details

Plots prior and posterior estimates of the same parameter across multiple models (prior distributions with orthonormal/meandif contrast are always plotted as differences from the grand mean).

Value

plot_models returns either NULL or an object of class 'ggplot' if plot_type is plot_type = "ggplot".

See Also

prior() lines_prior_list() geom_prior_list()

Plot samples from the mixed posterior distributions

Description

Plot samples from the mixed posterior distributions

Usage

plot_posterior(
  samples,
  parameter,
  plot_type = "base",
  prior = FALSE,
  n_points = 1000,
  n_samples = 10000,
  force_samples = FALSE,
  individual = FALSE,
  show_figures = NULL,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  rescale_x = FALSE,
  par_name = NULL,
  effect_direction = "positive",
  dots_prior = list(),
  data = NULL,
  show_data = FALSE,
  dots_data = list(),
  legend = TRUE,
  legend_title = NULL,
  legend_labels = NULL,
  legend_position = NULL,
  ...
)

Arguments

Details

When using scaled predictors (via formula_scale_list in JAGS_fit), you can plot posteriors on the original (unscaled) scale by preparing samples with as_mixed_posteriors(..., transform_scaled = TRUE). The function automatically detects this and uses the pre-computed transformed prior samples when prior = TRUE.

Value

plot_posterior returns either NULL or an object of class 'ggplot' if plot_type is plot_type = "ggplot".

See Also

prior() lines_prior_list() geom_prior_list()

Plot a list of prior distributions

Description

Plot a list of prior distributions

Usage

plot_prior_list(
  prior_list,
  plot_type = "base",
  x_seq = NULL,
  xlim = 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,
  par_name = NULL,
  prior_list_mu = NULL,
  effect_direction = "positive",
  legend = TRUE,
  legend_title = NULL,
  legend_labels = NULL,
  legend_position = NULL,
  ...
)

Arguments

Value

plot_prior_list returns either NULL or an object of class 'ggplot' if plot_type is plot_type = "ggplot".

See Also

prior() lines_prior_list() geom_prior_list()

Plot Transformed Prior Densities

Description

Plots a prior density after applying the same deterministic coefficient transformation used for formula-scale back-transforms. The helper supports continuous densities and point-mass priors in the same plot.

Usage

plot_transformed_prior(
  prior_list,
  column_names,
  formula_scale = NULL,
  parameter,
  n_points = 1000,
  x_range = NULL,
  transformation = NULL,
  transformation_arguments = NULL,
  transformation_settings = FALSE,
  plot_type = c("base", "ggplot"),
  par_name = NULL,
  ...
)

Arguments

Value

For plot_type = "base", invisibly returns base-plot metadata. For plot_type = "ggplot", returns a ggplot object. Returns NULL when the requested parameter is an identity transform and no output transformation was requested.

See Also

plot_prior_list() transform_scale_samples()

Point mass distribution

Description

Density, distribution function, quantile function and random generation for point distribution.

Usage

dpoint(x, location, log = FALSE)

rpoint(n, location)

ppoint(q, location, lower.tail = TRUE, log.p = FALSE)

qpoint(p, location, lower.tail = TRUE, log.p = FALSE)

Arguments

Value

dpoint gives the density, ppoint gives the distribution function, qpoint gives the quantile function, and rpoint generates random deviates.

Examples

# draw samples from a point distribution
rpoint(10, location = 1)

Helper functions for extracting and formatting posterior distributions

Description

Internal helper functions to extract posterior samples from JAGS fits and reformat them for further processing (summary tables, diagnostics, plots). These functions consolidate common logic that was duplicated across runjags_estimates_table, .diagnostics_plot_data, and plotting functions.

Helper to remove all columns associated with a parameter

Usage

.extract_posterior_samples(fit, as_list = FALSE)

.remove_auxiliary_parameters(
  model_samples,
  prior_list,
  remove_parameters = NULL
)

.remove_parameter_columns(model_samples, prior, par_name)

.filter_parameters(
  prior_list,
  remove_parameters = NULL,
  remove_formulas = NULL,
  keep_parameters = NULL,
  keep_formulas = NULL,
  remove_spike_0 = TRUE
)

.process_spike_and_slab(
  model_samples,
  prior_list,
  par,
  conditional = FALSE,
  remove_inclusion = FALSE,
  warnings = NULL
)

.apply_parameter_transformations(
  model_samples,
  transformations,
  prior_list,
  transform_factors = FALSE
)

.transform_factor_contrasts(
  model_samples,
  prior_list,
  transform_factors = FALSE,
  transformations = NULL
)

.rename_factor_levels(model_samples, prior_list)

Arguments

Value

matrix or mcmc.list of posterior samples

list with cleaned model_samples and updated prior_list

updated model_samples matrix

list with filtered model_samples and prior_list

list with updated model_samples, prior_list, and warnings

updated model_samples matrix

updated model_samples matrix

updated model_samples matrix with renamed columns

Print a BayesTools table

Description

Print a BayesTools table

Usage

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

Arguments

Value

print.BayesTools_table returns NULL.

Prints a prior object

Description

Prints a prior object

Usage

## S3 method for class 'prior'
print(
  x,
  short_name = FALSE,
  parameter_names = FALSE,
  plot = FALSE,
  digits_estimates = 2,
  silent = FALSE,
  ...
)

Arguments

Value

print.prior invisibly returns the print statement.

See Also

prior()

Examples

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

# print them
p0
p1

# use short names
print(p1, short_name = TRUE)

# print parameter names
print(p1, parameter_names = TRUE)

# generate bquote plotting syntax
plot(0, main = print(p1, plot = TRUE))

Creates a prior distribution

Description

prior creates a prior distribution. The prior can be visualized by the plot function.

Usage

prior(
  distribution,
  parameters,
  truncation = list(lower = -Inf, upper = Inf),
  prior_weights = 1
)

prior_none(prior_weights = 1)

Arguments

Value

prior and prior_none return an object of class 'prior'. A named list containing the distribution name, parameters, and prior weights.

See Also

plot.prior(), Normal, Lognormal, Cauchy, Beta, Exponential, LocationScaleT, InvGamma.

Examples

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

# create a half-normal standard normal prior distribution
p2 <- prior(distribution = "normal", parameters = list(mean = 1, sd = 1),
truncation = list(lower = 0, upper = Inf))

# the prior distribution can be visualized using the plot function
# (see ?plot.prior for all options)
plot(p1)

Creates a prior distribution for PET or PEESE models

Description

prior creates a prior distribution for fitting a PET or PEESE style models in RoBMA. The prior distribution can be visualized by the plot function.

Usage

prior_PET(
  distribution,
  parameters,
  truncation = list(lower = 0, upper = Inf),
  prior_weights = 1
)

prior_PEESE(
  distribution,
  parameters,
  truncation = list(lower = 0, upper = Inf),
  prior_weights = 1
)

Arguments

Value

prior_PET and prior_PEESE return an object of class 'prior'.

See Also

plot.prior(), prior()

Examples

# create a half-Cauchy prior distribution
# (PET and PEESE specific functions automatically set lower truncation at 0)
p1 <- prior_PET(distribution = "Cauchy", parameters = list(location = 0, scale = 1))

plot(p1)

Creates a composed publication-bias prior

Description

prior_bias() composes a step-selection prior_weightfunction() and/or a prior_phacking() object. It does not introduce new math; the backend compiler treats the composition as the product of both kernels.

Usage

prior_bias(selection = NULL, phacking = NULL, prior_weights = 1)

Arguments

Value

prior_bias() returns an object of class "prior".

Creates a prior distribution for factors

Description

prior_factor creates a prior distribution for fitting models with factor predictors. (Note that results across different operating systems might vary due to differences in JAGS numerical precision.)

Usage

prior_factor(
  distribution,
  parameters,
  truncation = list(lower = -Inf, upper = Inf),
  prior_weights = 1,
  contrast = "meandif"
)

Arguments

Value

return an object of class 'prior'.

See Also

prior()

Examples

# create an orthonormal prior distribution
p1 <- prior_factor(distribution = "mnormal", contrast = "orthonormal",
                   parameters = list(mean = 0, sd = 1))

Elementary prior related functions

Description

Density (pdf / lpdf), distribution function (cdf / ccdf), quantile function (quant), random generation (rng), mean, standard deviation (sd), and marginal variants of the functions (mpdf, mlpf, mcdf, mccdf, mquant) for prior distributions.

Usage

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

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

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

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

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

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

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

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

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

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

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

Arguments

Value

pdf (mpdf) and lpdf (mlpdf) give the (marginal) density and the log of (marginal) density, cdf (mcdf) and ccdf (mccdf) give the (marginal) distribution and the complement of (marginal) distribution function, quant (mquant) give the (marginal) quantile function, and rng generates random deviates for an object of class 'prior'.

Examples

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

# generate a random sample from the prior
rng(p1, 10)

# compute cumulative density function
cdf(p1, 0)

# obtain quantile
quant(p1, .5)

# compute probability density
pdf(p1, c(0, 1, 2))

Creates generics for common statistical functions

Description

Density (pdf / lpdf), distribution function (cdf / ccdf), quantile function (quant), random generation (rng), mean, standard deviation (sd), and marginal variants of the functions (mpdf, mlpf, mcdf, mccdf, mquant).

Usage

rng(x, ...)

cdf(x, ...)

ccdf(x, ...)

quant(x, ...)

lpdf(x, ...)

pdf(x, ...)

mcdf(x, ...)

mccdf(x, ...)

mquant(x, ...)

mlpdf(x, ...)

mpdf(x, ...)

Arguments

Value

pdf (mpdf) and lpdf (mlpdf) give the (marginal) density and the log of (marginal) density, cdf (mcdf) and ccdf (mccdf) give the (marginal) distribution and the complement of (marginal) distribution function, quant (mquant) give the (marginal) quantile function, and rng generates random deviates for an object of class 'prior'.

The pdf function proceeds to PDF graphics device if x is a character.

Creates an informed prior distribution based on research

Description

prior_informed creates an informed prior distribution based on past research. The prior can be visualized by the plot function.

Usage

prior_informed(name, parameter = NULL, type = "smd")

Arguments

Value

prior_informed returns an object of class 'prior'.

References

Bartoš F, Gronau QF, Timmers B, Otte WM, Ly A, Wagenmakers E (2021). “Bayesian model-averaged meta-analysis in medicine.” Statistics in Medicine, 40(30), 6743–6761. doi:10.1002/sim.9170.

Bartoš F, Otte WM, Gronau QF, Timmers B, Ly A, Wagenmakers E (2023). “Empirical prior distributions for Bayesian meta-analyses of binary and time-to-event outcomes.” doi:10.48550/arXiv.2306.11468. preprint at https://doi.org/10.48550/arXiv.2306.11468.

Gronau QF, Van Erp S, Heck DW, Cesario J, Jonas KJ, Wagenmakers E (2017). “A Bayesian model-averaged meta-analysis of the power pose effect with informed and default priors: The case of felt power.” Comprehensive Results in Social Psychology, 2(1), 123–138. doi:10.1080/23743603.2017.1326760.

van Erp S, Verhagen J, Grasman RP, Wagenmakers E (2017). “Estimates of between-study heterogeneity for 705 meta-analyses reported in Psychological Bulletin from 1990–2013.” Journal of Open Psychology Data, 5(1). doi:10.5334/jopd.33.

See Also

prior(), prior_informed_medicine_names

Examples

# prior distribution representing expected effect sizes in social psychology
# based on prior elicitation with dr. Oosterwijk
p1 <- prior_informed("Oosterwijk")

# the prior distribution can be visualized using the plot function
# (see ?plot.prior for all options)
plot(p1)


# empirical prior distribution for the standardized mean differences from the oral health
# medical subfield based on meta-analytic effect size estimates from the
# Cochrane database of systematic reviews
p2 <- prior_informed("Oral Health", parameter ="effect", type ="smd")
print(p2)

Names of medical subfields from the Cochrane database of systematic reviews

Description

Contains the union of names identifying the individual subfields from the Cochrane database of systematic reviews. Type-specific availability depends on the type argument passed to prior_informed().

Usage

prior_informed_medicine_names

Format

An object of class character of length 57.

Value

returns a character vector with names of medical subfields from Cochrane database of systematic reviews.

See Also

prior_informed()

Examples

print(prior_informed_medicine_names)

Creates a mixture of prior distributions

Description

prior_mixture creates a mixture of prior distributions. This is a more generic version of the prior_spike_and_slab function.

Usage

prior_mixture(
  prior_list,
  is_null = rep(FALSE, length(prior_list)),
  components = NULL
)

Arguments

See Also

prior()

Creates a prior distribution for a p-hacking selection kernel

Description

prior_phacking() creates a prior distribution for a mass-preserving p-hacking redistribution kernel. The initial backend supports linear and quadratic power depletion between source and target, with depleted probability mass redistributed between target and destination.

Usage

prior_phacking(
  side = "one-sided",
  target = 0.025,
  source = 0.25,
  destination = 0.005,
  form = c("linear", "quadratic"),
  alpha = prior("beta", list(1, 1)),
  report_scale = "pi_null",
  prior_weights = 1
)

Arguments

Value

prior_phacking() returns an object of class "prior".

Creates a spike and slab prior distribution

Description

prior_spike_and_slab creates a spike and slab prior distribution corresponding to the specification in Kuo and Mallick (1998) (see O'Hara and Sillanpää (2009) for further details). I.e., a prior distribution is multiplied by an independent indicator with values either zero or one.

Usage

prior_spike_and_slab(
  prior_parameter,
  prior_inclusion = prior(distribution = "spike", parameters = list(location = 0.5)),
  prior_weights = 1
)

Arguments

Value

return an object of class 'prior'.

See Also

prior()

Examples

# create a spike and slab prior distribution
p1 <- prior_spike_and_slab(
   prior(distribution = "normal", parameters = list(mean = 0, sd = 1)),
   prior_inclusion = prior(distribution = "beta", parameters = list(alpha = 1, beta = 1))
)

Creates a prior distribution for a weight function

Description

prior_weightfunction creates a prior distribution for fitting a RoBMA selection model. The side and steps arguments define the p-value bins, and the weights argument defines the prior on the publication weights in those bins.

Usage

prior_weightfunction(
  side = "one-sided",
  steps = c(0.025, 0.05),
  weights = wf_cumulative(),
  reference = "most_significant",
  prior_weights = 1
)

wf_cumulative(alpha = NULL)

wf_fixed(omega)

wf_independent(prior, scale = "omega")

Arguments

Value

prior_weightfunction returns an object of class 'prior'.

See Also

plot.prior()

Examples

p1 <- prior_weightfunction(
  side = "one-sided",
  steps = c(.05, .10),
  weights = wf_cumulative(alpha = c(1, 1, 1))
)

p2 <- prior_weightfunction(
  side = "one-sided",
  steps = c(.05),
  weights = wf_independent(prior("beta", list(1, 1)))
)

Prior range

Description

Computes range of a prior distribution (if the prior distribution is unbounded range from quantiles to 1 -quantiles) is returned.

Usage

## S3 method for class 'prior'
range(x, quantiles = NULL, ..., na.rm = FALSE)

Arguments

Value

range.prior returns a numeric vector of length with a plotting range of a prior distribution.

See Also

prior()

Removes column to BayesTools table

Description

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

Usage

remove_column(table, column_position = NULL)

Arguments

Value

returns an object of 'BayesTools_table' class.

Creates generic for sd function

Description

Creates generic for sd function

Usage

sd(x, ...)

Arguments

Value

sd returns a standard deviation of the supplied object (if it is either a numeric vector or an object of class 'prior').

See Also

sd

Prior sd

Description

Computes standard deviation of a prior distribution.

Usage

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

Arguments

Value

a standard deviation 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 sd of the prior distribution
sd(p1)

Compile selection priors for backend consumers

Description

selection_backend_spec() compiles step-selection and p-hacking prior objects into active backend parameters. The returned object contains stable p/z geometry, JAGS prior/transform code, monitor names, initial values, and data constants.

Usage

selection_backend_spec(
  priors,
  backend = "jags",
  names = list(omega = "omega", alpha = "alpha"),
  global_breaks = NULL
)

Arguments

Value

A list describing the compiled backend specification.

Transform factor posterior samples into differences from the mean

Description

Transforms posterior samples from model-averaged posterior distributions based on meandif/orthonormal prior distributions into differences from the mean.

Usage

transform_factor_samples(samples)

Arguments

Value

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

See Also

mix_posteriors transform_meandif_samples transform_meandif_samples transform_orthonormal_samples

Transform meandif posterior samples into differences from the mean

Description

Transforms posterior samples from model-averaged posterior distributions based on meandif prior distributions into differences from the mean.

Usage

transform_meandif_samples(samples)

Arguments

Value

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

See Also

mix_posteriors contr.meandif

Transform orthonomal posterior samples into differences from the mean

Description

Transforms posterior samples from model-averaged posterior distributions based on orthonormal prior distributions into differences from the mean.

Usage

transform_orthonormal_samples(samples)

Arguments

Value

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

See Also

mix_posteriors contr.orthonormal

Transform prior samples to original scale

Description

Generate prior samples and transform them using the same matrix transformation as posterior samples. This is the correct approach for visualizing priors on the original (unscaled) scale, especially for the intercept which depends on contributions from multiple coefficient priors.

Usage

transform_prior_samples(
  fit,
  n_samples = 10000,
  seed = NULL,
  formula_scale = NULL
)

Arguments

Details

When models use auto-scaling (standardizing predictors), the posterior samples are on the standardized scale. To correctly visualize priors on the original scale, we cannot simply apply a linear transformation to individual priors because the intercept on the original scale is a weighted sum of multiple priors:

\beta_0^{orig} = \beta_0^* - \sum_i \frac{\mu_i}{\sigma_i} \beta_i^*

This function generates samples from ALL priors simultaneously and applies the same matrix transformation used for posterior samples, which correctly handles the intercept and all other parameters.

Value

A matrix of prior samples on the original (unscaled) scale, with columns matching the structure of posterior samples.

See Also

transform_scale_samples() plot_posterior()

Examples

# With a fitted model that used formula_scale:
# prior_samples <- transform_prior_samples(fit, n_samples = 10000)
# This can then be used with density() or for custom plotting

Transform standardized posterior samples back to original scale

Description

Transforms posterior samples from standardized continuous predictors back to the original scale. This function is used when predictors were standardized during model fitting via the formula_scale parameter.

Usage

transform_scale_samples(fit, formula_scale = NULL)

Arguments

Details

The function transforms regression coefficients and intercepts to account for predictor standardization using a combinatorial approach that correctly handles interactions of any order.

For a k-way interaction between standardized predictors, the expansion of \prod_{i} (x_i - \mu_i)/\sigma_i contributes to all lower-order terms. The contribution to a target term T from a source term S (where T is a subset of S's scaled components) is:

(-1)^{|extra|} \cdot \prod_{i \in extra} \mu_i / \prod_{i \in S_{scaled}} \sigma_i

where extra = S_{scaled} \setminus T_{scaled}.

Value

transform_scale_samples returns posterior samples transformed back to the original predictor scale.

See Also

JAGS_formula() JAGS_fit()

Updates BayesTools table

Description

Updates BayesTools table while not breaking formatting, attributes, etc...

Usage

## S3 method for class 'BayesTools_table'
update(
  object,
  title = NULL,
  footnotes = NULL,
  warnings = NULL,
  remove_parameters = NULL,
  logBF = FALSE,
  BF01 = FALSE,
  ...
)

Arguments

Value

returns an object of 'BayesTools_table' class.

Creates generic for var function

Description

Creates generic for var function

Usage

var(x, ...)

Arguments

Value

var returns a variance of the supplied object (if it is either a numeric vector or an object of class 'prior').

See Also

cor

Prior var

Description

Computes variance of a prior distribution.

Usage

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

Arguments

Value

a variance 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 variance of the prior distribution
var(p1)

Weight functions

Description

Marginal density, marginal distribution function, marginal quantile function and random generation for weight functions.

Usage

mdone.sided(x, alpha = NULL, alpha1 = NULL, alpha2 = NULL, log = FALSE)

mdtwo.sided(x, alpha, log = FALSE)

mdone.sided_fixed(x, omega, log = FALSE)

mdtwo.sided_fixed(x, omega, log = FALSE)

rone.sided(n, alpha = NULL, alpha1 = NULL, alpha2 = NULL)

rtwo.sided(n, alpha)

rone.sided_fixed(n, omega)

rtwo.sided_fixed(n, omega)

mpone.sided(
  q,
  alpha = NULL,
  alpha1 = NULL,
  alpha2 = NULL,
  lower.tail = TRUE,
  log.p = FALSE
)

mptwo.sided(q, alpha, lower.tail = TRUE, log.p = FALSE)

mpone.sided_fixed(q, omega, lower.tail = TRUE, log.p = FALSE)

mptwo.sided_fixed(q, omega, lower.tail = TRUE, log.p = FALSE)

mqone.sided(
  p,
  alpha = NULL,
  alpha1 = NULL,
  alpha2 = NULL,
  lower.tail = TRUE,
  log.p = FALSE
)

mqtwo.sided(p, alpha, lower.tail = TRUE, log.p = FALSE)

mqone.sided_fixed(p, omega, lower.tail = TRUE, log.p = FALSE)

mqtwo.sided_fixed(p, omega, lower.tail = TRUE, log.p = FALSE)

Arguments

Value

mdone.sided, mdtwo.sided, mdone.sided_fixed, and mdtwo.sided_fixed give the marginal density, mpone.sided, mptwo.sided, mpone.sided_fixed, and mptwo.sided_fixed give the marginal distribution function, mqone.sided, mqtwo.sided, mqone.sided_fixed, and mqtwo.sided_fixed give the marginal quantile function, and rone.sided, rtwo.sided, rone.sided_fixed, and rtwo.sided_fixed generate random deviates.

Examples

# draw samples from a two-sided weight function
rtwo.sided(10, alpha = c(1, 1))

# draw samples from a monotone one-sided weight function
rone.sided(10, alpha = c(1, 1, 1))

# draw samples from a non-monotone one-sided weight function
rone.sided(10, alpha1 = c(1, 1), alpha2 = c(1, 1))

Create coefficient mapping between multiple weightfunctions

Description

Creates coefficients mapping between multiple weightfunctions.

Usage

weightfunctions_mapping(prior_list, cuts_only = FALSE, one_sided = FALSE)

Arguments

Value

weightfunctions_mapping returns a list of indices mapping the publication weights omega from the individual weightfunctions into a joint weightfunction.