Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

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