diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b4204be..8c6e40d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -79,6 +79,33 @@ Exported function and argument names are part of the public API that users' scri New exported functions start with a verb (`calculate_`, `make_`, `plot_`, ...), and new arguments follow the names already used elsewhere in the package (`psa`, `wtp`, `currency`, `effect_units`, `txtsize`, `col`). +### API style (decision record, #214) + +Adopted for dampack 1.1.0 (November 2026). It records the names the package uses now, so new code follows them, and the targets for 2.0 that the group still has to agree on. Nothing below renames an existing function or argument in 1.x except through soft deprecation. + +**Argument order.** The data object comes first, then the threshold: `calc_exp_loss(psa, wtp)`, `calc_evpi(psa, wtp)`, `calc_evppi(psa, wtp, ...)`, `calc_evsi(psa, wtp, ...)`, `owsa(sa_obj, ...)`, `twsa(sa_obj, ...)`. Since 1.1.0 `ceac(psa, wtp)` does too; the old positional `ceac(wtp, psa)` still works with a soft deprecation warning. + +**Plot arguments.** A plot method uses these names whenever it has the option, with these meanings: + +| Argument | Meaning | +|---|---| +| `txtsize` | base text size | +| `col` | `c("access", "full", "bw")`: accessible (viridis), full color, or black and white. Only where strategies or groups are told apart by color; `plot.icers()` (shape and line type), `plot.evpi()` and `plot.evppi()` (one line) have none | +| `currency` | `NULL` uses the currency stored in the object (from `make_psa_obj()` or `calculate_icers()`), otherwise `"$"` | +| `effect_units` | units of effectiveness in the plural, default `"QALYs"`; labels that mean "per unit" use the singular (`"$/QALY"`) | +| `n_x_ticks`, `n_y_ticks`, `xbreaks`, `ybreaks` | approximate number of ticks, or exact breaks | +| `xlim`, `ylim` | limits of each continuous axis (`NULL` sets them automatically) | +| `xtrans`, `ytrans` | axis transformations such as `"log10"` (`plot.psa()`) | +| `linewidth` | line width, as in ggplot2. `plot.owsa(size)` and `plot.exp_loss(lsize)` are deprecated in its favor | + +**Open questions for 2.0** (meeting decision 3; no aliases are added in 1.1.0): + +- Verb prefixes: the package has both `calc_` (`calc_evpi()`, `calc_exp_loss()`) and `calculate_` (`calculate_icers()`, `calculate_icers_psa()`). +- `effect` (`calculate_icers()`) versus `effectiveness` (`make_psa_obj()` and the `psa` object). +- Column case: most result tables use capitalized columns (`Strategy`, `Cost`, `WTP`, `Proportion`), while `owsa` and `twsa` objects use lower case (`strategy`, `parameter`, `outcome_val`). Until this is decided, new columns follow the existing style of their object. + +**Accepted minor break in 1.1.0.** `summary.ceac()` renames its third column from `cost_eff_strat` to `optimal_strategy` (#173), as recorded in NEWS.md. + ### Files and tests - Source files live in `R/`, one family of functions per file. diff --git a/DESCRIPTION b/DESCRIPTION index bd0dad3..fad7bb3 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -59,6 +59,7 @@ Imports: triangle, ggrepel, tidyr, + lifecycle, rlang, viridis, RColorBrewer diff --git a/NAMESPACE b/NAMESPACE index 7958a75..4fb5b30 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -46,6 +46,9 @@ importFrom(dplyr,bind_cols) importFrom(ellipse,ellipse) importFrom(ggrepel,geom_label_repel) importFrom(grDevices,grey.colors) +importFrom(lifecycle,deprecate_soft) +importFrom(lifecycle,deprecated) +importFrom(lifecycle,is_present) importFrom(mgcv,Predict.matrix) importFrom(mgcv,PredictMat) importFrom(mgcv,gam) diff --git a/NEWS.md b/NEWS.md index 5d3ad80..d890ef5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,6 +3,7 @@ ## New features - `plot.psa()` gains `xtrans` and `ytrans` to put the effectiveness and cost axes on, for example, a log scale. The ellipses are computed on the transformed scale, so they keep their shape instead of breaking where they cross zero; values a log axis cannot show give an informative error (#201). +- Plot arguments are more consistent across methods (#214): `plot.owsa()` and `plot.exp_loss()` take `linewidth` (as in ggplot2); `plot.owsa()` and `plot.twsa()` gain `xlim` and `ylim`, and `owsa_opt_strat()` gains `xlim`; `effect_units` defaults to `"QALYs"` in every plot, and willingness-to-pay labels use its singular ("$/QALY"). The naming rules are recorded in an API style section of CONTRIBUTING.md. - The currency of a `psa` object now carries through to its analyses: `ceac()`, `calc_exp_loss()`, `calc_evpi()`, `calc_evppi()`, `calc_evsi()`, and `calculate_icers_psa()` keep it, and their `plot()` and `print()` methods use it unless `currency` is given. `plot.ceac()` gains `effect_units` (#203). - `summary.psa()` gains `ref_str` and `wtp`. With a reference strategy it adds the mean incremental cost and effect and the proportion of PSA samples in each quadrant of the incremental cost-effectiveness plane (`propNE`, `propSE`, `propSW`, `propNW`); with `wtp` it adds the mean NMB and, with a reference, `meanIncNMB` and the proportion of samples that are cost-effective compared with the reference (`propCostEffective`) (#209, #202). - `calculate_icers_psa()` gains `ref_str`, `wtp`, and `nhb`. With `uncertainty = TRUE` and a reference strategy, it adds 95% intervals for the differences from the reference, computed sample by sample (#209). @@ -19,6 +20,8 @@ ## Superseded +- `ceac()` now takes the `psa` object first, like `calc_exp_loss()` and `calc_evpi()`: `ceac(psa, wtp)`. The old positional order `ceac(wtp, psa)` still works but gives a soft deprecation warning; named arguments work in either order (#214). +- `plot.owsa(size = )` and `plot.exp_loss(lsize = )` are deprecated in favor of `linewidth`; the old arguments still work, with a soft deprecation warning (#214). - `example_psa` and `example_psa_obj` are superseded by `cancer_psa_data`, which contains the same PSA samples. Both remain available for backward compatibility and will be removed in dampack 2.0. They are now rebuilt from `cancer_psa_data` when the package is installed, so the samples are stored only once. ## Breaking changes diff --git a/R/add_common_aes.R b/R/add_common_aes.R index 5e8bd5a..c26b626 100644 --- a/R/add_common_aes.R +++ b/R/add_common_aes.R @@ -279,3 +279,15 @@ resolve_currency <- function(currency, x) { voi_units <- function(x, currency, effect_units) { if (identical(attr(x, "outcome"), "nhb")) effect_units else currency } + +#' Singular form of the effect units, for "per unit" labels +#' +#' Drops a final "s", so \code{"QALYs"} becomes \code{"QALY"} in labels such as "$/QALY". A unit +#' already in the singular is returned unchanged. +#' +#' @param effect_units units of effectiveness, such as \code{"QALYs"}. +#' @return a string. +#' @keywords internal +per_unit <- function(effect_units) { + sub("s$", "", effect_units) +} diff --git a/R/ceac.R b/R/ceac.R index 2817f0d..62d2549 100644 --- a/R/ceac.R +++ b/R/ceac.R @@ -5,10 +5,14 @@ #' \code{ceac} is used to compute and plot the cost-effectiveness acceptability #' curves (CEAC) from a probabilistic sensitivity analysis (PSA) dataset. #' -#' @param wtp numeric vector with willingness-to-pay (WTP) thresholds #' @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 #' @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 +#' works but is deprecated; named arguments work in any order. +#' #' \code{ceac} computes the probability of each of the strategies being #' cost-effective at each \code{wtp} threshold. The returned object has classes #' \code{ceac} and \code{data.frame}, and has its own plot method (\code{\link{plot.ceac}}). @@ -28,7 +32,7 @@ #' #' # define wtp threshold vector (can also use a single wtp) #' wtp <- seq(1e4, 1e5, by = 1e4) -#' ceac_obj <- ceac(wtp, psa_cancer) +#' ceac_obj <- ceac(psa_cancer, wtp) #' plot(ceac_obj) # see ?plot.ceac for options #' #' # this is most useful when there are many strategies @@ -54,8 +58,17 @@ #' #' #' @importFrom tidyr pivot_longer +#' @importFrom lifecycle deprecate_soft deprecated is_present #' @export -ceac <- function(wtp, psa) { +ceac <- function(psa, wtp) { + # the order before 1.1.0 was ceac(wtp, psa): accept it, with a soft deprecation warning + if (inherits(wtp, "psa") && !inherits(psa, "psa")) { + deprecate_soft("1.1.0", "ceac(wtp = 'must come after `psa`')", + details = "Use `ceac(psa, wtp)`, the order of `calc_exp_loss()` and `calc_evpi()`.") + tmp <- psa + psa <- wtp + wtp <- tmp + } # check that psa has class 'psa' check_psa_object(psa) @@ -139,7 +152,9 @@ ceac <- function(wtp, psa) { #' @param currency string with currency used in the cost-effectiveness analysis (CEA). #' Defaults to the currency of the PSA the CEAC was computed from (or \code{$}), but can be any #' currency symbol or word (e.g., £, €, peso). -#' @param effect_units units of effectiveness, used in the x-axis label. Default: QALY +#' @param effect_units units of effectiveness, in the plural (for example \code{"QALYs"} or +#' \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. #' @param min_prob minimum probability to show strategy in plot. #' For example, if the min_prob is 0.05, only strategies that ever #' exceed Pr(Cost Effective) = 0.05 will be plotted. Most useful in situations @@ -172,7 +187,7 @@ plot.ceac <- function(x, ylim = NULL, xlim = c(0, NA), col = c("access", "full", "bw"), - effect_units = "QALY", + effect_units = "QALYs", ...) { currency <- resolve_currency(currency, x) wtp_name <- "WTP" @@ -224,7 +239,7 @@ plot.ceac <- function(x, y = !!sym(prop_name), color = !!sym(strat_name))) + geom_line() + - xlab(paste("Willingness to Pay (Thousand ", currency, " / ", effect_units, ")", sep = "")) + + xlab(paste("Willingness to Pay (Thousand ", currency, " / ", per_unit(effect_units), ")", sep = "")) + ylab("Pr Most Cost-Effective") if (points) { diff --git a/R/evpi.R b/R/evpi.R index 237e3bb..d4be944 100644 --- a/R/evpi.R +++ b/R/evpi.R @@ -69,7 +69,9 @@ calc_evpi <- function(psa, wtp, pop = 1) { #' @param currency string with currency used in the cost-effectiveness analysis (CEA). #' Default: the currency of the PSA the results were computed from (or $), but it could be any #' currency symbol or word (e.g., £, €, peso) -#' @param effect_units units of effectiveness. Default: QALY +#' @param effect_units units of effectiveness, in the plural (for example \code{"QALYs"} or +#' \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 #' @return A \code{ggplot2} plot with the EVPI @@ -80,7 +82,7 @@ calc_evpi <- function(psa, wtp, pop = 1) { plot.evpi <- function(x, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -94,7 +96,7 @@ plot.evpi <- function(x, g <- ggplot(data = x, aes(x = WTP_thou, y = EVPI)) + geom_line() + - xlab(paste("Willingness to Pay (Thousand ", currency, "/", effect_units, ")", sep = "")) + + xlab(paste("Willingness to Pay (Thousand ", currency, "/", per_unit(effect_units), ")", sep = "")) + ylab(paste("EVPI (", currency, ")", sep = "")) add_common_aes(g, txtsize, continuous = c("x", "y"), n_x_ticks = n_x_ticks, n_y_ticks = n_y_ticks, diff --git a/R/evppi.R b/R/evppi.R index 483b7ff..2719cb7 100644 --- a/R/evppi.R +++ b/R/evppi.R @@ -143,7 +143,9 @@ calc_evppi <- function(psa, #' @param currency string with currency used in the cost-effectiveness analysis (CEA). #' Default: the currency of the PSA the results were computed from (or $), but it could be any #' currency symbol or word (e.g., £, €, peso) -#' @param effect_units units of effectiveness. Default: QALY +#' @param effect_units units of effectiveness, in the plural (for example \code{"QALYs"} or +#' \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 #' @return A \code{ggplot2} plot with the EVPPI @@ -154,7 +156,7 @@ calc_evppi <- function(psa, plot.evppi <- function(x, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -170,7 +172,7 @@ plot.evppi <- function(x, g <- ggplot(data = x, aes(x = WTP_thou, y = EVPPI)) + geom_line() + - xlab(paste("Willingness to Pay (Thousand ", currency, "/", effect_units, ")", sep = "")) + + xlab(paste("Willingness to Pay (Thousand ", currency, "/", per_unit(effect_units), ")", sep = "")) + ylab(paste("EVPPI (", v_units, ")", sep = "")) add_common_aes(g, txtsize, continuous = c("x", "y"), n_x_ticks = n_x_ticks, n_y_ticks = n_y_ticks, diff --git a/R/evsi.R b/R/evsi.R index 5a5f42d..4968bae 100644 --- a/R/evsi.R +++ b/R/evsi.R @@ -287,7 +287,9 @@ predict_matrix_tensor_smooth_ga <- function(object, #' @param currency string with currency used in the cost-effectiveness analysis (CEA). #' Default: the currency of the PSA the results were computed from (or $), but it could be any #' currency symbol or word (e.g., £, €, peso) -#' @param effect_units units of effectiveness. Default: QALY +#' @param effect_units units of effectiveness, in the plural (for example \code{"QALYs"} or +#' \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 #' @return A \code{ggplot2} plot with the EVSI @@ -298,7 +300,7 @@ predict_matrix_tensor_smooth_ga <- function(object, plot.evsi <- function(x, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -317,7 +319,7 @@ plot.evsi <- function(x, if (length(unique(x$WTP)) == 1) { col <- "bw" } - scale_text <- paste("Willingness to Pay\n(Thousand ", currency, "/", effect_units, ")", sep = "") + scale_text <- paste("Willingness to Pay\n(Thousand ", currency, "/", per_unit(effect_units), ")", sep = "") if (length(unique(x$WTP)) == 1 && "n" %in% names(x)) { g <- ggplot(data = x, diff --git a/R/exp_loss.R b/R/exp_loss.R index 368b5e5..05a9a3d 100644 --- a/R/exp_loss.R +++ b/R/exp_loss.R @@ -100,12 +100,15 @@ calc_exp_loss <- function(psa, wtp) { #' @param currency string with currency used in the cost-effectiveness analysis (CEA). #' Default: the currency of the PSA the results were computed from (or $), but it could be any #' currency symbol or word (e.g., £, €, peso) -#' @param effect_units units of effectiveness. Default: QALY +#' @param effect_units units of effectiveness, in the plural (for example \code{"QALYs"} or +#' \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. #' @param log_y take the base 10 log of the y axis #' @param frontier indicate the frontier (also the expected value of perfect information). #' To only plot the EVPI see \code{\link{calc_evpi}}. #' @param points whether to plot points on the curve (TRUE) or not (FALSE) -#' @param lsize line size. defaults to 1. +#' @param linewidth width of the lines. Defaults to 1. +#' @param lsize deprecated; use \code{linewidth} instead. #' @inheritParams add_common_aes #' #' @return A \code{ggplot2} object with the expected loss @@ -118,10 +121,10 @@ plot.exp_loss <- function(x, log_y = TRUE, frontier = TRUE, points = TRUE, - lsize = 1, + linewidth = 1, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -129,7 +132,12 @@ plot.exp_loss <- function(x, xlim = c(0, NA), ylim = NULL, col = c("access", "full", "bw"), + lsize = deprecated(), ...) { + if (is_present(lsize)) { + deprecate_soft("1.1.0", "plot.exp_loss(lsize)", "plot.exp_loss(linewidth)") + linewidth <- lsize + } On_Frontier <- NULL currency <- resolve_currency(currency, x) wtp_name <- "WTP_thou" @@ -154,7 +162,7 @@ plot.exp_loss <- function(x, p <- ggplot(data = df_nofront, aes(x = !!sym(wtp_name), y = !!sym(loss_name))) + - xlab(paste0("Willingness to Pay (Thousand ", currency, "/", effect_units, ")")) + + xlab(paste0("Willingness to Pay (Thousand ", currency, "/", per_unit(effect_units), ")")) + ylab(paste0("Expected Loss (", currency, ")")) # color @@ -165,7 +173,7 @@ plot.exp_loss <- function(x, p <- p + geom_point(aes(color = !!sym(strat_name))) } p <- p + - geom_line(linewidth = lsize, aes(color = !!sym(strat_name))) + geom_line(linewidth = linewidth, aes(color = !!sym(strat_name))) } if (col == "bw") { @@ -173,7 +181,7 @@ plot.exp_loss <- function(x, p <- p + geom_point() } p <- p + - geom_line(linewidth = lsize, aes(linetype = !!sym(strat_name))) + geom_line(linewidth = linewidth, aes(linetype = !!sym(strat_name))) } # in black and white, strategies are told apart by line type, so no color scale is added diff --git a/R/icers.R b/R/icers.R index 3bb7a2f..449bbe5 100644 --- a/R/icers.R +++ b/R/icers.R @@ -222,7 +222,7 @@ calculate_icers <- function(cost, effect, strategies, ref_str = NULL, wtp = NULL #' @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) + unit <- per_unit(effect_units) paste0("Dotted line: WTP = ", currency, format(wtp, big.mark = ",", scientific = FALSE, trim = TRUE), "/", unit) } diff --git a/R/owsa.R b/R/owsa.R index 07a0c27..42c1bc1 100644 --- a/R/owsa.R +++ b/R/owsa.R @@ -82,7 +82,10 @@ owsa <- function(sa_obj, params = NULL, ranges = NULL, nsamp = 100, #' @param x an owsa object #' @param txtsize base text size in the plot #' @param col either full-color ("full") or black and white ("bw") -#' @param size either point size (ptype = "point") and/or line size (ptype = "line") +#' @param linewidth width of the lines. Defaults to 1. +#' @param xlim,ylim limits of the x (parameter values) and y (outcome) axes, applied to every +#' panel, or \code{NULL} (the default) to set them automatically. +#' @param size deprecated; use \code{linewidth} instead. #' @param facet_scales whether the x or y axes should be fixed. #' See \code{\link[ggplot2]{facet_grid}} in the \code{ggplo2} package for #' more details. @@ -105,11 +108,18 @@ plot.owsa <- function(x, txtsize = 12, facet_scales = c("free_x", "free_y", "free", "fixed"), facet_nrow = NULL, facet_ncol = NULL, - size = 1, + linewidth = 1, n_x_ticks = 6, n_y_ticks = 6, basecase = NULL, + xlim = NULL, + ylim = NULL, + size = deprecated(), ...) { + if (is_present(size)) { + deprecate_soft("1.1.0", "plot.owsa(size)", "plot.owsa(linewidth)") + linewidth <- size + } param_val <- outcome_val <- strategy <- NULL v_strategies <- unique(x$strategy) scales <- match.arg(facet_scales) @@ -123,12 +133,12 @@ plot.owsa <- function(x, txtsize = 12, if (col == "full" || col == "access") { owsa <- owsa + geom_line(aes(color = strategy), - linewidth = size) + linewidth = linewidth) } if (col == "bw") { owsa <- owsa + geom_line(aes(linetype = strategy), - linewidth = size) + + linewidth = linewidth) + scale_linetype_discrete(name = "Strategy") } @@ -153,6 +163,7 @@ plot.owsa <- function(x, txtsize = 12, scale_name = "Strategy", n_x_ticks = n_x_ticks, n_y_ticks = n_y_ticks, continuous = c("x", "y"), + xlim = xlim, ylim = ylim, v_str = v_strategies) } @@ -333,7 +344,8 @@ owsa_opt_strat <- function(owsa, params = NULL, maximize = TRUE, facet_ncol = 1, facet_nrow = NULL, facet_lab_txtsize = NULL, - n_x_ticks = 10) { + n_x_ticks = 10, + xlim = NULL) { # check that is owsa object if (!is_owsa(owsa)) { stop("must provide an owsa object created with owsa()") @@ -396,7 +408,7 @@ owsa_opt_strat <- function(owsa, params = NULL, maximize = TRUE, g <- add_common_aes(g, txtsize, scale_name = "Optimal Strategy: ", col, col_aes = "fill", continuous = "x", facet_lab_txtsize = facet_lab_txtsize, - n_x_ticks = n_x_ticks) + + n_x_ticks = n_x_ticks, xlim = xlim) + # these remove the meaningless y axis labels and text theme(axis.line.y = element_blank(), axis.text.y = element_blank(), diff --git a/R/twsa.R b/R/twsa.R index dda650b..1227b54 100644 --- a/R/twsa.R +++ b/R/twsa.R @@ -98,6 +98,8 @@ plot.twsa <- function(x, maximize = TRUE, n_y_ticks = 6, txtsize = 12, basecase = NULL, + xlim = NULL, + ylim = NULL, ...) { outcome_val <- strategy <- NULL @@ -142,6 +144,7 @@ plot.twsa <- function(x, maximize = TRUE, continuous = c("x", "y"), n_x_ticks = n_x_ticks, n_y_ticks = n_y_ticks, + xlim = xlim, ylim = ylim, xexpand = c(0, 0), yexpand = c(0, 0)) } diff --git a/man/ceac.Rd b/man/ceac.Rd index 31ade6a..2662651 100644 --- a/man/ceac.Rd +++ b/man/ceac.Rd @@ -4,12 +4,12 @@ \alias{ceac} \title{Cost-Effectiveness Acceptability Curve (CEAC)} \usage{ -ceac(wtp, psa) +ceac(psa, wtp) } \arguments{ -\item{wtp}{numeric vector with willingness-to-pay (WTP) thresholds} - \item{psa}{psa object from \code{\link{make_psa_obj}}} + +\item{wtp}{numeric vector with willingness-to-pay (WTP) thresholds} } \value{ An object of class \code{ceac} that can be visualized with \code{plot}. The \code{ceac} @@ -22,6 +22,10 @@ particular WTP is on the cost-efficient frontier. curves (CEAC) from a probabilistic sensitivity analysis (PSA) dataset. } \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 +works but is deprecated; named arguments work in any order. + \code{ceac} computes the probability of each of the strategies being cost-effective at each \code{wtp} threshold. The returned object has classes \code{ceac} and \code{data.frame}, and has its own plot method (\code{\link{plot.ceac}}). @@ -36,7 +40,7 @@ psa_cancer <- make_psa_obj(cost = cancer_psa_data$cost, # define wtp threshold vector (can also use a single wtp) wtp <- seq(1e4, 1e5, by = 1e4) -ceac_obj <- ceac(wtp, psa_cancer) +ceac_obj <- ceac(psa_cancer, wtp) plot(ceac_obj) # see ?plot.ceac for options # this is most useful when there are many strategies diff --git a/man/owsa_opt_strat.Rd b/man/owsa_opt_strat.Rd index 77970a5..9ee511d 100644 --- a/man/owsa_opt_strat.Rd +++ b/man/owsa_opt_strat.Rd @@ -17,7 +17,8 @@ owsa_opt_strat( facet_ncol = 1, facet_nrow = NULL, facet_lab_txtsize = NULL, - n_x_ticks = 10 + n_x_ticks = 10, + xlim = NULL ) } \arguments{ @@ -48,6 +49,8 @@ changes in optimal strategy as they vary.} \item{facet_lab_txtsize}{text size for plot facet labels} \item{n_x_ticks}{number of x-axis ticks} + +\item{xlim}{vector of x-axis limits, or NULL, which sets limits automatically} } \value{ If \code{return == "plot"}, a \code{ggplot2} optimal strategy plot derived from the \code{owsa} diff --git a/man/per_unit.Rd b/man/per_unit.Rd new file mode 100644 index 0000000..10466c2 --- /dev/null +++ b/man/per_unit.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/add_common_aes.R +\name{per_unit} +\alias{per_unit} +\title{Singular form of the effect units, for "per unit" labels} +\usage{ +per_unit(effect_units) +} +\arguments{ +\item{effect_units}{units of effectiveness, such as \code{"QALYs"}.} +} +\value{ +a string. +} +\description{ +Drops a final "s", so \code{"QALYs"} becomes \code{"QALY"} in labels such as "$/QALY". A unit +already in the singular is returned unchanged. +} +\keyword{internal} diff --git a/man/plot.ceac.Rd b/man/plot.ceac.Rd index ff0e269..1b648e8 100644 --- a/man/plot.ceac.Rd +++ b/man/plot.ceac.Rd @@ -18,7 +18,7 @@ ylim = NULL, xlim = c(0, NA), col = c("access", "full", "bw"), - effect_units = "QALY", + effect_units = "QALYs", ... ) } @@ -56,7 +56,9 @@ will override \code{n_y_ticks} if provided.} \item{col}{either none, full color, accessible colors, or black and white} -\item{effect_units}{units of effectiveness, used in the x-axis label. Default: QALY} +\item{effect_units}{units of effectiveness, in the plural (for example \code{"QALYs"} or +\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.} \item{...}{further arguments to plot. This is not used by \code{dampack} but required for generic consistency.} diff --git a/man/plot.evpi.Rd b/man/plot.evpi.Rd index 1978b0f..49fc72d 100644 --- a/man/plot.evpi.Rd +++ b/man/plot.evpi.Rd @@ -8,7 +8,7 @@ x, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -28,7 +28,9 @@ Default: the currency of the PSA the results were computed from (or $), but it could be any currency symbol or word (e.g., £, €, peso)} -\item{effect_units}{units of effectiveness. Default: QALY} +\item{effect_units}{units of effectiveness, in the plural (for example \code{"QALYs"} or +\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.} \item{n_y_ticks}{number of y-axis ticks} diff --git a/man/plot.evppi.Rd b/man/plot.evppi.Rd index 519e9df..5584a62 100644 --- a/man/plot.evppi.Rd +++ b/man/plot.evppi.Rd @@ -8,7 +8,7 @@ x, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -28,7 +28,9 @@ Default: the currency of the PSA the results were computed from (or $), but it could be any currency symbol or word (e.g., £, €, peso)} -\item{effect_units}{units of effectiveness. Default: QALY} +\item{effect_units}{units of effectiveness, in the plural (for example \code{"QALYs"} or +\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.} \item{n_y_ticks}{number of y-axis ticks} diff --git a/man/plot.evsi.Rd b/man/plot.evsi.Rd index 0c9e858..0954135 100644 --- a/man/plot.evsi.Rd +++ b/man/plot.evsi.Rd @@ -8,7 +8,7 @@ x, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -29,7 +29,9 @@ Default: the currency of the PSA the results were computed from (or $), but it could be any currency symbol or word (e.g., £, €, peso)} -\item{effect_units}{units of effectiveness. Default: QALY} +\item{effect_units}{units of effectiveness, in the plural (for example \code{"QALYs"} or +\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.} \item{n_y_ticks}{number of y-axis ticks} diff --git a/man/plot.exp_loss.Rd b/man/plot.exp_loss.Rd index 0d46626..29f21d7 100644 --- a/man/plot.exp_loss.Rd +++ b/man/plot.exp_loss.Rd @@ -9,10 +9,10 @@ log_y = TRUE, frontier = TRUE, points = TRUE, - lsize = 1, + linewidth = 1, txtsize = 12, currency = NULL, - effect_units = "QALY", + effect_units = "QALYs", n_y_ticks = 8, n_x_ticks = 20, xbreaks = NULL, @@ -20,6 +20,7 @@ xlim = c(0, NA), ylim = NULL, col = c("access", "full", "bw"), + lsize = deprecated(), ... ) } @@ -34,7 +35,7 @@ To only plot the EVPI see \code{\link{calc_evpi}}.} \item{points}{whether to plot points on the curve (TRUE) or not (FALSE)} -\item{lsize}{line size. defaults to 1.} +\item{linewidth}{width of the lines. Defaults to 1.} \item{txtsize}{base text size} @@ -42,7 +43,9 @@ To only plot the EVPI see \code{\link{calc_evpi}}.} Default: the currency of the PSA the results were computed from (or $), but it could be any currency symbol or word (e.g., £, €, peso)} -\item{effect_units}{units of effectiveness. Default: QALY} +\item{effect_units}{units of effectiveness, in the plural (for example \code{"QALYs"} or +\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.} \item{n_y_ticks}{number of y-axis ticks} @@ -60,6 +63,8 @@ will override \code{n_y_ticks} if provided.} \item{col}{either none, full color, accessible colors, or black and white} +\item{lsize}{deprecated; use \code{linewidth} instead.} + \item{...}{further arguments to plot. This is not used by \code{dampack} but required for generic consistency.} } diff --git a/man/plot.owsa.Rd b/man/plot.owsa.Rd index da9224b..1645918 100644 --- a/man/plot.owsa.Rd +++ b/man/plot.owsa.Rd @@ -11,10 +11,13 @@ facet_scales = c("free_x", "free_y", "free", "fixed"), facet_nrow = NULL, facet_ncol = NULL, - size = 1, + linewidth = 1, n_x_ticks = 6, n_y_ticks = 6, basecase = NULL, + xlim = NULL, + ylim = NULL, + size = deprecated(), ... ) } @@ -35,7 +38,7 @@ more details.} The default (NULL) is passed to \code{\link[ggplot2]{facet_wrap}}, which determines the number of rows and columns automatically.} -\item{size}{either point size (ptype = "point") and/or line size (ptype = "line")} +\item{linewidth}{width of the lines. Defaults to 1.} \item{n_x_ticks}{number of x-axis ticks} @@ -45,6 +48,11 @@ which determines the number of rows and columns automatically.} on the returned plot. Each list element must have the same name as the corresponding parameter in the \code{owsa} object.} +\item{xlim, ylim}{limits of the x (parameter values) and y (outcome) axes, applied to every +panel, or \code{NULL} (the default) to set them automatically.} + +\item{size}{deprecated; use \code{linewidth} instead.} + \item{...}{further arguments to plot. This is not used by \code{dampack} but required for generic consistency.} } diff --git a/man/plot.twsa.Rd b/man/plot.twsa.Rd index 725df6b..7693230 100644 --- a/man/plot.twsa.Rd +++ b/man/plot.twsa.Rd @@ -12,6 +12,8 @@ n_y_ticks = 6, txtsize = 12, basecase = NULL, + xlim = NULL, + ylim = NULL, ... ) } @@ -33,6 +35,10 @@ on the returned plot. Each list element must have the same name as the corresponding parameter in the \code{owsa} object.} +\item{xlim}{vector of x-axis limits, or NULL, which sets limits automatically} + +\item{ylim}{vector of y-axis limits, or NULL, which sets limits automatically} + \item{...}{further arguments to plot. This is not used by \code{dampack} but required for generic consistency.} } diff --git a/tests/testthat/test_api_harmonize.R b/tests/testthat/test_api_harmonize.R new file mode 100644 index 0000000..e461072 --- /dev/null +++ b/tests/testthat/test_api_harmonize.R @@ -0,0 +1,68 @@ +# Harmonized arguments across the analysis and plot functions (#214). Old call forms keep +# working, with a soft deprecation warning. + +data("cancer_psa_data") +psa_big <- make_psa_obj(cancer_psa_data$cost, cancer_psa_data$effectiveness, + cancer_psa_data$parameters, cancer_psa_data$strategies) +v_wtp <- seq(1e4, 1e5, by = 3e4) + +test_that("ceac() takes psa first; the old (wtp, psa) order still works, deprecated", { + df_new <- ceac(psa_big, v_wtp) + expect_s3_class(df_new, "ceac") + # named arguments work in either order, without a warning + expect_no_warning(df_named <- ceac(wtp = v_wtp, psa = psa_big)) + expect_identical(df_named, df_new) + # the old positional order gives the same result and one deprecation warning + lifecycle::expect_deprecated(df_old <- ceac(v_wtp, psa_big), "must come after `psa`") + expect_identical(df_old, df_new) + # a non-psa first argument still gets the usual error + expect_error(ceac(v_wtp, v_wtp), "class `psa`") +}) + +test_that("plot.owsa() and plot.exp_loss() take linewidth; size and lsize are deprecated", { + o <- owsa(psa_big, outcome = "eff") + line_width <- function(p) { + i <- which(vapply(p$layers, function(l) inherits(l$geom, "GeomLine"), logical(1)))[1] + unique(ggplot2::layer_data(p, i)$linewidth) + } + expect_equal(line_width(plot(o, linewidth = 2)), 2) + lifecycle::expect_deprecated(p_old <- plot(o, size = 2), "linewidth") + expect_equal(line_width(p_old), 2) + + el <- calc_exp_loss(psa_big, v_wtp) + expect_equal(line_width(plot(el, linewidth = 2)), 2) + lifecycle::expect_deprecated(p_old <- plot(el, lsize = 2), "linewidth") + expect_equal(line_width(p_old), 2) +}) + +test_that("plot.owsa(), plot.twsa() and owsa_opt_strat() accept axis limits", { + scale_limits <- function(p, aes) p$scales$get_scales(aes)$limits + o <- owsa(psa_big, outcome = "eff") + p <- plot(o, xlim = c(0, 1), ylim = c(5, 15)) + expect_equal(scale_limits(p, "x"), c(0, 1)) + expect_equal(scale_limits(p, "y"), c(5, 15)) + expect_null(scale_limits(plot(o), "x")) + + tw <- twsa(psa_big, "pFailChemo", "muDieCancer", outcome = "eff") + p <- plot(tw, xlim = c(0.3, 0.6), ylim = c(0.05, 0.2)) + expect_equal(scale_limits(p, "x"), c(0.3, 0.6)) + expect_equal(scale_limits(p, "y"), c(0.05, 0.2)) + + o_nmb <- owsa(psa_big, outcome = "nmb", wtp = 1e5) + p <- owsa_opt_strat(o_nmb, xlim = c(0, 1)) + expect_equal(scale_limits(p, "x"), c(0, 1)) +}) + +test_that("effect_units defaults to QALYs everywhere, singular in per-unit labels", { + # the default labels are unchanged: "$/QALY" on willingness-to-pay axes + expect_match(plot(ceac(psa_big, v_wtp))$labels$x, "Thousand $ / QALY)", fixed = TRUE) + expect_match(plot(calc_exp_loss(psa_big, v_wtp))$labels$x, "Thousand $/QALY)", fixed = TRUE) + expect_match(plot(calc_evpi(psa_big, v_wtp))$labels$x, "Thousand $/QALY)", fixed = TRUE) + # plural units are made singular there; units already in the singular are kept + expect_match(plot(calc_evpi(psa_big, v_wtp), effect_units = "life-years")$labels$x, + "$/life-year)", fixed = TRUE) + expect_match(plot(calc_evpi(psa_big, v_wtp), effect_units = "QALY")$labels$x, + "$/QALY)", fixed = TRUE) + expect_equal(per_unit(c("QALYs", "QALY", "life-years", "DALYs averted")), + c("QALY", "QALY", "life-year", "DALYs averted")) +}) diff --git a/tests/testthat/test_ceac.R b/tests/testthat/test_ceac.R index 3a03f6d..2a0787d 100644 --- a/tests/testthat/test_ceac.R +++ b/tests/testthat/test_ceac.R @@ -18,7 +18,7 @@ psa_obj <- make_psa_obj(cancer_psa_data$cost, cancer_psa_data$strategies) test_that("result has class 'ceac'", { - c <- ceac(wtp, psa_obj) + c <- ceac(psa_obj, wtp) expect_true(inherits(c, "data.frame")) expect_true(inherits(c, "ceac")) }) @@ -27,7 +27,7 @@ test_that("handles missing strategy", { psa_missing <- make_psa_obj(cancer_psa_data$cost, cancer_psa_data$effectiveness, cancer_psa_data$parameters) - c_missing <- ceac(wtp, psa_missing) + c_missing <- ceac(psa_missing, wtp) expected_generic_strat <- factor(c("Strategy_1", "Strategy_2", "Strategy_3"), ordered = TRUE) obtained_generic_strat <- sort(unique(c_missing$Strategy)) expect_equal(expected_generic_strat, obtained_generic_strat) @@ -38,7 +38,7 @@ test_that("handles missing strategy", { ## summary test_that("message is correct in summary.ceac", { - c <- ceac(wtp, psa_obj) + c <- ceac(psa_obj, wtp) df_sum <- summary(c) expect_equal(df_sum$optimal_strategy, c("Radio", "Chemo")) }) @@ -65,7 +65,7 @@ test_that("summary.ceac summarizes a real psa whose frontier switches many times data("df_example_psa_elc") l_psa <- make_psa_obj(cost = df_example_psa_elc[, 1:6], effectiveness = df_example_psa_elc[, 7:12]) - df_ceac <- ceac(seq(1000, 150000, 1000), l_psa) + df_ceac <- ceac(l_psa, seq(1000, 150000, 1000)) df_sum <- summary(df_ceac) # expected intervals derived independently, by run-length encoding the frontier @@ -83,7 +83,7 @@ test_that("summary.ceac summarizes a real psa whose frontier switches many times ## plot test_that("plot.ceac produces ggplot object", { - ceac_obj <- ceac(wtp, psa_obj) + ceac_obj <- ceac(psa_obj, wtp) gf <- plot(ceac_obj, frontier = TRUE) expect_s3_class(gf, "ggplot") @@ -107,7 +107,7 @@ test_that("near-tied strategies are not chosen at random (#167)", { psa_tie <- make_psa_obj(df_c, df_e, strategies = c("A", "B")) for (seed in 1:3) { set.seed(seed) - df_ceac <- ceac(1e5, psa_tie) + df_ceac <- ceac(psa_tie, 1e5) expect_equal(df_ceac$Proportion[df_ceac$Strategy == "B"], 1) expect_equal(calc_evpi(psa_tie, 1e5)$EVPI, 0) df_elc <- calc_exp_loss(psa_tie, 1e5) @@ -120,7 +120,7 @@ test_that("exact ties are broken deterministically, in favor of the first strate psa_same <- make_psa_obj(df_same, df_same, strategies = c("A", "B")) v_prop <- vapply(1:5, function(seed) { set.seed(seed) - df_ceac <- ceac(100, psa_same) + df_ceac <- ceac(psa_same, 100) df_ceac$Proportion[df_ceac$Strategy == "A"] }, numeric(1)) expect_equal(v_prop, rep(1, 5)) diff --git a/tests/testthat/test_currency.R b/tests/testthat/test_currency.R index fbc3e12..ef984d0 100644 --- a/tests/testthat/test_currency.R +++ b/tests/testthat/test_currency.R @@ -10,7 +10,7 @@ v_wtp <- seq(10000, 100000, by = 30000) eur <- "€" test_that("ceac() and calc_exp_loss() keep the currency and use it in their plots", { - df_ceac <- ceac(v_wtp, psa_eur) + df_ceac <- ceac(psa_eur, v_wtp) expect_identical(attr(df_ceac, "currency"), eur) expect_match(plot(df_ceac)$labels$x, eur, fixed = TRUE) expect_match(plot(df_ceac, currency = "£")$labels$x, "£", fixed = TRUE) @@ -29,11 +29,11 @@ test_that("EVPI, EVPPI, and EVSI plots use the currency or the health units of t evppi_nmb <- calc_evppi(psa_eur, v_wtp, params = "pFailChemo", outcome = "nmb", progress = FALSE) expect_equal(plot(evppi_nmb)$labels$y, paste0("EVPPI (", eur, ")")) evppi_nhb <- calc_evppi(psa_eur, v_wtp, params = "pFailChemo", outcome = "nhb", progress = FALSE) - expect_equal(plot(evppi_nhb)$labels$y, "EVPPI (QALY)") + expect_equal(plot(evppi_nhb)$labels$y, "EVPPI (QALYs)") # calc_evsi() defaults to outcome = "nhb", whose EVSI is in health units, not currency evsi_nhb <- calc_evsi(psa_eur, v_wtp, params = "pFailChemo", n = 100, n0 = 10, progress = FALSE) - expect_equal(plot(evsi_nhb)$labels$y, "EVSI (QALY)") + expect_equal(plot(evsi_nhb)$labels$y, "EVSI (QALYs)") evsi_nmb <- calc_evsi(psa_eur, v_wtp, params = "pFailChemo", n = 100, n0 = 10, outcome = "nmb", progress = FALSE) expect_equal(plot(evsi_nmb)$labels$y, paste0("EVSI (", eur, ")")) @@ -49,6 +49,6 @@ test_that("calculate_icers_psa() keeps the currency for print and plot", { }) test_that("a dollar psa object still gives dollar labels", { - expect_match(plot(ceac(v_wtp, psa_usd))$labels$x, "$", fixed = TRUE) + expect_match(plot(ceac(psa_usd, v_wtp))$labels$x, "$", fixed = TRUE) expect_equal(plot(calc_evpi(psa_usd, v_wtp))$labels$y, "EVPI ($)") }) diff --git a/tests/testthat/test_elc.R b/tests/testthat/test_elc.R index 0b8289e..cd0eeb1 100644 --- a/tests/testthat/test_elc.R +++ b/tests/testthat/test_elc.R @@ -60,9 +60,9 @@ test_that("plot.exp_loss runs with several combinations of arguments", { }) # black-and-white expected loss curves ignored lsize and warned about an unused color scale (#210) -test_that("plot.exp_loss(col = 'bw') uses lsize and builds without warnings", { +test_that("plot.exp_loss(col = 'bw') uses linewidth and builds without warnings", { el <- calc_exp_loss(psa_obj, wtp = seq(1e4, 1e5, 1e4)) - g <- plot(el, col = "bw", lsize = 3) + g <- plot(el, col = "bw", linewidth = 3) expect_warning(b <- ggplot2::ggplot_build(g), NA) i_line <- which(vapply(g$layers, function(l) inherits(l$geom, "GeomLine"), logical(1))) expect_equal(unique(b$data[[i_line]]$linewidth), 3) diff --git a/tests/testthat/test_plot_options.R b/tests/testthat/test_plot_options.R index e639464..6ce3691 100644 --- a/tests/testthat/test_plot_options.R +++ b/tests/testthat/test_plot_options.R @@ -41,7 +41,7 @@ test_that("plot.psa() without center points builds without a fill-scale warning" }) test_that("plot.ceac(): frontier, points, and min_prob", { - df_ceac <- ceac(v_wtp, psa_big) + df_ceac <- ceac(psa_big, v_wtp) expect_true("GeomPoint" %in% geoms(plot(df_ceac))) p_plain <- plot(df_ceac, frontier = FALSE, points = FALSE) expect_false("GeomPoint" %in% geoms(p_plain)) diff --git a/tests/testthat/test_strategy_names.R b/tests/testthat/test_strategy_names.R index 9949c4b..cc00c4c 100644 --- a/tests/testthat/test_strategy_names.R +++ b/tests/testthat/test_strategy_names.R @@ -29,7 +29,7 @@ test_that("ICERs, CEAC, expected loss, and EVPI keep the names", { df_icers <- calculate_icers(df_sum$meanCost, df_sum$meanEffect, df_sum$Strategy) expect_setequal(df_icers$Strategy, v_names) - df_ceac <- ceac(v_wtp, l_psa) + df_ceac <- ceac(l_psa, v_wtp) expect_setequal(as.character(unique(df_ceac$Strategy)), v_names) expect_true(all(summary(df_ceac)$optimal_strategy %in% v_names)) @@ -59,7 +59,7 @@ test_that("metamodel-based analyses work with non-syntactic names", { test_that("plot legends show the names exactly as typed", { l_psa <- make_named_psa() expect_setequal(guide_labels(plot(l_psa)), v_names) - expect_setequal(guide_labels(plot(ceac(v_wtp, l_psa))), v_names) + expect_setequal(guide_labels(plot(ceac(l_psa, v_wtp))), v_names) expect_setequal(guide_labels(plot(calc_exp_loss(l_psa, v_wtp))), v_names) df_owsa <- owsa(l_psa, params = "pFailChemo", outcome = "nmb", wtp = 50000) expect_setequal(guide_labels(plot(df_owsa)), v_names)