diff --git a/NEWS.md b/NEWS.md index 8878a02..534357c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,7 @@ ## New features +- `plot.icers()` gains `ref_str`, which plots the incremental cost-effectiveness plane with the reference strategy at the origin, and `wtp`, which draws a willingness-to-pay line. `plot.psa()` gains `wtp` for the same line on its incremental plane. `plot.icers()` uses the currency stored by `calculate_icers()` (#209, #202). - `calculate_icers()` can compare every strategy with a user-selected reference strategy: with `ref_str = "Standard of care"`, it adds `Inc_Cost_ref`, `Inc_Effect_ref`, `ICER_ref`, and `Status_ref` ("Reference", "Dominant", "Dominated", "More costly, more effective", "Less costly, less effective", or "Equivalent"). The frontier-based results are unchanged, and without `ref_str` no columns are added (#209). - `calculate_icers()` gains `wtp`, which adds the net monetary benefit (`NMB`, and `iNMB_ref` with a reference strategy), and `nhb = TRUE`, which also adds the net health benefit (`NHB`, `iNHB_ref`) (#200). - `calculate_icers()` gains `currency`, used by `print.icers()`. `print.icers()` gains `ref`: `"sequential"` (the default) prints the usual table, and `"reference"` or `"both"` print the comparison with the reference strategy (#209). @@ -24,6 +25,7 @@ ## Bug fixes +- `plot.psa(ref_str = )` now works when there are only two strategies; it used to fail with "'dims' cannot be of length 0" (#209). - `calculate_icers()` with a single strategy now returns a valid `icers` object, with the same columns as for several strategies (`Status` is `"ND"` and the incremental columns are `NA`), so `plot()` and `print()` work on it (#183). - `calculate_icers()` with no strategies now gives an informative error instead of "missing value where TRUE/FALSE needed", and its documentation no longer describes a reference-strategy option that does not exist (#178). - `metamodel()`, and the functions that use it (`owsa()` and `twsa()` on a PSA, `calc_evppi()`, `calc_evsi()`), now work with strategy names that are not syntactically valid R names (#208). diff --git a/R/icers.R b/R/icers.R index 266bb4d..29d7459 100644 --- a/R/icers.R +++ b/R/icers.R @@ -212,6 +212,19 @@ calculate_icers <- function(cost, effect, strategies, ref_str = NULL, wtp = NULL add_reference_and_nmb(df_results, ref_str, wtp, nhb, currency) } +#' Caption text for a willingness-to-pay line +#' +#' @param wtp willingness-to-pay threshold. +#' @param currency currency symbol. +#' @param effect_units units of effectiveness, e.g. \code{"QALYs"}. +#' @return a string such as \code{"Dotted line: WTP = $50,000/QALY"}. +#' @keywords internal +wtp_caption <- function(wtp, currency, effect_units = "QALYs") { + unit <- sub("s$", "", effect_units) + paste0("Dotted line: WTP = ", currency, format(wtp, big.mark = ",", scientific = FALSE, trim = TRUE), + "/", unit) +} + #' Check a reference strategy name #' #' @param ref_str reference strategy name, or \code{NULL}. @@ -424,6 +437,16 @@ compute_icers <- function(non_d) { #' longer strategies are truncated to save space. #' @param plot_frontier_only only plot the efficient frontier #' @param alpha opacity of points +#' @param ref_str name of a reference strategy. If given, the plot shows the incremental +#' cost-effectiveness plane, with the reference strategy at the origin. The frontier and the +#' status of each strategy do not change. Defaults to \code{NULL} (the cost-effectiveness plane). +#' @param wtp a willingness-to-pay threshold. If given, a dotted line with slope \code{wtp} is +#' drawn through the reference strategy (or, without \code{ref_str}, through the least costly +#' strategy on the frontier). Strategies below the line are cost-effective compared with that +#' strategy at this threshold. +#' @param ref_axis with \code{ref_str}, draw dashed axes through the origin. Defaults to \code{TRUE}. +#' @param ref_caption add a caption naming the reference strategy and the WTP threshold. +#' Defaults to \code{TRUE}. #' @inheritParams ggrepel::geom_label_repel #' #' @return a ggplot2 object which can be modified by adding additional geoms @@ -435,7 +458,7 @@ compute_icers <- function(non_d) { #' @export plot.icers <- function(x, txtsize = 12, - currency = "$", + currency = NULL, effect_units = "QALYs", label = c("frontier", "all", "none"), label_max_char = NULL, @@ -450,8 +473,17 @@ plot.icers <- function(x, xexpand = expansion(0.1), yexpand = expansion(0.1), max.iter = 20000, + ref_str = NULL, + wtp = NULL, + ref_axis = TRUE, + ref_caption = TRUE, ...) { Cost <- Effect <- Status <- Strategy <- Inc_Cost <- Inc_Effect <- ICER <- NULL + if (is.null(currency)) { + currency <- if (is.null(attr(x, "currency"))) "$" else attr(x, "currency") + } + ref_str <- check_ref_str(ref_str, x$Strategy) + check_wtp_nhb(wtp, nhb = FALSE) if (ncol(x) > 7) { # reformat icers class object if uncertainty bounds are present @@ -488,6 +520,23 @@ plot.icers <- function(x, eff_name <- "Effect" cost_name <- "Cost" + # point the WTP line goes through: the reference, or the least costly frontier strategy + if (!is.null(wtp)) { + df_front <- x[x$Status == nd_name, ] + df_anchor <- if (is.null(ref_str)) df_front[which.min(df_front$Cost), ] else x[x$Strategy == ref_str, ] + } + + # incremental plane: put the reference strategy at the origin + x_lab <- paste0("Effect (", effect_units, ")") + y_lab <- paste0("Cost (", currency, ")") + if (!is.null(ref_str)) { + i_ref <- which(x$Strategy == ref_str) + x$Cost <- x$Cost - x$Cost[i_ref] + x$Effect <- x$Effect - x$Effect[i_ref] + x_lab <- paste0("Incremental Effect (", effect_units, ")") + y_lab <- paste0("Incremental Cost (", currency, ")") + } + # frontier only if (plot_frontier_only) { df_plt_data <- x[x$Status == nd_name, ] @@ -502,8 +551,23 @@ plot.icers <- function(x, geom_line(aes(linetype = !!sym(stat_name), group = !!sym(stat_name))) + scale_linetype_manual(name = NULL, values = v_plot_lines) + scale_shape_discrete(name = NULL) + - labs(x = paste0("Effect (", effect_units, ")"), - y = paste0("Cost (", currency, ")")) + labs(x = x_lab, y = y_lab) + + if (!is.null(ref_str) && ref_axis) { + icer_plot <- icer_plot + + geom_hline(yintercept = 0, linetype = "dashed", color = "grey50") + + geom_vline(xintercept = 0, linetype = "dashed", color = "grey50") + } + if (!is.null(wtp)) { + intercept <- if (is.null(ref_str)) df_anchor$Cost - wtp * df_anchor$Effect else 0 + icer_plot <- icer_plot + + geom_abline(intercept = intercept, slope = wtp, linetype = "dotted", color = "grey30") + } + v_caption <- c(if (!is.null(ref_str)) paste0("Reference Strategy: ", ref_str), + if (!is.null(wtp)) wtp_caption(wtp, currency, effect_units)) + if (ref_caption && length(v_caption)) { + icer_plot <- icer_plot + labs(caption = paste(v_caption, collapse = "; ")) + } icer_plot <- add_common_aes(icer_plot, txtsize, col = "none", continuous = c("x", "y"), diff --git a/R/psa.R b/R/psa.R index 2b5a80f..3d64875 100644 --- a/R/psa.R +++ b/R/psa.R @@ -139,7 +139,11 @@ summary.psa <- function(object, calc_sds = FALSE, ...) { #' @param alpha opacity of the scatterplot points. #' 0 is completely transparent, 1 is completely opaque #' @param ref_axis Add dotted axes lines at (0,0). Defaults to TRUE -#' @param ref_caption Add the reference strategy as a caption. Defaults to TRUE +#' @param ref_caption Add the reference strategy (and the WTP threshold, if given) as a caption. +#' Defaults to TRUE +#' @param wtp a willingness-to-pay threshold. If given, a dotted line with slope \code{wtp} is +#' drawn through the origin of the incremental cost-effectiveness plane; samples below the line are +#' cost-effective compared with the reference strategy at this threshold. Requires \code{ref_str}. #' @inheritParams add_common_aes #' #' @importFrom ellipse ellipse @@ -161,6 +165,7 @@ plot.psa <- function(x, ylim = NULL, ref_axis = TRUE, ref_caption = TRUE, + wtp = NULL, ...) { Effectiveness <- Cost <- Strategy <- Eff.mean <- Cost.mean <- y <- group <- NULL @@ -168,6 +173,12 @@ plot.psa <- function(x, df_cost_wide <- x$cost v_strategies <- x$strategies currency <- x$currency + ref_str <- check_ref_str(ref_str, v_strategies) + if (!is.null(wtp) && is.null(ref_str)) { + stop("`wtp` draws a willingness-to-pay line on the incremental cost-effectiveness plane, ", + "so it needs `ref_str`.", call. = FALSE) + } + check_wtp_nhb(wtp, nhb = FALSE) if (is.null(ref_str)) { # expect that effectiveness and costs have strategy column names @@ -236,14 +247,11 @@ plot.psa <- function(x, v_str = v_strategies) } else { - ### Check that the reference strategy is in the list of strategies - if (!(ref_str %in% v_strategies)) { - stop("ref_str must be in the list of strategies") - } ## Function to convert the raw outcomes to incremental outcomes make_df_inc <- function(df) { v_ref <- df[, ref_str] - df_inc <- df[, !(names(df) %in% ref_str)] + # drop = FALSE keeps a data frame when there is a single comparator + df_inc <- df[, !(names(df) %in% ref_str), drop = FALSE] df_inc <- sweep(df_inc, 1, v_ref, "-") df_inc } @@ -281,9 +289,16 @@ plot.psa <- function(x, geom_vline(xintercept = 0, linetype = "dashed", color = "black") } + if (!is.null(wtp)) { + psa_plot <- psa_plot + + geom_abline(intercept = 0, slope = wtp, linetype = "dotted", color = "grey30") + } + if (ref_caption == TRUE) { + v_caption <- c(paste0("Reference Strategy: ", ref_str), + if (!is.null(wtp)) wtp_caption(wtp, currency)) psa_plot <- psa_plot + - labs(caption = paste("Reference Strategy: ", ref_str)) + labs(caption = paste(v_caption, collapse = "; ")) } # define strategy-specific means for the center of the ellipse diff --git a/man/plot.icers.Rd b/man/plot.icers.Rd index 132c482..af2dfdd 100644 --- a/man/plot.icers.Rd +++ b/man/plot.icers.Rd @@ -7,7 +7,7 @@ \method{plot}{icers}( x, txtsize = 12, - currency = "$", + currency = NULL, effect_units = "QALYs", label = c("frontier", "all", "none"), label_max_char = NULL, @@ -22,6 +22,10 @@ xexpand = expansion(0.1), yexpand = expansion(0.1), max.iter = 20000, + ref_str = NULL, + wtp = NULL, + ref_axis = TRUE, + ref_caption = TRUE, ... ) } @@ -67,6 +71,20 @@ for how to modify this.} \item{max.iter}{Maximum number of iterations to try to resolve overlaps. Defaults to 10000.} +\item{ref_str}{name of a reference strategy. If given, the plot shows the incremental +cost-effectiveness plane, with the reference strategy at the origin. The frontier and the +status of each strategy do not change. Defaults to \code{NULL} (the cost-effectiveness plane).} + +\item{wtp}{a willingness-to-pay threshold. If given, a dotted line with slope \code{wtp} is +drawn through the reference strategy (or, without \code{ref_str}, through the least costly +strategy on the frontier). Strategies below the line are cost-effective compared with that +strategy at this threshold.} + +\item{ref_axis}{with \code{ref_str}, draw dashed axes through the origin. Defaults to \code{TRUE}.} + +\item{ref_caption}{add a caption naming the reference strategy and the WTP threshold. +Defaults to \code{TRUE}.} + \item{...}{further arguments to plot. This is not used by \code{dampack} but required for generic consistency.} } diff --git a/man/plot.psa.Rd b/man/plot.psa.Rd index 32bbf8c..954ba5a 100644 --- a/man/plot.psa.Rd +++ b/man/plot.psa.Rd @@ -20,6 +20,7 @@ ylim = NULL, ref_axis = TRUE, ref_caption = TRUE, + wtp = NULL, ... ) } @@ -56,7 +57,12 @@ will override \code{n_y_ticks} if provided.} \item{ref_axis}{Add dotted axes lines at (0,0). Defaults to TRUE} -\item{ref_caption}{Add the reference strategy as a caption. Defaults to TRUE} +\item{ref_caption}{Add the reference strategy (and the WTP threshold, if given) as a caption. +Defaults to TRUE} + +\item{wtp}{a willingness-to-pay threshold. If given, a dotted line with slope \code{wtp} is +drawn through the origin of the incremental cost-effectiveness plane; samples below the line are +cost-effective compared with the reference strategy at this threshold. Requires \code{ref_str}.} \item{...}{further arguments to plot. This is not used by \code{dampack} but required for generic consistency.} diff --git a/man/wtp_caption.Rd b/man/wtp_caption.Rd new file mode 100644 index 0000000..73b50ab --- /dev/null +++ b/man/wtp_caption.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/icers.R +\name{wtp_caption} +\alias{wtp_caption} +\title{Caption text for a willingness-to-pay line} +\usage{ +wtp_caption(wtp, currency, effect_units = "QALYs") +} +\arguments{ +\item{wtp}{willingness-to-pay threshold.} + +\item{currency}{currency symbol.} + +\item{effect_units}{units of effectiveness, e.g. \code{"QALYs"}.} +} +\value{ +a string such as \code{"Dotted line: WTP = $50,000/QALY"}. +} +\description{ +Caption text for a willingness-to-pay line +} +\keyword{internal} diff --git a/tests/testthat/test_reference_plots.R b/tests/testthat/test_reference_plots.R new file mode 100644 index 0000000..8612bf7 --- /dev/null +++ b/tests/testthat/test_reference_plots.R @@ -0,0 +1,79 @@ +context("reference strategy and WTP lines in plot.icers() and plot.psa() (#209, #202)") + +df_toy <- data.frame(strategy = c("Standard of care", "New drug (A)", "Cheaper", "Worse"), + cost = c(100, 200, 50, 300), + effect = c(1, 2, 1.5, 0.5), + stringsAsFactors = FALSE) +x_toy <- calculate_icers(df_toy$cost, df_toy$effect, df_toy$strategy) + +point_layer <- function(p) { + i <- which(vapply(p$layers, function(l) inherits(l$geom, "GeomPoint"), logical(1)))[1] + ggplot2::layer_data(p, i) +} +abline_layers <- function(p) { + which(vapply(p$layers, function(l) inherits(l$geom, "GeomAbline"), logical(1))) +} + +test_that("plot.icers() is unchanged by default", { + p <- plot(x_toy) + expect_length(abline_layers(p), 0) + expect_equal(p$labels$y, "Cost ($)") + expect_setequal(point_layer(p)$y, df_toy$cost) +}) + +test_that("plot.icers(ref_str = ) puts the reference at the origin", { + p <- plot(x_toy, ref_str = "Standard of care") + d <- point_layer(p) + expect_setequal(d$x, df_toy$effect - 1) + expect_setequal(d$y, df_toy$cost - 100) + expect_equal(p$labels$y, "Incremental Cost ($)") + expect_equal(p$labels$x, "Incremental Effect (QALYs)") + expect_match(p$labels$caption, "Reference Strategy: Standard of care", fixed = TRUE) + expect_error(plot(x_toy, ref_str = "Nope"), "must be one of the strategies") +}) + +test_that("plot.icers(wtp = ) draws the WTP line", { + p_ref <- plot(x_toy, ref_str = "Standard of care", wtp = 150) + i <- abline_layers(p_ref) + expect_length(i, 1) + d <- ggplot2::layer_data(p_ref, i) + expect_equal(d$slope, 150) + expect_equal(d$intercept, 0) + expect_match(p_ref$labels$caption, "WTP = $150/QALY", fixed = TRUE) + + # without a reference, the line goes through the least costly strategy on the frontier + p_abs <- plot(x_toy, wtp = 150) + d <- ggplot2::layer_data(p_abs, abline_layers(p_abs)) + expect_equal(d$intercept, 50 - 150 * 1.5) +}) + +test_that("plot.icers() uses the currency stored by calculate_icers()", { + x_eur <- calculate_icers(df_toy$cost, df_toy$effect, df_toy$strategy, currency = "€") + expect_equal(plot(x_eur)$labels$y, "Cost (€)") + expect_equal(plot(x_eur, currency = "£")$labels$y, "Cost (£)") +}) + +# PSA with two strategies, to cover the drop = FALSE bug in plot.psa(ref_str = ) +set.seed(20261112) +n_sim <- 200 +df_cost2 <- data.frame(A = rnorm(n_sim, 1000, 50), B = rnorm(n_sim, 1500, 50)) +df_eff2 <- data.frame(A = rnorm(n_sim, 1, 0.05), B = rnorm(n_sim, 1.2, 0.05)) +psa_2 <- make_psa_obj(df_cost2, df_eff2, strategies = c("Standard of care", "New drug (A)")) + +test_that("plot.psa(ref_str = ) works with two strategies", { + expect_warning(p <- plot(psa_2, ref_str = "Standard of care"), NA) + d <- point_layer(p) + expect_equal(sort(d$y), sort(df_cost2$B - df_cost2$A)) + expect_equal(sort(d$x), sort(df_eff2$B - df_eff2$A)) +}) + +test_that("plot.psa(wtp = ) draws the WTP line on the incremental plane", { + p <- plot(psa_2, ref_str = "Standard of care", wtp = 2000) + i <- abline_layers(p) + expect_length(i, 1) + expect_equal(ggplot2::layer_data(p, i)$slope, 2000) + expect_match(p$labels$caption, "WTP = $2,000/QALY", fixed = TRUE) + expect_error(plot(psa_2, wtp = 2000), "needs `ref_str`") + expect_error(plot(psa_2, ref_str = "Nope"), "must be one of the strategies") + expect_length(abline_layers(plot(psa_2)), 0) +})