cace.study: CACE analysis for a single study, or a two-step approach for...
In BayesCACE: Bayesian Model for CACE Analysis
cace.study R Documentation
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: θ^{\mathrm{CACE}}
(CACE), u_1 (u1), v_1 (v1), s_1 (s1), b_1 (b1),
π_a (pi.a), π_n (pi.n), and π_c=1-π_a-π_n (pi.c).
Users can modify the string vector to only include parameters of interest besides
θ^{\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} ≤ 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
θ^{\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{β}}) = N_{000}\log\{π_{c}(1-v_1)+π_{n}(1-s_1)\}+N_{001}
\log(π_{c}v_1+π_{n}s_1)+N_{010}\log\{{π}_{a}(1-b_1)\}
+ N_{011}\log\{π_{a}b_1\}+ N_{100}
\log\{π_{n}(1-s_1)\}+N_{101}\log({π}_{n}s_1) + N_{110}\log\{(π_{c}(1-u_1)
+ π_{a}(1-b_1)\}+{N_{111}\log(π_{c}u_1+π_{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]]
BayesCACE documentation built on Oct. 2, 2022, 5:08 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| cace.study | R Documentation |
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 |
param |
a character string vector indicating the parameters to be tracked and estimated.
By default all parameters in the model (see |
re.values |
a list of parameter values for the random effects. It should contain the assignment for these
parameters only: |
model.code |
a string representation of the model code; each line should be separated. Default to constructing
model code using the |
digits |
a positive integer specifying the digits after the decimal point for
the effect size estimates. The default is |
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 |
n.iter |
the number of iterations of each MCMC chain.
The default is |
n.burnin |
the number of iterations for burn-in period. The default is
the largest integer not greater than |
n.chains |
the number of MCMC chains. The default is |
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 |
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} ≤ 1.1. The default is |
mcmc.samples |
a logical value indicating whether to save MCMC posterior samples
in the output object. The default is |
two.step |
a logical value indicating whether to conduct a two-step meta-analysis.
If |
method |
the method used in meta-analysis if |
Details
The likelihood
\log L({\boldsymbol{β}}) = N_{000}\log\{π_{c}(1-v_1)+π_{n}(1-s_1)\}+N_{001} \log(π_{c}v_1+π_{n}s_1)+N_{010}\log\{{π}_{a}(1-b_1)\}
+ N_{011}\log\{π_{a}b_1\}+ N_{100} \log\{π_{n}(1-s_1)\}+N_{101}\log({π}_{n}s_1) + N_{110}\log\{(π_{c}(1-u_1)
+ π_{a}(1-b_1)\}+{N_{111}\log(π_{c}u_1+π_{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]]
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.