Skip to content
1 change: 1 addition & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,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

Expand Down
13 changes: 12 additions & 1 deletion R/add_common_aes.R
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
31 changes: 27 additions & 4 deletions R/ceac.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 !!
Expand Down Expand Up @@ -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, ...) {
Expand Down
9 changes: 9 additions & 0 deletions R/create_sa.R
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
44 changes: 43 additions & 1 deletion R/data_cdiff.R
Original file line number Diff line number Diff line change
@@ -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"
2 changes: 1 addition & 1 deletion R/data_example_psa_elc.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 29 additions & 0 deletions R/dsa_oneway.R
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
29 changes: 26 additions & 3 deletions R/dsa_twoway.R
Original file line number Diff line number Diff line change
@@ -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
#'
Expand All @@ -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) {
Expand Down
16 changes: 14 additions & 2 deletions R/evpi.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
33 changes: 32 additions & 1 deletion R/evppi.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
66 changes: 65 additions & 1 deletion R/evsi.R
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading