diff --git a/NEWS.md b/NEWS.md index d890ef5..bbeb4a3 100644 --- a/NEWS.md +++ b/NEWS.md @@ -57,6 +57,7 @@ - Code hygiene throughout the package: progress bars in `run_owsa_det()` and `run_twsa_det()` are now closed, loops handle zero-length inputs (for example, `calc_evpi()` with an empty `wtp` returns an empty result), deprecated `trans`/`scales::trans_new()` are replaced by ggplot2's `transform` and `scales::new_transform()`, `cor()` is imported, and the `rdirichlet()` documentation is fixed. Thanks to @IG-ABHINAV for this contribution (#211, #224). - Fixed a pointer in the PSA vignette to a vignette that no longer exists (#168). - `citation("dampack")` now returns a single, current entry built from the package's DESCRIPTION; it used to also return a stale entry for version 1.0.1 (#213). +- Every exported function now has a runnable example, and several help pages have corrected titles, links, and keywords (#212). # dampack 1.0.2.1000 diff --git a/R/add_common_aes.R b/R/add_common_aes.R index c26b626..cafb602 100644 --- a/R/add_common_aes.R +++ b/R/add_common_aes.R @@ -245,7 +245,18 @@ labfun <- function(x) { #' \code{ggplot2} plots. Non-integer values are rounded down. #' @section Details: #' Based on function \code{pretty}. -#' @return a vector of axis-label breaks +#' @return a function that takes the axis limits and returns a vector of axis-label breaks +#' @examples +#' # number_ticks() returns a function of the axis limits +#' f_breaks <- number_ticks(5) +#' f_breaks(c(0, 97)) +#' +#' # use it for the breaks of a ggplot2 axis +#' data("hund_strat") +#' ggplot(hund_strat, aes(x = QALYs, y = Cost)) + +#' geom_point() + +#' scale_x_continuous(breaks = number_ticks(4)) + +#' scale_y_continuous(breaks = number_ticks(8)) #' @export number_ticks <- function(n) { function(limits) { diff --git a/R/ceac.R b/R/ceac.R index 62d2549..30d389b 100644 --- a/R/ceac.R +++ b/R/ceac.R @@ -7,7 +7,7 @@ #' #' @param psa psa object from \code{\link{make_psa_obj}} #' @param wtp numeric vector with willingness-to-pay (WTP) thresholds -#' @keywords cost-effectiveness acceptability curves +#' @concept cost-effectiveness acceptability curves #' @details #' Like \code{\link{calc_exp_loss}} and \code{\link{calc_evpi}}, \code{ceac} takes the #' \code{psa} object first. The order used before dampack 1.1.0, \code{ceac(wtp, psa)}, still @@ -161,13 +161,25 @@ ceac <- function(psa, wtp) { #' with many strategies. #' @inheritParams add_common_aes #' -#' @keywords internal -#' #' @details #' \code{ceac} computes the probability of each of the strategies being #' cost-effective at each \code{wtp} value. #' @return A \code{ggplot2} plot of the CEAC. #' +#' @seealso \code{\link{ceac}}, \code{\link{summary.ceac}} +#' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_ceac <- ceac(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) +#' plot(df_ceac) +#' +#' # without the frontier, and with fewer x-axis ticks +#' plot(df_ceac, frontier = FALSE, n_x_ticks = 5) +#' #' @import ggplot2 #' @import dplyr #' @importFrom rlang !! @@ -278,7 +290,18 @@ plot.ceac <- function(x, #' strategy on the cost-effectiveness frontier there. The intervals are open on #' the right endpoint - i.e., [\code{range_min}, \code{range_max}) #' -#' @keywords internal +#' @seealso \code{\link{ceac}}, \code{\link{plot.ceac}} +#' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_ceac <- ceac(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) +#' +#' # Radio is optimal up to a WTP of 40,000 and Chemo from there on +#' summary(df_ceac) #' #' @export summary.ceac <- function(object, ...) { diff --git a/R/create_sa.R b/R/create_sa.R index 93fe547..b94823e 100644 --- a/R/create_sa.R +++ b/R/create_sa.R @@ -108,6 +108,15 @@ create_sa <- function(parameters, parnames, effectiveness, strategies, #' @param ... further arguments to print (not used) #' #' @return None (invisible NULL). +#' +#' @examples +#' data("psa_cdiff") +#' +#' # the list of strategies is truncated at 5 +#' print(psa_cdiff) +#' +#' # print all of them +#' print(psa_cdiff, all_strat = TRUE) #' @export print.sa <- function(x, all_strat = FALSE, ...) { v_xclass <- class(x) diff --git a/R/data_cdiff.R b/R/data_cdiff.R index 7485c2a..a4fd1e9 100644 --- a/R/data_cdiff.R +++ b/R/data_cdiff.R @@ -1,3 +1,45 @@ -#' Sample PSA dataset +#' PSA of treatment strategies for Clostridioides difficile infection #' +#' Probabilistic sensitivity analysis (PSA) output from a decision model of +#' treatment strategies for \emph{Clostridioides difficile} infection (CDI). +#' The model compared 48 strategies, which varied in the treatment regimen +#' used for initial versus recurrent CDI and for different infection +#' severities; this sample keeps the 11 most relevant strategies. Costs include +#' all treatment costs and lifetime downstream medical costs, and effectiveness +#' is quality-adjusted life expectancy, for a 67-year-old patient (the median +#' age of patients with CDI). +#' +#' @format A \code{psa} object (see \code{\link{make_psa_obj}}): a list with 6 +#' elements. +#' \describe{ +#' \item{n_strategies}{number of strategies, 11.} +#' \item{strategies}{character vector of the 11 strategy names (\code{"s3"}, +#' \code{"s27"}, and so on), which follow the strategy numbering of the +#' source study.} +#' \item{n_sim}{number of PSA samples, 1,000.} +#' \item{cost}{data frame with 1,000 rows (PSA samples) and 11 columns (one +#' per strategy) with the cost of each strategy.} +#' \item{effectiveness}{data frame with 1,000 rows and 11 columns with the +#' quality-adjusted life years (QALYs) of each strategy.} +#' \item{currency}{currency symbol, \code{"$"}.} +#' } +#' The parameter values drawn in each sample are not included, so the sample +#' supports cost-effectiveness analysis but not metamodeling or EVPPI. +#' +#' @source Rajasingham R, Enns EA, Khoruts A, Vaughn BP. Cost-effectiveness of +#' Treatment Regimens for Clostridioides difficile Infection: An Evaluation of +#' the 2018 Infectious Diseases Society of America Guidelines. Clinical +#' Infectious Diseases. 2020;70(5):754-762. \doi{10.1093/cid/ciz318} +#' +#' @seealso \code{vignette("basic_cea", package = "dampack")}, which uses this +#' dataset. +#' +#' @examples +#' data("psa_cdiff") +#' df_cdiff <- summary(psa_cdiff) +#' df_icers <- calculate_icers(cost = df_cdiff$meanCost, +#' effect = df_cdiff$meanEffect, +#' strategies = df_cdiff$Strategy) +#' df_icers +#' plot(df_icers) "psa_cdiff" diff --git a/R/data_example_psa_elc.R b/R/data_example_psa_elc.R index 9402f56..105ea78 100644 --- a/R/data_example_psa_elc.R +++ b/R/data_example_psa_elc.R @@ -52,7 +52,7 @@ #' effectiveness = df_example_psa_elc[, 7:12]) #' #' # the frontier switches three times, so the summary has four intervals -#' df_ceac <- ceac(wtp = seq(1000, 150000, 1000), psa = l_psa) +#' df_ceac <- ceac(l_psa, wtp = seq(1000, 150000, 1000)) #' summary(df_ceac) #' #' # the strategy most likely to be cost effective is not necessarily the one diff --git a/R/dsa_oneway.R b/R/dsa_oneway.R index 514ec00..13b405b 100644 --- a/R/dsa_oneway.R +++ b/R/dsa_oneway.R @@ -20,6 +20,35 @@ #' #' @return a class \code{dsa_oneway} object that can be passed to the \code{\link{owsa}} function #' to visualize the one-way sensitivity analyses contained in the object. +#' +#' @seealso \code{\link{run_owsa_det}}, which runs a model function over the parameter ranges, +#' builds this object internally, and returns the result of \code{\link{owsa}}. +#' +#' @examples +#' # Outcomes of two strategies, evaluated at 5 values of the failure probability p_fail +#' # (with c_trt at its base case of 15,000) and at 5 values of the cost of the new +#' # treatment c_trt (with p_fail at its base case of 0.3) +#' v_p_fail <- seq(0.1, 0.5, length.out = 5) +#' v_c_trt <- seq(5000, 25000, length.out = 5) +#' df_params <- data.frame(parameter = rep(c("p_fail", "c_trt"), each = 5), +#' value = c(v_p_fail, v_c_trt)) +#' v_p_fail_all <- c(v_p_fail, rep(0.3, 5)) +#' v_c_trt_all <- c(rep(15000, 5), v_c_trt) +#' df_cost <- data.frame(Standard = 20000 * v_p_fail_all, +#' New = v_c_trt_all + 10000 * v_p_fail_all) +#' df_effect <- data.frame(Standard = 10 - 2 * v_p_fail_all, +#' New = 10 - v_p_fail_all) +#' +#' l_dsa <- create_dsa_oneway(parameters = df_params, +#' effectiveness = df_effect, +#' strategies = c("Standard", "New"), +#' cost = df_cost) +#' l_dsa +#' +#' # one-way sensitivity analysis of the net monetary benefit at a WTP of 50,000 +#' df_owsa <- owsa(l_dsa, outcome = "nmb", wtp = 5e4) +#' plot(df_owsa) +#' owsa_opt_strat(df_owsa) #' @export create_dsa_oneway <- function(parameters, effectiveness = NULL, strategies, cost = NULL, currency = "$", other_outcome = NULL) { diff --git a/R/dsa_twoway.R b/R/dsa_twoway.R index e523d22..08f1cb2 100644 --- a/R/dsa_twoway.R +++ b/R/dsa_twoway.R @@ -1,8 +1,8 @@ -#' Create one-way deterministic sensitivity analysis object +#' Create two-way deterministic sensitivity analysis object #' #' @description The object returned by this function can be passed to -#' \code{\link{owsa}} to do a one-way sensitivity analysis on each -#' parameter of interest. +#' \code{\link{twsa}} to do a two-way sensitivity analysis on the two +#' parameters of interest. #' #' @inheritParams create_sa #' @@ -18,6 +18,29 @@ #' } #' @return a class \code{dsa_twoway} object that can be passed to the \code{\link{twsa}} function #' to visualize the two-way sensitivity analysis contained in the object. +#' +#' @seealso \code{\link{run_twsa_det}}, which runs a model function over the parameter ranges, +#' builds this object internally, and returns the result of \code{\link{twsa}}. +#' +#' @examples +#' # Outcomes of two strategies on a 5 x 5 grid of the failure probability p_fail and +#' # the cost of the new treatment c_trt +#' df_params <- expand.grid(p_fail = seq(0.1, 0.5, length.out = 5), +#' c_trt = seq(5000, 25000, length.out = 5)) +#' df_cost <- data.frame(Standard = 20000 * df_params$p_fail, +#' New = df_params$c_trt + 10000 * df_params$p_fail) +#' df_effect <- data.frame(Standard = 10 - 2 * df_params$p_fail, +#' New = 10 - df_params$p_fail) +#' +#' l_dsa <- create_dsa_twoway(parameters = df_params, +#' effectiveness = df_effect, +#' strategies = c("Standard", "New"), +#' cost = df_cost) +#' l_dsa +#' +#' # strategy with the highest net monetary benefit at a WTP of 50,000 +#' df_twsa <- twsa(l_dsa, outcome = "nmb", wtp = 5e4) +#' plot(df_twsa) #' @export create_dsa_twoway <- function(parameters, effectiveness = NULL, strategies, cost = NULL, currency = "$", other_outcome = NULL) { diff --git a/R/evpi.R b/R/evpi.R index d4be944..13d29e3 100644 --- a/R/evpi.R +++ b/R/evpi.R @@ -5,7 +5,8 @@ #' @param wtp numeric vector with willingness-to-pay (WTP) thresholds #' @param psa psa object from \code{\link{make_psa_obj}} #' @param pop scalar that corresponds to the total population -#' @keywords expected value of perfect information; net monetary benefit +#' @concept expected value of perfect information +#' @concept net monetary benefit #' @section Details: #' \code{evpi} calculates the value of eliminating all the uncertainty of a #' cost-effectiveness analysis at each WTP threshold. @@ -73,9 +74,20 @@ calc_evpi <- function(psa, wtp, pop = 1) { #' \code{"life-years"}). Default: \code{"QALYs"}. The willingness-to-pay axis uses the singular #' ("$/QALY"), and a value already in the singular is used as given. #' @inheritParams add_common_aes -#' @keywords expected value of perfect information +#' @concept expected value of perfect information #' @return A \code{ggplot2} plot with the EVPI #' @seealso \code{\link{calc_evpi}} +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_evpi <- calc_evpi(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) +#' plot(df_evpi) +#' +#' # change the labels and the number of axis ticks +#' plot(df_evpi, currency = "USD", effect_units = "life-years", n_x_ticks = 5) #' @import ggplot2 #' @importFrom scales comma #' @export diff --git a/R/evppi.R b/R/evppi.R index 2719cb7..d4198c1 100644 --- a/R/evppi.R +++ b/R/evppi.R @@ -63,6 +63,25 @@ #' 2014;34(3):311–26. #' } #' +#' @seealso \code{\link{plot.evppi}}, \code{\link{calc_evpi}}, \code{\link{calc_evsi}} +#' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # EVPPI of the two treatment-failure probabilities, jointly, at three WTP thresholds +#' l_evppi <- calc_evppi(l_psa, +#' wtp = c(5e4, 1e5, 2e5), +#' params = c("pFailChemo", "pFailSurg"), +#' outcome = "nmb", +#' k = 3, +#' progress = FALSE) +#' l_evppi$df_evppi +#' plot(l_evppi) +#' #' @importFrom dplyr bind_cols #' #' @export @@ -147,9 +166,21 @@ calc_evppi <- function(psa, #' \code{"life-years"}). Default: \code{"QALYs"}. The willingness-to-pay axis uses the singular #' ("$/QALY"), and a value already in the singular is used as given. #' @inheritParams add_common_aes -#' @keywords expected value of perfect information +#' @concept expected value of partial perfect information #' @return A \code{ggplot2} plot with the EVPPI #' @seealso \code{\link{calc_evppi}} +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' l_evppi <- calc_evppi(l_psa, wtp = c(5e4, 1e5, 2e5), params = "pFailChemo", +#' progress = FALSE) +#' plot(l_evppi) +#' +#' # ggplot2 layers can be added to the plot +#' plot(l_evppi, n_x_ticks = 5) + ggtitle("EVPPI of pFailChemo") #' @import ggplot2 #' @importFrom scales comma #' @export diff --git a/R/evsi.R b/R/evsi.R index 4968bae..ebeb321 100644 --- a/R/evsi.R +++ b/R/evsi.R @@ -19,6 +19,52 @@ #' for the selected parameters and 2) a list of metamodels used to estimate EVSI for each #' strategy at each willingness to pay threshold. #' +#' @seealso \code{\link{plot.evsi}}, \code{\link{calc_evppi}} +#' +#' @references +#' \enumerate{ +#' \item Jalal H, Alarid-Escudero F. A Gaussian Approximation Approach for Value of +#' Information Analysis. Med Decis Making. 2018;38(2):174-188. +#' \doi{10.1177/0272989X17715627} +#' \item Strong M, Oakley JE, Brennan A. Estimating Multiparameter Partial Expected Value +#' of Perfect Information from a Probabilistic Sensitivity Analysis Sample: A Nonparametric +#' Regression Approach. Med Decis Making. 2014;34(3):311-326. \doi{10.1177/0272989X13505910} +#' } +#' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # EVSI of a study of n additional patients that informs both failure probabilities, +#' # which were each estimated from an initial study of n0 = 50 patients +#' l_evsi <- calc_evsi(l_psa, +#' wtp = 1e5, +#' params = c("pFailSurg", "pFailChemo"), +#' outcome = "nmb", +#' k = 3, +#' n = c(10, 50, 100, 200), +#' n0 = 50, +#' progress = FALSE) +#' l_evsi$df_evsi +#' plot(l_evsi) +#' +#' \donttest{ +#' # a separate initial and additional sample size for each parameter +#' l_evsi_by_param <- calc_evsi(l_psa, +#' wtp = c(5e4, 1e5, 2e5), +#' params = c("pFailSurg", "pFailChemo"), +#' outcome = "nmb", +#' k = 3, +#' n = c(100, 50), +#' n0 = c(50, 20), +#' n_by_param = TRUE, +#' progress = FALSE) +#' l_evsi_by_param$df_evsi +#' } +#' #' @export calc_evsi <- function(psa, wtp, @@ -291,9 +337,27 @@ predict_matrix_tensor_smooth_ga <- function(object, #' \code{"life-years"}). Default: \code{"QALYs"}. The willingness-to-pay axis uses the singular #' ("$/QALY"), and a value already in the singular is used as given. #' @inheritParams add_common_aes -#' @keywords expected value of sample information +#' @concept expected value of sample information #' @return A \code{ggplot2} plot with the EVSI #' @seealso \code{\link{calc_evsi}} +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # one WTP threshold and several sample sizes: EVSI by additional sample size +#' l_evsi <- calc_evsi(l_psa, wtp = 1e5, params = "pFailSurg", outcome = "nmb", +#' n = c(10, 50, 100, 200), n0 = 50, progress = FALSE) +#' plot(l_evsi) +#' +#' \donttest{ +#' # several WTP thresholds and one sample size: EVSI by WTP threshold +#' l_evsi_wtp <- calc_evsi(l_psa, wtp = c(5e4, 1e5, 2e5), params = "pFailSurg", +#' outcome = "nmb", n = 100, n0 = 50, progress = FALSE) +#' plot(l_evsi_wtp) +#' } #' @import ggplot2 #' @importFrom scales comma #' @export diff --git a/R/exp_loss.R b/R/exp_loss.R index 05a9a3d..836d80e 100644 --- a/R/exp_loss.R +++ b/R/exp_loss.R @@ -112,6 +112,18 @@ calc_exp_loss <- function(psa, wtp) { #' @inheritParams add_common_aes #' #' @return A \code{ggplot2} object with the expected loss +#' @seealso \code{\link{calc_exp_loss}} +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_exp_loss <- calc_exp_loss(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) +#' plot(df_exp_loss) +#' +#' # linear y axis, without the points or the frontier +#' plot(df_exp_loss, log_y = FALSE, points = FALSE, frontier = FALSE) #' @import ggplot2 #' @importFrom rlang !! #' @importFrom rlang sym diff --git a/R/gen_psa_samp.R b/R/gen_psa_samp.R index b98ad2f..4752fbe 100644 --- a/R/gen_psa_samp.R +++ b/R/gen_psa_samp.R @@ -302,7 +302,9 @@ rdirichlet <- function(n, alpha) { #' deviation \eqn{\sigma} of the random variable of interest. #' @param mean mean of the random variable. #' @param sigma standard deviation of the random variable (i.e., standard error). -#' @keywords beta distribution; methods of moments +#' @keywords distribution +#' @concept beta distribution +#' @concept method of moments #' @section Details: #' Based on methods of moments. If \eqn{\mu} is the mean and #' \eqn{\sigma} is the standard deviation of the random variable, then @@ -313,6 +315,13 @@ rdirichlet <- function(n, alpha) { #' @return a list containing the following: #' @return alpha The method-of-moments estimate for the alpha parameter of the beta distribution #' @return beta The method-of-moments estimate for the beta parameter of the beta distribution +#' @examples +#' # a probability with a mean of 0.2 and a standard error of 0.05 +#' l_beta <- beta_params(mean = 0.2, sigma = 0.05) +#' l_beta +#' +#' # the mean of the resulting beta distribution recovers the input mean +#' l_beta$alpha / (l_beta$alpha + l_beta$beta) #' @export beta_params <- function(mean, sigma) { alpha <- ((1 - mean) / sigma ^ 2 - 1 / mean) * mean ^ 2 @@ -332,7 +341,9 @@ beta_params <- function(mean, sigma) { #' @param p.mean Vector of means of the random variables. #' @param sigma Vector of standard deviation of the random variables #' (i.e., standard error). -#' @keywords dirichlet distribution; method of moments +#' @keywords distribution +#' @concept Dirichlet distribution +#' @concept method of moments #' @section Details: #' Based on methods of moments. If \eqn{\mu} is a vector of means and #' \eqn{\sigma} is a vector of standard deviations of the random variables, then @@ -385,7 +396,9 @@ dirichlet_params <- function(p.mean, sigma) { #' @param sigma scalar with the standard deviation of the random variable. #' @param scale logical variable indicating scale parameterization of the gamma distribution #' (Default is TRUE). If FALSE, rate parameterization is retrieved -#' @keywords gamma distribution; method of moments +#' @keywords distribution +#' @concept gamma distribution +#' @concept method of moments #' @section Details: #' Based on method of moments. If \eqn{\mu} is the mean and #' \eqn{\sigma} is the standard deviation of the random variable, then the @@ -439,7 +452,9 @@ gamma_params <- function(mu, sigma, scale = TRUE) { #' @param m Scalar with the mean of the random variable. #' @param v Scalar with the variance of the random variable. #' (i.e., squared standard error). -#' @keywords log-normal distribution; method of moments +#' @keywords distribution +#' @concept log-normal distribution +#' @concept method of moments #' @section Details: #' Based on method of moments. If \eqn{m} is the mean and #' \eqn{v} is the variance of the random variable, then the @@ -463,8 +478,11 @@ gamma_params <- function(mu, sigma, scale = TRUE) { #' @examples #' m <- 3 #' v <- 0.01 -#' lnorm_params(m, v) -#' # True values: 100, 30, 70 +#' l_lnorm <- lnorm_params(m, v) +#' l_lnorm +#' +#' # the mean of the resulting log-normal distribution recovers m +#' exp(l_lnorm$mu + l_lnorm$sigma^2 / 2) #' @export lnorm_params <- function(m = 1, v = 1) { ### Sanity checkd diff --git a/R/icers.R b/R/icers.R index 449bbe5..fa33cf2 100644 --- a/R/icers.R +++ b/R/icers.R @@ -348,10 +348,10 @@ add_reference_and_nmb <- function(df_icers, ref_str, wtp, nhb, currency) { #' Because the dominated vs. non-dominated status and the ordering of strategies in the ICER table are #' liable to change across different samples of the PSA, confidence intervals are not provided for the #' incremental costs and QALYs along the cost-effectiveness acceptability frontier. -#' \code{link{plot.psa}} does not show the confidence intervals in the resulting plot +#' \code{\link{plot.icers}} does not show the confidence intervals in the resulting plot #' even if present in the ICER table. #' -#' @param psa \code{psa} object from \code{link{make_psa_object}} +#' @param psa \code{psa} object from \code{\link{make_psa_obj}} #' @param uncertainty whether or not 95\% quantiles for the cost and QALY outcomes should be included #' in the resulting ICER table. Defaults to \code{FALSE}. #' @inheritParams calculate_icers @@ -368,6 +368,25 @@ add_reference_and_nmb <- function(df_icers, ref_str, wtp, nhb, currency) { #' \code{Inc_NMB_ref}, in columns such as \code{Lower_95_Inc_Cost_ref} and \code{Upper_95_Inc_Cost_ref}. #' @seealso \code{\link{plot.icers}} #' @seealso \code{\link{calculate_icers}} +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # ICERs from the mean cost and effectiveness of each strategy +#' df_icers <- calculate_icers_psa(l_psa) +#' df_icers +#' plot(df_icers) +#' +#' # add the 2.5th and 97.5th percentiles of the cost and effectiveness of each strategy +#' df_icers_unc <- calculate_icers_psa(l_psa, uncertainty = TRUE) +#' df_icers_unc +#' +#' # compare every strategy with Radio, adding the net monetary benefit at a WTP of 100,000 +#' df_icers_ref <- calculate_icers_psa(l_psa, ref_str = "Radio", wtp = 1e5) +#' print(df_icers_ref, ref = "reference") #' @importFrom tidyr pivot_longer #' @export calculate_icers_psa <- function(psa, uncertainty = FALSE, ref_str = NULL, wtp = NULL, nhb = FALSE) { @@ -526,6 +545,23 @@ compute_icers <- function(non_d) { #' #' @return a ggplot2 object which can be modified by adding additional geoms #' +#' @seealso \code{\link{calculate_icers}}, \code{\link{calculate_icers_psa}} +#' +#' @examples +#' data("psa_cdiff") +#' df_cdiff <- summary(psa_cdiff) +#' df_icers <- calculate_icers(cost = df_cdiff$meanCost, +#' effect = df_cdiff$meanEffect, +#' strategies = df_cdiff$Strategy) +#' plot(df_icers) +#' +#' # label every strategy, or show only the efficient frontier +#' plot(df_icers, label = "all") +#' plot(df_icers, plot_frontier_only = TRUE) +#' +#' # incremental cost-effectiveness plane with s3 at the origin and a WTP line +#' plot(df_icers, ref_str = "s3", wtp = 1e5) +#' #' @importFrom stringr str_sub #' @importFrom ggrepel geom_label_repel #' @importFrom rlang !! @@ -693,6 +729,26 @@ plot.icers <- function(x, #' or \code{"both"}. #' @param ... Additional arguments passed to other methods. #' @return a dataframe object - formatted CEA table +#' +#' @seealso \code{\link{calculate_icers}} +#' +#' @examples +#' data("psa_cdiff") +#' df_cdiff <- summary(psa_cdiff) +#' df_icers <- calculate_icers(cost = df_cdiff$meanCost, +#' effect = df_cdiff$meanEffect, +#' strategies = df_cdiff$Strategy, +#' ref_str = "s3", +#' wtp = 1e5) +#' +#' # sequential table: each strategy on the frontier against the previous one +#' df_icers +#' +#' # every strategy against the reference, with more digits for costs and effects +#' print(df_icers, ref = "reference", dig_cost = 2, dig_eff = 3) +#' +#' # both comparisons, with costs labeled in euros +#' print(df_icers, ref = "both", currency = "EUR") #' @export print.icers <- function(x, currency = NULL, diff --git a/R/metamodel.R b/R/metamodel.R index 7ea9f6f..212746f 100644 --- a/R/metamodel.R +++ b/R/metamodel.R @@ -34,6 +34,25 @@ #' \code{\link{owsa}}, #' \code{\link{twsa}} #' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # one linear metamodel of the effectiveness per parameter and strategy +#' l_mm <- metamodel(analysis = "oneway", psa = l_psa, +#' params = c("pFailChemo", "cChemo"), outcome = "eff") +#' l_mm +#' summary(l_mm) +#' +#' # a two-way polynomial metamodel of the net monetary benefit of Chemo +#' l_mm_twoway <- metamodel(analysis = "twoway", psa = l_psa, +#' params = c("pFailChemo", "cChemo"), strategies = "Chemo", +#' outcome = "nmb", wtp = 1e5, type = "poly", poly.order = 2) +#' head(predict(l_mm_twoway, nsamp = 5)) +#' #' @importFrom stats as.formula formula getCall lm #' @export metamodel <- function(analysis = c("oneway", "twoway", "multiway"), @@ -235,6 +254,15 @@ mm_run_reg <- function(analysis, dep, params, dat, type, poly.order, k) { #' @param x metamodel to print #' @param ... further arguments to print #' @return None (invisible NULL) +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' l_mm <- metamodel(analysis = "oneway", psa = l_psa, params = "pFailChemo", +#' outcome = "nmb", wtp = 1e5) +#' print(l_mm) #' @export print.metamodel <- function(x, ...) { wtp <- x$wtp @@ -259,6 +287,16 @@ print.metamodel <- function(x, ...) { #' @param object metamodel to summarize #' @param ... further arguments to summary #' @return a \code{data.frame} containing the r-squared for each strategy and parameter's metamodel. +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # which parameters explain most of the variation in the net monetary benefit? +#' l_mm <- metamodel(analysis = "oneway", psa = l_psa, outcome = "nmb", wtp = 1e5) +#' summary(l_mm) #' @export summary.metamodel <- function(object, ...) { analysis <- object$analysis @@ -311,6 +349,20 @@ summary.metamodel <- function(object, ...) { #' @importFrom stats quantile predict #' @return a \code{data.frame} containing the outcome values predicted by the metamodel #' for each strategy and each combination of parameter values defined by \code{ranges}. +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' l_mm <- metamodel(analysis = "oneway", psa = l_psa, +#' params = c("pFailChemo", "cChemo"), outcome = "eff") +#' +#' # predictions over the middle 95\% of the PSA samples of each parameter +#' head(predict(l_mm, nsamp = 10)) +#' +#' # predictions over a range given for one parameter +#' predict(l_mm, ranges = list("pFailChemo" = c(0.3, 0.6)), nsamp = 4) #' @export predict.metamodel <- function(object, ranges = NULL, nsamp = 100, ...) { diff --git a/R/owsa.R b/R/owsa.R index 42c1bc1..66967ed 100644 --- a/R/owsa.R +++ b/R/owsa.R @@ -16,6 +16,24 @@ #' @return An object of class \code{data.frame} and \code{owsa} with the results of the sensitivity analysis. #' Can be visualized with \code{\link{plot.owsa}, \link{owsa_tornado}, and \link{owsa_opt_strat}} #' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # metamodel predictions of the net monetary benefit as each parameter varies +#' df_owsa <- owsa(l_psa, params = c("pFailChemo", "pFailSurg", "cChemo"), +#' outcome = "nmb", wtp = 1e5) +#' head(df_owsa) +#' plot(df_owsa) +#' +#' # parameter ranges can be given, and only some strategies kept +#' df_owsa_chemo <- owsa(l_psa, params = "pFailChemo", ranges = list(pFailChemo = c(0.3, 0.5)), +#' outcome = "nmb", wtp = 1e5, strategies = c("Chemo", "Surgery")) +#' plot(df_owsa_chemo) +#' #' @export owsa <- function(sa_obj, params = NULL, ranges = NULL, nsamp = 100, outcome = c("eff", "cost", "nhb", "nmb", "nhb_loss", "nmb_loss"), @@ -100,6 +118,18 @@ owsa <- function(sa_obj, params = NULL, ranges = NULL, nsamp = 100, #' #' @return A \code{ggplot2} plot of the \code{owsa} object. #' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_owsa <- owsa(l_psa, params = c("pFailChemo", "pFailSurg"), outcome = "nmb", wtp = 1e5) +#' plot(df_owsa) +#' +#' # highlight a base case value of each parameter (here, close to its PSA mean), in black and white +#' plot(df_owsa, basecase = list(pFailChemo = 0.45, pFailSurg = 0.05), col = "bw") +#' #' @import ggplot2 #' @importFrom tidyr pivot_longer #' @export @@ -191,6 +221,22 @@ plot.owsa <- function(x, txtsize = 12, #' object, or if \code{return == "data"}, a \code{data.frame} containing all data contained in the plot. #' A tornado plot is a visual aid used to identify which parameters are driving most of the variation #' in a specified model outcome. +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_owsa <- owsa(l_psa, outcome = "nmb", wtp = 1e5) +#' +#' # parameters driving the net monetary benefit of Chemo +#' owsa_tornado(df_owsa, select_str = "Chemo", outcome_name = "NMB") +#' +#' # and the difference in net monetary benefit between Surgery and Chemo +#' owsa_tornado(df_owsa, select_str = c("Chemo", "Surgery"), outcome_name = "NMB") +#' +#' # the data behind the plot +#' owsa_tornado(df_owsa, return = "data", select_str = "Chemo") #' @importFrom stats median reorder #' @import ggplot2 #' @export @@ -332,6 +378,21 @@ offset_trans <- function(offset = 0) { #' object, or if \code{return == "data"}, a \code{data.frame} containing all data contained in the plot. #' The plot allows us to see how the strategy that maximizes the expectation of the outcome of interest #' changes as a function of each parameter of interest. +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_owsa <- owsa(l_psa, params = c("pFailChemo", "pFailSurg", "cChemo"), +#' outcome = "nmb", wtp = 1e5) +#' owsa_opt_strat(df_owsa) +#' +#' # only the parameters that change the optimal strategy +#' owsa_opt_strat(df_owsa, plot_const = FALSE) +#' +#' # the ranges of each parameter over which each strategy is optimal +#' owsa_opt_strat(df_owsa, return = "data") #' @import ggplot2 #' @export owsa_opt_strat <- function(owsa, params = NULL, maximize = TRUE, diff --git a/R/psa.R b/R/psa.R index 4bfc556..5c4b854 100644 --- a/R/psa.R +++ b/R/psa.R @@ -85,7 +85,7 @@ make_psa_obj <- function(cost, effectiveness, parameters = NULL, check_psa_object <- function(psa) { if (!inherits(psa, "psa")) { stop(paste0("The psa results parameter must be an object of class `psa`.\n", - "Please run the make_psa() function to create this object.")) + "Please run the make_psa_obj() function to create this object.")) } } @@ -125,6 +125,27 @@ check_df_and_coerce <- function(obj) { #' With \code{wtp}, \code{meanNMB} (\code{wtp * effect - cost}, averaged over samples) is added; with #' \code{ref_str} too, also \code{meanIncNMB} and \code{propCostEffective}, the proportion of samples in #' which the strategy has a higher NMB than the reference (it lies below the willingness-to-pay line). +#' +#' @seealso \code{\link{make_psa_obj}}, \code{\link{calculate_icers}} +#' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # mean cost and effectiveness of each strategy, with their standard deviations +#' summary(l_psa, calc_sds = TRUE) +#' +#' # compare every strategy with Radio, sample by sample, at a WTP of 100,000 +#' summary(l_psa, ref_str = "Radio", wtp = 1e5) +#' +#' # the means can be passed to calculate_icers() +#' df_psa_sum <- summary(l_psa) +#' calculate_icers(cost = df_psa_sum$meanCost, +#' effect = df_psa_sum$meanEffect, +#' strategies = df_psa_sum$Strategy) #' @export summary.psa <- function(object, calc_sds = FALSE, ref_str = NULL, wtp = NULL, ...) { ref_str <- check_ref_str(ref_str, object$strategies) @@ -201,6 +222,20 @@ summary.psa <- function(object, calc_sds = FALSE, ref_str = NULL, wtp = NULL, .. #' @importFrom scales dollar_format #' @return A \code{ggplot2} plot of the PSA, showing the distribution of each PSA sample and strategy #' on the cost-effectiveness plane. +#' @seealso \code{\link{make_psa_obj}} +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' plot(l_psa) +#' +#' # incremental cost-effectiveness plane with Radio at the origin and a WTP line +#' plot(l_psa, ref_str = "Radio", wtp = 1e5) +#' +#' # without ellipses, in black and white +#' plot(l_psa, ellipse = FALSE, col = "bw") #' @importFrom tidyr pivot_longer #' @importFrom stats cor #' @export diff --git a/R/run_dsa.R b/R/run_dsa.R index 655721c..a96aa03 100644 --- a/R/run_dsa.R +++ b/R/run_dsa.R @@ -38,6 +38,54 @@ #' \item "min" and "max" are the minimum and maximum values of the parameters of interest.} #' } #' +#' @seealso \code{\link{plot.owsa}}, \code{\link{owsa_tornado}}, \code{\link{owsa_opt_strat}}, +#' \code{\link{run_twsa_det}} +#' +#' @examples +#' # A tiny decision model. Treatment fails with probability p_fail under standard care +#' # and with half that probability under the new treatment, which costs c_trt. A failure +#' # costs 20,000 and loses 2 QALYs. FUN takes a named list of parameters and returns a data +#' # frame with the strategy names in its first column and one column per outcome. +#' f_model <- function(l_params, wtp = 5e4) { +#' v_p_fail <- l_params$p_fail * c(1, 0.5) +#' v_cost <- c(0, l_params$c_trt) + 20000 * v_p_fail +#' v_qaly <- 10 - 2 * v_p_fail +#' data.frame(Strategy = c("Standard", "New"), +#' Cost = v_cost, +#' QALY = v_qaly, +#' NMB = wtp * v_qaly - v_cost) +#' } +#' l_params_basecase <- list(p_fail = 0.3, c_trt = 15000) +#' f_model(l_params_basecase) +#' +#' # vary each parameter over its range, one at a time +#' df_params_range <- data.frame(pars = c("p_fail", "c_trt"), +#' min = c(0.1, 5000), +#' max = c(0.5, 25000)) +#' df_owsa_nmb <- run_owsa_det(params_range = df_params_range, +#' params_basecase = l_params_basecase, +#' nsamp = 20, +#' FUN = f_model, +#' outcomes = "NMB", +#' strategies = c("Standard", "New"), +#' progress = FALSE) +#' plot(df_owsa_nmb) +#' owsa_tornado(df_owsa_nmb, select_str = c("Standard", "New"), outcome_name = "NMB") +#' owsa_opt_strat(df_owsa_nmb) +#' +#' # with more than one outcome, a list with one owsa object per outcome is returned, +#' # and arguments of FUN other than l_params are passed through ... +#' l_owsa <- run_owsa_det(params_range = df_params_range, +#' params_basecase = l_params_basecase, +#' nsamp = 20, +#' FUN = f_model, +#' outcomes = c("Cost", "NMB"), +#' strategies = c("Standard", "New"), +#' progress = FALSE, +#' wtp = 1e5) +#' names(l_owsa) +#' owsa_opt_strat(l_owsa$owsa_NMB) +#' #' @importFrom utils txtProgressBar #' @export run_owsa_det <- function(params_range, params_basecase, nsamp = 100, FUN, @@ -204,6 +252,39 @@ run_owsa_det <- function(params_range, params_basecase, nsamp = 100, FUN, #' \item "min" and "max" are the minimum and maximum values of the parameters of interest.} #' } #' +#' @seealso \code{\link{plot.twsa}}, \code{\link{run_owsa_det}} +#' +#' @examples +#' # A tiny decision model. Treatment fails with probability p_fail under standard care +#' # and with half that probability under the new treatment, which costs c_trt. A failure +#' # costs 20,000 and loses 2 QALYs. FUN takes a named list of parameters and returns a data +#' # frame with the strategy names in its first column and one column per outcome. +#' f_model <- function(l_params, wtp = 5e4) { +#' v_p_fail <- l_params$p_fail * c(1, 0.5) +#' v_cost <- c(0, l_params$c_trt) + 20000 * v_p_fail +#' v_qaly <- 10 - 2 * v_p_fail +#' data.frame(Strategy = c("Standard", "New"), +#' Cost = v_cost, +#' QALY = v_qaly, +#' NMB = wtp * v_qaly - v_cost) +#' } +#' l_params_basecase <- list(p_fail = 0.3, c_trt = 15000) +#' f_model(l_params_basecase) +#' +#' # vary both parameters together over a 20 x 20 grid +#' df_params_range <- data.frame(pars = c("p_fail", "c_trt"), +#' min = c(0.1, 5000), +#' max = c(0.5, 25000)) +#' df_twsa_nmb <- run_twsa_det(params_range = df_params_range, +#' params_basecase = l_params_basecase, +#' nsamp = 20, +#' FUN = f_model, +#' outcomes = "NMB", +#' strategies = c("Standard", "New"), +#' progress = FALSE) +#' head(df_twsa_nmb) +#' plot(df_twsa_nmb, basecase = l_params_basecase) +#' #' @importFrom utils txtProgressBar #' @export run_twsa_det <- function(params_range, params_basecase, nsamp = 40, FUN, outcomes = NULL, diff --git a/R/run_psa.R b/R/run_psa.R index 0bc600e..88ea284 100644 --- a/R/run_psa.R +++ b/R/run_psa.R @@ -24,7 +24,49 @@ #' @seealso #' \code{\link{run_psa}}, #' \code{\link{make_psa_obj}}, -#' \code{\link{gen_psa_samp}}, +#' \code{\link{gen_psa_samp}} +#' +#' @examples +#' # A tiny decision model. Treatment fails with probability p_fail under standard care +#' # and with half that probability under the new treatment, which costs c_trt. A failure +#' # costs 20,000 and loses 2 QALYs. FUN takes a named list of parameters and returns a data +#' # frame with the strategy names in its first column and one column per outcome. +#' f_model <- function(l_params, wtp = 5e4) { +#' v_p_fail <- l_params$p_fail * c(1, 0.5) +#' v_cost <- c(0, l_params$c_trt) + 20000 * v_p_fail +#' v_qaly <- 10 - 2 * v_p_fail +#' data.frame(Strategy = c("Standard", "New"), +#' Cost = v_cost, +#' QALY = v_qaly, +#' NMB = wtp * v_qaly - v_cost) +#' } +#' l_params_basecase <- list(p_fail = 0.3, c_trt = 15000) +#' f_model(l_params_basecase) +#' +#' # 100 PSA samples of the two parameters +#' set.seed(2026) +#' df_psa_samp <- gen_psa_samp(params = c("p_fail", "c_trt"), +#' dists = c("beta", "gamma"), +#' parameterization_types = c("mean, sd", "mean, sd"), +#' dists_params = list(c(0.3, 0.05), c(15000, 3000)), +#' nsamp = 100) +#' +#' # run the model on every sample: a list with one psa object per outcome +#' l_psa_out <- run_psa(psa_samp = df_psa_samp, +#' params_basecase = l_params_basecase, +#' FUN = f_model, +#' outcomes = c("Cost", "QALY"), +#' strategies = c("Standard", "New"), +#' progress = FALSE) +#' names(l_psa_out) +#' +#' # combine the cost and QALY outcomes into one psa object for cost-effectiveness analysis +#' l_psa <- make_psa_obj(cost = l_psa_out$Cost$other_outcome, +#' effectiveness = l_psa_out$QALY$other_outcome, +#' parameters = l_psa_out$Cost$parameters, +#' strategies = l_psa_out$Cost$strategies) +#' plot(l_psa) +#' calculate_icers_psa(l_psa) #' @export run_psa <- function(psa_samp, params_basecase = NULL, FUN, outcomes = NULL, strategies = NULL, currency = "$", progress = TRUE, ...) { diff --git a/R/twsa.R b/R/twsa.R index 1227b54..f2d6708 100644 --- a/R/twsa.R +++ b/R/twsa.R @@ -6,7 +6,7 @@ #' #' @param sa_obj sensitivity analysis object; #' either a probabilistic sensitivity analysis (\code{\link{make_psa_obj}}) or -#' a deterministic sensitivity analysis object (\code{\link{run_owsa_det}}) +#' a two-way deterministic sensitivity analysis object (\code{\link{create_dsa_twoway}}) #' #' @param param1 String with the name of the first parameter of interest #' @param param2 String with the name of the second parameter of interest @@ -14,8 +14,23 @@ #' @inheritParams metamodel #' @inheritParams predict.metamodel #' -#' @return twsa A \code{ggplot2} object with the TWSA graph of \code{param1} and -#' \code{param2} on the outcome of interest. +#' @return A \code{data.frame} of class \code{twsa} with the outcome of each strategy over a grid of +#' values of \code{param1} and \code{param2}. It can be visualized with \code{\link{plot.twsa}}. +#' +#' @seealso \code{\link{plot.twsa}}, \code{\link{run_twsa_det}} +#' +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' +#' # strategy with the highest predicted net monetary benefit as two parameters vary +#' df_twsa <- twsa(l_psa, param1 = "pFailChemo", param2 = "muDieCancer", +#' outcome = "nmb", wtp = 1e5) +#' head(df_twsa) +#' plot(df_twsa) #' #' @export twsa <- function(sa_obj, param1 = NULL, param2 = NULL, ranges = NULL, @@ -91,6 +106,22 @@ twsa <- function(sa_obj, param1 = NULL, param2 = NULL, ranges = NULL, #' @importFrom rlang !! #' @importFrom rlang sym #' @return A \code{ggplot2} plot of the two-way sensitivity analysis. +#' @examples +#' data("cancer_psa_data") +#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost, +#' effectiveness = cancer_psa_data$effectiveness, +#' parameters = cancer_psa_data$parameters, +#' strategies = cancer_psa_data$strategies) +#' df_twsa <- twsa(l_psa, param1 = "pFailChemo", param2 = "muDieCancer", +#' outcome = "nmb", wtp = 1e5) +#' plot(df_twsa) +#' +#' # mark a base case (here, close to the PSA means), in black and white +#' plot(df_twsa, basecase = list(pFailChemo = 0.45, muDieCancer = 0.2), col = "bw") +#' +#' # the strategy with the lowest expected cost +#' df_twsa_cost <- twsa(l_psa, param1 = "pFailChemo", param2 = "muDieCancer", outcome = "cost") +#' plot(df_twsa_cost, maximize = FALSE) #' @export plot.twsa <- function(x, maximize = TRUE, col = c("access", "full", "bw"), diff --git a/man/beta_params.Rd b/man/beta_params.Rd index dd65f7c..1fb3fa5 100644 --- a/man/beta_params.Rd +++ b/man/beta_params.Rd @@ -32,8 +32,14 @@ and \deqn{\beta = \alpha (\frac{1}{\mu} -1)} } -\keyword{beta} -\keyword{distribution;} -\keyword{methods} -\keyword{moments} -\keyword{of} +\examples{ +# a probability with a mean of 0.2 and a standard error of 0.05 +l_beta <- beta_params(mean = 0.2, sigma = 0.05) +l_beta + +# the mean of the resulting beta distribution recovers the input mean +l_beta$alpha / (l_beta$alpha + l_beta$beta) +} +\concept{beta distribution} +\concept{method of moments} +\keyword{distribution} diff --git a/man/calc_evpi.Rd b/man/calc_evpi.Rd index 0b527ec..bdab81f 100644 --- a/man/calc_evpi.Rd +++ b/man/calc_evpi.Rd @@ -48,11 +48,5 @@ plot(evpi) + ggtitle("Expected Value of Perfect Information") \seealso{ \code{\link{plot.evpi}}, \code{\link{make_psa_obj}} } -\keyword{benefit} -\keyword{expected} -\keyword{information;} -\keyword{monetary} -\keyword{net} -\keyword{of} -\keyword{perfect} -\keyword{value} +\concept{expected value of perfect information} +\concept{net monetary benefit} diff --git a/man/calc_evppi.Rd b/man/calc_evppi.Rd index 6bdebb9..ccec9b9 100644 --- a/man/calc_evppi.Rd +++ b/man/calc_evppi.Rd @@ -79,6 +79,24 @@ and applying the following equation: \deqn{EVPPI_{\theta_I} = \frac{1}{K}\sum_{i=1}^{K}\max_d(\hat{L}_d)} The spline model in step 3 is fitted using the `mgcv` package. } +} +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# EVPPI of the two treatment-failure probabilities, jointly, at three WTP thresholds +l_evppi <- calc_evppi(l_psa, + wtp = c(5e4, 1e5, 2e5), + params = c("pFailChemo", "pFailSurg"), + outcome = "nmb", + k = 3, + progress = FALSE) +l_evppi$df_evppi +plot(l_evppi) + } \references{ \enumerate{ @@ -90,3 +108,6 @@ Analysis Sample: A Nonparametric Regression Approach. Med Decis Making. 2014;34(3):311–26. } } +\seealso{ +\code{\link{plot.evppi}}, \code{\link{calc_evpi}}, \code{\link{calc_evsi}} +} diff --git a/man/calc_evsi.Rd b/man/calc_evsi.Rd index 4277572..fe366a2 100644 --- a/man/calc_evsi.Rd +++ b/man/calc_evsi.Rd @@ -56,3 +56,51 @@ strategy at each willingness to pay threshold. \description{ Calculate Expected Value of Sample Information (EVSI) } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# EVSI of a study of n additional patients that informs both failure probabilities, +# which were each estimated from an initial study of n0 = 50 patients +l_evsi <- calc_evsi(l_psa, + wtp = 1e5, + params = c("pFailSurg", "pFailChemo"), + outcome = "nmb", + k = 3, + n = c(10, 50, 100, 200), + n0 = 50, + progress = FALSE) +l_evsi$df_evsi +plot(l_evsi) + +\donttest{ +# a separate initial and additional sample size for each parameter +l_evsi_by_param <- calc_evsi(l_psa, + wtp = c(5e4, 1e5, 2e5), + params = c("pFailSurg", "pFailChemo"), + outcome = "nmb", + k = 3, + n = c(100, 50), + n0 = c(50, 20), + n_by_param = TRUE, + progress = FALSE) +l_evsi_by_param$df_evsi +} + +} +\references{ +\enumerate{ +\item Jalal H, Alarid-Escudero F. A Gaussian Approximation Approach for Value of +Information Analysis. Med Decis Making. 2018;38(2):174-188. +\doi{10.1177/0272989X17715627} +\item Strong M, Oakley JE, Brennan A. Estimating Multiparameter Partial Expected Value +of Perfect Information from a Probabilistic Sensitivity Analysis Sample: A Nonparametric +Regression Approach. Med Decis Making. 2014;34(3):311-326. \doi{10.1177/0272989X13505910} +} +} +\seealso{ +\code{\link{plot.evsi}}, \code{\link{calc_evppi}} +} diff --git a/man/calculate_icers_psa.Rd b/man/calculate_icers_psa.Rd index 3766cea..1757c04 100644 --- a/man/calculate_icers_psa.Rd +++ b/man/calculate_icers_psa.Rd @@ -13,7 +13,7 @@ calculate_icers_psa( ) } \arguments{ -\item{psa}{\code{psa} object from \code{link{make_psa_object}}} +\item{psa}{\code{psa} object from \code{\link{make_psa_obj}}} \item{uncertainty}{whether or not 95\% quantiles for the cost and QALY outcomes should be included in the resulting ICER table. Defaults to \code{FALSE}.} @@ -53,9 +53,29 @@ quantiles for each strategy's cost and QALY outcomes based on the variation pres Because the dominated vs. non-dominated status and the ordering of strategies in the ICER table are liable to change across different samples of the PSA, confidence intervals are not provided for the incremental costs and QALYs along the cost-effectiveness acceptability frontier. -\code{link{plot.psa}} does not show the confidence intervals in the resulting plot +\code{\link{plot.icers}} does not show the confidence intervals in the resulting plot even if present in the ICER table. } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# ICERs from the mean cost and effectiveness of each strategy +df_icers <- calculate_icers_psa(l_psa) +df_icers +plot(df_icers) + +# add the 2.5th and 97.5th percentiles of the cost and effectiveness of each strategy +df_icers_unc <- calculate_icers_psa(l_psa, uncertainty = TRUE) +df_icers_unc + +# compare every strategy with Radio, adding the net monetary benefit at a WTP of 100,000 +df_icers_ref <- calculate_icers_psa(l_psa, ref_str = "Radio", wtp = 1e5) +print(df_icers_ref, ref = "reference") +} \seealso{ \code{\link{plot.icers}} diff --git a/man/ceac.Rd b/man/ceac.Rd index 2662651..af15b76 100644 --- a/man/ceac.Rd +++ b/man/ceac.Rd @@ -65,6 +65,4 @@ summary(ceac_obj) \seealso{ \code{\link{plot.ceac}}, \code{\link{summary.ceac}} } -\keyword{acceptability} -\keyword{cost-effectiveness} -\keyword{curves} +\concept{cost-effectiveness acceptability curves} diff --git a/man/create_dsa_oneway.Rd b/man/create_dsa_oneway.Rd index e58dc2a..0dff24a 100644 --- a/man/create_dsa_oneway.Rd +++ b/man/create_dsa_oneway.Rd @@ -50,3 +50,33 @@ The object returned by this function can be passed to \code{\link{owsa}} to do a one-way sensitivity analysis on each parameter of interest. } +\examples{ +# Outcomes of two strategies, evaluated at 5 values of the failure probability p_fail +# (with c_trt at its base case of 15,000) and at 5 values of the cost of the new +# treatment c_trt (with p_fail at its base case of 0.3) +v_p_fail <- seq(0.1, 0.5, length.out = 5) +v_c_trt <- seq(5000, 25000, length.out = 5) +df_params <- data.frame(parameter = rep(c("p_fail", "c_trt"), each = 5), + value = c(v_p_fail, v_c_trt)) +v_p_fail_all <- c(v_p_fail, rep(0.3, 5)) +v_c_trt_all <- c(rep(15000, 5), v_c_trt) +df_cost <- data.frame(Standard = 20000 * v_p_fail_all, + New = v_c_trt_all + 10000 * v_p_fail_all) +df_effect <- data.frame(Standard = 10 - 2 * v_p_fail_all, + New = 10 - v_p_fail_all) + +l_dsa <- create_dsa_oneway(parameters = df_params, + effectiveness = df_effect, + strategies = c("Standard", "New"), + cost = df_cost) +l_dsa + +# one-way sensitivity analysis of the net monetary benefit at a WTP of 50,000 +df_owsa <- owsa(l_dsa, outcome = "nmb", wtp = 5e4) +plot(df_owsa) +owsa_opt_strat(df_owsa) +} +\seealso{ +\code{\link{run_owsa_det}}, which runs a model function over the parameter ranges, +builds this object internally, and returns the result of \code{\link{owsa}}. +} diff --git a/man/create_dsa_twoway.Rd b/man/create_dsa_twoway.Rd index 9b758d1..5b4be27 100644 --- a/man/create_dsa_twoway.Rd +++ b/man/create_dsa_twoway.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/dsa_twoway.R \name{create_dsa_twoway} \alias{create_dsa_twoway} -\title{Create one-way deterministic sensitivity analysis object} +\title{Create two-way deterministic sensitivity analysis object} \usage{ create_dsa_twoway( parameters, @@ -46,6 +46,30 @@ to visualize the two-way sensitivity analysis contained in the object. } \description{ The object returned by this function can be passed to -\code{\link{owsa}} to do a one-way sensitivity analysis on each -parameter of interest. +\code{\link{twsa}} to do a two-way sensitivity analysis on the two +parameters of interest. +} +\examples{ +# Outcomes of two strategies on a 5 x 5 grid of the failure probability p_fail and +# the cost of the new treatment c_trt +df_params <- expand.grid(p_fail = seq(0.1, 0.5, length.out = 5), + c_trt = seq(5000, 25000, length.out = 5)) +df_cost <- data.frame(Standard = 20000 * df_params$p_fail, + New = df_params$c_trt + 10000 * df_params$p_fail) +df_effect <- data.frame(Standard = 10 - 2 * df_params$p_fail, + New = 10 - df_params$p_fail) + +l_dsa <- create_dsa_twoway(parameters = df_params, + effectiveness = df_effect, + strategies = c("Standard", "New"), + cost = df_cost) +l_dsa + +# strategy with the highest net monetary benefit at a WTP of 50,000 +df_twsa <- twsa(l_dsa, outcome = "nmb", wtp = 5e4) +plot(df_twsa) +} +\seealso{ +\code{\link{run_twsa_det}}, which runs a model function over the parameter ranges, +builds this object internally, and returns the result of \code{\link{twsa}}. } diff --git a/man/df_example_psa_elc.Rd b/man/df_example_psa_elc.Rd index 82fd9b4..15d779d 100644 --- a/man/df_example_psa_elc.Rd +++ b/man/df_example_psa_elc.Rd @@ -60,7 +60,7 @@ l_psa <- make_psa_obj(cost = df_example_psa_elc[, 1:6], effectiveness = df_example_psa_elc[, 7:12]) # the frontier switches three times, so the summary has four intervals -df_ceac <- ceac(wtp = seq(1000, 150000, 1000), psa = l_psa) +df_ceac <- ceac(l_psa, wtp = seq(1000, 150000, 1000)) summary(df_ceac) # the strategy most likely to be cost effective is not necessarily the one diff --git a/man/dirichlet_params.Rd b/man/dirichlet_params.Rd index cc33356..f170fef 100644 --- a/man/dirichlet_params.Rd +++ b/man/dirichlet_params.Rd @@ -45,8 +45,6 @@ Dec Sci. 1975;6(1):1–13. distribution. Comput Math with Appl. 1992;24(10):11–7. } } -\keyword{dirichlet} -\keyword{distribution;} -\keyword{method} -\keyword{moments} -\keyword{of} +\concept{Dirichlet distribution} +\concept{method of moments} +\keyword{distribution} diff --git a/man/gamma_params.Rd b/man/gamma_params.Rd index 999a777..20bd35a 100644 --- a/man/gamma_params.Rd +++ b/man/gamma_params.Rd @@ -56,8 +56,6 @@ Encyclopedia. Retrieved 17:23, February 11, 2018, from https://en.wikipedia.org/w/index.php?title=Gamma_distribution&oldid=824541785 } } -\keyword{distribution;} -\keyword{gamma} -\keyword{method} -\keyword{moments} -\keyword{of} +\concept{gamma distribution} +\concept{method of moments} +\keyword{distribution} diff --git a/man/lnorm_params.Rd b/man/lnorm_params.Rd index 7c8527f..b2b74f8 100644 --- a/man/lnorm_params.Rd +++ b/man/lnorm_params.Rd @@ -39,8 +39,11 @@ and \examples{ m <- 3 v <- 0.01 -lnorm_params(m, v) -# True values: 100, 30, 70 +l_lnorm <- lnorm_params(m, v) +l_lnorm + +# the mean of the resulting log-normal distribution recovers m +exp(l_lnorm$mu + l_lnorm$sigma^2 / 2) } \references{ \enumerate{ @@ -51,8 +54,6 @@ Encyclopedia. Retrieved 16:47, April 23, 2017, from https://en.wikipedia.org/w/index.php?title=Log-normal_distribution&oldid=776357974 } } -\keyword{distribution;} -\keyword{log-normal} -\keyword{method} -\keyword{moments} -\keyword{of} +\concept{log-normal distribution} +\concept{method of moments} +\keyword{distribution} diff --git a/man/metamodel.Rd b/man/metamodel.Rd index c1ec53b..428e275 100644 --- a/man/metamodel.Rd +++ b/man/metamodel.Rd @@ -60,6 +60,26 @@ for each combination of the parameters in \code{params} and strategies in \code{ If \code{analysis == "twoway"}, \code{params} must be a vector of two parameters, and a metamodel is created with these two parameters for each strategy in \code{strategies}. +} +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# one linear metamodel of the effectiveness per parameter and strategy +l_mm <- metamodel(analysis = "oneway", psa = l_psa, + params = c("pFailChemo", "cChemo"), outcome = "eff") +l_mm +summary(l_mm) + +# a two-way polynomial metamodel of the net monetary benefit of Chemo +l_mm_twoway <- metamodel(analysis = "twoway", psa = l_psa, + params = c("pFailChemo", "cChemo"), strategies = "Chemo", + outcome = "nmb", wtp = 1e5, type = "poly", poly.order = 2) +head(predict(l_mm_twoway, nsamp = 5)) + } \seealso{ \code{\link{predict.metamodel}}, diff --git a/man/number_ticks.Rd b/man/number_ticks.Rd index b859b53..c2c3974 100644 --- a/man/number_ticks.Rd +++ b/man/number_ticks.Rd @@ -11,7 +11,7 @@ number_ticks(n) \code{ggplot2} plots. Non-integer values are rounded down.} } \value{ -a vector of axis-label breaks +a function that takes the axis limits and returns a vector of axis-label breaks } \description{ Function for determining number of ticks on axis of \code{ggplot2} plots. @@ -21,3 +21,15 @@ Function for determining number of ticks on axis of \code{ggplot2} plots. Based on function \code{pretty}. } +\examples{ +# number_ticks() returns a function of the axis limits +f_breaks <- number_ticks(5) +f_breaks(c(0, 97)) + +# use it for the breaks of a ggplot2 axis +data("hund_strat") +ggplot(hund_strat, aes(x = QALYs, y = Cost)) + + geom_point() + + scale_x_continuous(breaks = number_ticks(4)) + + scale_y_continuous(breaks = number_ticks(8)) +} diff --git a/man/owsa.Rd b/man/owsa.Rd index ea18fec..82f34f5 100644 --- a/man/owsa.Rd +++ b/man/owsa.Rd @@ -53,3 +53,22 @@ as a function of the input parameter of interest. In the DSA context, this funct internally by \code{\link{run_owsa_det}} and should not be called by the user. In the PSA context, the user must use this function to produce an \code{owsa} object. } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# metamodel predictions of the net monetary benefit as each parameter varies +df_owsa <- owsa(l_psa, params = c("pFailChemo", "pFailSurg", "cChemo"), + outcome = "nmb", wtp = 1e5) +head(df_owsa) +plot(df_owsa) + +# parameter ranges can be given, and only some strategies kept +df_owsa_chemo <- owsa(l_psa, params = "pFailChemo", ranges = list(pFailChemo = c(0.3, 0.5)), + outcome = "nmb", wtp = 1e5, strategies = c("Chemo", "Surgery")) +plot(df_owsa_chemo) + +} diff --git a/man/owsa_opt_strat.Rd b/man/owsa_opt_strat.Rd index 9ee511d..666cca6 100644 --- a/man/owsa_opt_strat.Rd +++ b/man/owsa_opt_strat.Rd @@ -61,3 +61,19 @@ changes as a function of each parameter of interest. \description{ plot the optimal strategy as the parameter values change } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_owsa <- owsa(l_psa, params = c("pFailChemo", "pFailSurg", "cChemo"), + outcome = "nmb", wtp = 1e5) +owsa_opt_strat(df_owsa) + +# only the parameters that change the optimal strategy +owsa_opt_strat(df_owsa, plot_const = FALSE) + +# the ranges of each parameter over which each strategy is optimal +owsa_opt_strat(df_owsa, return = "data") +} diff --git a/man/owsa_tornado.Rd b/man/owsa_tornado.Rd index a9aa655..6486609 100644 --- a/man/owsa_tornado.Rd +++ b/man/owsa_tornado.Rd @@ -55,3 +55,20 @@ in a specified model outcome. \description{ Tornado plot of a one-way sensitivity analysis } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_owsa <- owsa(l_psa, outcome = "nmb", wtp = 1e5) + +# parameters driving the net monetary benefit of Chemo +owsa_tornado(df_owsa, select_str = "Chemo", outcome_name = "NMB") + +# and the difference in net monetary benefit between Surgery and Chemo +owsa_tornado(df_owsa, select_str = c("Chemo", "Surgery"), outcome_name = "NMB") + +# the data behind the plot +owsa_tornado(df_owsa, return = "data", select_str = "Chemo") +} diff --git a/man/plot.ceac.Rd b/man/plot.ceac.Rd index 1b648e8..8306741 100644 --- a/man/plot.ceac.Rd +++ b/man/plot.ceac.Rd @@ -73,4 +73,19 @@ Plots the CEAC, using the object created by \code{\link{ceac}}. \code{ceac} computes the probability of each of the strategies being cost-effective at each \code{wtp} value. } -\keyword{internal} +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_ceac <- ceac(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) +plot(df_ceac) + +# without the frontier, and with fewer x-axis ticks +plot(df_ceac, frontier = FALSE, n_x_ticks = 5) + +} +\seealso{ +\code{\link{ceac}}, \code{\link{summary.ceac}} +} diff --git a/man/plot.evpi.Rd b/man/plot.evpi.Rd index 49fc72d..ee0a987 100644 --- a/man/plot.evpi.Rd +++ b/man/plot.evpi.Rd @@ -55,11 +55,19 @@ A \code{ggplot2} plot with the EVPI \description{ Plots the \code{evpi} object created by \code{\link{calc_evpi}}. } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_evpi <- calc_evpi(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) +plot(df_evpi) + +# change the labels and the number of axis ticks +plot(df_evpi, currency = "USD", effect_units = "life-years", n_x_ticks = 5) +} \seealso{ \code{\link{calc_evpi}} } -\keyword{expected} -\keyword{information} -\keyword{of} -\keyword{perfect} -\keyword{value} +\concept{expected value of perfect information} diff --git a/man/plot.evppi.Rd b/man/plot.evppi.Rd index 5584a62..78acc13 100644 --- a/man/plot.evppi.Rd +++ b/man/plot.evppi.Rd @@ -55,11 +55,20 @@ A \code{ggplot2} plot with the EVPPI \description{ Plots the \code{evppi} object created by \code{\link{calc_evppi}}. } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +l_evppi <- calc_evppi(l_psa, wtp = c(5e4, 1e5, 2e5), params = "pFailChemo", + progress = FALSE) +plot(l_evppi) + +# ggplot2 layers can be added to the plot +plot(l_evppi, n_x_ticks = 5) + ggtitle("EVPPI of pFailChemo") +} \seealso{ \code{\link{calc_evppi}} } -\keyword{expected} -\keyword{information} -\keyword{of} -\keyword{perfect} -\keyword{value} +\concept{expected value of partial perfect information} diff --git a/man/plot.evsi.Rd b/man/plot.evsi.Rd index 0954135..fb6898e 100644 --- a/man/plot.evsi.Rd +++ b/man/plot.evsi.Rd @@ -63,11 +63,26 @@ as a function of each willingness-to-pay threshold, depending upon the usage of \code{\link{calc_evsi}} used to create the \code{evsi} object. } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# one WTP threshold and several sample sizes: EVSI by additional sample size +l_evsi <- calc_evsi(l_psa, wtp = 1e5, params = "pFailSurg", outcome = "nmb", + n = c(10, 50, 100, 200), n0 = 50, progress = FALSE) +plot(l_evsi) + +\donttest{ +# several WTP thresholds and one sample size: EVSI by WTP threshold +l_evsi_wtp <- calc_evsi(l_psa, wtp = c(5e4, 1e5, 2e5), params = "pFailSurg", + outcome = "nmb", n = 100, n0 = 50, progress = FALSE) +plot(l_evsi_wtp) +} +} \seealso{ \code{\link{calc_evsi}} } -\keyword{expected} -\keyword{information} -\keyword{of} -\keyword{sample} -\keyword{value} +\concept{expected value of sample information} diff --git a/man/plot.exp_loss.Rd b/man/plot.exp_loss.Rd index 29f21d7..7933f82 100644 --- a/man/plot.exp_loss.Rd +++ b/man/plot.exp_loss.Rd @@ -74,3 +74,18 @@ A \code{ggplot2} object with the expected loss \description{ Plot of Expected Loss Curves (ELC) } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_exp_loss <- calc_exp_loss(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) +plot(df_exp_loss) + +# linear y axis, without the points or the frontier +plot(df_exp_loss, log_y = FALSE, points = FALSE, frontier = FALSE) +} +\seealso{ +\code{\link{calc_exp_loss}} +} diff --git a/man/plot.icers.Rd b/man/plot.icers.Rd index af2dfdd..a9de7de 100644 --- a/man/plot.icers.Rd +++ b/man/plot.icers.Rd @@ -94,3 +94,22 @@ a ggplot2 object which can be modified by adding additional geoms \description{ Plots the cost-effectiveness plane for a ICER object, calculated with \code{\link{calculate_icers}} } +\examples{ +data("psa_cdiff") +df_cdiff <- summary(psa_cdiff) +df_icers <- calculate_icers(cost = df_cdiff$meanCost, + effect = df_cdiff$meanEffect, + strategies = df_cdiff$Strategy) +plot(df_icers) + +# label every strategy, or show only the efficient frontier +plot(df_icers, label = "all") +plot(df_icers, plot_frontier_only = TRUE) + +# incremental cost-effectiveness plane with s3 at the origin and a WTP line +plot(df_icers, ref_str = "s3", wtp = 1e5) + +} +\seealso{ +\code{\link{calculate_icers}}, \code{\link{calculate_icers_psa}} +} diff --git a/man/plot.owsa.Rd b/man/plot.owsa.Rd index 1645918..9217861 100644 --- a/man/plot.owsa.Rd +++ b/man/plot.owsa.Rd @@ -62,3 +62,16 @@ A \code{ggplot2} plot of the \code{owsa} object. \description{ Plot a sensitivity analysis } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_owsa <- owsa(l_psa, params = c("pFailChemo", "pFailSurg"), outcome = "nmb", wtp = 1e5) +plot(df_owsa) + +# highlight a base case value of each parameter (here, close to its PSA mean), in black and white +plot(df_owsa, basecase = list(pFailChemo = 0.45, pFailSurg = 0.05), col = "bw") + +} diff --git a/man/plot.psa.Rd b/man/plot.psa.Rd index 67391ea..24824c5 100644 --- a/man/plot.psa.Rd +++ b/man/plot.psa.Rd @@ -84,3 +84,20 @@ on the cost-effectiveness plane. \description{ Plot the psa object } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +plot(l_psa) + +# incremental cost-effectiveness plane with Radio at the origin and a WTP line +plot(l_psa, ref_str = "Radio", wtp = 1e5) + +# without ellipses, in black and white +plot(l_psa, ellipse = FALSE, col = "bw") +} +\seealso{ +\code{\link{make_psa_obj}} +} diff --git a/man/plot.twsa.Rd b/man/plot.twsa.Rd index 7693230..0d7e9b6 100644 --- a/man/plot.twsa.Rd +++ b/man/plot.twsa.Rd @@ -48,3 +48,20 @@ A \code{ggplot2} plot of the two-way sensitivity analysis. \description{ Two-way sensitivity analysis plot } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_twsa <- twsa(l_psa, param1 = "pFailChemo", param2 = "muDieCancer", + outcome = "nmb", wtp = 1e5) +plot(df_twsa) + +# mark a base case (here, close to the PSA means), in black and white +plot(df_twsa, basecase = list(pFailChemo = 0.45, muDieCancer = 0.2), col = "bw") + +# the strategy with the lowest expected cost +df_twsa_cost <- twsa(l_psa, param1 = "pFailChemo", param2 = "muDieCancer", outcome = "cost") +plot(df_twsa_cost, maximize = FALSE) +} diff --git a/man/predict.metamodel.Rd b/man/predict.metamodel.Rd index ec60a1d..0f46a46 100644 --- a/man/predict.metamodel.Rd +++ b/man/predict.metamodel.Rd @@ -25,3 +25,18 @@ for each strategy and each combination of parameter values defined by \code{rang \description{ Predict from a one-way or two-way metamodel } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +l_mm <- metamodel(analysis = "oneway", psa = l_psa, + params = c("pFailChemo", "cChemo"), outcome = "eff") + +# predictions over the middle 95\\% of the PSA samples of each parameter +head(predict(l_mm, nsamp = 10)) + +# predictions over a range given for one parameter +predict(l_mm, ranges = list("pFailChemo" = c(0.3, 0.6)), nsamp = 4) +} diff --git a/man/print.icers.Rd b/man/print.icers.Rd index 558f9aa..7993f25 100644 --- a/man/print.icers.Rd +++ b/man/print.icers.Rd @@ -42,3 +42,24 @@ comparison of every strategy with the reference instead, listing the reference f other strategies by increasing cost. \code{ref = "both"} shows both comparisons, in the frontier order of the sequential table. } +\examples{ +data("psa_cdiff") +df_cdiff <- summary(psa_cdiff) +df_icers <- calculate_icers(cost = df_cdiff$meanCost, + effect = df_cdiff$meanEffect, + strategies = df_cdiff$Strategy, + ref_str = "s3", + wtp = 1e5) + +# sequential table: each strategy on the frontier against the previous one +df_icers + +# every strategy against the reference, with more digits for costs and effects +print(df_icers, ref = "reference", dig_cost = 2, dig_eff = 3) + +# both comparisons, with costs labeled in euros +print(df_icers, ref = "both", currency = "EUR") +} +\seealso{ +\code{\link{calculate_icers}} +} diff --git a/man/print.metamodel.Rd b/man/print.metamodel.Rd index 674f4bb..cef7dcc 100644 --- a/man/print.metamodel.Rd +++ b/man/print.metamodel.Rd @@ -17,3 +17,13 @@ None (invisible NULL) \description{ Print metamodel } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +l_mm <- metamodel(analysis = "oneway", psa = l_psa, params = "pFailChemo", + outcome = "nmb", wtp = 1e5) +print(l_mm) +} diff --git a/man/print.sa.Rd b/man/print.sa.Rd index a295dbd..8034c46 100644 --- a/man/print.sa.Rd +++ b/man/print.sa.Rd @@ -20,3 +20,12 @@ None (invisible NULL). \description{ print a psa object } +\examples{ +data("psa_cdiff") + +# the list of strategies is truncated at 5 +print(psa_cdiff) + +# print all of them +print(psa_cdiff, all_strat = TRUE) +} diff --git a/man/psa_cdiff.Rd b/man/psa_cdiff.Rd index c1a8991..0a5700d 100644 --- a/man/psa_cdiff.Rd +++ b/man/psa_cdiff.Rd @@ -3,14 +3,55 @@ \docType{data} \name{psa_cdiff} \alias{psa_cdiff} -\title{Sample PSA dataset} +\title{PSA of treatment strategies for Clostridioides difficile infection} \format{ -An object of class \code{psa} (inherits from \code{sa}) of length 6. +A \code{psa} object (see \code{\link{make_psa_obj}}): a list with 6 +elements. +\describe{ + \item{n_strategies}{number of strategies, 11.} + \item{strategies}{character vector of the 11 strategy names (\code{"s3"}, + \code{"s27"}, and so on), which follow the strategy numbering of the + source study.} + \item{n_sim}{number of PSA samples, 1,000.} + \item{cost}{data frame with 1,000 rows (PSA samples) and 11 columns (one + per strategy) with the cost of each strategy.} + \item{effectiveness}{data frame with 1,000 rows and 11 columns with the + quality-adjusted life years (QALYs) of each strategy.} + \item{currency}{currency symbol, \code{"$"}.} +} +The parameter values drawn in each sample are not included, so the sample +supports cost-effectiveness analysis but not metamodeling or EVPPI. +} +\source{ +Rajasingham R, Enns EA, Khoruts A, Vaughn BP. Cost-effectiveness of +Treatment Regimens for Clostridioides difficile Infection: An Evaluation of +the 2018 Infectious Diseases Society of America Guidelines. Clinical +Infectious Diseases. 2020;70(5):754-762. \doi{10.1093/cid/ciz318} } \usage{ psa_cdiff } \description{ -Sample PSA dataset +Probabilistic sensitivity analysis (PSA) output from a decision model of +treatment strategies for \emph{Clostridioides difficile} infection (CDI). +The model compared 48 strategies, which varied in the treatment regimen +used for initial versus recurrent CDI and for different infection +severities; this sample keeps the 11 most relevant strategies. Costs include +all treatment costs and lifetime downstream medical costs, and effectiveness +is quality-adjusted life expectancy, for a 67-year-old patient (the median +age of patients with CDI). +} +\examples{ +data("psa_cdiff") +df_cdiff <- summary(psa_cdiff) +df_icers <- calculate_icers(cost = df_cdiff$meanCost, + effect = df_cdiff$meanEffect, + strategies = df_cdiff$Strategy) +df_icers +plot(df_icers) +} +\seealso{ +\code{vignette("basic_cea", package = "dampack")}, which uses this +dataset. } \keyword{datasets} diff --git a/man/run_owsa_det.Rd b/man/run_owsa_det.Rd index ba62038..eabf9b9 100644 --- a/man/run_owsa_det.Rd +++ b/man/run_owsa_det.Rd @@ -65,3 +65,53 @@ given function that produces outcomes. } } +\examples{ +# A tiny decision model. Treatment fails with probability p_fail under standard care +# and with half that probability under the new treatment, which costs c_trt. A failure +# costs 20,000 and loses 2 QALYs. FUN takes a named list of parameters and returns a data +# frame with the strategy names in its first column and one column per outcome. +f_model <- function(l_params, wtp = 5e4) { + v_p_fail <- l_params$p_fail * c(1, 0.5) + v_cost <- c(0, l_params$c_trt) + 20000 * v_p_fail + v_qaly <- 10 - 2 * v_p_fail + data.frame(Strategy = c("Standard", "New"), + Cost = v_cost, + QALY = v_qaly, + NMB = wtp * v_qaly - v_cost) +} +l_params_basecase <- list(p_fail = 0.3, c_trt = 15000) +f_model(l_params_basecase) + +# vary each parameter over its range, one at a time +df_params_range <- data.frame(pars = c("p_fail", "c_trt"), + min = c(0.1, 5000), + max = c(0.5, 25000)) +df_owsa_nmb <- run_owsa_det(params_range = df_params_range, + params_basecase = l_params_basecase, + nsamp = 20, + FUN = f_model, + outcomes = "NMB", + strategies = c("Standard", "New"), + progress = FALSE) +plot(df_owsa_nmb) +owsa_tornado(df_owsa_nmb, select_str = c("Standard", "New"), outcome_name = "NMB") +owsa_opt_strat(df_owsa_nmb) + +# with more than one outcome, a list with one owsa object per outcome is returned, +# and arguments of FUN other than l_params are passed through ... +l_owsa <- run_owsa_det(params_range = df_params_range, + params_basecase = l_params_basecase, + nsamp = 20, + FUN = f_model, + outcomes = c("Cost", "NMB"), + strategies = c("Standard", "New"), + progress = FALSE, + wtp = 1e5) +names(l_owsa) +owsa_opt_strat(l_owsa$owsa_NMB) + +} +\seealso{ +\code{\link{plot.owsa}}, \code{\link{owsa_tornado}}, \code{\link{owsa_opt_strat}}, +\code{\link{run_twsa_det}} +} diff --git a/man/run_psa.Rd b/man/run_psa.Rd index 07afd75..a6efdd9 100644 --- a/man/run_psa.Rd +++ b/man/run_psa.Rd @@ -44,8 +44,50 @@ A list containing PSA objects for each outcome in \code{outcomes}. \code{run_psa} calculates outcomes using a user-defined function and creates PSA objects corresponding to the specified outcomes. } +\examples{ +# A tiny decision model. Treatment fails with probability p_fail under standard care +# and with half that probability under the new treatment, which costs c_trt. A failure +# costs 20,000 and loses 2 QALYs. FUN takes a named list of parameters and returns a data +# frame with the strategy names in its first column and one column per outcome. +f_model <- function(l_params, wtp = 5e4) { + v_p_fail <- l_params$p_fail * c(1, 0.5) + v_cost <- c(0, l_params$c_trt) + 20000 * v_p_fail + v_qaly <- 10 - 2 * v_p_fail + data.frame(Strategy = c("Standard", "New"), + Cost = v_cost, + QALY = v_qaly, + NMB = wtp * v_qaly - v_cost) +} +l_params_basecase <- list(p_fail = 0.3, c_trt = 15000) +f_model(l_params_basecase) + +# 100 PSA samples of the two parameters +set.seed(2026) +df_psa_samp <- gen_psa_samp(params = c("p_fail", "c_trt"), + dists = c("beta", "gamma"), + parameterization_types = c("mean, sd", "mean, sd"), + dists_params = list(c(0.3, 0.05), c(15000, 3000)), + nsamp = 100) + +# run the model on every sample: a list with one psa object per outcome +l_psa_out <- run_psa(psa_samp = df_psa_samp, + params_basecase = l_params_basecase, + FUN = f_model, + outcomes = c("Cost", "QALY"), + strategies = c("Standard", "New"), + progress = FALSE) +names(l_psa_out) + +# combine the cost and QALY outcomes into one psa object for cost-effectiveness analysis +l_psa <- make_psa_obj(cost = l_psa_out$Cost$other_outcome, + effectiveness = l_psa_out$QALY$other_outcome, + parameters = l_psa_out$Cost$parameters, + strategies = l_psa_out$Cost$strategies) +plot(l_psa) +calculate_icers_psa(l_psa) +} \seealso{ \code{\link{run_psa}}, \code{\link{make_psa_obj}}, -\code{\link{gen_psa_samp}}, +\code{\link{gen_psa_samp}} } diff --git a/man/run_twsa_det.Rd b/man/run_twsa_det.Rd index 7a4b097..b462d26 100644 --- a/man/run_twsa_det.Rd +++ b/man/run_twsa_det.Rd @@ -61,3 +61,38 @@ given function that produces outcomes. } } +\examples{ +# A tiny decision model. Treatment fails with probability p_fail under standard care +# and with half that probability under the new treatment, which costs c_trt. A failure +# costs 20,000 and loses 2 QALYs. FUN takes a named list of parameters and returns a data +# frame with the strategy names in its first column and one column per outcome. +f_model <- function(l_params, wtp = 5e4) { + v_p_fail <- l_params$p_fail * c(1, 0.5) + v_cost <- c(0, l_params$c_trt) + 20000 * v_p_fail + v_qaly <- 10 - 2 * v_p_fail + data.frame(Strategy = c("Standard", "New"), + Cost = v_cost, + QALY = v_qaly, + NMB = wtp * v_qaly - v_cost) +} +l_params_basecase <- list(p_fail = 0.3, c_trt = 15000) +f_model(l_params_basecase) + +# vary both parameters together over a 20 x 20 grid +df_params_range <- data.frame(pars = c("p_fail", "c_trt"), + min = c(0.1, 5000), + max = c(0.5, 25000)) +df_twsa_nmb <- run_twsa_det(params_range = df_params_range, + params_basecase = l_params_basecase, + nsamp = 20, + FUN = f_model, + outcomes = "NMB", + strategies = c("Standard", "New"), + progress = FALSE) +head(df_twsa_nmb) +plot(df_twsa_nmb, basecase = l_params_basecase) + +} +\seealso{ +\code{\link{plot.twsa}}, \code{\link{run_owsa_det}} +} diff --git a/man/summary.ceac.Rd b/man/summary.ceac.Rd index 26309b7..7f5ceab 100644 --- a/man/summary.ceac.Rd +++ b/man/summary.ceac.Rd @@ -22,4 +22,18 @@ the right endpoint - i.e., [\code{range_min}, \code{range_max}) Describes cost-effective strategies and their associated intervals of cost-effectiveness } -\keyword{internal} +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) +df_ceac <- ceac(l_psa, wtp = seq(1e4, 1e5, by = 1e4)) + +# Radio is optimal up to a WTP of 40,000 and Chemo from there on +summary(df_ceac) + +} +\seealso{ +\code{\link{ceac}}, \code{\link{plot.ceac}} +} diff --git a/man/summary.metamodel.Rd b/man/summary.metamodel.Rd index ec2305a..30e459e 100644 --- a/man/summary.metamodel.Rd +++ b/man/summary.metamodel.Rd @@ -17,3 +17,14 @@ a \code{data.frame} containing the r-squared for each strategy and parameter's m \description{ Summary of metamodel } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# which parameters explain most of the variation in the net monetary benefit? +l_mm <- metamodel(analysis = "oneway", psa = l_psa, outcome = "nmb", wtp = 1e5) +summary(l_mm) +} diff --git a/man/summary.psa.Rd b/man/summary.psa.Rd index ca0a145..964e9f4 100644 --- a/man/summary.psa.Rd +++ b/man/summary.psa.Rd @@ -38,3 +38,25 @@ which the strategy has a higher NMB than the reference (it lies below the willin \description{ summarize a psa object across all simulations } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# mean cost and effectiveness of each strategy, with their standard deviations +summary(l_psa, calc_sds = TRUE) + +# compare every strategy with Radio, sample by sample, at a WTP of 100,000 +summary(l_psa, ref_str = "Radio", wtp = 1e5) + +# the means can be passed to calculate_icers() +df_psa_sum <- summary(l_psa) +calculate_icers(cost = df_psa_sum$meanCost, + effect = df_psa_sum$meanEffect, + strategies = df_psa_sum$Strategy) +} +\seealso{ +\code{\link{make_psa_obj}}, \code{\link{calculate_icers}} +} diff --git a/man/twsa.Rd b/man/twsa.Rd index 9c5f0a3..8d14cd9 100644 --- a/man/twsa.Rd +++ b/man/twsa.Rd @@ -19,7 +19,7 @@ twsa( \arguments{ \item{sa_obj}{sensitivity analysis object; either a probabilistic sensitivity analysis (\code{\link{make_psa_obj}}) or -a deterministic sensitivity analysis object (\code{\link{run_owsa_det}})} +a two-way deterministic sensitivity analysis object (\code{\link{create_dsa_twoway}})} \item{param1}{String with the name of the first parameter of interest} @@ -45,11 +45,28 @@ used in internal function calls of metamodel within other VOI functions.} Default: 2} } \value{ -twsa A \code{ggplot2} object with the TWSA graph of \code{param1} and -\code{param2} on the outcome of interest. +A \code{data.frame} of class \code{twsa} with the outcome of each strategy over a grid of +values of \code{param1} and \code{param2}. It can be visualized with \code{\link{plot.twsa}}. } \description{ This function displays a two-way sensitivity analysis (TWSA) graph by estimating a linear regression metamodel of a PSA for a given decision-analytic model } +\examples{ +data("cancer_psa_data") +l_psa <- make_psa_obj(cost = cancer_psa_data$cost, + effectiveness = cancer_psa_data$effectiveness, + parameters = cancer_psa_data$parameters, + strategies = cancer_psa_data$strategies) + +# strategy with the highest predicted net monetary benefit as two parameters vary +df_twsa <- twsa(l_psa, param1 = "pFailChemo", param2 = "muDieCancer", + outcome = "nmb", wtp = 1e5) +head(df_twsa) +plot(df_twsa) + +} +\seealso{ +\code{\link{plot.twsa}}, \code{\link{run_twsa_det}} +}