Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
648d937
Compare strategies with a user-selected reference in calculate_icers()
feralaes Nov 12, 2026
fa72c22
Plot the incremental CE plane against a reference strategy, with WTP …
feralaes Nov 12, 2026
481dfa5
Reference strategy and quadrant shares in summary.psa() and calculate…
feralaes Nov 12, 2026
a22ee3d
Merge pull request #228 from DARTH-git/209-reference-strategy-plots
feralaes Nov 12, 2026
caeda9e
Merge pull request #229 from DARTH-git/209-reference-strategy-psa
feralaes Nov 12, 2026
de80cd4
Merge remote-tracking branch 'origin/main' into 209-reference-strateg…
feralaes Nov 13, 2026
915cac8
Merge main into 209-reference-strategy-core; keep this PR's NEWS bug-…
feralaes Nov 13, 2026
3886a04
Carry the currency of a psa object through to its analyses
feralaes Nov 13, 2026
33c9905
Merge pull request #242 from DARTH-git/203-currency
feralaes Nov 13, 2026
308850f
Address review of #227: reference-first print order, Inc_NMB_ref nami…
feralaes Nov 13, 2026
53b8ba1
Merge remote-tracking branch 'origin/main' into 209-reference-strateg…
feralaes Nov 13, 2026
ae98e8c
Merge-with-main fixes: identical plot.icers data with or without unce…
feralaes Nov 13, 2026
2b6a447
Merge remote-tracking branch 'origin/main' into 209-reference-strateg…
feralaes Nov 14, 2026
64c6584
plot.psa(): xtrans/ytrans, with ellipses computed on the transformed …
feralaes Nov 14, 2026
95dcc22
Harmonize the API with soft deprecation (#214): ceac(psa, wtp), linew…
feralaes Nov 14, 2026
785f347
Merge pull request #250 from DARTH-git/201-psa-ellipse-log
feralaes Nov 14, 2026
0d6af8e
Require lifecycle (>= 1.0.3): ggplot2 3.5.0 needs lifecycle > 1.0.1
feralaes Nov 14, 2026
2861f85
Merge remote-tracking branch 'origin/209-reference-strategy-core' int…
feralaes Nov 14, 2026
b7d53e9
List lifecycle without a version bound
feralaes Nov 14, 2026
6afb4a7
Merge pull request #251 from DARTH-git/214-api-harmonize
feralaes Nov 14, 2026
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
13 changes: 13 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

## 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).
- `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, drawn through the reference strategy or, without one, through the least costly strategy. `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 `Inc_NMB_ref` with a reference strategy), and `nhb = TRUE`, which also adds the net health benefit (`NHB`, `Inc_NHB_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).
- `print.icers()` prints a formatted ICER table, with options for the currency symbol and the number of digits (#184, #171).
- `plot.psa()` gains a `ref_str` argument that plots the PSA on the incremental cost-effectiveness plane relative to a chosen reference strategy (#188).
- Plotting functions now default to an accessible, colorblind-friendly palette (`col = "access"`, based on viridis). The previous palettes remain available as `col = "full"` and `col = "bw"`.
Expand All @@ -11,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 All @@ -22,6 +33,8 @@

## Bug fixes

- EVPPI and EVSI computed from net health benefit (`outcome = "nhb"`, the default of `calc_evsi()`) are in health units, and their plots are now labeled with `effect_units` (e.g., "EVSI (QALY)") instead of a currency (#203).
- `plot.psa(ref_str = )` now works when there are only two strategies; it used to fail with "'dims' cannot be of length 0" (#209).
- The `hund_strat` help page now describes the data (simulated costs and QALYs for 100 hypothetical strategies) and its columns, with an example. Typos in several help pages are fixed (#219).
- `plot.psa(center = FALSE)` no longer warns "No shared levels found between `names(values)` of the manual scale and the data's fill values" when it is drawn. The fill scale is now added only when the center points that use it are.
- `plot.owsa(col = "bw")` now draws each strategy with its own line type; all strategies used to share one line type and could not be told apart (#176).
Expand Down
39 changes: 39 additions & 0 deletions R/add_common_aes.R
Original file line number Diff line number Diff line change
Expand Up @@ -252,3 +252,42 @@ number_ticks <- function(n) {
pretty(limits, n + 1)
}
}

#' Currency to use for labels
#'
#' @param currency currency given by the user, or \code{NULL}.
#' @param x a result object that may carry a \code{"currency"} attribute.
#' @return \code{currency} if given, otherwise the currency stored on \code{x}, otherwise \code{"$"}.
#' @keywords internal
resolve_currency <- function(currency, x) {
if (!is.null(currency)) {
return(currency)
}
if (is.null(attr(x, "currency"))) "$" else attr(x, "currency")
}

#' Units of a value-of-information result
#'
#' EVPPI and EVSI computed from net health benefit are in health units; from net monetary
#' benefit, in currency.
#'
#' @param x an \code{evppi} or \code{evsi} object.
#' @param currency currency label.
#' @param effect_units units of effectiveness.
#' @return \code{effect_units} if \code{x} was computed with \code{outcome = "nhb"}, else \code{currency}.
#' @keywords internal
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)
}
32 changes: 26 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 @@ -124,6 +137,7 @@ ceac <- function(wtp, psa) {
# define classes
# defining data.frame as well allows the object to use print.data.frame, for example
class(ceac) <- c("ceac", "data.frame")
attr(ceac, "currency") <- psa$currency

ceac
}
Expand All @@ -136,7 +150,11 @@ ceac <- function(wtp, psa) {
#' @param frontier whether to plot acceptability frontier (TRUE) or not (FALSE)
#' @param points whether to plot points (TRUE) or not (FALSE)
#' @param currency string with currency used in the cost-effectiveness analysis (CEA).
#'Defaults to \code{$}, but can be any currency symbol or word (e.g., £, €, peso)
#' 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, 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 All @@ -159,7 +177,7 @@ ceac <- function(wtp, psa) {
plot.ceac <- function(x,
frontier = TRUE,
points = TRUE,
currency = "$",
currency = NULL,
min_prob = 0,
txtsize = 12,
n_x_ticks = 10,
Expand All @@ -169,7 +187,9 @@ plot.ceac <- function(x,
ylim = NULL,
xlim = c(0, NA),
col = c("access", "full", "bw"),
effect_units = "QALYs",
...) {
currency <- resolve_currency(currency, x)
wtp_name <- "WTP"
prop_name <- "Proportion"
strat_name <- "Strategy"
Expand Down Expand Up @@ -219,7 +239,7 @@ plot.ceac <- function(x,
y = !!sym(prop_name),
color = !!sym(strat_name))) +
geom_line() +
xlab(paste("Willingness to Pay (Thousand ", currency, " / QALY)", sep = "")) +
xlab(paste("Willingness to Pay (Thousand ", currency, " / ", per_unit(effect_units), ")", sep = "")) +
ylab("Pr Most Cost-Effective")

if (points) {
Expand Down
15 changes: 10 additions & 5 deletions R/evpi.R
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ calc_evpi <- function(psa, wtp, pop = 1) {

# declare class as both evpi (plotting) and data.frame (printing)
class(df_evpi) <- c("evpi", "data.frame")
attr(df_evpi, "currency") <- psa$currency
df_evpi
}

Expand All @@ -66,8 +67,11 @@ calc_evpi <- function(psa, wtp, pop = 1) {
#' @param x object of class \code{evpi}, produced by function
#' \code{\link{calc_evpi}}
#' @param currency string with currency used in the cost-effectiveness analysis (CEA).
#' Default: $, but it could be any currency symbol or word (e.g., £, €, peso)
#' @param effect_units units of effectiveness. Default: QALY
#' 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, 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 @@ -77,8 +81,8 @@ calc_evpi <- function(psa, wtp, pop = 1) {
#' @export
plot.evpi <- function(x,
txtsize = 12,
currency = "$",
effect_units = "QALY",
currency = NULL,
effect_units = "QALYs",
n_y_ticks = 8,
n_x_ticks = 20,
xbreaks = NULL,
Expand All @@ -87,11 +91,12 @@ plot.evpi <- function(x,
ylim = NULL,
...) {
WTP_thou <- EVPI <- NULL
currency <- resolve_currency(currency, x)
x$WTP_thou <- x$WTP / 1000
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
20 changes: 14 additions & 6 deletions R/evppi.R
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ calc_evppi <- function(psa,
# define parameter values and make sure they correspond to a valid option
type <- match.arg(type)
outcome <- match.arg(outcome)
outcome_input <- outcome

# adjust outcome type
outcome <- paste0(outcome, "_loss_voi")
Expand Down Expand Up @@ -127,6 +128,8 @@ calc_evppi <- function(psa,

evppi_ls <- list(df_evppi = df_evppi, metamodel_ls = l_mms)
class(evppi_ls) <- c("evppi")
attr(evppi_ls, "currency") <- psa$currency
attr(evppi_ls, "outcome") <- outcome_input
evppi_ls
}

Expand All @@ -138,8 +141,11 @@ calc_evppi <- function(psa,
#' @param x object of class \code{evppi}, produced by function
#' \code{\link{calc_evppi}}
#' @param currency string with currency used in the cost-effectiveness analysis (CEA).
#' Default: $, but it could be any currency symbol or word (e.g., £, €, peso)
#' @param effect_units units of effectiveness. Default: QALY
#' 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, 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 @@ -149,8 +155,8 @@ calc_evppi <- function(psa,
#' @export
plot.evppi <- function(x,
txtsize = 12,
currency = "$",
effect_units = "QALY",
currency = NULL,
effect_units = "QALYs",
n_y_ticks = 8,
n_x_ticks = 20,
xbreaks = NULL,
Expand All @@ -159,13 +165,15 @@ plot.evppi <- function(x,
ylim = NULL,
...) {
WTP_thou <- EVPPI <- NULL
currency <- resolve_currency(currency, x)
v_units <- voi_units(x, currency, effect_units)
x <- x[[1]]
x$WTP_thou <- x$WTP / 1000
g <- ggplot(data = x,
aes(x = WTP_thou, y = EVPPI)) +
geom_line() +
xlab(paste("Willingness to Pay (Thousand ", currency, "/", effect_units, ")", sep = "")) +
ylab(paste("EVPPI (", currency, ")", 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,
xbreaks = xbreaks, ybreaks = ybreaks,
Expand Down
Loading
Loading