binom_bf_informed {multibridge}

Evaluates Informed Hypotheses on Multiple Binomial Parameters

Description

Evaluates informed hypotheses on multiple binomial parameters. These hypotheses can contain (a mixture of) inequality constraints, equality constraints, and free parameters. Informed hypothesis H_r states that binomial proportions obey a particular constraint. H_r can be tested against the encompassing hypothesis H_e or the null hypothesis H_0. Encompassing hypothesis H_e states that binomial proportions are free to vary. Null hypothesis H_0 states that category proportions are exactly equal.

Usage

binom_bf_informed(
  x,
  n = NULL,
  Hr,
  a,
  b,
  factor_levels = NULL,
  cred_level = 0.95,
  niter = 5000,
  bf_type = "LogBFer",
  seed = NULL,
  maxiter = 1000,
  nburnin = niter * 0.05
)

Arguments

x

a vector of counts of successes, or a two-dimensional table (or matrix) with 2 columns, giving the counts of successes and failures, respectively

n

numeric. Vector of counts of trials. Must be the same length as x. Ignored if x is a matrix or a table

Hr

string or character. Encodes the user specified informed hypothesis. Use either specified factor_levels or indices to refer to parameters. See “Note” section for details on how to formulate informed hypotheses

a

numeric. Vector with alpha parameters. Must be the same length as x. Default sets all alpha parameters to 1

b

numeric. Vector with beta parameters. Must be the same length as x. Default sets all beta parameters to 1

factor_levels

character. Vector with category names. Must be the same length as x

cred_level

numeric. Credible interval for the posterior point estimates. Must be a single number between 0 and 1

niter

numeric. Vector with number of samples to be drawn from truncated distribution

bf_type

character. The Bayes factor type. When the informed hypothesis is compared to the encompassing hypothesis, the Bayes factor type can be LogBFer, BFer, or BFre. When the informed hypothesis is compared to the null hypothesis, the Bayes factor type can be LogBFr0, BF0r, or BFr0. Default is LogBFer

seed

numeric. Sets the seed for reproducible pseudo-random number generation

maxiter

numeric. Maximum number of iterations for the iterative updating scheme used in the bridge sampling routine. Default is 1,000 to avoid infinite loops

nburnin

numeric. A single value specifying the number of burn-in samples when drawing from the truncated distribution. Minimum number of burn-in samples is 10. Default is 5% of the number of samples. Burn-in samples are removed automatically after the sampling.

Details

The model assumes that the data in x (i.e., x_1, ..., x_K) are the observations of K independent binomial experiments, based on n_1, ..., n_K observations. Hence, the underlying likelihood is the product of the k = 1, ..., K individual binomial functions:

(x_1, ... x_K) ~ \prod Binomial(N_k, \theta_k)

Furthermore, the model assigns a beta distribution as prior to each model parameter (i.e., underlying binomial proportions). That is:

\theta_k ~ Beta(\alpha_k, \beta_k)

Value

List consisting of the following elements

$bf_list

gives an overview of the Bayes factor analysis:

• bf_type: string. Contains Bayes factor type as specified by the user

• bf: data.frame. Contains Bayes factors for all Bayes factor types

• error_measures: data.frame. Contains for the overall Bayes factor the approximate relative mean-squared error re2, the approximate coefficient of variation cv, and the approximate percentage error percentage

• logBFe_equalities: data.frame. Lists the log Bayes factors for all independent equality constrained hypotheses

• logBFe_inequalities: data.frame. Lists the log Bayes factor for all independent inequality constrained hypotheses

$cred_level

numeric. User specified credible interval

$restrictions

list that encodes informed hypothesis for each independent restriction:

• full_model: list containing the hypothesis, parameter names, data and prior specifications for the full model.

• equality_constraints: list containing the hypothesis, parameter names, data and prior specifications for each equality constrained hypothesis.

• inequality_constraints: list containing the hypothesis, parameter names, data and prior specifications for each inequality constrained hypothesis. In addition, in nr_mult_equal and nr_mult_free encodes which and how many parameters are equality constraint or free, in boundaries includes the boundaries of each parameter, in nineq_per_hyp states the number of inequality constraint parameters per independent inequality constrained hypothesis, and in direction states the direction of the inequality constraint.

$bridge_output

list containing output from bridge sampling function:

• eval: list containing the log prior or posterior evaluations (q11) and the log proposal evaluations (q12) for the prior or posterior samples, as well as the log prior or posterior evaluations (q21) and the log proposal evaluations (q22) for the samples from the proposal distribution

• niter: number of iterations of the iterative updating scheme

• logml: estimate of log marginal likelihood

• hyp: evaluated inequality constrained hypothesis

• error_measures: list containing in re2 the approximate relative mean-squared error for the marginal likelihood estimate, in cv the approximate coefficient of variation for the marginal likelihood estimate (assumes that bridge estimate is unbiased), and in percentage the approximate percentage error of the marginal likelihood estimate

$samples

list containing a list for prior samples and a list of posterior samples from truncated distributions which were used to evaluate inequality constraints. Prior and posterior samples of independent inequality constraints are again saved in separate lists. Samples are stored as matrix of dimension nsamples x nparams.

Note

The following signs can be used to encode restricted hypotheses: "<" and ">" for inequality constraints, "=" for equality constraints, "," for free parameters, and "&" for independent hypotheses. The restricted hypothesis can either be a string or a character vector. For instance, the hypothesis c("theta1 < theta2, theta3") means

• theta1 is smaller than both theta2 and theta3

• The parameters theta2 and theta3 both have theta1 as lower bound, but are not influenced by each other.

The hypothesis c("theta1 < theta2 = theta3 & theta4 > theta5") means that

• Two independent hypotheses are stipulated: "theta1 < theta2 = theta3" and "theta4 > theta5"

• The restrictions on the parameters theta1, theta2, and theta3 do not influence the restrictions on the parameters theta4 and theta5.

• theta1 is smaller than theta2 and theta3

• theta2 and theta3 are assumed to be equal

• theta4 is larger than theta5

References

Damien P, Walker SG (2001). “Sampling truncated normal, beta, and gamma densities.” Journal of Computational and Graphical Statistics, 10, 206–215.

Gronau QF, Sarafoglou A, Matzke D, Ly A, Boehm U, Marsman M, Leslie DS, Forster JJ, Wagenmakers E, Steingroever H (2017). “A tutorial on bridge sampling.” Journal of Mathematical Psychology, 81, 80–97.

Frühwirth-Schnatter S (2004). “Estimating marginal likelihoods for mixture and Markov switching models using bridge sampling techniques.” The Econometrics Journal, 7, 143–167.

Sarafoglou A, Haaf JM, Ly A, Gronau QF, Wagenmakers EJ, Marsman M (2021). “Evaluating Multinomial Order Restrictions with Bridge Sampling.” Psychological Methods.

See Also

Other functions to evaluate informed hypotheses: binom_bf_equality(), binom_bf_inequality(), mult_bf_equality(), mult_bf_inequality(), mult_bf_informed()

Examples

# data
x <- c(3, 4, 10, 11)
n <- c(15, 12, 12, 12)
# priors
a <- c(1, 1, 1, 1)
b <- c(1, 1, 1, 1)
# informed hypothesis
factor_levels <- c('binom1', 'binom2', 'binom3', 'binom4')
Hr            <- c('binom1', '<',  'binom2', '<', 'binom3', '<', 'binom4')
output_total  <- binom_bf_informed(x, n, Hr, a, b, niter=2e3, factor_levels, seed=2020)