cace.study {BayesCACE}

CACE analysis for a single study, or a two-step approach for meta-analysis with complete complice information

Description

This function performs CACE analysis for a single study using the likelihood and model specified in Section 2.1 of the package manuscript, or a two-step approach for meta-analysis with complete compliance information as described in Section 2.2, "the two-step approach".

Usage

cace.study(
  data,
  param = c("CACE", "u1", "v1", "s1", "b1", "pi.c", "pi.n", "pi.a"),
  re.values = list(),
  model.code = "",
  digits = 3,
  n.adapt = 1000,
  n.iter = 1e+05,
  n.burnin = floor(n.iter/2),
  n.chains = 3,
  n.thin = max(1, floor((n.iter - n.burnin)/1e+05)),
  conv.diag = FALSE,
  mcmc.samples = FALSE,
  two.step = FALSE,
  method = "REML"
)

Arguments

data

a input dataset the same structure as the example data epidural_c, containing either one row of observations for a single study, or multiple rows referring to multiple studies in a meta-analysis.

param

a character string vector indicating the parameters to be tracked and estimated. By default all parameters in the model (see details) are included: \theta^{\mathrm{CACE}} (CACE), u_1 (u1), v_1 (v1), s_1 (s1), b_1 (b1), \pi_a (pi.a), \pi_n (pi.n), and \pi_c=1-\pi_a-\pi_n (pi.c). Users can modify the string vector to only include parameters of interest besides \theta^{\mathrm{CACE}}.

re.values

a list of parameter values for the random effects. It should contain the assignment for these parameters only: n.m and n.s, which refer to the mean and standard deviation used in the normal distribution estimation of n, as well as a.m, a.s, alpha.s.m, alpha.s.s, alpha.b.m, alpha.b.s, alpha.u.m, alpha.u.s, alpha.v.m, alpha.v.s. By default, this is an empty list, and all the mean are set to 0, and alpha.n.s = alpha.a.s = 0.16, and alpha.s.s = alpha.b.s = alpha.u.s = alpha.v.s = 0.25.

model.code

a string representation of the model code; each line should be separated. Default to constructing model code using the model.meta.ic function with the parameters that are inputted to this function. This parameter is only necessary if user wishes to make functional changes to the model code, such as changing the probability distributions of the parameters. Default to empty string.

digits

a positive integer specifying the digits after the decimal point for the effect size estimates. The default is 3.

n.adapt

the number of iterations for adaptation in Markov chain Monte Carlo (MCMC) algorithm; it is used to maximize the sampling efficiency. The default is 1,000. If a warning "adaptation incomplete" appears, users may increase n.adapt. This argument and the following n.iter, n.burnin, n.chains, n.thin are passed to the functions in R package rjags.

n.iter

the number of iterations of each MCMC chain. The default is 100,000.

n.burnin

the number of iterations for burn-in period. The default is the largest integer not greater than n.iter/2.

n.chains

the number of MCMC chains. The default is 3.

n.thin

a positive integer indicating thinning rate for MCMC chains, which is used to avoid potential high auto-correlation and to save computer memory when n.iter is large. The default is set as 1 or the largest integer not greater than ((n.iter - n.burnin)/1e+05), whichever is larger.

conv.diag

a logical value indicating whether to compute the Gelman and Rubin convergence statistic (\hat{R}) of each parameter as a convergence diagnostic. It is considered the chains are well mixed and have converged to the target distribution if \hat{R} \le 1.1. The default is FALSE. If TRUE, n.chains must be greater than 1, and the function saves each chain's MCMC samples for all parameters, which can be used to produce trace, posterior density, and auto-correlation plots by calling the function plt.cacebayes.

mcmc.samples

a logical value indicating whether to save MCMC posterior samples in the output object. The default is FALSE. If TRUE, the output object list includes each chain's MCMC samples for all parameters. They can be used in the function plt.cacebayes to generate the trace, posterior density, and auto-correlation plots for further model diagnostics.

two.step

a logical value indicating whether to conduct a two-step meta-analysis. If two.step = TRUE, the posterior mean and standard deviation of study-specific \theta^{\mathrm{CACE}}_i are used to perform a standard meta-analysis, using the R package metafor.

method

the method used in meta-analysis if two.step = TRUE. The default estimation method is the REML (restricted maximum-likelihood estimator) method for the random-effects model. Users can change the argument method to obtain different meta-analysis estimators from either a random-effects model or a fixed-effect model, e.g., method = 'DL' refers to the DerSimonian–Laird estimator, method = 'HE' returns the Hedges estimator, and method = 'HS' gives the Hunter–Schmidt estimator. More details are available from the documentation of the function metafor::rma. If the input data include only one study, the meta-analysis result is just the same as the result from the single study.

Details

The likelihood

\log L({\boldsymbol{\beta}}) = N_{000}\log\{\pi_{c}(1-v_1)+\pi_{n}(1-s_1)\}+N_{001} \log(\pi_{c}v_1+\pi_{n}s_1)+N_{010}\log\{{\pi}_{a}(1-b_1)\}

+ N_{011}\log\{\pi_{a}b_1\}+ N_{100} \log\{\pi_{n}(1-s_1)\}+N_{101}\log({\pi}_{n}s_1) + N_{110}\log\{(\pi_{c}(1-u_1)

+ \pi_{a}(1-b_1)\}+{N_{111}\log(\pi_{c}u_1+\pi_{a}b_1)} + constant

. If the input data includes more than one study, the study-specific CACEs will be estimated by retrieving data row by row. By default, the function cace.study() returns a list including posterior estimates (posterior mean, standard deviation, median, and a 95% credible interval (CrI) with 2.5% and 97.5% quantiles as the lower and upper bounds), and the deviance information criterion (DIC) statistic for each study.

Value

It returns a model object whose attribute type is cace.Bayes

See Also

cace.meta.c, cace.meta.ic

Examples

data("epidural_c", package = "BayesCACE")
set.seed(123)
out.study <- cace.study(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, two.step = TRUE) 
# Show the estimates of theta for each single study (posterior mean and 
# standard deviation, posterior median, 95% credible interval, and time-series 
# standard error):
out.study$CACE
# If the argument conv.diag is specified as TRUE, the output list contains 
# a sub-list conv.out, which outputs the Gelman and Rubin convergence statistic,
# labelled Point est.) calculated for each parameter from each single study, and 
# their upper confidence limits (labelled Upper C.I.).
out.study$conv.out[[1]]