% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/AnalysisFunctions.R
\name{performAnalyses}
\alias{performAnalyses}
\title{performAnalyses}
\usage{
performAnalyses(
  scenario_list,
  evidence_levels = c(0.025, 0.05, 0.5, 0.8, 0.9, 0.95, 0.975),
  method_names = c("berry", "exnex", "exnex_mix", "exnex_adj", "exnex_adj_mix", "pooled",
    "stratified", "stratified_mix"),
  target_rates = NULL,
  prior_parameters_list = NULL,
  calc_differences = NULL,
  n_mcmc_iterations = 10000,
  n_cores = 1,
  seed = 1,
  verbose = TRUE
)
}
\arguments{
\item{scenario_list}{An object of class \code{scenario_list},
as e.g. created with \code{\link[bhmbasket]{simulateScenarios}}}

\item{evidence_levels}{A vector of numerics in \verb{(0, 1)} for the
\code{1-evidence_levels}-quantiles of the posterior response rates to be saved.
Default: \code{c(0.025, 0.05, 0.5, 0.8, 0.9, 0.95, 0.975)}}

\item{method_names}{A vector of strings for the names of the methods to be used. Must
be one of the default values, Default:
\code{c("berry", "exnex", "exnex_mix", "exnex_adj", "exnex_adj_mix", "pooled", "stratified", "stratified_mix")}}

\item{target_rates}{A vector of numerics in \verb{(0, 1)} for the
target rates of each cohort, Default: \code{NULL}}

\item{prior_parameters_list}{An object of class \code{prior_parameters_list},
as e.g. created with \code{\link[bhmbasket]{getPriorParameters}}}

\item{calc_differences}{A matrix of positive integers with 2 columns.
For each row the differences will be calculated.
Also a vector of positive integers can be provided for a single difference.
The integers are the numbers for the cohorts to be subtracted from one another.
E.g. providing \code{c(2, 1)} calculates the difference between cohort \code{2} and cohort \code{1}.
If \code{NULL}, no subtractions are performed, Default: \code{NULL}}

\item{n_mcmc_iterations}{A positive integer for the number of MCMC iterations,
see Details, Default: \code{10000}.
If \code{n_mcmc_iterations} is present in \code{.GlobalEnv} and \code{missing(n_mcmc_iterations)},
the globally available value will be used.}

\item{n_cores}{Argument is deprecated and does nothing as of version 0.9.3.
A positive integer for the number of cores for the parallelization,
Default: \code{1}}

\item{seed}{Argument is deprecated and does nothing as of version 0.9.3.
A numeric for the random seed, Default: \code{1}}

\item{verbose}{A logical indicating whether messages should be printed, Default: \code{TRUE}}
}
\value{
An object of class \code{analysis_list}.
}
\description{
This function performs the analysis of simulated or observed trial data with the
specified methods
and returns the quantiles of the posterior response rates
}
\details{
This function applies the following analysis models to (simulated) scenarios of class
\code{scenario_list}:
\itemize{
\item Bayesian hierarchical model (BHM) proposed by Berry et al. (2013): \code{"berry"}
\item BHM proposed by Neuenschwander et al. (2016): \code{"exnex"}
\item BHM that combines above approaches: \code{"exnex_adj"}
\item Pooled beta-binomial approach: \code{"pooled"}
\item Stratified beta-binomial approach: \code{"stratified"}
\item BHM with mixture prior on the Nex component: \code{"exnex_mix"}
\item Adjusted BHM with mixture prior on the Nex component: \code{"exnex_adj_mix"}
\item Stratified beta-binomial approach with mixture beta prior: \code{"stratified_mix"}
}
The posterior distributions of the BHMs are approximated with Markov chain Monte Carlo (MCMC)
methods implemented in JAGS.
Two independent chains are used with each \code{n_mcmc_iterations} number of MCMC iterations.
The first \code{floor(n_mcmc_iterations / 3)} number of iterations are discarded as burn-in period.
No thinning is applied.

Note that the value for \code{n_mcmc_iterations} required for a good approximation of the posterior
distributions depends on the analysis model, the investigated scenarios, and the use case.
The default value might be a good compromise between run-time and approximation for
the estimation of decision probabilities, but
it should definitively be increased for the analysis of a single trial's outcome.

The analysis models will only be applied to the unique trial realizations across
all simulated scenarios.
The models can be applied in parallel by registering a parallel backend for the 'foreach'
framework, e.g. with \code{doFuture::registerDoFuture()} and \code{future::plan(future::multisession)}.
The parallelization is nested, so that the resources of a HPC environment can be used
efficiently.
For more on this topic, kindly see the respective vignette.
The tasks that are to be performed in parallel are chunked according to the number of workers
determined with \code{foreach::getDoParWorkers()}.

The JAGS code for the BHM \code{"exnex"} was taken from Neuenschwander et al. (2016).
The JAGS code for the BHM \code{"exnex_adj"} is based on the JAGS code for \code{"exnex"}.
The JAGS code for the BHM \code{"exnex_mix"} extends the \code{"exnex"} model by using
a mixture prior for the Nex component.
The JAGS code for the BHM \code{"exnex_adj_mix"} extends the \code{"exnex_adj"} model by using
a mixture prior for the Nex component.
}
\examples{
 trial_data <- createTrial(
   n_subjects   = c(10, 20, 30),
   n_responders = c(1, 2, 3))

 analysis_list <- performAnalyses(
   scenario_list      = trial_data,
   target_rates       = rep(0.5, 3),
   calc_differences   = matrix(c(3, 2, 1, 1), ncol = 2),
   n_mcmc_iterations  = 100)
}
\references{
Berry, Scott M., et al. "Bayesian hierarchical modeling of patient subpopulations:
efficient designs of phase II oncology clinical trials."
\emph{Clinical Trials} 10.5 (2013): 720-734.

Neuenschwander, Beat, et al. "Robust exchangeability designs
for early phase clinical trials with multiple strata."
\emph{Pharmaceutical statistics} 15.2 (2016): 123-134.

Plummer, Martyn. "JAGS: A program for analysis of Bayesian graphical models
using Gibbs sampling."
\emph{Proceedings of the 3rd international workshop on distributed statistical computing.}
Vol. 124. No. 125.10. 2003.
}
\seealso{
\code{\link[bhmbasket]{simulateScenarios}}
\code{\link[bhmbasket]{createTrial}}
\code{\link[bhmbasket]{getPriorParameters}}
}
\author{
Stephan Wojciekowski
}
