bayesassurance (version 0.1.0)

bayes_sim_unbalanced: Unbalanced Bayesian Simulation in Conjugate Linear Model Framework

Description

Approximates the Bayesian assurance of attaining \(u'\beta > C\) for unbalanced study designs through Monte Carlo sampling. See Argument descriptions for more detail.

Usage

bayes_sim_unbalanced(
  n1,
  n2,
  repeats = 1,
  u,
  C,
  Xn = NULL,
  Vn = NULL,
  Vbeta_d,
  Vbeta_a_inv,
  sigsq,
  mu_beta_d,
  mu_beta_a,
  alt,
  alpha,
  mc_iter,
  surface_plot = TRUE
)

Arguments

n1

first sample size (vector or scalar).

n2

second sample size (vector or scalar).

repeats

an positive integer specifying number of times to repeat c(n1, n2). Applicable for studies that consider multiple measures within each group. Default setting is repeats = 1 if not applicable.

u

a scalar or vector to evaluate $$u'\beta > C,$$ where \(\beta\) is an unknown parameter that is to be estimated. Default setting is u = 1.

C

constant value to be compared to when evaluating \(u'\beta > C\)

Xn

design matrix that characterizes where the data is to be generated from. This is specifically designed under the normal linear regression model $$yn = Xn\beta + \epsilon,$$ $$\epsilon ~ N(0, \sigma^2 Vn).$$ When set to NULL, Xn is generated in-function using bayesassurance::gen_Xn(). Note that setting Xn = NULL also enables user to pass in a vector of sample sizes to undergo evaluation.

Vn

a correlation matrix for the marginal distribution of the sample data yn. Takes on an identity matrix when set to NULL.

Vbeta_d

correlation matrix that helps describe the prior information on \(\beta\) in the design stage

Vbeta_a_inv

inverse-correlation matrix that helps describe the prior information on \(\beta\) in the analysis stage

sigsq

a known and fixed constant preceding all correlation matrices Vn, Vbeta_d and Vbeta_a_inv.

mu_beta_d

design stage mean

mu_beta_a

analysis stage mean

alt

specifies alternative test case, where alt = "greater" tests if \(u'\beta > C\), alt = "less" tests if \(u'\beta < C\), and alt = "two.sided" performs a two-sided test. By default, alt = "greater".

alpha

significance level

mc_iter

number of MC samples evaluated under the analysis objective

surface_plot

when set to TRUE and \(n1\) and \(n2\) are vectors, a contour map showcasing various assurance values corresponding to different combinations of \(n1\) and \(n2\) is produced.

Value

a list of objects corresponding to the assurance approximations

• assurance_table: table of sample size and corresponding assurance values

• contourplot: contour map of assurance values

• mc_samples: number of Monte Carlo samples that were generated and evaluated

Examples

# NOT RUN {
## Example 1
## Sample size vectors are passed in for n1 and n2 to evaluate
## assurance. 
n1 <- seq(20, 75, 5)
n2 <- seq(50, 160, 10)

assur_out <- bayes_sim_unbalanced(n1 = n1, n2 = n2, repeats = 1, u = c(1, -1),
C = 0, Xn = NULL, Vbeta_d = matrix(c(50, 0, 0, 10),nrow = 2, ncol = 2),
Vbeta_a_inv = matrix(rep(0, 4), nrow = 2, ncol = 2),
Vn = NULL, sigsq = 100,  mu_beta_d = c(1.17, 1.25),
mu_beta_a = c(0, 0), alt = "two.sided", alpha = 0.05, mc_iter = 1000,
surface_plot = FALSE)

assur_out$assurance_table


## Example 2
## We can produce a contour plot that evaluates unique combinations of n1
## and n2 simply by setting `surfaceplot = TRUE`.
# }
# NOT RUN {
n1 <- seq(20, 75, 5)
n2 <- seq(50, 160, 10)
assur_out <- bayes_sim_unbalanced(n1 = n1, n2 = n2, repeats = 1, 
u = c(1, -1), C = 0, Xn = NULL, Vbeta_d = matrix(c(50, 0, 0, 10),
nrow = 2, ncol = 2), Vbeta_a_inv = matrix(rep(0, 4), nrow = 2, ncol = 2),
Vn = NULL, sigsq = 100,  mu_beta_d = c(1.17, 1.25),
mu_beta_a = c(0, 0), alt = "two.sided", alpha = 0.05, mc_iter = 1000,
surface_plot = TRUE)

assur_out$assurance_table
assur_out$contourplot
# }