performAnalyses {bhmbasket}

performAnalyses

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

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_adj", "pooled", "stratified"),
  target_rates = NULL,
  prior_parameters_list = NULL,
  calc_differences = NULL,
  n_mcmc_iterations = 10000,
  n_cores = 1,
  seed = 1,
  verbose = TRUE
)

Arguments

scenario_list

An object of class scenario_list, as e.g. created with simulateScenarios

evidence_levels

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

method_names

A vector of strings for the names of the methods to be used. Must be one of the default values, Default: c("berry", "exnex", "exnex_adj", "pooled", "stratified")

target_rates

A vector of numerics in ⁠(0, 1)⁠ for the target rates of each cohort, Default: NULL

prior_parameters_list

An object of class prior_parameters_list, as e.g. created with getPriorParameters

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 c(2, 1) calculates the difference between cohort 2 and cohort 1. If NULL, no subtractions are performed, Default: NULL

n_mcmc_iterations

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

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: 1

seed

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

verbose

A logical indicating whether messages should be printed, Default: TRUE

Details

This function applies the following analysis models to (simulated) scenarios of class scenario_list:

• Bayesian hierarchical model (BHM) proposed by Berry et al. (2013): "berry"

• BHM proposed by Neuenschwander et al. (2016): "exnex"

• BHM that combines above approaches: "exnex_adj"

• Pooled beta-binomial approach: "pooled"

• Stratified beta-binomial approach: "stratified"

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 n_mcmc_iterations number of MCMC iterations. The first floor(n_mcmc_iterations / 3) number of iterations are discarded as burn-in period. No thinning is applied.

Note that the value for 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 doFuture::registerDoFuture() and 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 foreach::getDoParWorkers().

The JAGS code for the BHM "exnex" was taken from Neuenschwander et al. (2016). The JAGS code for the BHM "exnex_adj" is based on the JAGS code for "exnex".

Value

An object of class analysis_list.

Author(s)

Stephan Wojciekowski

References

Berry, Scott M., et al. "Bayesian hierarchical modeling of patient subpopulations: efficient designs of phase II oncology clinical trials." Clinical Trials 10.5 (2013): 720-734.

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

Plummer, Martyn. "JAGS: A program for analysis of Bayesian graphical models using Gibbs sampling." Proceedings of the 3rd international workshop on distributed statistical computing. Vol. 124. No. 125.10. 2003.

See Also

simulateScenarios createTrial getPriorParameters

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)