Package 'BayesCACE' reference manual

Title:	Bayesian Model for CACE Analysis
Description:	Performs CACE (Complier Average Causal Effect analysis) on either a single study or meta-analysis of datasets with binary outcomes, using either complete or incomplete noncompliance information. Our package implements the Bayesian methods proposed in Zhou et al. (2019) <doi:10.1111/biom.13028>, which introduces a Bayesian hierarchical model for estimating CACE in meta-analysis of clinical trials with noncompliance, and Zhou et al. (2021) <doi:10.1080/01621459.2021.1900859>, with an application example on Epidural Analgesia.
Authors:	Jinhui Yang [aut, cre] , Jincheng Zhou [aut] , James Hodges [ctb], Haitao Chu [ctb]
Maintainer:	Jinhui Yang <[email protected]>
License:	GPL (>= 2)
Version:	1.2.3
Built:	2024-10-09 06:37:31 UTC
Source:	CRAN

Bayesian hierarchical models for CACE meta-analysis with complete compliance data

Description

This function performs the Bayesian hierarchical model method for meta-analysis when the dataset has complete compliance information for all studies, as described in Section 2.2, "the Bayesian hierarchical model", of the package manuscript.

Usage

cace.meta.c(
  data,
  param = c("CACE", "u1out", "v1out", "s1out", "b1out", "pic", "pin", "pia"),
  random.effects = list(),
  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,
  study.specific = FALSE
)
cace.meta.c(
  data,
  param = c("CACE", "u1out", "v1out", "s1out", "b1out", "pic", "pin", "pia"),
  random.effects = list(),
  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,
  study.specific = FALSE
)

Arguments

`data`	an input dataset with the same structure as the example data `epidural_c`, containing 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 the following parameters (see `details`) are included: $\theta^{\mathrm{CACE}}$ (`CACE`), $E(u_{i1})$ (`u1out`), $E(v_{i1})$ (`v1out`), $E(s_{i1})$ (`s1out`), $E(b_{i1})$ (`b1out`), $\pi_a$ (`pia`), $\pi_n$ (`pin`), and $\pi_c=1-\pi_a-\pi_n$ (`pic`). Users can modify the string vector to only include parameters of interest besides $\theta^{\mathrm{CACE}}$ .
`random.effects`	a list of logical values indicating whether random effects are included in the model. The list should contain the assignment for these parameters only: `delta.n` ( $\delta_{in}$ ), `delta.a` ( $\delta_{ia}$ ), `delta.u` ( $\delta_{iu}$ ), `delta.v` ( $\delta_{iv}$ ), `delta.s` ( $\delta_{is}$ ), `delta.b` ( $\delta_{ib}$ ), `cor`. The list should be in the form of `list(delta.a = FALSE, cor = FALSE, ...)`. By default, this is an empty list, and all parameters are default to `TRUE`. Parameters that are not listed in the list are assumed to be `TRUE`. Note that $\rho$ (`cor`) can only be included when both $\delta_{in}$ (`delta.n`) and $\delta_{ia}$ (`delta.a`) are set to `TRUE`. Otherwise, a warning occurs and the model continues running by forcing `delta.n = TRUE` and `delta.a = TRUE`.
`re.values`	a list of parameter values for the random effects. It should contain the assignment for these parameters only: `alpha.n.m` and `alpha.n.s`, which refer to the mean and standard deviation used in the normal distribution estimation of `alpha.n`, as well as `alpha.a.m`, `alpha.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`. It also contains the shape and rate parameters of the gamma distributions of the standard deviation variable of `delta.n`, `delta.a`, `delta.u`, `delta.v` `delta.s`, `delta.b`. The shape parameters are named as `tau.n.h` and `tau.a.h`, for example, and the rate parameters are named as `tau.n.r` and `tau.a.r`. You do not need to specify the shape and rate parameters if the corresponding random effect is set to `FALSE` in `random.effects`, since they will not be used anyways. By default, `re.values` 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`, and the shape and rate parameters are default to `2`.
`model.code`	a string representation of the model code; each line should be separated. Default to constructing model code using the `model.meta.c` 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`	number of digits. Default to `3`.
`n.adapt`	adapt value. Default to `1000`.
`n.iter`	number of iterations. Default to `100000`.
`n.burnin`	number of burn-in iterations. Default to `n.iter/2`.
`n.chains`	number of chains. Default to `3`.
`n.thin`	thinning rate, must be a positive integer. Default to `max(1,floor((n.iter-n.burnin)/100000))`.
`conv.diag`	whether or not to show convergence diagnostics. Default to `FALSE`.
`mcmc.samples`	whether to include JAGS samples in the final output. Default to `FALSE`.
`study.specific`	a logical value indicating whether to calculate the study-specific $\theta^{\mathrm{CACE}}_i$ . If `TRUE`, the model will first check the logical status of arguments `delta.u` and `delta.v`. If both are `FALSE`, meaning that neither response rate $u_{i1}$ or $v_{i1}$ is modeled with a random effect, then the study-specific $\theta^{\mathrm{CACE}}_i$ is the same across studies. The function gives a warning and continues by making `study.specific = FALSE`. Otherwise, the study-specific $\theta^{\mathrm{CACE}}_i$ are estimated and saved as the parameter `cacei`.

Value

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

References

Zhou J, Hodges JS, Suri MFK, Chu H (2019). “A Bayesian hierarchical model estimating CACE in meta-analysis of randomized clinical trials with noncompliance.” Biometrics, 75(3), 978–987.

Lunn D, Jackson C, Best N, Thomas A, Spiegelhalter D (2012). The BUGS book: A practical introduction to Bayesian analysis. CRC press.

Zeger SL, Liang K, Albert PS (1988). “Models for longitudinal data: a generalized estimating equation approach.” Biometrics, 1049–1060.

Examples


data("epidural_c", package = "BayesCACE")
set.seed(123)
out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
# By calling the object smry from the output list out.meta.c, posterior estimates 
# (posterior mean, standard deviation, posterior median, 95\% credible interval, and 
# time-series standard error) are displayed.
out.meta.c$smry
out.meta.c$DIC

data("epidural_c", package = "BayesCACE")
set.seed(123)
out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
# By calling the object smry from the output list out.meta.c, posterior estimates 
# (posterior mean, standard deviation, posterior median, 95\% credible interval, and 
# time-series standard error) are displayed.
out.meta.c$smry
out.meta.c$DIC

Bayesian hierarchical models for CACE meta-analysis with incomplete compliance information

Description

This function also estimates $\theta^{\mathrm{CACE}}$ using the Bayesian hierarchcal model but can accommodate studies with incomplete compliance data. The necessary data structure and the likelihood function are presented in Section 2.3 of the package manuscript, "CACE for meta-analysis with incomplete compliance information".

Usage

cace.meta.ic(
  data,
  param = c("CACE", "u1out", "v1out", "s1out", "b1out", "pic", "pin", "pia"),
  random.effects = list(),
  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,
  study.specific = FALSE
)
cace.meta.ic(
  data,
  param = c("CACE", "u1out", "v1out", "s1out", "b1out", "pic", "pin", "pia"),
  random.effects = list(),
  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,
  study.specific = FALSE
)

Arguments

`data`	a input dataset the same structure as the example data `epidural_ic`, containing multiple rows referring to multiple studies in a meta-analysis.
`param`	the list of parameter used. Default to `c("CACE", "u1out", "v1out", "s1out", "b1out", "pic", "pin", "pia")`.
`random.effects`	a list of logical values indicating whether random effects are included in the model. The list should contain the assignment for these parameters only: `delta.n` ( $\delta_{in}$ ), `delta.a` ( $\delta_{ia}$ ), `delta.u` ( $\delta_{iu}$ ), `delta.v` ( $\delta_{iv}$ ), `delta.s` ( $\delta_{is}$ ), `delta.b` ( $\delta_{ib}$ ), `cor`. The list should be in the form of `list(delta.a = FALSE, cor = FALSE, ...)`. By default, this is an empty list, and all parameters are default to `TRUE`. Parameters that are not listed in the list are assumed to be `TRUE`. Note that $\rho$ (`cor`) can only be included when both $\delta_{in}$ (`delta.n`) and $\delta_{ia}$ (`delta.a`) are set to `TRUE`. Otherwise, a warning occurs and the model continues running by forcing `delta.n = TRUE` and `delta.a = TRUE`.
`re.values`	a list of parameter values for the random effects. It should contain the assignment for these parameters only: `alpha.n.m` and `alpha.n.s`, which refer to the mean and standard deviation used in the normal distribution estimation of `alpha.n`, as well as `alpha.a.m`, `alpha.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`. It also contains the shape and rate parameters of the gamma distributions of the standard deviation variable of `delta.n`, `delta.a`, `delta.u`, `delta.v` `delta.s`, `delta.b`. The shape parameters are named as `tau.n.h` and `tau.a.h`, for example, and the rate parameters are named as `tau.n.r` and `tau.a.r`. You do not need to specify the shape and rate parameters if the corresponding random effect is set to `FALSE` in `random.effects`, since they will not be used anyways. By default, `re.values` 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`, and the shape and rate parameters are default to `2`.
`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`	number of digits. Default to `3`.
`n.adapt`	adapt value. Default to `1000`.
`n.iter`	number of iterations. Default to `100000`.
`n.burnin`	number of burn-in iterations. Default to `n.iter/2`.
`n.chains`	number of chains. Default to `3`.
`n.thin`	thinning rate, must be a positive integer. Default to `max(1,floor((n.iter-n.burnin)/100000))`.
`conv.diag`	whether or not to show convergence diagnostics. Default to `FALSE`.
`mcmc.samples`	whether to include JAGS samples in the final output. Default to `FALSE`.
`study.specific`	a logical value indicating whether to calculate the study-specific $\theta^{\mathrm{CACE}}_i$ . If `TRUE`, the model will first check the logical status of arguments `delta.u` and `delta.v`. If both are `FALSE`, meaning that neither response rate $u_{i1}$ or $v_{i1}$ is modeled with a random effect, then the study-specific $\theta^{\mathrm{CACE}}_i$ is the same across studies. The function gives a warning and continues by making `study.specific = FALSE`. Otherwise, the study-specific $\theta^{\mathrm{CACE}}_i$ are estimated and saved as the parameter `cacei`.

Details

Note that when compiling the JAGS model, the warning ‘adaptation incomplete’ may occasionally occur, indicating that the number of iterations for the adaptation process is not sufficient. The default value of n.adapt (the number of iterations for adaptation) is 1,000. This is an initial sampling phase during which the samplers adapt their behavior to maximize their efficiency (e.g., a Metropolis–Hastings random walk algorithm may change its step size). The ‘adaptation incomplete’ warning indicates the MCMC algorithm may not achieve maximum efficiency, but it generally has little impact on the posterior estimates of the treatment effects. To avoid this warning, users may increase n.adapt.

Value

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

References

Zhou J, Hodges JS, Suri MFK, Chu H (2019). “A Bayesian hierarchical model estimating CACE in meta-analysis of randomized clinical trials with noncompliance.” Biometrics, 75(3), 978–987.

Examples


data("epidural_ic", package = "BayesCACE")
set.seed(123)
out.meta.ic <- cace.meta.ic(data = epidural_ic, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)

data("epidural_ic", package = "BayesCACE")
set.seed(123)
out.meta.ic <- cace.meta.ic(data = epidural_ic, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)

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

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

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

Get names of node array

Description

This is a helper function from the rjags library in order to get the names of the individual elements of a node array. See the package rjags for more details.

Usage

coda.names(basename, dim)
coda.names(basename, dim)

Arguments

`basename`	the node names
`dim`	dimension of the nodes

Value

It returns a list of the names of individual elements

References

Plummer M (2021). rjags: Bayesian Graphical Models using MCMC. R package version 4-12, https://CRAN.R-project.org/package=rjags.

Generate posterior samples in mcmc.list format

Description

This is a wrapper function for jags.samples which sets a trace monitor for all requested nodes, updates the model, and coerces the output to a single mcmc.list object. It also converts to the output to dic format. This function is based on the coda.samples function from the rjags library, and modified by Prof. Matthias Mittner.

Usage

coda.samples.dic(model, variable.names, n.iter, thin, ...)
coda.samples.dic(model, variable.names, n.iter, thin, ...)

Arguments

`model`	a jags model object
`variable.names`	a character vector giving the names of variables to be monitored
`n.iter`	number of iterations to monitor
`thin`	thinning interval for monitors
`...`	optional arguments that are passed to the `jags.samples` method from the `rjags` library, for jags model objects

Value

It returns the output to the input model object, and in dic format.

References

Plummer M (2021). rjags: Bayesian Graphical Models using MCMC. R package version 4-12, https://CRAN.R-project.org/package=rjags.

https://ihrke.github.io/post/2014/10/07/dicjags/

Meta-analysis data with full compliance information

Description

The data contains a meta analysis of the association between using epidural analgesia in labor and the risk of cesarean section. It contains 10 trials with full compliance information, each with 8 observed counts.

Usage

data(epidural_c)
data(epidural_c)

Format

An object of class data.frame with 10 rows and 10 columns.

Source

https://pubmed.ncbi.nlm.nih.gov/25592169/

References

Bannister-Tyrrell M, Miladinovic B, Roberts CL, Ford JB (2015). “Adjustment for compliance behavior in trials of epidural analgesia in labor using instrumental variable meta-analysis.” Journal of Clinical Epidemiology, 68(5), 525–533.

Examples

data(epidural_c)
data(epidural_c)

Meta-analysis data without full compliance information

Description

The data contains a meta analysis of the association between using epidural analgesia in labor and the risk of cesarean section. It contains 27 studies, only 10 out of which have full compliance information.

Usage

data(epidural_ic)
data(epidural_ic)

Format

An object of class data.frame with 27 rows and 14 columns.

Source

https://pubmed.ncbi.nlm.nih.gov/25592169/

References

Examples

data(epidural_ic)
data(epidural_ic)

Bayesian hierarchical model code for CACE meta-analysis with complete compliance data

Description

This function generates part of the model code for meta-analysis when the dataset has complete compliance information for all studies, as described in Section 2.2, "the Bayesian hierarchical model" of the package manuscript. This function will be called internally if user uses the cace.meta.c function.

Usage

model.meta.c(random.effects = list(), re.values = list())
model.meta.c(random.effects = list(), re.values = list())

Arguments

random.effects

a list of logical values indicating whether random effects are included in the model. The list should contain the assignment for these parameters only: delta.n ( $\delta_{in}$ ), delta.a ( $\delta_{ia}$ ), delta.u ( $\delta_{iu}$ ), delta.v ( $\delta_{iv}$ ), delta.s ( $\delta_{is}$ ), delta.b ( $\delta_{ib}$ ), cor. The list should be in the form of list(delta.a = FALSE, cor = FALSE, ...). By default, this is an empty list, and all parameters are default to TRUE. Parameters that are not listed in the list are assumed to be TRUE. Note that $\rho$ (cor) can only be included when both $\delta_{in}$ (delta.n) and $\delta_{ia}$ (delta.a) are set to TRUE. Otherwise, a warning occurs and the model continues running by forcing delta.n = TRUE and delta.a = TRUE.

re.values

a list of parameter values for the random effects. It should contain the assignment for these parameters only: alpha.n.m and alpha.n.s, which refer to the mean and standard deviation used in the normal distribution estimation of alpha.n, as well as alpha.a.m, alpha.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. It also contains the shape and rate parameters of the gamma distributions of the standard deviation variable of delta.n, delta.a, delta.u, delta.v delta.s, delta.b. The shape parameters are named as tau.n.h and tau.a.h, for example, and the rate parameters are named as tau.n.r and tau.a.r. You do not need to specify the shape and rate parameters if the corresponding random effect is set to FALSE in random.effects, since they will not be used anyways. By default, re.values 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, and the shape and rate parameters are default to 2.

Value

It returns a model string

Examples

# use default settings
model.string <- model.meta.c()
# use default settings
model.string <- model.meta.c()

Bayesian hierarchical model code for CACE meta-analysis with complete compliance data

Description

This function generates the model code for meta-analysis when the dataset has incomplete compliance information for all studies, as described in Section 2.2.2, "the Bayesian hierarchical model" of the package manuscript. This function will be called internally if user uses the cace.meta.ic function.

Usage

model.meta.ic(random.effects = list(), re.values = list())
model.meta.ic(random.effects = list(), re.values = list())

Arguments

random.effects

re.values

Value

It returns a model string

Examples

# use default settings
model.string <- model.meta.ic()
# use default settings
model.string <- model.meta.ic()

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

Description

This function generates the model code for a single study using the likelihood and model specified in Section 2.1, or a two-step approach for meta-analysis with complete compliance information as described in Section 2.2, "The two-step approach" of the package manuscript. This function will be called internally if user uses the cace.study function.

Usage

model.study(re.values = list())
model.study(re.values = list())

Arguments

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.

Value

It returns a model string

Examples

model.string <- model.study()
model.string <- model.study()

Parse strings of specific form

Description

This is a helper function from the rjags library in order to parse the string of form "a" or "a[n,p:q,r]". See the package rjags for more details.

Usage

parse.varname(varname)
parse.varname(varname)

Arguments

varname

string name of variable

Value

It returns a list of parsed parameters

References

Plummer M (2021). rjags: Bayesian Graphical Models using MCMC. R package version 4-12, https://CRAN.R-project.org/package=rjags.

this plot function creates an acf plot

Description

This function creates an acf (Autocorrelation Function) plot for a model object with the type attribute cace.Bayes.

Usage

plt.acf(obj, param = c("CACE"), trialnumber = 1, ...)
plt.acf(obj, param = c("CACE"), trialnumber = 1, ...)

Arguments

`obj`	a model object, returned by `cace.meta.c`, `cace.meta.ic`, or `cace.study`
`param`	list of parameters to plot
`trialnumber`	indicator for which trial number of the mcmc samples to use. The default is `1`
`...`	optional parameters to pass into the `acf` function from the `stats` library.

Value

It returns an acf plot in an R plot window.

Examples


out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.acf(obj=out.meta.c)

out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.acf(obj=out.meta.c)

this plot function creates a density plot

Description

This function creates a density plot for a model object with the type attribute cace.Bayes.

Usage

plt.density(obj, param = c("CACE"), trialnumber = 1, ...)
plt.density(obj, param = c("CACE"), trialnumber = 1, ...)

Arguments

`obj`	a model object, returned by `cace.meta.c`, `cace.meta.ic`, or `cace.study`
`param`	list of parameters to plot
`trialnumber`	indicator for which trial number of the mcmc samples to use. The default is `1`
`...`	optional parameters to pass into the `plot` function

Value

It returns a density plot in an R plot window.

Examples


out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.density(obj=out.meta.c)

out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.density(obj=out.meta.c)

this plot function makes a forest plot.

Description

This function provides a visual overview (forest plot) for a model object and corresponding dataset.

Usage

plt.forest(data, obj, ...)
plt.forest(data, obj, ...)

Arguments

`data`	an input dataset with the same structure as the example data `epidural_c`, containing multiple rows referring to multiple studies in a meta-analysis.
`obj`	a model object returned by `cace.meta.c`, `cace.meta.ic`, or `cace.study`
`...`	optional parameters passed into the `forestplot` function from the `forestplot` library

Value

It returns a forestplot object in an R plot window.

Examples


data("epidural_c", package = "BayesCACE")
out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.forest(data=epidural_c, obj=out.meta.c)

data("epidural_c", package = "BayesCACE")
out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.forest(data=epidural_c, obj=out.meta.c)

Plotting noncompliance rates for a given dataset

Description

Provides a forest plot of noncompliance rates in an R plot window.

Usage

plt.noncomp(data, overall = TRUE, ...)
plt.noncomp(data, overall = TRUE, ...)

Arguments

`data`	a dataset with structure like the example `epidural_c` or `epidural_ic`
`overall`	a logical value indicating whether a summary estimate of the compliance rates per randomization group is provided. The default is `TRUE`. This overall rate is estimated using a logit generalized linear mixed model.
`...`	optional parameters passed into the `forestplot` function from the `forestplot` library

Details

This function provides a visual overview (forest plot) of study-specific noncompliance rates in both randomization arms.

Only studies with full compliance information are included in this plot because noncompliance rates cannot be calculated without compliance data. In the generated plot, the red dot with its horizontal line shows the study-specific noncompliance rate with its 95% exact confidence interval for the patients randomized to the treatment arm, and the blue square with its horizontal line represents that rate and interval for those in the control arm. The confidence intervals are calculated by the Clopper–Pearson exact method, which is based on the cumulative distribution function of the binomial distribution.

Value

A forest plot of noncompliance rates in an R plot window

Examples

data("epidural_c", package = "BayesCACE")
plt.noncomp(data=epidural_c, overall = TRUE)
data("epidural_c", package = "BayesCACE")
plt.noncomp(data=epidural_c, overall = TRUE)

this plot function creates a traceplot

Description

This function creates a traceplot for a model object with the type attribute cace.Bayes.

Usage

plt.trace(obj, param = c("CACE"), trialnumber = 1, ...)
plt.trace(obj, param = c("CACE"), trialnumber = 1, ...)

Arguments

`obj`	a model object, returned by `cace.meta.c`, `cace.meta.ic`, or `cace.study`
`param`	list of parameters to plot
`trialnumber`	indicator for which trial number of the mcmc samples to use. The default is `1`
`...`	optional parameters to pass into the `plot` function

Value

It returns a traceplot in an R plot window.

Examples


out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.trace(obj=out.meta.c)

out.meta.c <- cace.meta.c(data = epidural_c, conv.diag = TRUE, 
mcmc.samples = TRUE, study.specific = TRUE)
plt.trace(obj=out.meta.c)

The function returns a custom string that specifies part of the model.

Description

This function returns a partially complete prior string. Used internally - cannot be directly used.

Usage

prior.meta(random.effects = list(), re.values = list())
prior.meta(random.effects = list(), re.values = list())

Arguments

random.effects

re.values

Value

custom prior string

Examples

model.string <- prior.meta()
model.string <- prior.meta()

The function returns a custom string that specifies part of the model (single-study).

Description

This function returns a partially complete prior string. Used internally - cannot be directly used.

Usage

prior.study(re.values = list())
prior.study(re.values = list())

Arguments

re.values

Value

custom model string

Examples

model.string <- prior.study()
model.string <- prior.study()

Package 'BayesCACE'

Help Index

Bayesian hierarchical models for CACE meta-analysis with complete compliance data

Description

Usage

Arguments

Value

References

See Also

Examples

Bayesian hierarchical models for CACE meta-analysis with incomplete compliance information

Description

Usage

Arguments

Details

Value

References

See Also

Examples

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

Description

Usage

Arguments

Details

Value

See Also

Examples

Get names of node array

Description

Usage

Arguments

Value

References

Generate posterior samples in mcmc.list format

Description

Usage

Arguments

Value

References

Meta-analysis data with full compliance information

Description

Usage

Format

Source

References

Examples

Meta-analysis data without full compliance information

Description

Usage

Format

Source

References

Examples

Bayesian hierarchical model code for CACE meta-analysis with complete compliance data

Description

Usage

Arguments

Value

Examples

Bayesian hierarchical model code for CACE meta-analysis with complete compliance data

Description

Usage

Arguments

Value

Examples

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

Description

Usage

Arguments

Value

Examples

Parse strings of specific form

Description

Usage

Arguments

Value

References

this plot function creates an acf plot

Description

Usage