Skip to content
Merged
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
27 changes: 27 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions DESCRIPTION
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ Imports:
triangle,
ggrepel,
tidyr,
lifecycle,
rlang,
viridis,
RColorBrewer
Expand Down
3 changes: 3 additions & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
3 changes: 3 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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
Expand Down
12 changes: 12 additions & 0 deletions R/add_common_aes.R
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
27 changes: 21 additions & 6 deletions R/ceac.R
Original file line number Diff line number Diff line change
Expand Up @@ -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}}).
Expand All @@ -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
Expand All @@ -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)

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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) {
Expand Down
8 changes: 5 additions & 3 deletions R/evpi.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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,
Expand Down
8 changes: 5 additions & 3 deletions R/evppi.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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,
Expand Down
8 changes: 5 additions & 3 deletions R/evsi.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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,
Expand Down
22 changes: 15 additions & 7 deletions R/exp_loss.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -118,18 +121,23 @@ 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,
ybreaks = NULL,
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"
Expand All @@ -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
Expand All @@ -165,15 +173,15 @@ 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") {
if (points) {
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
Expand Down
2 changes: 1 addition & 1 deletion R/icers.R
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down
Loading
Loading