| Type: | Package |
| Title: | Tipping Point Analysis for Bayesian Dynamic Borrowing |
| Version: | 0.5.2 |
| Description: | Tipping point analysis for clinical trials that employ Bayesian dynamic borrowing via robust meta-analytic predictive (MAP) priors. Further functions facilitate expert elicitation of a primary weight of the informative component of the robust MAP prior and computation of operating characteristics. Intended use is the planning, analysis and interpretation of extrapolation studies in pediatric drug development, but applicability is generally wider. |
| License: | Apache License 2.0 |
| URL: | https://github.com/Boehringer-Ingelheim/tipmap |
| BugReports: | https://github.com/Boehringer-Ingelheim/tipmap/issues |
| Encoding: | UTF-8 |
| Imports: | dplyr, magrittr, purrr, ggplot2, RBesT, assertthat, stats,furrr, future |
| Suggests: | knitr, rmarkdown, tidyr, tibble, testthat (≥ 3.0.0), |
| Config/testthat/edition: | 3 |
| RoxygenNote: | 7.2.3 |
| VignetteBuilder: | knitr |
| Depends: | R (≥ 3.5.0) |
| NeedsCompilation: | no |
| Repository: | CRAN |
| Packaged: | 2023-08-13 22:13:56 UTC; stockch |
| Author: | Christian Stock [aut, cre], Morten Dreher [aut], Emma Torrini [ctb], Boehringer Ingelheim Pharma GmbH & Co. KG [cph, fnd] |
| Maintainer: | Christian Stock <christian.stock@boehringer-ingelheim.com> |
| Date/Publication: | 2023-08-14 10:30:03 UTC |
tipmap: Tipping Point Analysis for Bayesian Dynamic Borrowing
Description
Tipping point analysis for clinical trials that employ Bayesian dynamic borrowing via robust meta-analytic predictive (MAP) priors. Further functions facilitate expert elicitation of a primary weight of the informative component of the robust MAP prior and computation of operating characteristics. Intended use is the planning, analysis and interpretation of extrapolation studies in pediatric drug development, but applicability is generally wider.
Author(s)
Maintainer: Christian Stockchristian.stock@boehringer-ingelheim.com (ORCID)
Authors:
Morten Dreher
Other contributors:
Emma Torrini [contributor]
Boehringer Ingelheim Pharma GmbH & Co. KG [copyright holder, funder]
See Also
Useful links:
Report bugs athttps://github.com/Boehringer-Ingelheim/tipmap/issues
Data on new trial in target population
Description
Creates a vector containing data on the new trial in the target population. This may be hypothetical data in the planning stage.
Usage
create_new_trial_data(n_total, est, se)Arguments
n_total | The total sample size. |
est | Treatment effect estimate. |
se | Standard error of the treatment effect estimate. |
Value
A numeric vector with data on the new trial, incl. quantiles of an assumed normal data likelihood.
See Also
create_posterior_data,create_tipmap_data
Examples
new_trial_data <- create_new_trial_data( n_total = 30, est = 1.27, se = 0.95)Creates posterior distributions for a range of weights on the informative component of the robust MAP prior
Description
Returns a data frame containing the default quantiles of posterior mixture distributionsgenerated with varying weights on the informative component of the MAP prior.
Usage
create_posterior_data(map_prior, new_trial_data, sigma, null_effect = 0)Arguments
map_prior | A MAP prior containing information about the trial(s) in the source population, created using |
new_trial_data | A vector containing information about the new trial. See |
sigma | Standard deviation to be used for the weakly informative component of the MAP prior, recommended to be the unit-information standard deviation. |
null_effect | The mean of the robust component of the MAP prior. Defaults to 0. |
Value
A data frame containing posterior distributions for varying weights
References
Best, N., Price, R. G., Pouliquen, I. J., & Keene, O. N. (2021).Assessing efficacy in important subgroups in confirmatory trials: An exampleusing Bayesian dynamic borrowing. Pharm Stat, 20(3), 551–562.https://doi.org/10.1002/pst.2093
See Also
create_new_trial_data,create_prior_data
Examples
# create vector containing data on new trialnew_trial_data <- create_new_trial_data( n_total = 30, est = 1.27, se = 0.95)# read MAP prior created by RBesTmap_prior <- load_tipmap_data("tipmapPrior.rds")# create posterior data## Not run: posterior_data <- create_posterior_data( map_prior = map_prior, new_trial_data = new_trial_data, sigma = 12)## End(Not run)Creates input data frame for construction of MAP prior
Description
Assembling information from trials in the source population in a structured way (required as a pre-processing step for MAP prior creation).
Usage
create_prior_data(study_label = NULL, n_total, est, se)Arguments
study_label | An optional vector containing trial labels. |
n_total | A vector containing total sample sizes. |
est | A vector containing treatment effect estimates. |
se | A vector containing standard errors of the effect estimates. |
Value
A data frame containing data on the trials in the source population.
See Also
create_new_trial_data,create_posterior_data
Examples
prior_data <- create_prior_data( n_total = c(160, 240, 320), est = c(1.23, 1.40, 1.51), se = c(0.4, 0.36, 0.31))Create data frame ready to use for tipping point analysis
Description
Combines new trial data created bycreateTargetData(), a posterior distribution created bycreate_posterior_data() and arobust MAP prior usingRBesT::automixfit() and an optional meta-analysis, e.g. created using themeta package, into a data frameneeded for the functionstipmap_plot() andget_tipping_point().
Usage
create_tipmap_data(new_trial_data, posterior, map_prior, meta_analysis = NULL)Arguments
new_trial_data | A data frame containing data on the new trial in the target population. See |
posterior | A mixture combining MAP prior and target population. See |
map_prior | A robust MAP prior created by |
meta_analysis | A data frame containing a meta-analysis of trial(s) to be borrowed from. See |
Value
A data frame ready to be used fortipmap_plot() andget_tipping_point()
See Also
create_new_trial_data,create_posterior_data,tipmap_plot,get_tipping_points
Examples
# specify new trial datanew_trial_data <- create_new_trial_data(n_total = 30, est = 1.5, se = 2.1)# read MAP prior datamap_prior <- load_tipmap_data("tipmapPrior.rds")# read posterior dataposterior <- load_tipmap_data("tipPost.rds")tip_dat <- create_tipmap_data( new_trial_data = new_trial_data, posterior = posterior, map_prior = map_prior)Default quantiles
Description
Default quantiles
Usage
default_quantilesFormat
An object of classnumeric of length 13.
Default weights
Description
Default weights
Usage
default_weightsFormat
An object of classnumeric of length 201.
Draw samples from a mixture of beta distributions
Description
Draws samples from a mixture of beta distributions, representing pooled weights on the informative component of a robust MAP prior, as elicited from experts via the roulette method.
Usage
draw_beta_mixture_nsamples(n, chips_mult, expert_weight = NULL)Arguments
n | Numeric value, the number of samples to be drawn. |
chips_mult | Numeric matrix, containing expert weighting (distributions of chips). Rows should represent experts, columns should represent bins / weight intervals. |
expert_weight | An optional numeric vector, containing the weight assigned to each expert (defaults to equal weights). |
Value
A numeric vector containing samples from a pooled distribution of expert opinions.
See Also
fit_beta_mult_exp andget_summary_mult_exp.
Examples
rweights <- draw_beta_mixture_nsamples( n = 50, chips_mult = rbind( c(0, 0, 0, 0, 2, 3, 3, 2, 0, 0), c(0, 0, 0, 1, 2, 4, 2, 1, 0, 0), c(0, 0, 0, 2, 2, 2, 2, 2, 0, 0) ), expert_weight = rep(1/3, 3))print(rweights)## Not run: hist(rweights)## End(Not run)Fit beta distribution for one expert
Description
Fit beta distribution to data elicited from one expert via the roulette method.
Usage
fit_beta_1exp(df)Arguments
df | A dataframe generated by |
Details
This function is based onSHELF::fitdist and yields identical results.
Value
Parameters (alpha andbeta) of a beta fit.
See Also
get_model_input_1exp andfit_beta_mult_exp.
Examples
chips <- c(0, 2, 3, 2, 1, 1, 1, 0, 0, 0)x <- get_cum_probs_1exp(chips)y <- get_model_input_1exp(x)fit_beta_1exp(df = y)["par"]Fit beta distributions for multiple experts
Description
Fit beta distributions to data elicited from multiple experts via the roulette method.
Usage
fit_beta_mult_exp(chips_mult)Arguments
chips_mult | A dataframe or matrix containing weights.It should contain one row per expert and 10 columns, one for each bin, representing weights from 0 to 1. |
Value
A dataframe containing the parameters of the individual beta distributions.
See Also
Examples
beta_fits <- fit_beta_mult_exp( chips_mult = rbind( c(0, 0, 0, 0, 2, 3, 3, 2, 0, 0), c(0, 0, 0, 1, 2, 4, 2, 1, 0, 0), c(0, 0, 0, 2, 2, 2, 2, 2, 0, 0) ))print(beta_fits)Get cumulative probabilities from distribution of chips of one expert
Description
Get cumulative probabilities from distribution of chips of one expert
Usage
get_cum_probs_1exp(chips)Arguments
chips | Vector of integers, representing the distribution of chips assigned by one expert, as elicited through the roulette method.Each element of the vector represents one bin in the grid. |
Value
A numeric vector with the cumulative distribution of chips.
See Also
get_model_input_1exp andfit_beta_1exp.
Examples
chips <- c(0, 2, 3, 2, 1, 1, 1, 0, 0, 0)x <- get_cum_probs_1exp(chips)print(x)Transform cumulative probabilities to fit beta distributions
Description
Transform cumulative probabilities to fit beta distributions
Usage
get_model_input_1exp(cum_probs, w = NULL)Arguments
cum_probs | Numeric vector, containing cumulative probabilities of weights for one expert, as elicited through the roulette method. Each element of the vector represents one bin in the grid. |
w | Numeric vector, upper interval limit of bin (defaults to |
Value
Dataframe to be used as input to fit beta distributions byfit_beta_1exp.
See Also
get_cum_probs_1exp andfit_beta_1exp.
Examples
chips <- c(0, 2, 3, 2, 1, 1, 1, 0, 0, 0)x <- get_cum_probs_1exp(chips)print(x)y <- get_model_input_1exp(x)print(y)Filter posterior by given weights
Description
Returns quantiles of the posterior distribution of the treatment effect for one or more specified weights.
Usage
get_posterior_by_weight(posterior, weight)Arguments
posterior | The posterior data to be filtered (see |
weight | The weight(s) to be filtered by. |
Value
The filtered posterior values
See Also
Examples
get_posterior_by_weight( posterior = load_tipmap_data("tipPost.rds"), weight = c(0.05, 0.1))Summarize expert weights
Description
Computes minimum, maximum, mean and quartiles for expert weights.
Usage
get_summary_mult_exp(chips_mult, n = 500, expert_weight = NULL)Arguments
chips_mult | Numeric matrix, containing expert weights. |
n | Number of samples to be drawn to obtain summary statistics (defaults to 500). |
expert_weight | Weights assigned to each expert (defaults to equal weights). |
Value
A vector containing summary statistics.
Examples
get_summary_mult_exp( chips_mult = rbind( c(0, 0, 0, 0, 2, 3, 3, 2, 0, 0), c(0, 0, 0, 1, 2, 4, 2, 1, 0, 0), c(0, 0, 0, 2, 2, 2, 2, 2, 0, 0) ), n = 50)Identify tipping point for a specific quantile.
Description
Identifies the weights closest to tipping points for specified quantiles.
Usage
get_tipping_points(tipmap_data, quantile, null_effect = 0)Arguments
tipmap_data | A data frame created by |
quantile | The quantile(s) of the tipping point. Possible values are 0.025, 0.05, 0.1, 0.2, 0.8, 0.9, 0.95 and 0.975. |
null_effect | The null treatment effect. Defaults to 0. |
Value
The weight closest to the tipping point for the specified quantile
See Also
Examples
tip_dat <- load_tipmap_data("tipdat.rds")#'get_tipping_points(tip_dat, quantile = 0.025)get_tipping_points(tip_dat, quantile = c(0.025, 0.05, 0.1, 0.2), null_effect = 0.1)Load exemplary datasets
Description
Loads one of three exemplary datasets in the package.
Usage
load_tipmap_data(file)Arguments
file | The dataset to be loaded. |
Value
A pre-saved dataset.
Examples
load_tipmap_data(file = "tipdat.rds")load_tipmap_data(file = "tipmapPrior.rds")load_tipmap_data(file = "tipPost.rds")Assessing bias
Description
Assessment of absolute bias in posterior means and medians for a given weight and evidence level, using simulated data as input.
Usage
oc_bias( m, se, true_effect, weights = seq(0, 1, by = 0.01), map_prior, sigma, n_cores = 1, eval_strategy = "sequential")Arguments
m | Numerical vector of simulated effect estimates. |
se | Numerical vector of simulated standard errors ( |
true_effect | Numerical value, representing the true treatment effect (usually the mean of the simulated |
weights | Vector of weights of the informative component of the MAP prior (defaults to |
map_prior | A MAP prior containing information about the trials in the source population, created using |
sigma | Standard deviation of the weakly informative component of the MAP prior, recommended to be the unit-information standard deviation. |
n_cores | Integer value, representing the number of cores to be used (defaults to 1); only applies if |
eval_strategy | Character variable, representing the evaluation strategy, either "sequential", "multisession", or "multicore" (see documentation of |
Value
A 2-dimensional array containing results on bias.
See Also
oc_pos andoc_coverage.
Examples
set.seed(123)n_sims <- 5 # small number for exemplary application sim_dat <- list( "m" = rnorm(n = n_sims, mean = 1.15, sd = 0.1), "se" = rnorm(n = n_sims, mean = 1.8, sd = 0.3))results <- oc_bias( m = sim_dat[["m"]], se = sim_dat[["se"]], true_effect = 1.15, weights = seq(0, 1, by = 0.01), map_prior = load_tipmap_data("tipmapPrior.rds"), sigma = 16.23, eval_strategy = "sequential", n_cores = 1) print(results)Assessing coverage
Description
Assessment of coverage of posterior intervals for a given weight and evidence level, using simulated data as input.
Usage
oc_coverage( m, se, true_effect, weights = seq(0, 1, by = 0.01), map_prior, sigma, n_cores = 1, eval_strategy = "sequential")Arguments
m | Numerical vector of simulated effect estimates. |
se | Numerical vector of simulated standard errors ( |
true_effect | Numerical value, representing the true treatment effect (usually the mean of the simulated |
weights | Vector of weights of the informative component of the MAP prior (defaults to |
map_prior | A MAP prior containing information about the trials in the source population, created using |
sigma | Standard deviation of the weakly informative component of the MAP prior, recommended to be the unit-information standard deviation. |
n_cores | Integer value, representing the number of cores to be used (defaults to 1); only applies if |
eval_strategy | Character variable, representing the evaluation strategy, either "sequential", "multisession", or "multicore" (see documentation of |
Value
A 2-dimensional array containing results on coverage.
See Also
Examples
set.seed(123)n_sims <- 5 # small number for exemplary application sim_dat <- list( "m" = rnorm(n = n_sims, mean = 1.15, sd = 0.1), "se" = rnorm(n = n_sims, mean = 1.8, sd = 0.3))results <- oc_coverage( m = sim_dat[["m"]], se = sim_dat[["se"]], true_effect = 1.15, weights = seq(0, 1, by = 0.01), map_prior = load_tipmap_data("tipmapPrior.rds"), sigma = 16.23) print(results)Assessing probability of success
Description
Assessment of the probability of truly or falsely (depending on simulated scenario) rejecting the null hypothesis of interest for a given weight and evidence level, using simulated data as input.
Usage
oc_pos( m, se, probs, weights = seq(0, 1, by = 0.01), map_prior, sigma, null_effect = 0, direction_pos = T, n_cores = 1, eval_strategy = "sequential")Arguments
m | Numerical vector of simulated effect estimates. |
se | Numerical vector of simulated standard errors ( |
probs | Vector of quantiles q, with 1 minus q representing an evidence level of interest (where positive effect estimate indicate a beneficial treatment). |
weights | Vector of weights of the informative component of the MAP prior (defaults to |
map_prior | A MAP prior containing information about the trials in the source population, created using |
sigma | Standard deviation of the weakly informative component of the MAP prior, recommended to be the unit-information standard deviation. |
null_effect | Numerical value, representing the null effect (defaults to 0). |
direction_pos | Logical value, |
n_cores | Integer value, representing the number of cores to be used (defaults to 1); only applies if |
eval_strategy | Character variable, representing the evaluation strategy, either "sequential", "multisession", or "multicore" (see documentation of |
Value
A 2-dimensional array containing probabilities, either of truly (probability of success) or falsely rejecting the null hypothesis of interest for a given weight and evidence level.
See Also
oc_bias andoc_coverage.
Examples
set.seed(123)n_sims <- 5 # small number for exemplary applicationsim_dat <- list( "m" = rnorm(n = n_sims, mean = 1.15, sd = 0.1), "se" = rnorm(n = n_sims, mean = 1.8, sd = 0.3))results <- oc_pos( m = sim_dat[["m"]], se = sim_dat[["se"]], probs = c(0.025, 0.05, 0.1, 0.2), weights = seq(0, 1, by = 0.01), map_prior = load_tipmap_data("tipmapPrior.rds"), sigma = 16.23, null_effect = 0, direction_pos = TRUE, eval_strategy = "sequential", n_cores = 1) print(results)Custom dark blue
Description
Custom dark blue
Usage
tipmap_darkblueFormat
An object of classcharacter of length 1.
Custom light red
Description
Custom light red
Usage
tipmap_lightredFormat
An object of classcharacter of length 1.
Visualize tipping point analysis
Description
Uses a data frame created bycreate_tipmap_data() to visualize the tipping point analysis.
Usage
tipmap_plot( tipmap_data, target_pop_lab = "Trial in target\n population", y_range = NULL, y_breaks = NULL, title = NULL, y_lab = "Mean difference", x_lab = "Weight on informative component of MAP prior", map_prior_lab = "MAP\nprior", meta_analysis_lab = "MA", legend_title = "Posterior quantile", null_effect = 0)Arguments
tipmap_data | A data frame containing tipping point data, generated by |
target_pop_lab | A label for the trial in the target population. |
y_range | An optional argument specifying range of the y-axis. |
y_breaks | An optional vector specifying breaks on the y-axis. |
title | The plot title. |
y_lab | The label for the y axis. Defaults to "Mean difference". |
x_lab | The label for the x axis. Defaults to "Weight on informative component of MAP prior". |
map_prior_lab | The label for the MAP prior. Defaults to "MAP prior" |
meta_analysis_lab | An optional label for a meta-analysis (if included). |
legend_title | An optional title for the plot legend. Defaults to "Posterior quantiles". |
null_effect | The null treatment effect, determining where tipping points are calculated. Defaults to 0. |
Value
Aggplot object of the tipping point plot
See Also
Examples
tipmap_data <- load_tipmap_data("tipdat.rds")tipmap_plot(tipmap_data)