diff --git a/.Rbuildignore b/.Rbuildignore
index c67a5e5..731edee 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -14,3 +14,5 @@
^codecov\.yml$
^LICENSE\.md$
^CODE_OF_CONDUCT\.md$
+^README\.Rmd$
+^logo$
diff --git a/.github/workflows/check-min-deps.yaml b/.github/workflows/check-min-deps.yaml
index ccb5581..f095174 100644
--- a/.github/workflows/check-min-deps.yaml
+++ b/.github/workflows/check-min-deps.yaml
@@ -3,6 +3,8 @@
# Runs R CMD check with the *minimum* versions of the dependencies declared in DESCRIPTION
# (for example ggplot2 (>= 3.5.0) installs ggplot2 3.5.0), so that a lower bound that is too low
# fails CI instead of failing for users with older packages (as with #198).
+# It runs twice: on the current R release, and on the minimum R version in DESCRIPTION
+# (`R (>= x.y)`), so that the R bound is tested too.
on:
push:
branches: [main]
@@ -19,18 +21,39 @@ concurrency:
jobs:
min-deps:
- runs-on: ubuntu-latest
- name: minimum dependency versions
+ runs-on: ${{ matrix.os }}
+ name: minimum dependency versions (R ${{ matrix.r }})
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - {r: 'release', os: ubuntu-latest}
+ # An old R needs an Ubuntu release that the package manager still builds binaries
+ # for, and the Bioconductor mirrors of that era are gone (dampack uses none).
+ - {r: 'minimum', os: ubuntu-24.04}
env:
GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
R_KEEP_PKG_SOURCE: yes
+ PKG_USE_BIOCONDUCTOR: false
steps:
- uses: actions/checkout@v6
- uses: r-lib/actions/setup-pandoc@v2
+ - name: Resolve the R version
+ id: rver
+ run: |
+ if [ "${{ matrix.r }}" = "minimum" ]; then
+ v=$(grep -oE 'R \(>= *[0-9.]+\)' DESCRIPTION | grep -oE '[0-9.]+')
+ else
+ v=release
+ fi
+ echo "R version: $v"
+ echo "version=$v" >> "$GITHUB_OUTPUT"
+
- uses: r-lib/actions/setup-r@v2
with:
+ r-version: ${{ steps.rver.outputs.version }}
use-public-rspm: true
- uses: r-lib/actions/setup-r-dependencies@v2
diff --git a/DESCRIPTION b/DESCRIPTION
index fad7bb3..b90d60a 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -47,7 +47,7 @@ BugReports: https://github.com/DARTH-git/dampack/issues
Encoding: UTF-8
Language: en-US
Depends:
- R (>= 4.1.0),
+ R (>= 4.2.0),
ggplot2 (>= 3.5.0)
Imports:
ellipse,
@@ -67,8 +67,10 @@ Suggests:
testthat,
knitr,
rmarkdown,
- kableExtra
+ kableExtra,
+ ragg
LazyData: true
+LazyDataCompression: xz
BuildResaveData: no
RoxygenNote: 7.3.2
VignetteBuilder: knitr
diff --git a/NAMESPACE b/NAMESPACE
index 4fb5b30..1dca31c 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,6 +1,7 @@
# Generated by roxygen2: do not edit by hand
S3method(plot,ceac)
+S3method(plot,cers_ref)
S3method(plot,evpi)
S3method(plot,evppi)
S3method(plot,evsi)
@@ -10,6 +11,7 @@ S3method(plot,owsa)
S3method(plot,psa)
S3method(plot,twsa)
S3method(predict,metamodel)
+S3method(print,cers_ref)
S3method(print,icers)
S3method(print,metamodel)
S3method(print,sa)
@@ -21,6 +23,8 @@ export(calc_evpi)
export(calc_evppi)
export(calc_evsi)
export(calc_exp_loss)
+export(calculate_cers_ref)
+export(calculate_cers_ref_psa)
export(calculate_icers)
export(calculate_icers_psa)
export(ceac)
diff --git a/NEWS.md b/NEWS.md
index d890ef5..9d802f2 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -5,12 +5,10 @@
- `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).
+- New `calculate_cers_ref()` and `calculate_cers_ref_psa()` compare every strategy with a reference strategy chosen by the user, such as the standard of care: the difference in cost and effect from the reference, the cost-effectiveness ratio (CER) of that difference, and the status relative to the reference ("Dominant", "Dominated", "More costly, more effective", "Less costly, less effective", or "Equivalent"). With `wtp`, they add the net monetary benefit and its difference from the reference. From a PSA, `uncertainty = TRUE` adds 95% intervals for the differences and the proportion of samples in each quadrant of the incremental cost-effectiveness plane and, with `wtp`, the proportion that is cost-effective compared with the reference. `plot()` draws the incremental plane centered at the reference, with a segment to each strategy and an optional willingness-to-pay line. These comparisons complement, and do not replace, the fully incremental analysis of `calculate_icers()`, which HTA guidelines require; the documentation cites the NICE, CDA-AMC, and Zorginstituut Nederland guidelines (#209).
+- `plot.icers()` gains `incremental = TRUE`, which plots the incremental cost-effectiveness plane with the first non-dominated strategy (the least costly strategy on the frontier) at the origin, and `wtp`, which draws a willingness-to-pay line through that strategy. `plot.psa()` gains `wtp` for the same line, drawn through the reference strategy or, without one, through the least costly strategy (#209, #202).
+- `calculate_icers()` and `calculate_icers_psa()` gain `wtp`, which adds the net monetary benefit (`NMB`) of each strategy, and `nhb = TRUE`, which also adds the net health benefit (`NHB`) (#200).
+- `calculate_icers()` gains `currency`, which `print.icers()` and `plot.icers()` use (#203).
- `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"`.
@@ -28,13 +26,14 @@
- Strategy names are now kept exactly as provided in `make_psa_obj()`, `create_dsa_oneway()`, `create_dsa_twoway()`, and the objects built from them, so names such as "Standard of care" appear unchanged in tables and plot legends. Previously they were converted with `make.names()` (to `Standard.of.care`) with a warning. Code that refers to the converted names must use the original ones, for example `psa$cost[["Standard of care"]]` instead of `psa$cost$Standard.of.care`. Strategy names must be unique and not missing or empty, and a wrong number of names now gives an informative error (#208).
- `summary.ceac()` renames its third output column from `cost_eff_strat` to `optimal_strategy`. Code that refers to the old column name with `$cost_eff_strat` must be updated (#173).
-- dampack now requires R 4.1.0 or later, the minimum required by current versions of ggplot2.
+- dampack now requires R 4.2.0 or later. Current versions of its dependencies need at least R 4.1.3 (triangle), and CRAN only accepts R bounds of the form x.y.0.
- dampack now requires ggplot2 3.5.0 or later and scales 1.3.0 or later, for ggplot2's `transform` argument and `scales::new_transform()` (#211).
## 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).
+- `plot.exp_loss()` with its default log-scale y axis (`log_y = TRUE`) now labels every order of magnitude. Its evenly spaced default breaks used to bunch up at the top of the log axis and leave the lower curves without any labels.
- 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).
diff --git a/R/cers_ref.R b/R/cers_ref.R
new file mode 100644
index 0000000..c26d5e0
--- /dev/null
+++ b/R/cers_ref.R
@@ -0,0 +1,481 @@
+# nolint start: line_length_linter. (guideline URL in the references)
+#' Compare every strategy with a reference strategy
+#'
+#' @description
+#' Compares each strategy with a single reference strategy chosen by the user, such as the
+#' current standard of care: the difference in cost and in effect from the reference, the
+#' cost-effectiveness ratio (CER) of that difference, and where each strategy lies on the
+#' incremental cost-effectiveness plane centered at the reference.
+#'
+#' These comparisons are \emph{not} the incremental cost-effectiveness ratios (ICERs) of a
+#' fully incremental analysis. When more than two strategies are compared, health technology
+#' assessment guidelines require a fully incremental (sequential) analysis, in which dominated
+#' and extendedly dominated strategies are removed and each strategy on the cost-effectiveness
+#' frontier is compared with the next less costly one: use \code{\link{calculate_icers}} for that.
+#' Comparisons with a single reference are a complement for settings where they are relevant
+#' and justified. The NICE manual (2022), for example, states that "pairwise comparisons may be
+#' presented when relevant and justified (for example, when the technology is expected to
+#' specifically displace individual comparators)", after requiring a fully incremental
+#' analysis. The CDA-AMC (2017) and Zorginstituut Nederland (2024) guidelines also require a
+#' sequential analysis when more than two interventions are compared.
+#'
+#' @param cost vector of cost for each strategy.
+#' @param effect vector of effect for each strategy.
+#' @param strategies string vector of strategy names.
+#' @param ref_str name of the reference strategy, one of \code{strategies}, for example
+#' \code{"Standard of care"}.
+#' @param wtp a single willingness-to-pay threshold (currency per unit of effect). If given, the
+#' net monetary benefit of each strategy and its difference from the reference are added.
+#' The default (\code{NULL}) adds no net-benefit columns.
+#' @param nhb if \code{TRUE}, also add the net health benefit and its difference from the
+#' reference. Requires \code{wtp}.
+#' @param currency currency symbol used when printing and plotting the results, for example
+#' \code{"€"}. The default (\code{NULL}) uses \code{"$"}.
+#'
+#' @return A data frame of class \code{cers_ref}, with the reference strategy in the first row
+#' and the other strategies by increasing cost, and these columns:
+#' \describe{
+#' \item{Strategy, Cost, Effect}{as given.}
+#' \item{Inc_Cost, Inc_Effect}{cost and effect minus those of the reference.}
+#' \item{CER}{\code{Inc_Cost / Inc_Effect}, the cost-effectiveness ratio compared with the
+#' reference. It is \code{NA} where a ratio is not meaningful: for the reference itself and for
+#' dominant, dominated and equivalent strategies.}
+#' \item{Status}{one of \code{"Reference"}, \code{"Dominant"} (not more costly and at least as
+#' effective), \code{"Dominated"} (not less costly and no more effective),
+#' \code{"More costly, more effective"}, \code{"Less costly, less effective"}, or
+#' \code{"Equivalent"} (same cost and effect).}
+#' \item{NMB, Inc_NMB}{with \code{wtp}: the net monetary benefit, \code{wtp * Effect - Cost},
+#' and its difference from the reference. A strategy with a positive \code{Inc_NMB} is
+#' cost-effective compared with the reference at this threshold.}
+#' \item{NHB, Inc_NHB}{with \code{nhb = TRUE}: the net health benefit,
+#' \code{Effect - Cost / wtp}, and its difference from the reference.}
+#' }
+#' The reference strategy, threshold and currency are stored as attributes, which the
+#' \code{print} and \code{plot} methods use.
+#'
+#' For a strategy that is more costly and more effective than the reference, a \code{CER} below
+#' the willingness-to-pay threshold means it is cost-effective compared with the reference. For a
+#' strategy that is less costly and less effective, the \code{CER} is the cost saved per unit of
+#' effect lost, and the strategy is cost-effective compared with the reference when its
+#' \code{CER} is \emph{above} the threshold.
+#'
+#' @references
+#' National Institute for Health and Care Excellence (NICE). NICE health technology evaluations:
+#' the manual (PMG36), section 4.6, "Economic evaluation". London: NICE; 2022.
+#' \url{https://www.nice.org.uk/process/pmg36/chapter/economic-evaluation-2}
+#'
+#' CDA-AMC (formerly CADTH). Guidelines for the Economic Evaluation of Health Technologies:
+#' Canada. 4th ed. Ottawa: CADTH; 2017.
+#' \url{https://www.cda-amc.ca/sites/default/files/pdf/guidelines_for_the_economic_evaluation_of_health_technologies_canada_4th_ed.pdf}
+#'
+#' Zorginstituut Nederland. Guideline for economic evaluations in healthcare (2024 version).
+#' Diemen: Zorginstituut Nederland; 2024.
+#' \url{https://english.zorginstituutnederland.nl/documents/2024/01/16/guideline-for-economic-evaluations-in-healthcare}
+#'
+#' @seealso \code{\link{plot.cers_ref}}, \code{\link{calculate_cers_ref_psa}} for the same
+#' comparison from a PSA, and \code{\link{calculate_icers}} for the fully incremental analysis.
+#'
+#' @examples
+#' # three strategies; "Standard of care" is neither the cheapest nor the least effective
+#' df_ref <- calculate_cers_ref(cost = c(12000, 9000, 20000),
+#' effect = c(8.0, 7.6, 8.5),
+#' strategies = c("Standard of care", "Generic drug", "New drug"),
+#' ref_str = "Standard of care",
+#' wtp = 50000)
+#' df_ref
+#' plot(df_ref)
+#'
+#' # the fully incremental analysis of the same strategies
+#' calculate_icers(cost = c(12000, 9000, 20000),
+#' effect = c(8.0, 7.6, 8.5),
+#' strategies = c("Standard of care", "Generic drug", "New drug"))
+#' @export
+calculate_cers_ref <- function(cost, effect, strategies, ref_str, wtp = NULL, nhb = FALSE,
+ currency = NULL) {
+ if (length(cost) != length(effect) || length(effect) != length(strategies)) {
+ stop("cost, effect, and strategies must all be vectors of the same length", call. = FALSE)
+ }
+ if (length(strategies) == 0) {
+ stop("cost, effect, and strategies must contain at least one strategy", call. = FALSE)
+ }
+ if (missing(ref_str) || is.null(ref_str)) {
+ stop("`ref_str` must name the reference strategy.", call. = FALSE)
+ }
+ v_strat <- as.character(strategies)
+ if (anyDuplicated(v_strat)) {
+ stop("Strategy names must be unique.", call. = FALSE)
+ }
+ ref_str <- check_ref_str(ref_str, v_strat)
+ check_wtp_nhb(wtp, nhb)
+
+ # reference first, then the other strategies by increasing cost (and decreasing effect)
+ v_order <- order(v_strat != ref_str, cost, -effect)
+ df_ref <- data.frame(Strategy = v_strat[v_order], Cost = cost[v_order],
+ Effect = effect[v_order], stringsAsFactors = FALSE)
+ is_ref <- df_ref$Strategy == ref_str
+
+ # differences from the reference; its own are reported as NA
+ df_ref$Inc_Cost <- df_ref$Cost - df_ref$Cost[is_ref]
+ df_ref$Inc_Effect <- df_ref$Effect - df_ref$Effect[is_ref]
+ v_status <- status_vs_reference(df_ref$Inc_Cost, df_ref$Inc_Effect)
+ v_status[is_ref] <- "Reference"
+ df_ref$Inc_Cost[is_ref] <- NA_real_
+ df_ref$Inc_Effect[is_ref] <- NA_real_
+ # a ratio is only meaningful when cost and effect move in the same direction (NE and SW
+ # quadrants); for dominant, dominated, and equivalent strategies the CER stays NA
+ v_has_ratio <- v_status %in% c("More costly, more effective", "Less costly, less effective")
+ df_ref$CER <- ifelse(v_has_ratio, df_ref$Inc_Cost / df_ref$Inc_Effect, NA_real_)
+ df_ref$Status <- v_status
+
+ if (!is.null(wtp)) {
+ df_ref$NMB <- wtp * df_ref$Effect - df_ref$Cost
+ df_ref$Inc_NMB <- df_ref$NMB - df_ref$NMB[is_ref]
+ df_ref$Inc_NMB[is_ref] <- NA_real_
+ if (nhb) {
+ df_ref$NHB <- df_ref$Effect - df_ref$Cost / wtp
+ df_ref$Inc_NHB <- df_ref$NHB - df_ref$NHB[is_ref]
+ df_ref$Inc_NHB[is_ref] <- NA_real_
+ }
+ }
+
+ structure(df_ref, class = c("cers_ref", "data.frame"), ref_str = ref_str, wtp = wtp,
+ currency = currency)
+}
+
+# nolint end
+
+#' Compare every strategy with a reference strategy, from a \code{psa} object
+#'
+#' @description
+#' Compares each strategy with a reference strategy using the mean costs and effects of a
+#' probabilistic sensitivity analysis (PSA), as \code{\link{calculate_cers_ref}} does for a base
+#' case. With \code{uncertainty = TRUE}, it also summarizes the uncertainty in each comparison
+#' across the PSA samples. See \code{\link{calculate_cers_ref}} for when a comparison with a
+#' single reference is appropriate, and \code{\link{calculate_icers_psa}} for the fully
+#' incremental analysis.
+#'
+#' @param psa \code{psa} object from \code{\link{make_psa_obj}}.
+#' @param uncertainty if \code{TRUE}, add the 95\% intervals and quadrant proportions described
+#' in Value. Defaults to \code{FALSE}.
+#' @inheritParams calculate_cers_ref
+#'
+#' @return A \code{cers_ref} object with the columns described in
+#' \code{\link{calculate_cers_ref}}, computed from the mean cost and effect of each strategy. The
+#' currency of \code{psa} is kept.
+#'
+#' With \code{uncertainty = TRUE}, the differences from the reference are computed in every PSA
+#' sample, and these columns are added (\code{NA} for the reference itself):
+#' \itemize{
+#' \item \code{Lower_95_Inc_Cost} and \code{Upper_95_Inc_Cost}, the 2.5th and 97.5th
+#' percentiles of the difference in cost, placed after \code{Inc_Cost}; likewise for
+#' \code{Inc_Effect} and, with \code{wtp}, \code{Inc_NMB} (and \code{Inc_NHB}).
+#' \item \code{Prop_NE}, \code{Prop_SE}, \code{Prop_SW}, and \code{Prop_NW}, the proportion of
+#' samples in each quadrant of the incremental cost-effectiveness plane: NE more effective and
+#' more costly; SE more effective and not more costly; SW not more effective and not more
+#' costly; NW not more effective and more costly. The four proportions sum to 1.
+#' \item With \code{wtp}, \code{Prop_CE}, the proportion of samples in which the strategy is
+#' cost-effective compared with the reference (it has a higher net monetary benefit).
+#' }
+#'
+#' @inherit calculate_cers_ref references
+#' @seealso \code{\link{calculate_cers_ref}}, \code{\link{plot.cers_ref}}, and
+#' \code{\link{plot.psa}} with \code{ref_str} for the PSA samples on the incremental plane.
+#'
+#' @examples
+#' data(cancer_psa_data)
+#' l_psa <- make_psa_obj(cost = cancer_psa_data$cost,
+#' effectiveness = cancer_psa_data$effectiveness,
+#' parameters = cancer_psa_data$parameters,
+#' strategies = cancer_psa_data$strategies)
+#' df_ref <- calculate_cers_ref_psa(l_psa, ref_str = "Radio", wtp = 50000,
+#' uncertainty = TRUE)
+#' df_ref
+#' plot(df_ref)
+#' @export
+calculate_cers_ref_psa <- function(psa, ref_str, wtp = NULL, nhb = FALSE, uncertainty = FALSE) {
+ check_psa_object(psa)
+ if (!isTRUE(uncertainty) && !isFALSE(uncertainty)) {
+ stop("`uncertainty` must be TRUE or FALSE.", call. = FALSE)
+ }
+ df_sum <- summary(psa)
+ df_ref <- calculate_cers_ref(cost = df_sum$meanCost, effect = df_sum$meanEffect,
+ strategies = df_sum$Strategy, ref_str = ref_str, wtp = wtp,
+ nhb = nhb, currency = psa$currency)
+ if (uncertainty) {
+ df_ref <- add_cers_ref_uncertainty(df_ref, psa, wtp, nhb)
+ }
+ df_ref
+}
+
+#' Add PSA intervals and quadrant proportions to a \code{cers_ref} object
+#'
+#' @param df_ref a \code{cers_ref} object computed from the means of \code{psa}.
+#' @param psa the \code{psa} object.
+#' @inheritParams calculate_cers_ref
+#' @return \code{df_ref} with the columns described in \code{\link{calculate_cers_ref_psa}}.
+#' @keywords internal
+add_cers_ref_uncertainty <- function(df_ref, psa, wtp, nhb) {
+ ref_str <- attr(df_ref, "ref_str")
+ v_strat <- df_ref$Strategy
+ is_ref <- v_strat == ref_str
+ # sample-by-sample differences from the reference: one row per PSA sample, one column per
+ # strategy in the row order of df_ref (subtracting a vector recycles it down each column)
+ m_inc_cost <- as.matrix(psa$cost)[, v_strat, drop = FALSE] - psa$cost[[ref_str]]
+ m_inc_effect <- as.matrix(psa$effectiveness)[, v_strat, drop = FALSE] -
+ psa$effectiveness[[ref_str]]
+ l_inc <- list(Inc_Cost = m_inc_cost, Inc_Effect = m_inc_effect)
+ if (!is.null(wtp)) {
+ m_inc_nmb <- wtp * m_inc_effect - m_inc_cost
+ l_inc$Inc_NMB <- m_inc_nmb
+ if (nhb) {
+ l_inc$Inc_NHB <- m_inc_effect - m_inc_cost / wtp
+ }
+ }
+ na_ref <- function(v) {
+ v <- unname(v)
+ v[is_ref] <- NA_real_
+ v
+ }
+
+ # 95% intervals, each placed right after its point estimate
+ v_cols <- names(df_ref)
+ for (col in names(l_inc)) {
+ df_ref[[paste0("Lower_95_", col)]] <- na_ref(apply(l_inc[[col]], 2, quantile, probs = 0.025,
+ names = FALSE))
+ df_ref[[paste0("Upper_95_", col)]] <- na_ref(apply(l_inc[[col]], 2, quantile, probs = 0.975,
+ names = FALSE))
+ v_cols <- append(v_cols, paste0(c("Lower_95_", "Upper_95_"), col), after = match(col, v_cols))
+ }
+
+ # share of samples in each quadrant of the incremental plane, and cost-effective ones
+ df_ref$Prop_NE <- na_ref(colMeans(m_inc_effect > 0 & m_inc_cost > 0))
+ df_ref$Prop_SE <- na_ref(colMeans(m_inc_effect > 0 & m_inc_cost <= 0))
+ df_ref$Prop_SW <- na_ref(colMeans(m_inc_effect <= 0 & m_inc_cost <= 0))
+ df_ref$Prop_NW <- na_ref(colMeans(m_inc_effect <= 0 & m_inc_cost > 0))
+ v_cols <- c(v_cols, "Prop_NE", "Prop_SE", "Prop_SW", "Prop_NW")
+ if (!is.null(wtp)) {
+ df_ref$Prop_CE <- na_ref(colMeans(m_inc_nmb > 0))
+ v_cols <- c(v_cols, "Prop_CE")
+ }
+
+ l_attr <- attributes(df_ref)[c("class", "ref_str", "wtp", "currency")]
+ df_ref <- as.data.frame(unclass(df_ref)[v_cols], check.names = FALSE, stringsAsFactors = FALSE)
+ for (a in names(l_attr)) {
+ attr(df_ref, a) <- l_attr[[a]]
+ }
+ df_ref
+}
+
+#' Check a reference strategy name
+#'
+#' @param ref_str reference strategy name, or \code{NULL}.
+#' @param strategies names of the strategies in the analysis.
+#' @return \code{ref_str} as a character string, or \code{NULL}.
+#' @keywords internal
+check_ref_str <- function(ref_str, strategies) {
+ if (is.null(ref_str)) {
+ return(NULL)
+ }
+ if (length(ref_str) != 1 || is.na(ref_str)) {
+ stop("`ref_str` must be a single strategy name.", call. = FALSE)
+ }
+ ref_str <- as.character(ref_str)
+ if (!ref_str %in% strategies) {
+ stop("`ref_str` must be one of the strategies: ",
+ paste0("\"", strategies, "\"", collapse = ", "), ".", call. = FALSE)
+ }
+ ref_str
+}
+
+#' Status of each strategy relative to a reference strategy
+#'
+#' @param v_inc_cost,v_inc_effect cost and effect of each strategy minus those of the reference.
+#' @return character vector of statuses (the reference itself is labeled by the caller).
+#' @keywords internal
+status_vs_reference <- function(v_inc_cost, v_inc_effect) {
+ ifelse(v_inc_cost == 0 & v_inc_effect == 0, "Equivalent",
+ ifelse(v_inc_cost <= 0 & v_inc_effect >= 0, "Dominant",
+ ifelse(v_inc_cost >= 0 & v_inc_effect <= 0, "Dominated",
+ ifelse(v_inc_cost > 0, "More costly, more effective",
+ "Less costly, less effective"))))
+}
+
+#' Print a comparison with a reference strategy
+#'
+#' Prints the table of a \code{\link{calculate_cers_ref}} object with formatted numbers and
+#' headers that name the reference strategy.
+#'
+#' @param x a \code{cers_ref} object.
+#' @param currency currency symbol. Defaults to the currency stored in \code{x}, or \code{"$"}.
+#' @param dig_cost number of digits to round costs and net monetary benefits to.
+#' @param dig_eff number of digits to round effects and net health benefits to.
+#' @param dig_cer number of digits to round the cost-effectiveness ratios to.
+#' @param dig_prop number of digits to round the proportions of PSA samples to.
+#' @param ... further arguments (not used).
+#' @return the formatted table, invisibly.
+#' @export
+print.cers_ref <- function(x, currency = NULL, dig_cost = 0, dig_eff = 2, dig_cer = 0,
+ dig_prop = 3, ...) {
+ currency <- resolve_currency(currency, x)
+ vs <- paste0(" vs ", attr(x, "ref_str"))
+ cat("Comparison of each strategy with the reference strategy, ", attr(x, "ref_str"),
+ "\n(not a fully incremental analysis; see calculate_icers())\n\n", sep = "")
+ df_table <- as.data.frame(unclass(x), check.names = FALSE, stringsAsFactors = FALSE)
+ l_format <- list(
+ Cost = list(dig_cost, paste0("Costs (", currency, ")")),
+ Effect = list(dig_eff, "QALYs"),
+ Inc_Cost = list(dig_cost, paste0("Incremental Costs", vs, " (", currency, ")")),
+ Inc_Effect = list(dig_eff, paste0("Incremental QALYs", vs)),
+ CER = list(dig_cer, paste0("CER", vs, " (", currency, "/QALY)")),
+ Status = list(NA, paste0("Status", vs)),
+ NMB = list(dig_cost, paste0("NMB (", currency, ")")),
+ Inc_NMB = list(dig_cost, paste0("Incremental NMB", vs, " (", currency, ")")),
+ NHB = list(dig_eff, "NHB (QALYs)"),
+ Inc_NHB = list(dig_eff, paste0("Incremental NHB", vs, " (QALYs)"))
+ )
+ # interval columns use the digits of their point estimate; proportions their own
+ for (col in grep("^(Lower|Upper)_95_", names(df_table), value = TRUE)) {
+ base <- sub("^(Lower|Upper)_95_", "", col)
+ l_format[[col]] <- list(l_format[[base]][[1]], col)
+ }
+ # proportions with a fixed number of decimals, so they line up
+ for (col in grep("^Prop_", names(df_table), value = TRUE)) {
+ v <- df_table[[col]]
+ df_table[[col]] <- ifelse(is.na(v), "-", formatC(v, format = "f", digits = dig_prop))
+ }
+ df_table <- format_cea_table(df_table, l_format)
+ print(df_table)
+ invisible(df_table)
+}
+
+#' Plot a comparison with a reference strategy
+#'
+#' Draws the incremental cost-effectiveness plane centered at the reference strategy: each
+#' strategy is placed at its difference in effect (x) and cost (y) from the reference, which sits
+#' at the origin. Optional segments join the reference to each strategy, forming a star, and an
+#' optional willingness-to-pay line goes through the origin: strategies below the line are
+#' cost-effective compared with the reference at that threshold.
+#'
+#' @param x a \code{cers_ref} object from \code{\link{calculate_cers_ref}} or
+#' \code{\link{calculate_cers_ref_psa}}.
+#' @param wtp a willingness-to-pay threshold for the dotted line through the origin. Defaults to
+#' the threshold stored in \code{x}, if any; \code{NULL} draws no line.
+#' @param lines whether to draw a segment from the reference to each strategy. The default
+#' (\code{NULL}) draws them when there are at most 20 strategies besides the reference, since
+#' with many strategies they make the plot hard to read.
+#' @param label whether to label all strategies (the default) or none.
+#' @param label_max_char maximum number of characters of the strategy labels; longer names are
+#' truncated. The default (\code{NULL}) does not truncate.
+#' @param ref_axis 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}.
+#' @param currency currency symbol. Defaults to the currency stored in \code{x}, or \code{"$"}.
+#' @param effect_units units of effectiveness. Defaults to \code{"QALYs"}.
+#' @param col color palette for the status of each strategy: \code{"access"} (the default, an
+#' accessible palette), \code{"full"}, or \code{"bw"}.
+#' @param alpha opacity of the points.
+#' @inheritParams add_common_aes
+#' @inheritParams ggrepel::geom_label_repel
+#' @param ... further arguments (not used).
+#'
+#' @return a \code{ggplot2} object, which can be modified by adding further layers.
+#' @seealso \code{\link{calculate_cers_ref}}
+#' @examples
+#' df_ref <- calculate_cers_ref(cost = c(12000, 9000, 20000),
+#' effect = c(8.0, 7.6, 8.5),
+#' strategies = c("Standard of care", "Generic drug", "New drug"),
+#' ref_str = "Standard of care")
+#' plot(df_ref, wtp = 50000)
+#'
+#' # many strategies: no segments, no labels
+#' data(hund_strat)
+#' df_hund <- calculate_cers_ref(hund_strat$Cost, hund_strat$QALYs, hund_strat$Strategy,
+#' ref_str = "1")
+#' plot(df_hund, label = "none")
+#' @importFrom ggrepel geom_label_repel
+#' @export
+plot.cers_ref <- function(x,
+ wtp = attr(x, "wtp"),
+ lines = NULL,
+ label = c("all", "none"),
+ label_max_char = NULL,
+ ref_axis = TRUE,
+ ref_caption = TRUE,
+ currency = NULL,
+ effect_units = "QALYs",
+ col = c("access", "full", "bw"),
+ alpha = 1,
+ txtsize = 12,
+ n_x_ticks = 6,
+ n_y_ticks = 6,
+ xbreaks = NULL,
+ ybreaks = NULL,
+ xlim = NULL,
+ ylim = NULL,
+ xexpand = expansion(0.1),
+ yexpand = expansion(0.1),
+ max.iter = 20000,
+ ...) {
+ Inc_Effect <- Inc_Cost <- Status <- Strategy <- NULL
+ label <- match.arg(label)
+ col <- match.arg(col)
+ currency <- resolve_currency(currency, x)
+ check_wtp_nhb(wtp, nhb = FALSE)
+ ref_str <- attr(x, "ref_str")
+ is_ref <- x$Strategy == ref_str
+ n_comp <- sum(!is_ref)
+ if (is.null(lines)) {
+ lines <- n_comp <= 20
+ }
+
+ # the reference sits at the origin of the incremental plane
+ df_plot <- data.frame(Strategy = x$Strategy, Status = x$Status,
+ Inc_Cost = ifelse(is_ref, 0, x$Inc_Cost),
+ Inc_Effect = ifelse(is_ref, 0, x$Inc_Effect),
+ stringsAsFactors = FALSE)
+ if (!is.null(label_max_char)) {
+ df_plot$Strategy <- substr(df_plot$Strategy, 1, label_max_char)
+ }
+ v_levels <- c("Dominant", "More costly, more effective", "Less costly, less effective",
+ "Dominated", "Equivalent")
+ df_comp <- df_plot[!is_ref, , drop = FALSE]
+ # all levels, so each status keeps its color whichever statuses are present
+ df_comp$Status <- factor(df_comp$Status, levels = v_levels)
+ df_ref <- df_plot[is_ref, , drop = FALSE]
+
+ p <- ggplot(df_comp, aes(x = Inc_Effect, y = Inc_Cost))
+ if (ref_axis) {
+ p <- p +
+ geom_hline(yintercept = 0, linetype = "dashed", color = "grey50") +
+ geom_vline(xintercept = 0, linetype = "dashed", color = "grey50")
+ }
+ if (lines && n_comp > 0) {
+ p <- p + geom_segment(aes(x = 0, y = 0, xend = Inc_Effect, yend = Inc_Cost),
+ color = "grey60", linewidth = 0.4)
+ }
+ if (!is.null(wtp)) {
+ p <- p + geom_abline(intercept = 0, slope = wtp, linetype = "dotted", color = "grey30")
+ }
+ p <- p +
+ geom_point(aes(color = Status), size = 2.5, alpha = alpha) +
+ geom_point(data = df_ref, shape = 23, size = 3.5, fill = "black", color = "black") +
+ labs(x = paste0("Incremental Effect (", effect_units, ")"),
+ y = paste0("Incremental Cost (", currency, ")"))
+ v_caption <- c(paste0("Reference Strategy (diamond): ", ref_str),
+ if (!is.null(wtp)) wtp_caption(wtp, currency, effect_units))
+ if (ref_caption) {
+ p <- p + labs(caption = paste(v_caption, collapse = "\n"))
+ }
+ p <- add_common_aes(p, txtsize, col = col, col_aes = "color", scale_name = NULL,
+ continuous = c("x", "y"),
+ n_x_ticks = n_x_ticks, n_y_ticks = n_y_ticks,
+ xbreaks = xbreaks, ybreaks = ybreaks,
+ xlim = xlim, ylim = ylim,
+ xexpand = xexpand, yexpand = yexpand,
+ v_str = v_levels)
+ if (label == "all") {
+ p <- p + geom_label_repel(data = df_plot, aes(label = Strategy), size = 3,
+ show.legend = FALSE, max.iter = max.iter, direction = "both")
+ }
+ p
+}
diff --git a/R/exp_loss.R b/R/exp_loss.R
index 05a9a3d..539946c 100644
--- a/R/exp_loss.R
+++ b/R/exp_loss.R
@@ -156,6 +156,11 @@ plot.exp_loss <- function(x,
# formatting if logging the y axis
if (log_y) {
tr <- "log10"
+ # evenly spaced breaks (number_ticks()) bunch up at the top of a log axis and leave its
+ # lower part without labels, so use breaks spread over the orders of magnitude instead
+ if (is.null(ybreaks)) {
+ ybreaks <- scales::breaks_log(n = n_y_ticks)
+ }
} else {
tr <- "identity"
}
diff --git a/R/icers.R b/R/icers.R
index 449bbe5..1b849dc 100644
--- a/R/icers.R
+++ b/R/icers.R
@@ -14,10 +14,6 @@
#' @param cost vector of cost for each strategy
#' @param effect vector of effect for each strategy
#' @param strategies string vector of strategy names
-#' @param ref_str name of a reference strategy (one of \code{strategies}) to compare every
-#' strategy against, for example \code{"Standard of care"}. The default (\code{NULL}) adds no
-#' reference columns. The frontier-based results (\code{Status}, \code{Inc_Cost},
-#' \code{Inc_Effect}, \code{ICER}) never depend on the reference.
#' @param wtp a single willingness-to-pay threshold (currency per unit of effect). If given,
#' the net monetary benefit (\code{NMB}) of each strategy is added. The default (\code{NULL})
#' adds no net-benefit columns.
@@ -29,20 +25,16 @@
#' status, incremental cost, incremental effect, and ICER, computed sequentially along the
#' cost-effectiveness frontier.
#'
-#' If \code{ref_str} is given, four columns compare each strategy with the reference:
-#' \code{Inc_Cost_ref} and \code{Inc_Effect_ref} (cost and effect minus those of the
-#' reference), \code{ICER_ref}, and \code{Status_ref}, one of \code{"Reference"},
-#' \code{"Dominant"} (less costly and at least as effective), \code{"Dominated"} (more costly
-#' and no more effective), \code{"More costly, more effective"},
-#' \code{"Less costly, less effective"}, or \code{"Equivalent"} (same cost and effect).
-#' \code{ICER_ref} is \code{NA} where a ratio is not meaningful: for the reference itself and
-#' for dominant, dominated, and equivalent strategies.
+#' If \code{wtp} is given, \code{NMB} (\code{wtp * Effect - Cost}) is added. With
+#' \code{nhb = TRUE}, \code{NHB} (\code{Effect - Cost / wtp}) is added too.
#'
-#' If \code{wtp} is given, \code{NMB} (\code{wtp * Effect - Cost}) is added, and with
-#' \code{ref_str} also \code{Inc_NMB_ref}, the NMB minus that of the reference. With
-#' \code{nhb = TRUE}, \code{NHB} (\code{Effect - Cost / wtp}) and \code{Inc_NHB_ref} are added too.
+#' The ICERs are always sequential: each strategy on the frontier is compared with the next less
+#' costly one, after removing dominated and extendedly dominated strategies. This is the fully
+#' incremental analysis that health technology assessment guidelines require when more than two
+#' strategies are compared. To compare every strategy with a single reference strategy instead,
+#' use \code{\link{calculate_cers_ref}}.
#'
-#' @seealso \code{\link{plot.icers}}
+#' @seealso \code{\link{plot.icers}}, \code{\link{calculate_cers_ref}}
#'
#' @examples
#' ## Base Case
@@ -77,15 +69,15 @@
#' # note that longer strategy names will get truncated
#' plot(icers, label = "all")
#'
-#' ## Comparing every strategy with a reference strategy
-#' hund_ref <- calculate_icers(hund_strat$Cost,
-#' hund_strat$QALYs,
-#' hund_strat$Strategy,
-#' ref_str = hund_strat$Strategy[1],
-#' wtp = 50000)
-#' print(hund_ref, ref = "reference")
+#' # the incremental cost-effectiveness plane, with the least costly strategy on the
+#' # frontier at the origin
+#' plot(icers, incremental = TRUE)
+#'
+#' ## Net monetary benefit at a willingness-to-pay threshold
+#' calculate_icers(sum_cdiff$meanCost, sum_cdiff$meanEffect, sum_cdiff$Strategy,
+#' wtp = 50000)
#' @export
-calculate_icers <- function(cost, effect, strategies, ref_str = NULL, wtp = NULL,
+calculate_icers <- function(cost, effect, strategies, wtp = NULL,
nhb = FALSE, currency = NULL) {
# checks on input
n_cost <- length(cost)
@@ -97,7 +89,6 @@ calculate_icers <- function(cost, effect, strategies, ref_str = NULL, wtp = NULL
if (n_strat == 0) {
stop("cost, effect, and strategies must contain at least one strategy", call. = FALSE)
}
- ref_str <- check_ref_str(ref_str, as.character(strategies))
check_wtp_nhb(wtp, nhb)
# column names used unquoted in the dplyr code below; declaring them avoids the
@@ -122,7 +113,7 @@ calculate_icers <- function(cost, effect, strategies, ref_str = NULL, wtp = NULL
df_cea$ICER <- NA_real_
df_cea$Status <- "ND"
class(df_cea) <- c("icers", "data.frame")
- return(add_reference_and_nmb(df_cea, ref_str, wtp, nhb, currency))
+ return(add_nmb(df_cea, wtp, nhb, currency))
}
# three statuses: dominated, extended dominated, and non-dominated
@@ -211,7 +202,7 @@ calculate_icers <- function(cost, effect, strategies, ref_str = NULL, wtp = NULL
# declare class of results
class(df_results) <- c("icers", "data.frame")
- add_reference_and_nmb(df_results, ref_str, wtp, nhb, currency)
+ add_nmb(df_results, wtp, nhb, currency)
}
#' Caption text for a willingness-to-pay line
@@ -227,27 +218,6 @@ wtp_caption <- function(wtp, currency, effect_units = "QALYs") {
"/", unit)
}
-#' Check a reference strategy name
-#'
-#' @param ref_str reference strategy name, or \code{NULL}.
-#' @param strategies names of the strategies in the analysis.
-#' @return \code{ref_str} as a character string, or \code{NULL}.
-#' @keywords internal
-check_ref_str <- function(ref_str, strategies) {
- if (is.null(ref_str)) {
- return(NULL)
- }
- if (length(ref_str) != 1 || is.na(ref_str)) {
- stop("`ref_str` must be a single strategy name.", call. = FALSE)
- }
- ref_str <- as.character(ref_str)
- if (!ref_str %in% strategies) {
- stop("`ref_str` must be one of the strategies: ",
- paste0("\"", strategies, "\"", collapse = ", "), ".", call. = FALSE)
- }
- ref_str
-}
-
#' Check the willingness-to-pay and NHB arguments of calculate_icers()
#'
#' @inheritParams calculate_icers
@@ -266,20 +236,7 @@ check_wtp_nhb <- function(wtp, nhb) {
invisible(NULL)
}
-#' Status of each strategy relative to a reference strategy
-#'
-#' @param v_inc_cost,v_inc_effect cost and effect of each strategy minus those of the reference.
-#' @return character vector of statuses (the reference itself is labeled by the caller).
-#' @keywords internal
-status_vs_reference <- function(v_inc_cost, v_inc_effect) {
- ifelse(v_inc_cost == 0 & v_inc_effect == 0, "Equivalent",
- ifelse(v_inc_cost <= 0 & v_inc_effect >= 0, "Dominant",
- ifelse(v_inc_cost >= 0 & v_inc_effect <= 0, "Dominated",
- ifelse(v_inc_cost > 0, "More costly, more effective",
- "Less costly, less effective"))))
-}
-
-#' Add reference-strategy and net-benefit columns to an icers object
+#' Add net-benefit columns and stored attributes to an icers object
#'
#' The frontier-based columns are not modified. Columns and attributes are only added
#' for the arguments that are given, so with all of them \code{NULL} the object is unchanged.
@@ -288,44 +245,13 @@ status_vs_reference <- function(v_inc_cost, v_inc_effect) {
#' @inheritParams calculate_icers
#' @return \code{df_icers} with the requested columns and attributes added.
#' @keywords internal
-add_reference_and_nmb <- function(df_icers, ref_str, wtp, nhb, currency) {
- if (!is.null(ref_str)) {
- # row of the reference strategy; check_ref_str() has already confirmed it exists
- i_ref <- match(ref_str, df_icers$Strategy)
- # differences of every strategy from the reference (the reference's own are 0)
- v_inc_cost <- df_icers$Cost - df_icers$Cost[i_ref]
- v_inc_effect <- df_icers$Effect - df_icers$Effect[i_ref]
- # classify each strategy by its quadrant of the incremental CE plane
- v_status <- status_vs_reference(v_inc_cost, v_inc_effect)
- # the reference has no comparison with itself: label it and blank its differences
- v_status[i_ref] <- "Reference"
- v_inc_cost[i_ref] <- NA_real_
- v_inc_effect[i_ref] <- NA_real_
- # a ratio is only meaningful when cost and effect move in the same direction (NE and SW
- # quadrants); for dominant, dominated, and equivalent strategies ICER_ref stays NA
- v_has_ratio <- v_status %in% c("More costly, more effective", "Less costly, less effective")
- df_icers$Inc_Cost_ref <- v_inc_cost
- df_icers$Inc_Effect_ref <- v_inc_effect
- df_icers$ICER_ref <- ifelse(v_has_ratio, v_inc_cost / v_inc_effect, NA_real_)
- df_icers$Status_ref <- v_status
- # print.icers() and plot.icers() read the reference from this attribute
- attr(df_icers, "ref_str") <- ref_str
- }
+add_nmb <- function(df_icers, wtp, nhb, currency) {
if (!is.null(wtp)) {
# net monetary benefit of each strategy at the given threshold
df_icers$NMB <- wtp * df_icers$Effect - df_icers$Cost
- if (!is.null(ref_str)) {
- # incremental NMB versus the reference; positive means cost-effective versus the reference
- df_icers$Inc_NMB_ref <- df_icers$NMB - df_icers$NMB[i_ref]
- df_icers$Inc_NMB_ref[i_ref] <- NA_real_
- }
if (nhb) {
# net health benefit: the same comparison expressed in units of effect
df_icers$NHB <- df_icers$Effect - df_icers$Cost / wtp
- if (!is.null(ref_str)) {
- df_icers$Inc_NHB_ref <- df_icers$NHB - df_icers$NHB[i_ref]
- df_icers$Inc_NHB_ref[i_ref] <- NA_real_
- }
}
attr(df_icers, "wtp") <- wtp
}
@@ -361,16 +287,14 @@ add_reference_and_nmb <- function(df_icers, ref_str, wtp, nhb, currency) {
#' set to \code{TRUE}, four additional columns are provided for the 2.5th and 97.5th quantiles for
#' each strategy's cost and effect.
#'
-#' With \code{ref_str}, \code{wtp}, or \code{nhb}, the reference-strategy and net-benefit columns
-#' described in \code{\link{calculate_icers}} are added. With \code{uncertainty = TRUE} and
-#' \code{ref_str}, the 2.5th and 97.5th quantiles of the sample-by-sample differences from the reference
-#' are also given for \code{Inc_Cost_ref}, \code{Inc_Effect_ref}, and (with \code{wtp})
-#' \code{Inc_NMB_ref}, in columns such as \code{Lower_95_Inc_Cost_ref} and \code{Upper_95_Inc_Cost_ref}.
+#' With \code{wtp} or \code{nhb}, the net-benefit columns described in
+#' \code{\link{calculate_icers}} are added.
#' @seealso \code{\link{plot.icers}}
#' @seealso \code{\link{calculate_icers}}
+#' @seealso \code{\link{calculate_cers_ref_psa}} to compare every strategy with a reference strategy
#' @importFrom tidyr pivot_longer
#' @export
-calculate_icers_psa <- function(psa, uncertainty = FALSE, ref_str = NULL, wtp = NULL, nhb = FALSE) {
+calculate_icers_psa <- function(psa, uncertainty = FALSE, wtp = NULL, nhb = FALSE) {
# check that psa has class 'psa'
check_psa_object(psa)
@@ -387,12 +311,12 @@ calculate_icers_psa <- function(psa, uncertainty = FALSE, ref_str = NULL, wtp =
df_icers <- calculate_icers(cost = df_psa_sum$meanCost,
effect = df_psa_sum$meanEffect,
strategies = df_psa_sum$Strategy,
- ref_str = ref_str, wtp = wtp, nhb = nhb,
+ wtp = wtp, nhb = nhb,
currency = psa$currency)
if (uncertainty == TRUE) {
# the joins and column selection below drop the icers class and attributes; keep them
- l_attr <- attributes(df_icers)[c("class", "ref_str", "wtp", "currency")]
+ l_attr <- attributes(df_icers)[c("class", "wtp", "currency")]
l_attr <- l_attr[!vapply(l_attr, is.null, logical(1))]
# extract cost and effect data.frames from psa object
@@ -417,14 +341,11 @@ calculate_icers_psa <- function(psa, uncertainty = FALSE, ref_str = NULL, wtp =
left_join(df_cost_bounds, by = "Strategy") %>%
left_join(df_effect_bounds, by = "Strategy") %>%
# put each interval next to its estimate; everything() keeps the remaining columns
- # (the reference and net-benefit columns), which select() would otherwise drop
+ # (the net-benefit columns), which select() would otherwise drop
select(Strategy, Cost, Lower_95_Cost, Upper_95_Cost,
Effect, Lower_95_Effect, Upper_95_Effect,
Inc_Cost, Inc_Effect, ICER, Status, everything())
- if (!is.null(ref_str)) {
- df_icers <- add_reference_intervals(df_icers, psa, ref_str, wtp)
- }
df_icers <- as.data.frame(df_icers)
for (a in names(l_attr)) {
attr(df_icers, a) <- l_attr[[a]]
@@ -434,45 +355,6 @@ calculate_icers_psa <- function(psa, uncertainty = FALSE, ref_str = NULL, wtp =
df_icers
}
-#' Add 95\% intervals for the differences from a reference strategy
-#'
-#' Quantiles of the sample-by-sample differences between each strategy and the reference, placed
-#' after the corresponding point estimate. \code{NA} for the reference itself.
-#'
-#' @param df_icers an \code{icers} object with reference columns.
-#' @param psa the \code{psa} object it was computed from.
-#' @inheritParams calculate_icers
-#' @return \code{df_icers} with the interval columns added.
-#' @keywords internal
-add_reference_intervals <- function(df_icers, psa, ref_str, wtp) {
- # sample-by-sample differences from the reference: one row per PSA sample, one column per
- # strategy (subtracting a vector from a matrix recycles it down each column)
- m_inc_cost <- as.matrix(psa$cost) - psa$cost[[ref_str]]
- m_inc_effect <- as.matrix(psa$effectiveness) - psa$effectiveness[[ref_str]]
- # one matrix of differences per point-estimate column that gets an interval
- l_inc <- list(Inc_Cost_ref = m_inc_cost, Inc_Effect_ref = m_inc_effect)
- if (!is.null(wtp)) {
- l_inc$Inc_NMB_ref <- wtp * m_inc_effect - m_inc_cost
- }
- v_strat <- df_icers$Strategy
- # running column order, so each interval lands right after its point estimate
- v_cols <- names(df_icers)
- for (col in names(l_inc)) {
- # reorder the matrix columns to match the rows of df_icers (frontier order)
- m_inc <- l_inc[[col]][, v_strat, drop = FALSE]
- v_lower <- unname(apply(m_inc, 2, quantile, probs = 0.025, names = FALSE))
- v_upper <- unname(apply(m_inc, 2, quantile, probs = 0.975, names = FALSE))
- # the reference's differences are all 0, so its interval is reported as NA
- v_lower[v_strat == ref_str] <- NA_real_
- v_upper[v_strat == ref_str] <- NA_real_
- df_icers[[paste0("Lower_95_", col)]] <- v_lower
- df_icers[[paste0("Upper_95_", col)]] <- v_upper
- i <- match(col, v_cols)
- v_cols <- append(v_cols, paste0(c("Lower_95_", "Upper_95_"), col), after = i)
- }
- df_icers[, v_cols]
-}
-
#' compute icers for non-dominated strategies
#'
#' @param non_d a data frame of non-dominated strategies, with columns
@@ -512,16 +394,19 @@ 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 incremental if \code{TRUE}, plot the incremental cost-effectiveness plane: the costs
+#' and effects of every strategy are shown relative to those of the first non-dominated strategy
+#' (the least costly strategy on the frontier), which is placed at the origin (0, 0). The frontier
+#' and the status of each strategy do not change. Defaults to \code{FALSE} (absolute costs and
+#' effects). To compare every strategy with a reference strategy of your choice, use
+#' \code{\link{calculate_cers_ref}} and its \code{plot} method.
#' @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.
+#' drawn 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{incremental = TRUE}, draw dashed axes through the origin.
#' Defaults to \code{TRUE}.
+#' @param ref_caption add a caption naming the strategy at the origin (with
+#' \code{incremental = TRUE}) and the WTP threshold (with \code{wtp}). Defaults to \code{TRUE}.
#' @inheritParams ggrepel::geom_label_repel
#'
#' @return a ggplot2 object which can be modified by adding additional geoms
@@ -548,7 +433,7 @@ plot.icers <- function(x,
xexpand = expansion(0.1),
yexpand = expansion(0.1),
max.iter = 20000,
- ref_str = NULL,
+ incremental = FALSE,
wtp = NULL,
ref_axis = TRUE,
ref_caption = TRUE,
@@ -558,11 +443,13 @@ plot.icers <- function(x,
if (is.null(currency)) {
currency <- if (is.null(attr(x, "currency"))) "$" else attr(x, "currency")
}
- ref_str <- check_ref_str(ref_str, x$Strategy)
+ if (!isTRUE(incremental) && !isFALSE(incremental)) {
+ stop("`incremental` must be TRUE or FALSE.", call. = FALSE)
+ }
check_wtp_nhb(wtp, nhb = FALSE)
# keep only the columns the plot uses, as a plain data frame, so the plot data are the same
- # whether or not x has uncertainty bounds, reference columns, or stored attributes
+ # whether or not x has uncertainty bounds, net-benefit columns, or stored attributes
v_plot_cols <- c("Strategy", "Cost", "Effect", "Inc_Cost", "Inc_Effect", "ICER", "Status")
x <- data.frame(unclass(x)[v_plot_cols], check.names = FALSE, stringsAsFactors = FALSE)
@@ -593,19 +480,16 @@ 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, ]
- }
+ # first non-dominated strategy: the least costly strategy on the frontier. It is the origin of
+ # the incremental plane and the point the WTP line goes through
+ df_front <- x[x$Status == nd_name, ]
+ df_anchor <- df_front[which.min(df_front$Cost), ]
- # 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]
+ if (incremental) {
+ x$Cost <- x$Cost - df_anchor$Cost
+ x$Effect <- x$Effect - df_anchor$Effect
x_lab <- paste0("Incremental Effect (", effect_units, ")")
y_lab <- paste0("Incremental Cost (", currency, ")")
}
@@ -626,17 +510,19 @@ plot.icers <- function(x,
scale_shape_discrete(name = NULL) +
labs(x = x_lab, y = y_lab)
- if (!is.null(ref_str) && ref_axis) {
+ if (incremental && 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
+ # through the anchor strategy, which is at the origin on the incremental plane
+ intercept <- if (incremental) 0 else df_anchor$Cost - wtp * df_anchor$Effect
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),
+ v_caption <- c(if (incremental) paste0("Origin: ", df_anchor$Strategy,
+ " (least costly strategy on the frontier)"),
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 = "; "))
@@ -676,12 +562,8 @@ plot.icers <- function(x,
#' Print the formatted CEA table
#'
-#' By default, prints the sequential cost-effectiveness table: each strategy on the frontier is
-#' compared with the previous one. If the \code{icers} object was created with a reference
-#' strategy (\code{ref_str} in \code{\link{calculate_icers}}), \code{ref = "reference"} shows the
-#' comparison of every strategy with the reference instead, listing the reference first and the
-#' other strategies by increasing cost. \code{ref = "both"} shows both comparisons, in the
-#' frontier order of the sequential table.
+#' Prints the sequential cost-effectiveness table: each strategy on the frontier is compared with
+#' the previous one.
#'
#' @param x Object of class \code{icers}
#' @param currency string. with currency used in the cost-effectiveness analysis (CEA).
@@ -689,8 +571,6 @@ plot.icers <- function(x,
#' @param dig_cost integer. number of digits to round costs to
#' @param dig_eff integer. number of digits to round effects to
#' @param dig_icer integer. number of digits to round ICER to
-#' @param ref which comparison to show: \code{"sequential"} (the default), \code{"reference"},
-#' or \code{"both"}.
#' @param ... Additional arguments passed to other methods.
#' @return a dataframe object - formatted CEA table
#' @export
@@ -699,22 +579,42 @@ print.icers <- function(x,
dig_cost = 0,
dig_eff = 2,
dig_icer = 0,
- ref = c("sequential", "reference", "both"),
...) {
# check if icers object
if (!inherits(x, "icers")) {
stop("x must be an object of class icers")
}
- ref <- match.arg(ref)
if (is.null(currency)) {
currency <- if (is.null(attr(x, "currency"))) "$" else attr(x, "currency")
}
- ref_str <- attr(x, "ref_str")
- if (ref != "sequential" && is.null(ref_str)) {
- stop("x has no reference strategy; create it with calculate_icers(..., ref_str = ) ",
- "to use ref = \"", ref, "\".", call. = FALSE)
- }
+ df_table_cea <- x
+ class(df_table_cea) <- "data.frame"
+
+ # display digits and header for each known column
+ l_format <- list(
+ Cost = list(dig_cost, paste0("Costs (", currency, ")")),
+ Effect = list(dig_eff, "QALYs"),
+ Inc_Cost = list(dig_cost, paste0("Incremental Costs (", currency, ")")),
+ Inc_Effect = list(dig_eff, "Incremental QALYs"),
+ ICER = list(dig_icer, paste0("ICER (", currency, "/QALY)")),
+ NMB = list(dig_cost, paste0("NMB (", currency, ")")),
+ NHB = list(dig_eff, "NHB (QALYs)")
+ )
+ df_table_cea <- format_cea_table(df_table_cea, l_format)
+
+ print(df_table_cea)
+ invisible(df_table_cea)
+}
+
+#' Format the numeric columns of a CEA table for printing
+#'
+#' @param df_table data frame to format.
+#' @param l_format named list, one element per column to format: a list of the number of digits
+#' (\code{NA} to leave the column as it is) and the header to print.
+#' @return \code{df_table} with the formatted columns, as character, and renamed.
+#' @keywords internal
+format_cea_table <- function(df_table, l_format) {
format_numbers <- function(col, n_digits) {
v_new_col <- rep("-", length(col))
v_non_na <- !is.na(col)
@@ -725,49 +625,13 @@ print.icers <- function(x,
v_new_col[v_non_na] <- format(round(col[v_non_na], n_digits), big.mark = ",",
nsmall = n_digits, scientific = FALSE)
}
-
v_new_col
}
-
- # columns that belong to each view
- v_seq_cols <- c("Inc_Cost", "Inc_Effect", "ICER", "Status")
- v_ref_cols <- grep("_ref$", names(x), value = TRUE)
- v_drop <- switch(ref, sequential = v_ref_cols, reference = v_seq_cols, both = character(0))
- df_table_cea <- x
- class(df_table_cea) <- "data.frame"
- df_table_cea <- df_table_cea[, setdiff(names(df_table_cea), v_drop), drop = FALSE]
- # the reference view lists the reference first, then the other strategies by cost; the
- # sequential and combined views keep the frontier order, in which the sequential ICERs are read
- if (ref == "reference") {
- v_order <- order(df_table_cea$Strategy != ref_str, df_table_cea$Cost)
- df_table_cea <- df_table_cea[v_order, , drop = FALSE]
- rownames(df_table_cea) <- NULL
- }
-
- # display digits and header for each known column
- vs <- paste0(" vs ", ref_str)
- l_format <- list(
- Cost = list(dig_cost, paste0("Costs (", currency, ")")),
- Effect = list(dig_eff, "QALYs"),
- Inc_Cost = list(dig_cost, paste0("Incremental Costs (", currency, ")")),
- Inc_Effect = list(dig_eff, "Incremental QALYs"),
- ICER = list(dig_icer, paste0("ICER (", currency, "/QALY)")),
- Inc_Cost_ref = list(dig_cost, paste0("Incremental Costs", vs, " (", currency, ")")),
- Inc_Effect_ref = list(dig_eff, paste0("Incremental QALYs", vs)),
- ICER_ref = list(dig_icer, paste0("ICER", vs, " (", currency, "/QALY)")),
- Status_ref = list(NA, paste0("Status", vs)),
- NMB = list(dig_cost, paste0("NMB (", currency, ")")),
- Inc_NMB_ref = list(dig_cost, paste0("Incremental NMB", vs, " (", currency, ")")),
- NHB = list(dig_eff, "NHB (QALYs)"),
- Inc_NHB_ref = list(dig_eff, paste0("Incremental NHB", vs, " (QALYs)"))
- )
- for (col in intersect(names(l_format), names(df_table_cea))) {
+ for (col in intersect(names(l_format), names(df_table))) {
if (!is.na(l_format[[col]][[1]])) {
- df_table_cea[[col]] <- format_numbers(df_table_cea[[col]], n_digits = l_format[[col]][[1]])
+ df_table[[col]] <- format_numbers(df_table[[col]], n_digits = l_format[[col]][[1]])
}
- names(df_table_cea)[names(df_table_cea) == col] <- l_format[[col]][[2]]
+ names(df_table)[names(df_table) == col] <- l_format[[col]][[2]]
}
-
- print(df_table_cea)
- invisible(df_table_cea)
+ df_table
}
diff --git a/R/psa.R b/R/psa.R
index 4bfc556..2013e66 100644
--- a/R/psa.R
+++ b/R/psa.R
@@ -104,31 +104,13 @@ check_df_and_coerce <- function(obj) {
#'
#' @param object the psa object
#' @param calc_sds whether or not to calculate the standard deviations. Defaults to FALSE
-#' @param ref_str name of a reference strategy. If given, each strategy is compared with it
-#' sample by sample (see Value). Defaults to \code{NULL}.
-#' @param wtp a single willingness-to-pay threshold. If given, the mean net monetary benefit is
-#' added (see Value). Defaults to \code{NULL}.
#' @param ... further arguments to summary (not used)
#'
#' @importFrom stats sd
#' @return a \code{data.frame} containing the mean cost and effectiveness for each strategy and, if requested,
#' the standard deviations of the cost and effectiveness for each strategy.
-#'
-#' With \code{ref_str}, the differences between each strategy and the reference are computed in
-#' every PSA sample, and these columns are added (\code{NA} for the reference itself):
-#' \code{meanIncCost} and \code{meanIncEffect}, the mean differences in cost and effect; and
-#' \code{propNE}, \code{propSE}, \code{propSW}, and \code{propNW}, the proportion of samples in each
-#' quadrant of the incremental cost-effectiveness plane: NE more effective and more costly, SE more
-#' effective and not more costly (dominant), SW not more effective and not more costly, and NW not more
-#' effective and more costly (dominated). The four proportions sum to 1.
-#'
-#' With \code{wtp}, \code{meanNMB} (\code{wtp * effect - cost}, averaged over samples) is added; with
-#' \code{ref_str} too, also \code{meanIncNMB} and \code{propCostEffective}, the proportion of samples in
-#' which the strategy has a higher NMB than the reference (it lies below the willingness-to-pay line).
#' @export
-summary.psa <- function(object, calc_sds = FALSE, ref_str = NULL, wtp = NULL, ...) {
- ref_str <- check_ref_str(ref_str, object$strategies)
- check_wtp_nhb(wtp, nhb = FALSE)
+summary.psa <- function(object, calc_sds = FALSE, ...) {
v_mean_cost <- colMeans(object$cost)
v_mean_effect <- colMeans(object$effectiveness)
@@ -143,30 +125,6 @@ summary.psa <- function(object, calc_sds = FALSE, ref_str = NULL, wtp = NULL, ..
df_sum_psa[, "sdCost"] <- v_sd_cost
df_sum_psa[, "sdEffect"] <- v_sd_effect
}
- if (!is.null(wtp)) {
- df_sum_psa[, "meanNMB"] <- unname(colMeans(wtp * object$effectiveness - object$cost))
- }
- if (!is.null(ref_str)) {
- # sample-by-sample differences from the reference strategy
- m_inc_cost <- as.matrix(object$cost) - object$cost[[ref_str]]
- m_inc_effect <- as.matrix(object$effectiveness) - object$effectiveness[[ref_str]]
- v_is_ref <- v_strat == ref_str
- na_ref <- function(v) {
- v[v_is_ref] <- NA_real_
- unname(v)
- }
- df_sum_psa[, "meanIncCost"] <- na_ref(colMeans(m_inc_cost))
- df_sum_psa[, "meanIncEffect"] <- na_ref(colMeans(m_inc_effect))
- df_sum_psa[, "propNE"] <- na_ref(colMeans(m_inc_effect > 0 & m_inc_cost > 0))
- df_sum_psa[, "propSE"] <- na_ref(colMeans(m_inc_effect > 0 & m_inc_cost <= 0))
- df_sum_psa[, "propSW"] <- na_ref(colMeans(m_inc_effect <= 0 & m_inc_cost <= 0))
- df_sum_psa[, "propNW"] <- na_ref(colMeans(m_inc_effect <= 0 & m_inc_cost > 0))
- if (!is.null(wtp)) {
- m_inc_nmb <- wtp * m_inc_effect - m_inc_cost
- df_sum_psa[, "meanIncNMB"] <- na_ref(colMeans(m_inc_nmb))
- df_sum_psa[, "propCostEffective"] <- na_ref(colMeans(m_inc_nmb > 0))
- }
- }
rownames(df_sum_psa) <- seq_len(nrow(df_sum_psa))
df_sum_psa
}
diff --git a/README.Rmd b/README.Rmd
new file mode 100644
index 0000000..9237d51
--- /dev/null
+++ b/README.Rmd
@@ -0,0 +1,197 @@
+---
+output: github_document
+---
+
+
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.path = "man/figures/README-",
+ fig.width = 7,
+ fig.height = 4.5,
+ dpi = 96,
+ dev = if (requireNamespace("ragg", quietly = TRUE)) "ragg_png" else "png",
+ out.width = "100%"
+)
+```
+
+# dampack
+
+
+[](https://CRAN.R-project.org/package=dampack)
+[](https://github.com/DARTH-git/dampack/actions/workflows/check-standard.yaml)
+[](https://app.codecov.io/gh/DARTH-git/dampack?branch=main)
+
+
+The Decision Analytic Modeling Package (dampack) is a suite of functions for analyzing and visualizing the health economic outputs of mathematical models.
+
+## Why dampack
+
+Decision-analytic models, such as decision trees, Markov cohort models, microsimulations and discrete-event simulations, estimate the costs and health outcomes of a set of strategies. Turning those outputs into the results that cost-effectiveness studies and health technology assessments report takes the same analyses every time: finding the efficient frontier, computing incremental cost-effectiveness ratios (ICERs), summarizing the probabilistic sensitivity analysis (PSA), and estimating the value of collecting more information.
+
+dampack does these analyses in R for any model. It only needs the model's outputs, so it works the same whether the model was written in R or elsewhere. It is developed by the [DARTH workgroup](https://www.darthworkgroup.com/), alongside the DARTH coding framework for decision models ([Alarid-Escudero et al., 2019](https://doi.org/10.1007/s40273-019-00837-x)), for health decision scientists, health economists, and students.
+
+## What it does
+
+- **Cost-effectiveness analysis.** `calculate_icers()` identifies dominated and extendedly dominated strategies and computes ICERs along the efficient frontier; `plot()` draws the frontier on absolute or incremental axes. Where guidelines allow it alongside this fully incremental analysis, `calculate_cers_ref()` also compares every strategy with a single reference strategy, such as the standard of care.
+- **Probabilistic sensitivity analysis.** `make_psa_obj()` stores the PSA output of any model. Its `plot()` and `summary()` methods show the cost-effectiveness plane, `ceac()` computes cost-effectiveness acceptability curves (CEACs) together with the acceptability frontier (CEAF), and `calc_exp_loss()` computes expected loss curves (ELCs), which show in one figure the expected foregone benefit of each strategy, the optimal strategy, and the expected value of perfect information ([Alarid-Escudero et al., 2019](https://doi.org/10.1016/j.jval.2019.02.008)).
+- **Value of information.** `calc_evpi()` computes the expected value of perfect information (EVPI). `calc_evppi()` estimates the expected value of partial perfect information (EVPPI) with regression metamodels of the PSA ([Strong et al., 2014](https://doi.org/10.1177/0272989X13505910); [Jalal and Alarid-Escudero, 2018](https://doi.org/10.1177/0272989X17715627)), and `calc_evsi()` estimates the expected value of sample information (EVSI) of a future study with the Gaussian approximation approach ([Jalal and Alarid-Escudero, 2018](https://doi.org/10.1177/0272989X17715627)). Both work from the PSA sample you already have, so no further model runs are needed.
+- **Deterministic sensitivity analysis.** One-way and two-way analyses come either from the PSA, through metamodels (`owsa()`, `twsa()`), or from running your model directly (`run_owsa_det()`, `run_twsa_det()`), with tornado diagrams and optimal-strategy plots.
+- **PSA inputs.** `gen_psa_samp()` draws parameter samples from common distributions, helpers such as `beta_params()` and `gamma_params()` convert means and standard deviations into distribution parameters, and `run_psa()` runs your model over the samples.
+
+## Installation
+
+Install the released version from CRAN:
+
+``` r
+install.packages("dampack")
+```
+
+Or the development version from GitHub:
+
+``` r
+# install.packages("remotes")
+remotes::install_github("DARTH-git/dampack")
+```
+
+Installing from GitHub on macOS with a non-US locale may fail with `Error: (converted from warning) Setting LC_CTYPE failed, using "C"`. Running `defaults write org.R-project.R force.LANG en_US.UTF-8` in the terminal fixes it.
+
+## Example
+
+`cancer_psa_data` holds the PSA output of an illustrative model that compares three cancer treatments over 10,000 samples.
+
+```{r example, message = FALSE}
+library(dampack)
+data("cancer_psa_data")
+l_psa <- make_psa_obj(cost = cancer_psa_data$cost,
+ effectiveness = cancer_psa_data$effectiveness,
+ parameters = cancer_psa_data$parameters,
+ strategies = cancer_psa_data$strategies)
+
+# ICERs from the mean costs and QALYs of each strategy
+calculate_icers_psa(l_psa)
+```
+
+How likely is each strategy to be cost-effective across willingness-to-pay thresholds? The acceptability frontier (squares) marks the strategy with the highest expected net benefit at each threshold.
+
+```{r ceac, fig.alt = "Cost-effectiveness acceptability curves for chemotherapy, radiation and surgery, with the acceptability frontier."}
+v_wtp <- seq(0, 200000, by = 10000)
+df_ceac <- ceac(l_psa, wtp = v_wtp)
+plot(df_ceac)
+```
+
+```{r ceac-50k, include = FALSE}
+df_ceac_50k <- df_ceac[df_ceac$WTP == 50000, ]
+most_likely <- df_ceac_50k$Strategy[which.max(df_ceac_50k$Proportion)]
+optimal <- df_ceac_50k$Strategy[df_ceac_50k$On_Frontier]
+pr_most_likely <- max(df_ceac_50k$Proportion)
+pr_optimal <- df_ceac_50k$Proportion[df_ceac_50k$On_Frontier]
+```
+
+The strategy most likely to be cost-effective is not always the optimal one. At a willingness to pay of $50,000 per QALY, `r most_likely` has the highest probability of being cost-effective (`r round(pr_most_likely, 3)`), but `r optimal` has the highest expected net benefit (probability `r round(pr_optimal, 3)`), so `r optimal` is the strategy on the frontier. This is why a CEAC should always be shown with its frontier.
+
+### Expected loss curves
+
+Expected loss curves go one step further. For each strategy, they show the benefit expected to be lost by choosing it instead of the strategy that would turn out best, so they combine how likely a strategy is to be the wrong choice with how much is lost when it is. In a single figure, the strategy with the lowest expected loss is the optimal one, the curves show where the optimal strategy switches across thresholds, and the expected loss of the optimal strategy equals the expected value of perfect information (EVPI). Alarid-Escudero et al. ([2019](https://doi.org/10.1016/j.jval.2019.02.008)) describe these advantages of ELCs over CEACs and the CEAF, and recommend reporting them alongside CEACs, the CEAF and the EVPI.
+
+```{r elc, fig.alt = "Expected loss curves for chemotherapy, radiation and surgery on a log scale, with the frontier, which equals the expected value of perfect information."}
+df_elc <- calc_exp_loss(l_psa, wtp = v_wtp)
+plot(df_elc, n_x_ticks = 10)
+```
+
+```{r elc-50k, include = FALSE}
+df_elc_50k <- df_elc[df_elc$WTP == 50000, ]
+loss_optimal <- df_elc_50k$Expected_Loss[df_elc_50k$On_Frontier]
+evpi_50k <- calc_evpi(l_psa, wtp = 50000)$EVPI
+stopifnot(isTRUE(all.equal(loss_optimal, evpi_50k)))
+```
+
+At $50,000 per QALY, `r optimal` has the lowest expected loss, $`r format(round(loss_optimal), big.mark = ",")` per patient, which is also the EVPI at that threshold.
+
+### Value of research: EVPPI and EVSI from one PSA
+
+The EVPI is the most a decision maker should pay to remove all uncertainty. To decide which research is worth doing, it helps to know how much of that value comes from a few parameters, the EVPPI, and how much a study of a given size would capture, the EVSI. Both usually need nested simulations: running the model again for every possible study result.
+
+dampack avoids them. `calc_evppi()` fits a regression metamodel of the net benefit on the parameters of interest across the PSA samples. `calc_evsi()` uses the Gaussian approximation approach of Jalal and Alarid-Escudero ([2018](https://doi.org/10.1177/0272989X17715627)). A regression metamodel relates the net benefit to the parameters, and a Gaussian approximation of the preposterior distribution tells how much a study of `n` patients would narrow the uncertainty around them. It needs only the PSA sample, and it works for correlated parameters, non-Gaussian distributions, and several parameters informed by one study.
+
+Here the parameters of interest are the probabilities of treatment failure with chemotherapy and with surgery, each estimated from an earlier study of `n0 = 50` patients:
+
+```{r voi}
+v_params <- c("pFailChemo", "pFailSurg")
+calc_evpi(l_psa, wtp = 100000)
+l_evppi <- calc_evppi(l_psa, wtp = 100000, params = v_params,
+ outcome = "nmb", k = 3, progress = FALSE)
+l_evppi$df_evppi
+l_evsi <- calc_evsi(l_psa, wtp = 100000, params = v_params,
+ outcome = "nmb", k = 3, n0 = 50,
+ n = c(10, 50, 100, 500, 1000), progress = FALSE)
+l_evsi$df_evsi
+```
+
+```{r voi-check, include = FALSE}
+evpi <- calc_evpi(l_psa, wtp = 100000)$EVPI
+evppi <- l_evppi$df_evppi$EVPPI
+v_evsi <- l_evsi$df_evsi$EVSI
+stopifnot(all(diff(v_evsi) > 0), max(v_evsi) < evppi, evppi < evpi)
+fmt <- function(x) format(round(x), big.mark = ",")
+```
+
+At $100,000 per QALY, removing all uncertainty is worth $`r fmt(evpi)` per patient, and `r round(100 * evppi / evpi)`% of that comes from the two failure probabilities. A new study of 10 patients would capture $`r fmt(v_evsi[1])` per patient, and one of 1,000 patients would capture $`r fmt(max(v_evsi))`, close to the EVPPI. Scaled to the population affected by the decision and compared with the cost of each study design, these values show whether a study is worth running, and how large it should be.
+
+## Learn more
+
+The [package website](https://darth-git.github.io/dampack/) has the full [function reference](https://darth-git.github.io/dampack/reference/) and these articles, best read in this order:
+
+1. [Basic Cost Effectiveness Analysis](https://darth-git.github.io/dampack/articles/basic_cea.html)
+2. [Probabilistic Sensitivity Analysis](https://darth-git.github.io/dampack/articles/psa_analysis.html)
+3. [Value of Information Analysis](https://darth-git.github.io/dampack/articles/voi.html)
+4. [Probabilistic Sensitivity Analysis: Generation](https://darth-git.github.io/dampack/articles/psa_generation.html)
+5. [Deterministic Sensitivity Analysis: Generation](https://darth-git.github.io/dampack/articles/dsa_generation.html)
+
+The same articles are installed with the package: see `vignette(package = "dampack")`. What changed in each release is in the [news](https://darth-git.github.io/dampack/news/).
+
+## Citation
+
+Run `citation("dampack")` for how to cite the package.
+
+The expected loss curves in dampack, and why they complement CEACs and the CEAF, are described in:
+
+> Alarid-Escudero F, Enns EA, Kuntz KM, Michaud TL, Jalal H. "Time Traveling Is Just Too Dangerous" but Some Methods Are Worth Revisiting: The Advantages of Expected Loss Curves Over Cost-Effectiveness Acceptability Curves and Frontier. *Value in Health*. 2019;22(5):611-618. [doi:10.1016/j.jval.2019.02.008](https://doi.org/10.1016/j.jval.2019.02.008)
+
+The Gaussian approximation approach that `calc_evsi()` uses to compute the EVSI from a single PSA sample is described in:
+
+> Jalal H, Alarid-Escudero F. A Gaussian Approximation Approach for Value of Information Analysis. *Medical Decision Making*. 2018;38(2):174-188. [doi:10.1177/0272989X17715627](https://doi.org/10.1177/0272989X17715627)
+
+## Getting help and contributing
+
+Please report bugs and suggest features in the [issue tracker](https://github.com/DARTH-git/dampack/issues). To contribute code, see the [contributing guide](https://github.com/DARTH-git/dampack/blob/main/.github/CONTRIBUTING.md). Everyone taking part in the project agrees to follow its [code of conduct](https://github.com/DARTH-git/dampack/blob/main/CODE_OF_CONDUCT.md).
+
+## Funding
+
+This package was developed with funding from the National Institute of Allergy and Infectious Diseases of the National Institutes of Health under award no. R01AI138783. The content of this package is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.
+
+## The DARTH team
+
+dampack is developed by members of the [DARTH workgroup](https://www.darthworkgroup.com/), a group of researchers developing open-source tools for decision analysis in health.
+
+**Package authors:** Fernando Alarid-Escudero (maintainer), Greg Knowlton, Caleb W. Easterly, Matthew B. Kaufmann, and Eva Enns, with contributions from David Garibay and Mark Clements.
+
+**DARTH workgroup members:**
+
+- Fernando Alarid-Escudero ([@feralaes](https://github.com/feralaes))
+- Eva Enns ([@evaenns](https://github.com/evaenns))
+- David U. Garibay-Treviño ([@du-gartre](https://github.com/du-gartre))
+- Hawre Jalal ([@hjalal](https://github.com/hjalal))
+- Matthew B. Kaufmann ([@mbkauf](https://github.com/mbkauf))
+- Gregory Knowlton ([@gknowlt](https://github.com/gknowlt))
+- Eline Krijkamp ([@krijkamp](https://github.com/krijkamp))
+- Alexandra Moskalewicz ([@amoskalewicz](https://github.com/amoskalewicz))
+- Petros Pechlivanoglou ([@ppehli](https://github.com/ppehli))
+- Jorge Roa ([@jurjoroa](https://github.com/jurjoroa))
+- Mathyn Vervaart ([@matverv](https://github.com/matverv))
+- Ervin Wu ([@ervinro](https://github.com/ervinro))
+- Yansi Wu ([@yansi5](https://github.com/yansi5))
+
+**Other code contributors:** Szu-Yu Zoe Kao ([@syzoekao](https://github.com/syzoekao)) and Michael Fairley ([@mfairley](https://github.com/mfairley)).
diff --git a/README.md b/README.md
index f466e97..2569fa8 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,290 @@
-# dampack
+
+
+
+# dampack
- [](https://github.com/DARTH-git/dampack/actions/workflows/check-standard.yaml)
- [](https://app.codecov.io/gh/DARTH-git/dampack?branch=main)
-
-
-The Decision Analytic Modeling Package (dampack) is a suite of functions for analyzing and visualizing the health economic outputs of mathematical models.
-dampack is developed and maintained by the [Decision Analysis in R for Technologies in Health (DARTH)](https://www.darthworkgroup.com/) workgroup; see [The DARTH team](#the-darth-team) below.
+[](https://CRAN.R-project.org/package=dampack)
+[](https://github.com/DARTH-git/dampack/actions/workflows/check-standard.yaml)
+[](https://app.codecov.io/gh/DARTH-git/dampack?branch=main)
+
+
+The Decision Analytic Modeling Package (dampack) is a suite of functions
+for analyzing and visualizing the health economic outputs of
+mathematical models.
+
+## Why dampack
+
+Decision-analytic models, such as decision trees, Markov cohort models,
+microsimulations and discrete-event simulations, estimate the costs and
+health outcomes of a set of strategies. Turning those outputs into the
+results that cost-effectiveness studies and health technology
+assessments report takes the same analyses every time: finding the
+efficient frontier, computing incremental cost-effectiveness ratios
+(ICERs), summarizing the probabilistic sensitivity analysis (PSA), and
+estimating the value of collecting more information.
+
+dampack does these analyses in R for any model. It only needs the
+model’s outputs, so it works the same whether the model was written in R
+or elsewhere. It is developed by the [DARTH
+workgroup](https://www.darthworkgroup.com/), alongside the DARTH coding
+framework for decision models ([Alarid-Escudero et al.,
+2019](https://doi.org/10.1007/s40273-019-00837-x)), for health decision
+scientists, health economists, and students.
-This package was developed with funding from the National Institute of Allergy and Infectious Diseases of the National Institutes of Health under award no. R01AI138783. The content of this package is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.
+## What it does
+
+- **Cost-effectiveness analysis.** `calculate_icers()` identifies
+ dominated and extendedly dominated strategies and computes ICERs along
+ the efficient frontier; `plot()` draws the frontier on absolute or
+ incremental axes. Where guidelines allow it alongside this fully
+ incremental analysis, `calculate_cers_ref()` also compares every
+ strategy with a single reference strategy, such as the standard of
+ care.
+- **Probabilistic sensitivity analysis.** `make_psa_obj()` stores the
+ PSA output of any model. Its `plot()` and `summary()` methods show the
+ cost-effectiveness plane, `ceac()` computes cost-effectiveness
+ acceptability curves (CEACs) together with the acceptability frontier
+ (CEAF), and `calc_exp_loss()` computes expected loss curves (ELCs),
+ which show in one figure the expected foregone benefit of each
+ strategy, the optimal strategy, and the expected value of perfect
+ information ([Alarid-Escudero et al.,
+ 2019](https://doi.org/10.1016/j.jval.2019.02.008)).
+- **Value of information.** `calc_evpi()` computes the expected value of
+ perfect information (EVPI). `calc_evppi()` estimates the expected
+ value of partial perfect information (EVPPI) with regression
+ metamodels of the PSA ([Strong et al.,
+ 2014](https://doi.org/10.1177/0272989X13505910); [Jalal and
+ Alarid-Escudero, 2018](https://doi.org/10.1177/0272989X17715627)), and
+ `calc_evsi()` estimates the expected value of sample information
+ (EVSI) of a future study with the Gaussian approximation approach
+ ([Jalal and Alarid-Escudero,
+ 2018](https://doi.org/10.1177/0272989X17715627)). Both work from the
+ PSA sample you already have, so no further model runs are needed.
+- **Deterministic sensitivity analysis.** One-way and two-way analyses
+ come either from the PSA, through metamodels (`owsa()`, `twsa()`), or
+ from running your model directly (`run_owsa_det()`, `run_twsa_det()`),
+ with tornado diagrams and optimal-strategy plots.
+- **PSA inputs.** `gen_psa_samp()` draws parameter samples from common
+ distributions, helpers such as `beta_params()` and `gamma_params()`
+ convert means and standard deviations into distribution parameters,
+ and `run_psa()` runs your model over the samples.
## Installation
+
+Install the released version from CRAN:
+
``` r
-# Install release version from CRAN
install.packages("dampack")
```
+Or the development version from GitHub:
+
``` r
-# Install development version from GitHub
-devtools::install_github("DARTH-git/dampack")
+# install.packages("remotes")
+remotes::install_github("DARTH-git/dampack")
```
-Trying to install dampack from Github in a non-US locale on macOS may produce the following error:
+Installing from GitHub on macOS with a non-US locale may fail with
+`Error: (converted from warning) Setting LC_CTYPE failed, using "C"`.
+Running `defaults write org.R-project.R force.LANG en_US.UTF-8` in the
+terminal fixes it.
+
+## Example
+
+`cancer_psa_data` holds the PSA output of an illustrative model that
+compares three cancer treatments over 10,000 samples.
-```
-Error: (converted from warning) Setting LC_CTYPE failed, using "C"
+``` r
+library(dampack)
+data("cancer_psa_data")
+l_psa <- make_psa_obj(cost = cancer_psa_data$cost,
+ effectiveness = cancer_psa_data$effectiveness,
+ parameters = cancer_psa_data$parameters,
+ strategies = cancer_psa_data$strategies)
+
+# ICERs from the mean costs and QALYs of each strategy
+calculate_icers_psa(l_psa)
+#> Strategy Costs ($) QALYs Incremental Costs ($) Incremental QALYs
+#> 1 Radio 16,129 10.68 - -
+#> 2 Chemo 30,901 11.07 14,772 0.38
+#> 3 Surgery 25,110 10.88 - -
+#> ICER ($/QALY) Status
+#> 1 - ND
+#> 2 38,492 ND
+#> 3 - ED
```
-To solve this problem, run the following code in the terminal:
+How likely is each strategy to be cost-effective across
+willingness-to-pay thresholds? The acceptability frontier (squares)
+marks the strategy with the highest expected net benefit at each
+threshold.
+
+``` r
+v_wtp <- seq(0, 200000, by = 10000)
+df_ceac <- ceac(l_psa, wtp = v_wtp)
+plot(df_ceac)
```
-defaults write org.R-project.R force.LANG en_US.UTF-8
+
+
+
+The strategy most likely to be cost-effective is not always the optimal
+one. At a willingness to pay of \$50,000 per QALY, Surgery has the
+highest probability of being cost-effective (0.369), but Chemo has the
+highest expected net benefit (probability 0.356), so Chemo is the
+strategy on the frontier. This is why a CEAC should always be shown with
+its frontier.
+
+### Expected loss curves
+
+Expected loss curves go one step further. For each strategy, they show
+the benefit expected to be lost by choosing it instead of the strategy
+that would turn out best, so they combine how likely a strategy is to be
+the wrong choice with how much is lost when it is. In a single figure,
+the strategy with the lowest expected loss is the optimal one, the
+curves show where the optimal strategy switches across thresholds, and
+the expected loss of the optimal strategy equals the expected value of
+perfect information (EVPI). Alarid-Escudero et
+al. ([2019](https://doi.org/10.1016/j.jval.2019.02.008)) describe these
+advantages of ELCs over CEACs and the CEAF, and recommend reporting them
+alongside CEACs, the CEAF and the EVPI.
+
+``` r
+df_elc <- calc_exp_loss(l_psa, wtp = v_wtp)
+plot(df_elc, n_x_ticks = 10)
```
-## Vignettes
-dampack has a series of vignettes designed to showcase the functionality of the package and explain its underlying methodology.
-The vignettes serve as a guide for proper usage, and it is highly recommended that new users read any relevant vignettes before using the package.
-After installing the package, vignettes can be accessed by typing `vignette(topic, package = "dampack")`, where topic is a character string corresponding to the name of the vignette.
-There is some overlap between the topics and functions covered in the six vignettes, and they should ideally be read in the following order:
-1. basic_cea
-2. psa_analysis
-3. voi
-4. psa_generation
-5. dsa_generation
+
+
+At \$50,000 per QALY, Chemo has the lowest expected loss, \$14,954 per
+patient, which is also the EVPI at that threshold.
+
+### Value of research: EVPPI and EVSI from one PSA
+
+The EVPI is the most a decision maker should pay to remove all
+uncertainty. To decide which research is worth doing, it helps to know
+how much of that value comes from a few parameters, the EVPPI, and how
+much a study of a given size would capture, the EVSI. Both usually need
+nested simulations: running the model again for every possible study
+result.
+
+dampack avoids them. `calc_evppi()` fits a regression metamodel of the
+net benefit on the parameters of interest across the PSA samples.
+`calc_evsi()` uses the Gaussian approximation approach of Jalal and
+Alarid-Escudero ([2018](https://doi.org/10.1177/0272989X17715627)). A
+regression metamodel relates the net benefit to the parameters, and a
+Gaussian approximation of the preposterior distribution tells how much a
+study of `n` patients would narrow the uncertainty around them. It needs
+only the PSA sample, and it works for correlated parameters,
+non-Gaussian distributions, and several parameters informed by one
+study.
+
+Here the parameters of interest are the probabilities of treatment
+failure with chemotherapy and with surgery, each estimated from an
+earlier study of `n0 = 50` patients:
+
+``` r
+v_params <- c("pFailChemo", "pFailSurg")
+calc_evpi(l_psa, wtp = 100000)
+#> WTP EVPI
+#> 1 1e+05 22683.95
+l_evppi <- calc_evppi(l_psa, wtp = 100000, params = v_params,
+ outcome = "nmb", k = 3, progress = FALSE)
+l_evppi$df_evppi
+#> WTP EVPPI
+#> 1 1e+05 8213.325
+l_evsi <- calc_evsi(l_psa, wtp = 100000, params = v_params,
+ outcome = "nmb", k = 3, n0 = 50,
+ n = c(10, 50, 100, 500, 1000), progress = FALSE)
+l_evsi$df_evsi
+#> WTP n EVSI
+#> 1 1e+05 10 1331.363
+#> 2 1e+05 50 4492.632
+#> 3 1e+05 100 5837.748
+#> 4 1e+05 500 7599.690
+#> 5 1e+05 1000 7894.617
+```
+
+At \$100,000 per QALY, removing all uncertainty is worth \$22,684 per
+patient, and 36% of that comes from the two failure probabilities. A new
+study of 10 patients would capture \$1,331 per patient, and one of 1,000
+patients would capture \$7,895, close to the EVPPI. Scaled to the
+population affected by the decision and compared with the cost of each
+study design, these values show whether a study is worth running, and
+how large it should be.
+
+## Learn more
+
+The [package website](https://darth-git.github.io/dampack/) has the full
+[function reference](https://darth-git.github.io/dampack/reference/) and
+these articles, best read in this order:
+
+1. [Basic Cost Effectiveness
+ Analysis](https://darth-git.github.io/dampack/articles/basic_cea.html)
+2. [Probabilistic Sensitivity
+ Analysis](https://darth-git.github.io/dampack/articles/psa_analysis.html)
+3. [Value of Information
+ Analysis](https://darth-git.github.io/dampack/articles/voi.html)
+4. [Probabilistic Sensitivity Analysis:
+ Generation](https://darth-git.github.io/dampack/articles/psa_generation.html)
+5. [Deterministic Sensitivity Analysis:
+ Generation](https://darth-git.github.io/dampack/articles/dsa_generation.html)
+
+The same articles are installed with the package: see
+`vignette(package = "dampack")`. What changed in each release is in the
+[news](https://darth-git.github.io/dampack/news/).
+
+## Citation
+
+Run `citation("dampack")` for how to cite the package.
+
+The expected loss curves in dampack, and why they complement CEACs and
+the CEAF, are described in:
+
+> Alarid-Escudero F, Enns EA, Kuntz KM, Michaud TL, Jalal H. “Time
+> Traveling Is Just Too Dangerous” but Some Methods Are Worth
+> Revisiting: The Advantages of Expected Loss Curves Over
+> Cost-Effectiveness Acceptability Curves and Frontier. *Value in
+> Health*. 2019;22(5):611-618.
+> [doi:10.1016/j.jval.2019.02.008](https://doi.org/10.1016/j.jval.2019.02.008)
+
+The Gaussian approximation approach that `calc_evsi()` uses to compute
+the EVSI from a single PSA sample is described in:
+
+> Jalal H, Alarid-Escudero F. A Gaussian Approximation Approach for
+> Value of Information Analysis. *Medical Decision Making*.
+> 2018;38(2):174-188.
+> [doi:10.1177/0272989X17715627](https://doi.org/10.1177/0272989X17715627)
+
+## Getting help and contributing
+
+Please report bugs and suggest features in the [issue
+tracker](https://github.com/DARTH-git/dampack/issues). To contribute
+code, see the [contributing
+guide](https://github.com/DARTH-git/dampack/blob/main/.github/CONTRIBUTING.md).
+Everyone taking part in the project agrees to follow its [code of
+conduct](https://github.com/DARTH-git/dampack/blob/main/CODE_OF_CONDUCT.md).
+
+## Funding
+
+This package was developed with funding from the National Institute of
+Allergy and Infectious Diseases of the National Institutes of Health
+under award no. R01AI138783. The content of this package is solely the
+responsibility of the authors and does not necessarily represent the
+official views of the National Institutes of Health.
## The DARTH team
-dampack is developed by members of the [DARTH workgroup](https://www.darthworkgroup.com/), a group of researchers developing open-source tools for decision analysis in health.
+dampack is developed by members of the [DARTH
+workgroup](https://www.darthworkgroup.com/), a group of researchers
+developing open-source tools for decision analysis in health.
-**Package authors:** Fernando Alarid-Escudero, Greg Knowlton, Caleb W. Easterly, Matthew B. Kaufmann, and Eva Enns, with contributions from David Garibay (CRAN maintainer) and Mark Clements.
+**Package authors:** Fernando Alarid-Escudero (maintainer), Greg
+Knowlton, Caleb W. Easterly, Matthew B. Kaufmann, and Eva Enns, with
+contributions from David Garibay and Mark Clements.
**DARTH workgroup members:**
@@ -59,11 +295,14 @@ dampack is developed by members of the [DARTH workgroup](https://www.darthworkgr
- Matthew B. Kaufmann ([@mbkauf](https://github.com/mbkauf))
- Gregory Knowlton ([@gknowlt](https://github.com/gknowlt))
- Eline Krijkamp ([@krijkamp](https://github.com/krijkamp))
-- Alexandra Moskalewicz ([@amoskalewicz](https://github.com/amoskalewicz))
+- Alexandra Moskalewicz
+ ([@amoskalewicz](https://github.com/amoskalewicz))
- Petros Pechlivanoglou ([@ppehli](https://github.com/ppehli))
- Jorge Roa ([@jurjoroa](https://github.com/jurjoroa))
- Mathyn Vervaart ([@matverv](https://github.com/matverv))
- Ervin Wu ([@ervinro](https://github.com/ervinro))
- Yansi Wu ([@yansi5](https://github.com/yansi5))
-**Other code contributors:** Szu-Yu Zoe Kao ([@syzoekao](https://github.com/syzoekao)) and Michael Fairley ([@mfairley](https://github.com/mfairley)).
+**Other code contributors:** Szu-Yu Zoe Kao
+([@syzoekao](https://github.com/syzoekao)) and Michael Fairley
+([@mfairley](https://github.com/mfairley)).
diff --git a/_pkgdown.yml b/_pkgdown.yml
index 2219e97..f4e24c1 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -50,6 +50,17 @@ reference:
- print.icers
- plot.icers
+ - title: Comparisons with a reference strategy
+ desc: >
+ Compare every strategy with a single reference strategy, such as
+ the standard of care, where guidelines allow it alongside the fully
+ incremental analysis.
+ contents:
+ - calculate_cers_ref
+ - calculate_cers_ref_psa
+ - print.cers_ref
+ - plot.cers_ref
+
- title: Probabilistic sensitivity analysis (PSA) objects
desc: >
Build a `psa` object from the costs, effects, and parameter draws of any
diff --git a/logo/README.md b/logo/README.md
new file mode 100644
index 0000000..7db9452
--- /dev/null
+++ b/logo/README.md
@@ -0,0 +1,42 @@
+# The dampack logo
+
+The hex sticker is drawn from dampack's own output on `cancer_psa_data`, the package's main
+example dataset:
+
+- **Top panel:** the cost-effectiveness acceptability curves (CEACs) of the three strategies,
+ from `ceac()`, with the acceptability frontier (CEAF) as the heavy line and squares.
+- **Bottom panel:** their expected loss curves (ELCs), from `calc_exp_loss()`, on a log scale.
+ The heavy line is the frontier, which equals the expected value of perfect information.
+- **Dotted line:** both frontiers switch from Radio to Chemo at the same willingness-to-pay
+ threshold, $40,000/QALY. That is the argument for reporting ELCs alongside the CEAC and
+ CEAF ([Alarid-Escudero et al., 2019](https://doi.org/10.1016/j.jval.2019.02.008)).
+
+The colours are viridis option D, the palette of `col = "access"` in dampack's plots. The
+wordmark is set in JetBrains Mono Bold (SIL Open Font License).
+
+## Files
+
+| File | Use |
+|---|---|
+| `dampack-hex.svg` | The sticker. |
+| `dampack-hex-600dpi.png` | Print: 2 in tall at 600 dpi, transparent outside the hex. |
+| `dampack-hex-small.svg` | ELCs only, for small sizes where two panels are too busy. |
+| `dampack-hex-icon.svg` | ELCs only, without text, for favicons. |
+| `../man/figures/logo.png` | README and the pkgdown home page (240 × 278 px). |
+| `../pkgdown/favicon/` | Site favicons, rendered from the icon. |
+
+The SVGs load the wordmark font from Google Fonts. Print shops that ask for outlined text
+need the text in `dampack-hex.svg` converted to paths, for example with
+Inkscape (*Path > Object to Path*).
+
+## Rebuilding
+
+From the package root:
+
+```sh
+Rscript logo/make_hex.R # SVGs, from the current dampack
+bash logo/render.sh # PNGs and favicons, with headless Google Chrome
+```
+
+`logo/` and `pkgdown/` are excluded from the package build, so only `man/figures/logo.png`
+(17 KB) is installed with dampack.
diff --git a/logo/dampack-hex-600dpi.png b/logo/dampack-hex-600dpi.png
new file mode 100644
index 0000000..fbb9b12
Binary files /dev/null and b/logo/dampack-hex-600dpi.png differ
diff --git a/logo/dampack-hex-icon.svg b/logo/dampack-hex-icon.svg
new file mode 100644
index 0000000..e11e782
--- /dev/null
+++ b/logo/dampack-hex-icon.svg
@@ -0,0 +1,12 @@
+
diff --git a/logo/dampack-hex-small.svg b/logo/dampack-hex-small.svg
new file mode 100644
index 0000000..0686aaf
--- /dev/null
+++ b/logo/dampack-hex-small.svg
@@ -0,0 +1,25 @@
+
diff --git a/logo/dampack-hex.svg b/logo/dampack-hex.svg
new file mode 100644
index 0000000..d4334ca
--- /dev/null
+++ b/logo/dampack-hex.svg
@@ -0,0 +1,39 @@
+
diff --git a/logo/make_hex.R b/logo/make_hex.R
new file mode 100644
index 0000000..6bd560c
--- /dev/null
+++ b/logo/make_hex.R
@@ -0,0 +1,130 @@
+# Builds the dampack hex sticker from the package's own output.
+#
+# The sticker shows the cost-effectiveness acceptability curves (CEACs) with the
+# acceptability frontier (CEAF) above the expected loss curves (ELCs) of the three
+# strategies in `cancer_psa_data`, on one willingness-to-pay (WTP) axis. Both frontiers
+# switch from Radio to Chemo at the same threshold, marked by the dotted line
+# (Alarid-Escudero et al. 2019, Value in Health 22(5):611-618, doi:10.1016/j.jval.2019.02.008).
+#
+# Run from the package root: Rscript logo/make_hex.R
+# It writes three SVGs to logo/:
+# dampack-hex.svg the sticker (CEAC/CEAF and ELCs)
+# dampack-hex-small.svg ELCs only, for small sizes such as a navbar
+# dampack-hex-icon.svg ELCs only and no wordmark, for favicons
+# logo/README.md explains how the PNGs in man/figures/ and pkgdown/favicon/ are made from them.
+
+library(dampack)
+
+# ---- data -------------------------------------------------------------------------------
+data("cancer_psa_data")
+l_psa <- make_psa_obj(cost = cancer_psa_data$cost,
+ effectiveness = cancer_psa_data$effectiveness,
+ parameters = cancer_psa_data$parameters,
+ strategies = cancer_psa_data$strategies)
+v_wtp <- seq(0, 100000, by = 2500)
+df_ceac <- as.data.frame(ceac(l_psa, wtp = v_wtp))
+df_elc <- as.data.frame(calc_exp_loss(l_psa, wtp = v_wtp))
+
+# ---- colours and geometry ---------------------------------------------------------------
+# viridis option D, the palette of col = "access" in dampack's plots
+l_col <- list(bg = "#eff5f2", ink = "#440154", rim = "#31688e",
+ strat = c("#3b528b", "#21908c", "#5dc863"), mark = "#5dc863")
+v_dash <- c("none", "3 2", "1 2") # one line type per strategy, as in col = "bw"
+hex_points <- "86.6,0 173.2,50 173.2,150 86.6,200 0,150 0,50" # pointy-top hex, 173.2 x 200
+v_log_loss <- range(log10(df_elc$Expected_Loss))
+
+f1 <- function(x) formatC(x, format = "f", digits = 1)
+wtp_x <- function(w, x0 = 34, x1 = 139) x0 + w / max(v_wtp) * (x1 - x0)
+y_prob <- function(p, top, bottom) bottom - p * (bottom - top)
+y_loss <- function(v, top, bottom) {
+ bottom - (log10(v) - v_log_loss[1]) / diff(v_log_loss) * (bottom - top)
+}
+
+path_d <- function(x, y) paste0("M", paste(f1(x), f1(y), collapse = " L"))
+
+# strategy curves, frontier line, and frontier squares every 12,500 for one panel
+panel <- function(df, value, yfun, lwd_front, sq, x0 = 34, x1 = 139, lwd_strat = 1.2) {
+ v_strat <- sort(unique(df$Strategy))
+ v_curves <- vapply(seq_along(v_strat), function(i) {
+ d <- df[df$Strategy == v_strat[i], ]
+ d <- d[order(d$WTP), ]
+ dash <- if (v_dash[i] == "none") "" else sprintf(' stroke-dasharray="%s"', v_dash[i])
+ sprintf('',
+ path_d(wtp_x(d$WTP, x0, x1), yfun(d[[value]])), l_col$strat[i], lwd_strat, dash)
+ }, character(1))
+ d_f <- df[df$On_Frontier, ]
+ d_f <- d_f[order(d_f$WTP), ]
+ front <- sprintf('',
+ path_d(wtp_x(d_f$WTP, x0, x1), yfun(d_f[[value]])), l_col$ink, lwd_front)
+ d_sq <- d_f[d_f$WTP %% 12500 == 0, ]
+ squares <- sprintf('',
+ f1(wtp_x(d_sq$WTP, x0, x1) - sq / 2), f1(yfun(d_sq[[value]]) - sq / 2), sq, sq,
+ l_col$mark, l_col$ink)
+ c(v_curves, front, squares)
+}
+
+grid <- function(v_y) {
+ sprintf('',
+ paste(sprintf("M34,%s H139", v_y), collapse = " "), l_col$ink)
+}
+
+wordmark <- function(y) {
+ sprintf('dampack',
+ y, l_col$ink)
+}
+label <- function(x, y, txt, anchor = "end") {
+ sprintf('%s',
+ x, y, anchor, l_col$ink, txt)
+}
+
+hex_svg <- function(body, font = TRUE) {
+ c('")
+}
+
+# ---- the sticker: CEAC/CEAF on top, ELCs below ------------------------------------------
+top <- c(41, 75) # CEAC panel, probability 1 at the top
+bot <- c(88, 122) # ELC panel, log expected loss
+d_front <- df_ceac[df_ceac$On_Frontier, ]
+d_front <- d_front[order(d_front$WTP), ]
+wtp_switch <- d_front$WTP[which(d_front$Strategy != d_front$Strategy[1])[1]]
+d_front_elc <- df_elc[df_elc$On_Frontier, ]
+d_front_elc <- d_front_elc[order(d_front_elc$WTP), ]
+stopifnot(wtp_switch == d_front_elc$WTP[which(d_front_elc$Strategy != d_front_elc$Strategy[1])[1]])
+
+v_sticker <- hex_svg(c(
+ grid(c(top, bot)),
+ sprintf('',
+ f1(wtp_x(wtp_switch)), top[1] - 3, bot[2] + 3, l_col$ink),
+ panel(df_ceac, "Proportion", function(p) y_prob(p, top[1], top[2]), 3.2, 4.5),
+ panel(df_elc, "Expected_Loss", function(v) y_loss(v, bot[1], bot[2]), 3.2, 4.5),
+ label(139, 131, "WTP →"),
+ wordmark(156)
+))
+
+# ---- small version: ELCs only -----------------------------------------------------------
+v_small <- hex_svg(c(
+ grid(c(46, 83, 120)),
+ panel(df_elc, "Expected_Loss", function(v) y_loss(v, 46, 120), 3.6, 5.5),
+ label(139, 129, "WTP →"),
+ wordmark(153)
+))
+
+# ---- icon: ELCs only, no wordmark, no text (so it needs no font) ------------------------
+# the icon keeps only the strategy curves and the frontier, drawn wider and thicker
+v_icon <- hex_svg(panel(df_elc, "Expected_Loss", function(v) y_loss(v, 48, 146), 12, 0,
+ x0 = 24, x1 = 149, lwd_strat = 6), font = FALSE)
+v_icon <- v_icon[!grepl("^
+render() {
+ python3 -I - "$1" "$2" "$3" "$5" "$TMP/page.html" <<'EOF'
+import sys
+svg, w, h, bg, out = sys.argv[1:6]
+s = open(svg).read().replace('width="173.2" height="200"',
+ f'width="{w}" height="{h}" preserveAspectRatio="xMidYMid meet"')
+open(out, "w").write("" + s + "")
+EOF
+ "$CHROME" --headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 \
+ --default-background-color=00000000 --virtual-time-budget=8000 \
+ --window-size="$2,$3" --screenshot="$4" "file://$TMP/page.html" > /dev/null 2>&1
+}
+
+# the sticker: README, pkgdown home page, and print (600 dpi at 2 in tall)
+render logo/dampack-hex.svg 240 278 man/figures/logo.png transparent
+render logo/dampack-hex.svg 1039 1200 logo/dampack-hex-600dpi.png transparent
+
+# favicons for the pkgdown site, from the icon (no text, so no font needed)
+cp logo/dampack-hex-icon.svg pkgdown/favicon/favicon.svg
+render logo/dampack-hex-icon.svg 96 96 pkgdown/favicon/favicon-96x96.png transparent
+render logo/dampack-hex-icon.svg 192 192 pkgdown/favicon/web-app-manifest-192x192.png transparent
+render logo/dampack-hex-icon.svg 512 512 pkgdown/favicon/web-app-manifest-512x512.png transparent
+render logo/dampack-hex-icon.svg 180 180 pkgdown/favicon/apple-touch-icon.png "#ffffff"
+for s in 16 32 48; do render logo/dampack-hex-icon.svg $s $s "$TMP/icon-$s.png" transparent; done
+
+# favicon.ico holding the 16, 32 and 48 px PNGs
+python3 -I - "$TMP" pkgdown/favicon/favicon.ico <<'EOF'
+import struct, sys
+tmp, out = sys.argv[1], sys.argv[2]
+v_png = [open(f"{tmp}/icon-{s}.png", "rb").read() for s in (16, 32, 48)]
+header = struct.pack(" pkgdown/favicon/site.webmanifest <<'EOF'
+{
+ "name": "dampack",
+ "short_name": "dampack",
+ "icons": [
+ {"src": "/web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable"},
+ {"src": "/web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}
+ ],
+ "theme_color": "#ffffff",
+ "background_color": "#ffffff",
+ "display": "standalone"
+}
+EOF
+echo "Rendered man/figures/logo.png, logo/dampack-hex-600dpi.png and pkgdown/favicon/"
diff --git a/man/add_cers_ref_uncertainty.Rd b/man/add_cers_ref_uncertainty.Rd
new file mode 100644
index 0000000..053f30b
--- /dev/null
+++ b/man/add_cers_ref_uncertainty.Rd
@@ -0,0 +1,27 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/cers_ref.R
+\name{add_cers_ref_uncertainty}
+\alias{add_cers_ref_uncertainty}
+\title{Add PSA intervals and quadrant proportions to a \code{cers_ref} object}
+\usage{
+add_cers_ref_uncertainty(df_ref, psa, wtp, nhb)
+}
+\arguments{
+\item{df_ref}{a \code{cers_ref} object computed from the means of \code{psa}.}
+
+\item{psa}{the \code{psa} object.}
+
+\item{wtp}{a single willingness-to-pay threshold (currency per unit of effect). If given, the
+net monetary benefit of each strategy and its difference from the reference are added.
+The default (\code{NULL}) adds no net-benefit columns.}
+
+\item{nhb}{if \code{TRUE}, also add the net health benefit and its difference from the
+reference. Requires \code{wtp}.}
+}
+\value{
+\code{df_ref} with the columns described in \code{\link{calculate_cers_ref_psa}}.
+}
+\description{
+Add PSA intervals and quadrant proportions to a \code{cers_ref} object
+}
+\keyword{internal}
diff --git a/man/add_reference_and_nmb.Rd b/man/add_nmb.Rd
similarity index 63%
rename from man/add_reference_and_nmb.Rd
rename to man/add_nmb.Rd
index 7d4f97b..c7764b4 100644
--- a/man/add_reference_and_nmb.Rd
+++ b/man/add_nmb.Rd
@@ -1,19 +1,14 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/icers.R
-\name{add_reference_and_nmb}
-\alias{add_reference_and_nmb}
-\title{Add reference-strategy and net-benefit columns to an icers object}
+\name{add_nmb}
+\alias{add_nmb}
+\title{Add net-benefit columns and stored attributes to an icers object}
\usage{
-add_reference_and_nmb(df_icers, ref_str, wtp, nhb, currency)
+add_nmb(df_icers, wtp, nhb, currency)
}
\arguments{
\item{df_icers}{an \code{icers} object.}
-\item{ref_str}{name of a reference strategy (one of \code{strategies}) to compare every
-strategy against, for example \code{"Standard of care"}. The default (\code{NULL}) adds no
-reference columns. The frontier-based results (\code{Status}, \code{Inc_Cost},
-\code{Inc_Effect}, \code{ICER}) never depend on the reference.}
-
\item{wtp}{a single willingness-to-pay threshold (currency per unit of effect). If given,
the net monetary benefit (\code{NMB}) of each strategy is added. The default (\code{NULL})
adds no net-benefit columns.}
diff --git a/man/add_reference_intervals.Rd b/man/add_reference_intervals.Rd
deleted file mode 100644
index 45abbf9..0000000
--- a/man/add_reference_intervals.Rd
+++ /dev/null
@@ -1,30 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/icers.R
-\name{add_reference_intervals}
-\alias{add_reference_intervals}
-\title{Add 95\% intervals for the differences from a reference strategy}
-\usage{
-add_reference_intervals(df_icers, psa, ref_str, wtp)
-}
-\arguments{
-\item{df_icers}{an \code{icers} object with reference columns.}
-
-\item{psa}{the \code{psa} object it was computed from.}
-
-\item{ref_str}{name of a reference strategy (one of \code{strategies}) to compare every
-strategy against, for example \code{"Standard of care"}. The default (\code{NULL}) adds no
-reference columns. The frontier-based results (\code{Status}, \code{Inc_Cost},
-\code{Inc_Effect}, \code{ICER}) never depend on the reference.}
-
-\item{wtp}{a single willingness-to-pay threshold (currency per unit of effect). If given,
-the net monetary benefit (\code{NMB}) of each strategy is added. The default (\code{NULL})
-adds no net-benefit columns.}
-}
-\value{
-\code{df_icers} with the interval columns added.
-}
-\description{
-Quantiles of the sample-by-sample differences between each strategy and the reference, placed
-after the corresponding point estimate. \code{NA} for the reference itself.
-}
-\keyword{internal}
diff --git a/man/calculate_cers_ref.Rd b/man/calculate_cers_ref.Rd
new file mode 100644
index 0000000..144c920
--- /dev/null
+++ b/man/calculate_cers_ref.Rd
@@ -0,0 +1,114 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/cers_ref.R
+\name{calculate_cers_ref}
+\alias{calculate_cers_ref}
+\title{Compare every strategy with a reference strategy}
+\usage{
+calculate_cers_ref(
+ cost,
+ effect,
+ strategies,
+ ref_str,
+ wtp = NULL,
+ nhb = FALSE,
+ currency = NULL
+)
+}
+\arguments{
+\item{cost}{vector of cost for each strategy.}
+
+\item{effect}{vector of effect for each strategy.}
+
+\item{strategies}{string vector of strategy names.}
+
+\item{ref_str}{name of the reference strategy, one of \code{strategies}, for example
+\code{"Standard of care"}.}
+
+\item{wtp}{a single willingness-to-pay threshold (currency per unit of effect). If given, the
+net monetary benefit of each strategy and its difference from the reference are added.
+The default (\code{NULL}) adds no net-benefit columns.}
+
+\item{nhb}{if \code{TRUE}, also add the net health benefit and its difference from the
+reference. Requires \code{wtp}.}
+
+\item{currency}{currency symbol used when printing and plotting the results, for example
+\code{"€"}. The default (\code{NULL}) uses \code{"$"}.}
+}
+\value{
+A data frame of class \code{cers_ref}, with the reference strategy in the first row
+and the other strategies by increasing cost, and these columns:
+\describe{
+ \item{Strategy, Cost, Effect}{as given.}
+ \item{Inc_Cost, Inc_Effect}{cost and effect minus those of the reference.}
+ \item{CER}{\code{Inc_Cost / Inc_Effect}, the cost-effectiveness ratio compared with the
+ reference. It is \code{NA} where a ratio is not meaningful: for the reference itself and for
+ dominant, dominated and equivalent strategies.}
+ \item{Status}{one of \code{"Reference"}, \code{"Dominant"} (not more costly and at least as
+ effective), \code{"Dominated"} (not less costly and no more effective),
+ \code{"More costly, more effective"}, \code{"Less costly, less effective"}, or
+ \code{"Equivalent"} (same cost and effect).}
+ \item{NMB, Inc_NMB}{with \code{wtp}: the net monetary benefit, \code{wtp * Effect - Cost},
+ and its difference from the reference. A strategy with a positive \code{Inc_NMB} is
+ cost-effective compared with the reference at this threshold.}
+ \item{NHB, Inc_NHB}{with \code{nhb = TRUE}: the net health benefit,
+ \code{Effect - Cost / wtp}, and its difference from the reference.}
+}
+The reference strategy, threshold and currency are stored as attributes, which the
+\code{print} and \code{plot} methods use.
+
+For a strategy that is more costly and more effective than the reference, a \code{CER} below
+the willingness-to-pay threshold means it is cost-effective compared with the reference. For a
+strategy that is less costly and less effective, the \code{CER} is the cost saved per unit of
+effect lost, and the strategy is cost-effective compared with the reference when its
+\code{CER} is \emph{above} the threshold.
+}
+\description{
+Compares each strategy with a single reference strategy chosen by the user, such as the
+current standard of care: the difference in cost and in effect from the reference, the
+cost-effectiveness ratio (CER) of that difference, and where each strategy lies on the
+incremental cost-effectiveness plane centered at the reference.
+
+These comparisons are \emph{not} the incremental cost-effectiveness ratios (ICERs) of a
+fully incremental analysis. When more than two strategies are compared, health technology
+assessment guidelines require a fully incremental (sequential) analysis, in which dominated
+and extendedly dominated strategies are removed and each strategy on the cost-effectiveness
+frontier is compared with the next less costly one: use \code{\link{calculate_icers}} for that.
+Comparisons with a single reference are a complement for settings where they are relevant
+and justified. The NICE manual (2022), for example, states that "pairwise comparisons may be
+presented when relevant and justified (for example, when the technology is expected to
+specifically displace individual comparators)", after requiring a fully incremental
+analysis. The CDA-AMC (2017) and Zorginstituut Nederland (2024) guidelines also require a
+sequential analysis when more than two interventions are compared.
+}
+\examples{
+# three strategies; "Standard of care" is neither the cheapest nor the least effective
+df_ref <- calculate_cers_ref(cost = c(12000, 9000, 20000),
+ effect = c(8.0, 7.6, 8.5),
+ strategies = c("Standard of care", "Generic drug", "New drug"),
+ ref_str = "Standard of care",
+ wtp = 50000)
+df_ref
+plot(df_ref)
+
+# the fully incremental analysis of the same strategies
+calculate_icers(cost = c(12000, 9000, 20000),
+ effect = c(8.0, 7.6, 8.5),
+ strategies = c("Standard of care", "Generic drug", "New drug"))
+}
+\references{
+National Institute for Health and Care Excellence (NICE). NICE health technology evaluations:
+the manual (PMG36), section 4.6, "Economic evaluation". London: NICE; 2022.
+\url{https://www.nice.org.uk/process/pmg36/chapter/economic-evaluation-2}
+
+CDA-AMC (formerly CADTH). Guidelines for the Economic Evaluation of Health Technologies:
+Canada. 4th ed. Ottawa: CADTH; 2017.
+\url{https://www.cda-amc.ca/sites/default/files/pdf/guidelines_for_the_economic_evaluation_of_health_technologies_canada_4th_ed.pdf}
+
+Zorginstituut Nederland. Guideline for economic evaluations in healthcare (2024 version).
+Diemen: Zorginstituut Nederland; 2024.
+\url{https://english.zorginstituutnederland.nl/documents/2024/01/16/guideline-for-economic-evaluations-in-healthcare}
+}
+\seealso{
+\code{\link{plot.cers_ref}}, \code{\link{calculate_cers_ref_psa}} for the same
+comparison from a PSA, and \code{\link{calculate_icers}} for the fully incremental analysis.
+}
diff --git a/man/calculate_cers_ref_psa.Rd b/man/calculate_cers_ref_psa.Rd
new file mode 100644
index 0000000..0a30074
--- /dev/null
+++ b/man/calculate_cers_ref_psa.Rd
@@ -0,0 +1,85 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/cers_ref.R
+\name{calculate_cers_ref_psa}
+\alias{calculate_cers_ref_psa}
+\title{Compare every strategy with a reference strategy, from a \code{psa} object}
+\usage{
+calculate_cers_ref_psa(
+ psa,
+ ref_str,
+ wtp = NULL,
+ nhb = FALSE,
+ uncertainty = FALSE
+)
+}
+\arguments{
+\item{psa}{\code{psa} object from \code{\link{make_psa_obj}}.}
+
+\item{ref_str}{name of the reference strategy, one of \code{strategies}, for example
+\code{"Standard of care"}.}
+
+\item{wtp}{a single willingness-to-pay threshold (currency per unit of effect). If given, the
+net monetary benefit of each strategy and its difference from the reference are added.
+The default (\code{NULL}) adds no net-benefit columns.}
+
+\item{nhb}{if \code{TRUE}, also add the net health benefit and its difference from the
+reference. Requires \code{wtp}.}
+
+\item{uncertainty}{if \code{TRUE}, add the 95\% intervals and quadrant proportions described
+in Value. Defaults to \code{FALSE}.}
+}
+\value{
+A \code{cers_ref} object with the columns described in
+\code{\link{calculate_cers_ref}}, computed from the mean cost and effect of each strategy. The
+currency of \code{psa} is kept.
+
+With \code{uncertainty = TRUE}, the differences from the reference are computed in every PSA
+sample, and these columns are added (\code{NA} for the reference itself):
+\itemize{
+ \item \code{Lower_95_Inc_Cost} and \code{Upper_95_Inc_Cost}, the 2.5th and 97.5th
+ percentiles of the difference in cost, placed after \code{Inc_Cost}; likewise for
+ \code{Inc_Effect} and, with \code{wtp}, \code{Inc_NMB} (and \code{Inc_NHB}).
+ \item \code{Prop_NE}, \code{Prop_SE}, \code{Prop_SW}, and \code{Prop_NW}, the proportion of
+ samples in each quadrant of the incremental cost-effectiveness plane: NE more effective and
+ more costly; SE more effective and not more costly; SW not more effective and not more
+ costly; NW not more effective and more costly. The four proportions sum to 1.
+ \item With \code{wtp}, \code{Prop_CE}, the proportion of samples in which the strategy is
+ cost-effective compared with the reference (it has a higher net monetary benefit).
+}
+}
+\description{
+Compares each strategy with a reference strategy using the mean costs and effects of a
+probabilistic sensitivity analysis (PSA), as \code{\link{calculate_cers_ref}} does for a base
+case. With \code{uncertainty = TRUE}, it also summarizes the uncertainty in each comparison
+across the PSA samples. See \code{\link{calculate_cers_ref}} for when a comparison with a
+single reference is appropriate, and \code{\link{calculate_icers_psa}} for the fully
+incremental analysis.
+}
+\examples{
+data(cancer_psa_data)
+l_psa <- make_psa_obj(cost = cancer_psa_data$cost,
+ effectiveness = cancer_psa_data$effectiveness,
+ parameters = cancer_psa_data$parameters,
+ strategies = cancer_psa_data$strategies)
+df_ref <- calculate_cers_ref_psa(l_psa, ref_str = "Radio", wtp = 50000,
+ uncertainty = TRUE)
+df_ref
+plot(df_ref)
+}
+\references{
+National Institute for Health and Care Excellence (NICE). NICE health technology evaluations:
+the manual (PMG36), section 4.6, "Economic evaluation". London: NICE; 2022.
+\url{https://www.nice.org.uk/process/pmg36/chapter/economic-evaluation-2}
+
+CDA-AMC (formerly CADTH). Guidelines for the Economic Evaluation of Health Technologies:
+Canada. 4th ed. Ottawa: CADTH; 2017.
+\url{https://www.cda-amc.ca/sites/default/files/pdf/guidelines_for_the_economic_evaluation_of_health_technologies_canada_4th_ed.pdf}
+
+Zorginstituut Nederland. Guideline for economic evaluations in healthcare (2024 version).
+Diemen: Zorginstituut Nederland; 2024.
+\url{https://english.zorginstituutnederland.nl/documents/2024/01/16/guideline-for-economic-evaluations-in-healthcare}
+}
+\seealso{
+\code{\link{calculate_cers_ref}}, \code{\link{plot.cers_ref}}, and
+\code{\link{plot.psa}} with \code{ref_str} for the PSA samples on the incremental plane.
+}
diff --git a/man/calculate_icers.Rd b/man/calculate_icers.Rd
index e6e2fbb..c42d49e 100644
--- a/man/calculate_icers.Rd
+++ b/man/calculate_icers.Rd
@@ -8,7 +8,6 @@ calculate_icers(
cost,
effect,
strategies,
- ref_str = NULL,
wtp = NULL,
nhb = FALSE,
currency = NULL
@@ -21,11 +20,6 @@ calculate_icers(
\item{strategies}{string vector of strategy names}
-\item{ref_str}{name of a reference strategy (one of \code{strategies}) to compare every
-strategy against, for example \code{"Standard of care"}. The default (\code{NULL}) adds no
-reference columns. The frontier-based results (\code{Status}, \code{Inc_Cost},
-\code{Inc_Effect}, \code{ICER}) never depend on the reference.}
-
\item{wtp}{a single willingness-to-pay threshold (currency per unit of effect). If given,
the net monetary benefit (\code{NMB}) of each strategy is added. The default (\code{NULL})
adds no net-benefit columns.}
@@ -40,18 +34,14 @@ A data frame and \code{icers} object of strategies and their associated
status, incremental cost, incremental effect, and ICER, computed sequentially along the
cost-effectiveness frontier.
-If \code{ref_str} is given, four columns compare each strategy with the reference:
-\code{Inc_Cost_ref} and \code{Inc_Effect_ref} (cost and effect minus those of the
-reference), \code{ICER_ref}, and \code{Status_ref}, one of \code{"Reference"},
-\code{"Dominant"} (less costly and at least as effective), \code{"Dominated"} (more costly
-and no more effective), \code{"More costly, more effective"},
-\code{"Less costly, less effective"}, or \code{"Equivalent"} (same cost and effect).
-\code{ICER_ref} is \code{NA} where a ratio is not meaningful: for the reference itself and
-for dominant, dominated, and equivalent strategies.
-
-If \code{wtp} is given, \code{NMB} (\code{wtp * Effect - Cost}) is added, and with
-\code{ref_str} also \code{Inc_NMB_ref}, the NMB minus that of the reference. With
-\code{nhb = TRUE}, \code{NHB} (\code{Effect - Cost / wtp}) and \code{Inc_NHB_ref} are added too.
+If \code{wtp} is given, \code{NMB} (\code{wtp * Effect - Cost}) is added. With
+\code{nhb = TRUE}, \code{NHB} (\code{Effect - Cost / wtp}) is added too.
+
+The ICERs are always sequential: each strategy on the frontier is compared with the next less
+costly one, after removing dominated and extendedly dominated strategies. This is the fully
+incremental analysis that health technology assessment guidelines require when more than two
+strategies are compared. To compare every strategy with a single reference strategy instead,
+use \code{\link{calculate_cers_ref}}.
}
\description{
This function takes in strategies and their associated cost and effect, assigns them
@@ -97,14 +87,14 @@ plot(icers)
# note that longer strategy names will get truncated
plot(icers, label = "all")
-## Comparing every strategy with a reference strategy
-hund_ref <- calculate_icers(hund_strat$Cost,
- hund_strat$QALYs,
- hund_strat$Strategy,
- ref_str = hund_strat$Strategy[1],
- wtp = 50000)
-print(hund_ref, ref = "reference")
+# the incremental cost-effectiveness plane, with the least costly strategy on the
+# frontier at the origin
+plot(icers, incremental = TRUE)
+
+## Net monetary benefit at a willingness-to-pay threshold
+calculate_icers(sum_cdiff$meanCost, sum_cdiff$meanEffect, sum_cdiff$Strategy,
+ wtp = 50000)
}
\seealso{
-\code{\link{plot.icers}}
+\code{\link{plot.icers}}, \code{\link{calculate_cers_ref}}
}
diff --git a/man/calculate_icers_psa.Rd b/man/calculate_icers_psa.Rd
index 3766cea..a672a51 100644
--- a/man/calculate_icers_psa.Rd
+++ b/man/calculate_icers_psa.Rd
@@ -4,13 +4,7 @@
\alias{calculate_icers_psa}
\title{Calculate incremental cost-effectiveness ratios from a \code{psa} object.}
\usage{
-calculate_icers_psa(
- psa,
- uncertainty = FALSE,
- ref_str = NULL,
- wtp = NULL,
- nhb = FALSE
-)
+calculate_icers_psa(psa, uncertainty = FALSE, wtp = NULL, nhb = FALSE)
}
\arguments{
\item{psa}{\code{psa} object from \code{link{make_psa_object}}}
@@ -18,11 +12,6 @@ calculate_icers_psa(
\item{uncertainty}{whether or not 95\% quantiles for the cost and QALY outcomes should be included
in the resulting ICER table. Defaults to \code{FALSE}.}
-\item{ref_str}{name of a reference strategy (one of \code{strategies}) to compare every
-strategy against, for example \code{"Standard of care"}. The default (\code{NULL}) adds no
-reference columns. The frontier-based results (\code{Status}, \code{Inc_Cost},
-\code{Inc_Effect}, \code{ICER}) never depend on the reference.}
-
\item{wtp}{a single willingness-to-pay threshold (currency per unit of effect). If given,
the net monetary benefit (\code{NMB}) of each strategy is added. The default (\code{NULL})
adds no net-benefit columns.}
@@ -35,11 +24,8 @@ status, cost, effect, incremental cost, incremental effect, and ICER. If \code{u
set to \code{TRUE}, four additional columns are provided for the 2.5th and 97.5th quantiles for
each strategy's cost and effect.
-With \code{ref_str}, \code{wtp}, or \code{nhb}, the reference-strategy and net-benefit columns
-described in \code{\link{calculate_icers}} are added. With \code{uncertainty = TRUE} and
-\code{ref_str}, the 2.5th and 97.5th quantiles of the sample-by-sample differences from the reference
-are also given for \code{Inc_Cost_ref}, \code{Inc_Effect_ref}, and (with \code{wtp})
-\code{Inc_NMB_ref}, in columns such as \code{Lower_95_Inc_Cost_ref} and \code{Upper_95_Inc_Cost_ref}.
+With \code{wtp} or \code{nhb}, the net-benefit columns described in
+\code{\link{calculate_icers}} are added.
}
\description{
The mean costs and QALYs for each strategy in a PSA are used
@@ -60,4 +46,6 @@ even if present in the ICER table.
\code{\link{plot.icers}}
\code{\link{calculate_icers}}
+
+\code{\link{calculate_cers_ref_psa}} to compare every strategy with a reference strategy
}
diff --git a/man/check_ref_str.Rd b/man/check_ref_str.Rd
index 38e818a..d888f0c 100644
--- a/man/check_ref_str.Rd
+++ b/man/check_ref_str.Rd
@@ -1,5 +1,5 @@
% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/icers.R
+% Please edit documentation in R/cers_ref.R
\name{check_ref_str}
\alias{check_ref_str}
\title{Check a reference strategy name}
diff --git a/man/figures/README-ceac-1.png b/man/figures/README-ceac-1.png
new file mode 100644
index 0000000..6a9b816
Binary files /dev/null and b/man/figures/README-ceac-1.png differ
diff --git a/man/figures/README-elc-1.png b/man/figures/README-elc-1.png
new file mode 100644
index 0000000..6a8a99e
Binary files /dev/null and b/man/figures/README-elc-1.png differ
diff --git a/man/figures/logo.png b/man/figures/logo.png
new file mode 100644
index 0000000..cd79329
Binary files /dev/null and b/man/figures/logo.png differ
diff --git a/man/format_cea_table.Rd b/man/format_cea_table.Rd
new file mode 100644
index 0000000..d5bec25
--- /dev/null
+++ b/man/format_cea_table.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/icers.R
+\name{format_cea_table}
+\alias{format_cea_table}
+\title{Format the numeric columns of a CEA table for printing}
+\usage{
+format_cea_table(df_table, l_format)
+}
+\arguments{
+\item{df_table}{data frame to format.}
+
+\item{l_format}{named list, one element per column to format: a list of the number of digits
+(\code{NA} to leave the column as it is) and the header to print.}
+}
+\value{
+\code{df_table} with the formatted columns, as character, and renamed.
+}
+\description{
+Format the numeric columns of a CEA table for printing
+}
+\keyword{internal}
diff --git a/man/plot.cers_ref.Rd b/man/plot.cers_ref.Rd
new file mode 100644
index 0000000..22a3d92
--- /dev/null
+++ b/man/plot.cers_ref.Rd
@@ -0,0 +1,114 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/cers_ref.R
+\name{plot.cers_ref}
+\alias{plot.cers_ref}
+\title{Plot a comparison with a reference strategy}
+\usage{
+\method{plot}{cers_ref}(
+ x,
+ wtp = attr(x, "wtp"),
+ lines = NULL,
+ label = c("all", "none"),
+ label_max_char = NULL,
+ ref_axis = TRUE,
+ ref_caption = TRUE,
+ currency = NULL,
+ effect_units = "QALYs",
+ col = c("access", "full", "bw"),
+ alpha = 1,
+ txtsize = 12,
+ n_x_ticks = 6,
+ n_y_ticks = 6,
+ xbreaks = NULL,
+ ybreaks = NULL,
+ xlim = NULL,
+ ylim = NULL,
+ xexpand = expansion(0.1),
+ yexpand = expansion(0.1),
+ max.iter = 20000,
+ ...
+)
+}
+\arguments{
+\item{x}{a \code{cers_ref} object from \code{\link{calculate_cers_ref}} or
+\code{\link{calculate_cers_ref_psa}}.}
+
+\item{wtp}{a willingness-to-pay threshold for the dotted line through the origin. Defaults to
+the threshold stored in \code{x}, if any; \code{NULL} draws no line.}
+
+\item{lines}{whether to draw a segment from the reference to each strategy. The default
+(\code{NULL}) draws them when there are at most 20 strategies besides the reference, since
+with many strategies they make the plot hard to read.}
+
+\item{label}{whether to label all strategies (the default) or none.}
+
+\item{label_max_char}{maximum number of characters of the strategy labels; longer names are
+truncated. The default (\code{NULL}) does not truncate.}
+
+\item{ref_axis}{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{currency}{currency symbol. Defaults to the currency stored in \code{x}, or \code{"$"}.}
+
+\item{effect_units}{units of effectiveness. Defaults to \code{"QALYs"}.}
+
+\item{col}{color palette for the status of each strategy: \code{"access"} (the default, an
+accessible palette), \code{"full"}, or \code{"bw"}.}
+
+\item{alpha}{opacity of the points.}
+
+\item{txtsize}{base text size}
+
+\item{n_x_ticks}{number of x-axis ticks}
+
+\item{n_y_ticks}{number of y-axis ticks}
+
+\item{xbreaks}{vector of x-axis breaks.
+will override \code{n_x_ticks} if provided.}
+
+\item{ybreaks}{vector of y-axis breaks.
+will override \code{n_y_ticks} if provided.}
+
+\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{xexpand}{Padding around data. See \code{\link[ggplot2]{scale_continuous}} for details.}
+
+\item{yexpand}{Padding around data. See \code{\link[ggplot2]{scale_continuous}} for details.
+The default behavior in ggplot2 is \code{expansion(0.05)}. See \code{\link[ggplot2]{expansion}}
+for how to modify this.}
+
+\item{max.iter}{Maximum number of iterations to try to resolve overlaps.
+Defaults to 10000.}
+
+\item{...}{further arguments (not used).}
+}
+\value{
+a \code{ggplot2} object, which can be modified by adding further layers.
+}
+\description{
+Draws the incremental cost-effectiveness plane centered at the reference strategy: each
+strategy is placed at its difference in effect (x) and cost (y) from the reference, which sits
+at the origin. Optional segments join the reference to each strategy, forming a star, and an
+optional willingness-to-pay line goes through the origin: strategies below the line are
+cost-effective compared with the reference at that threshold.
+}
+\examples{
+df_ref <- calculate_cers_ref(cost = c(12000, 9000, 20000),
+ effect = c(8.0, 7.6, 8.5),
+ strategies = c("Standard of care", "Generic drug", "New drug"),
+ ref_str = "Standard of care")
+plot(df_ref, wtp = 50000)
+
+# many strategies: no segments, no labels
+data(hund_strat)
+df_hund <- calculate_cers_ref(hund_strat$Cost, hund_strat$QALYs, hund_strat$Strategy,
+ ref_str = "1")
+plot(df_hund, label = "none")
+}
+\seealso{
+\code{\link{calculate_cers_ref}}
+}
diff --git a/man/plot.icers.Rd b/man/plot.icers.Rd
index af2dfdd..bd06faf 100644
--- a/man/plot.icers.Rd
+++ b/man/plot.icers.Rd
@@ -22,7 +22,7 @@
xexpand = expansion(0.1),
yexpand = expansion(0.1),
max.iter = 20000,
- ref_str = NULL,
+ incremental = FALSE,
wtp = NULL,
ref_axis = TRUE,
ref_caption = TRUE,
@@ -71,20 +71,23 @@ 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{incremental}{if \code{TRUE}, plot the incremental cost-effectiveness plane: the costs
+and effects of every strategy are shown relative to those of the first non-dominated strategy
+(the least costly strategy on the frontier), which is placed at the origin (0, 0). The frontier
+and the status of each strategy do not change. Defaults to \code{FALSE} (absolute costs and
+effects). To compare every strategy with a reference strategy of your choice, use
+\code{\link{calculate_cers_ref}} and its \code{plot} method.}
\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.}
+drawn 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.
+\item{ref_axis}{with \code{incremental = TRUE}, draw dashed axes through the origin.
Defaults to \code{TRUE}.}
+\item{ref_caption}{add a caption naming the strategy at the origin (with
+\code{incremental = TRUE}) and the WTP threshold (with \code{wtp}). 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/print.cers_ref.Rd b/man/print.cers_ref.Rd
new file mode 100644
index 0000000..4ebffff
--- /dev/null
+++ b/man/print.cers_ref.Rd
@@ -0,0 +1,38 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/cers_ref.R
+\name{print.cers_ref}
+\alias{print.cers_ref}
+\title{Print a comparison with a reference strategy}
+\usage{
+\method{print}{cers_ref}(
+ x,
+ currency = NULL,
+ dig_cost = 0,
+ dig_eff = 2,
+ dig_cer = 0,
+ dig_prop = 3,
+ ...
+)
+}
+\arguments{
+\item{x}{a \code{cers_ref} object.}
+
+\item{currency}{currency symbol. Defaults to the currency stored in \code{x}, or \code{"$"}.}
+
+\item{dig_cost}{number of digits to round costs and net monetary benefits to.}
+
+\item{dig_eff}{number of digits to round effects and net health benefits to.}
+
+\item{dig_cer}{number of digits to round the cost-effectiveness ratios to.}
+
+\item{dig_prop}{number of digits to round the proportions of PSA samples to.}
+
+\item{...}{further arguments (not used).}
+}
+\value{
+the formatted table, invisibly.
+}
+\description{
+Prints the table of a \code{\link{calculate_cers_ref}} object with formatted numbers and
+headers that name the reference strategy.
+}
diff --git a/man/print.icers.Rd b/man/print.icers.Rd
index 558f9aa..677b0f4 100644
--- a/man/print.icers.Rd
+++ b/man/print.icers.Rd
@@ -4,15 +4,7 @@
\alias{print.icers}
\title{Print the formatted CEA table}
\usage{
-\method{print}{icers}(
- x,
- currency = NULL,
- dig_cost = 0,
- dig_eff = 2,
- dig_icer = 0,
- ref = c("sequential", "reference", "both"),
- ...
-)
+\method{print}{icers}(x, currency = NULL, dig_cost = 0, dig_eff = 2, dig_icer = 0, ...)
}
\arguments{
\item{x}{Object of class \code{icers}}
@@ -26,19 +18,12 @@ Defaults to the currency stored in \code{x}, or \code{"$"}.}
\item{dig_icer}{integer. number of digits to round ICER to}
-\item{ref}{which comparison to show: \code{"sequential"} (the default), \code{"reference"},
-or \code{"both"}.}
-
\item{...}{Additional arguments passed to other methods.}
}
\value{
a dataframe object - formatted CEA table
}
\description{
-By default, prints the sequential cost-effectiveness table: each strategy on the frontier is
-compared with the previous one. If the \code{icers} object was created with a reference
-strategy (\code{ref_str} in \code{\link{calculate_icers}}), \code{ref = "reference"} shows the
-comparison of every strategy with the reference instead, listing the reference first and the
-other strategies by increasing cost. \code{ref = "both"} shows both comparisons, in the
-frontier order of the sequential table.
+Prints the sequential cost-effectiveness table: each strategy on the frontier is compared with
+the previous one.
}
diff --git a/man/status_vs_reference.Rd b/man/status_vs_reference.Rd
index 10def36..8fcd925 100644
--- a/man/status_vs_reference.Rd
+++ b/man/status_vs_reference.Rd
@@ -1,5 +1,5 @@
% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/icers.R
+% Please edit documentation in R/cers_ref.R
\name{status_vs_reference}
\alias{status_vs_reference}
\title{Status of each strategy relative to a reference strategy}
diff --git a/man/summary.psa.Rd b/man/summary.psa.Rd
index ca0a145..9251f93 100644
--- a/man/summary.psa.Rd
+++ b/man/summary.psa.Rd
@@ -4,36 +4,18 @@
\alias{summary.psa}
\title{summarize a psa object across all simulations}
\usage{
-\method{summary}{psa}(object, calc_sds = FALSE, ref_str = NULL, wtp = NULL, ...)
+\method{summary}{psa}(object, calc_sds = FALSE, ...)
}
\arguments{
\item{object}{the psa object}
\item{calc_sds}{whether or not to calculate the standard deviations. Defaults to FALSE}
-\item{ref_str}{name of a reference strategy. If given, each strategy is compared with it
-sample by sample (see Value). Defaults to \code{NULL}.}
-
-\item{wtp}{a single willingness-to-pay threshold. If given, the mean net monetary benefit is
-added (see Value). Defaults to \code{NULL}.}
-
\item{...}{further arguments to summary (not used)}
}
\value{
a \code{data.frame} containing the mean cost and effectiveness for each strategy and, if requested,
the standard deviations of the cost and effectiveness for each strategy.
-
-With \code{ref_str}, the differences between each strategy and the reference are computed in
-every PSA sample, and these columns are added (\code{NA} for the reference itself):
-\code{meanIncCost} and \code{meanIncEffect}, the mean differences in cost and effect; and
-\code{propNE}, \code{propSE}, \code{propSW}, and \code{propNW}, the proportion of samples in each
-quadrant of the incremental cost-effectiveness plane: NE more effective and more costly, SE more
-effective and not more costly (dominant), SW not more effective and not more costly, and NW not more
-effective and more costly (dominated). The four proportions sum to 1.
-
-With \code{wtp}, \code{meanNMB} (\code{wtp * effect - cost}, averaged over samples) is added; with
-\code{ref_str} too, also \code{meanIncNMB} and \code{propCostEffective}, the proportion of samples in
-which the strategy has a higher NMB than the reference (it lies below the willingness-to-pay line).
}
\description{
summarize a psa object across all simulations
diff --git a/pkgdown/favicon/apple-touch-icon.png b/pkgdown/favicon/apple-touch-icon.png
new file mode 100644
index 0000000..d2a2f61
Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon.png differ
diff --git a/pkgdown/favicon/favicon-96x96.png b/pkgdown/favicon/favicon-96x96.png
new file mode 100644
index 0000000..a3134ca
Binary files /dev/null and b/pkgdown/favicon/favicon-96x96.png differ
diff --git a/pkgdown/favicon/favicon.ico b/pkgdown/favicon/favicon.ico
new file mode 100644
index 0000000..4fcc881
Binary files /dev/null and b/pkgdown/favicon/favicon.ico differ
diff --git a/pkgdown/favicon/favicon.svg b/pkgdown/favicon/favicon.svg
new file mode 100644
index 0000000..e11e782
--- /dev/null
+++ b/pkgdown/favicon/favicon.svg
@@ -0,0 +1,12 @@
+
diff --git a/pkgdown/favicon/site.webmanifest b/pkgdown/favicon/site.webmanifest
new file mode 100644
index 0000000..105ff31
--- /dev/null
+++ b/pkgdown/favicon/site.webmanifest
@@ -0,0 +1,11 @@
+{
+ "name": "dampack",
+ "short_name": "dampack",
+ "icons": [
+ {"src": "/web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable"},
+ {"src": "/web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}
+ ],
+ "theme_color": "#ffffff",
+ "background_color": "#ffffff",
+ "display": "standalone"
+}
diff --git a/pkgdown/favicon/web-app-manifest-192x192.png b/pkgdown/favicon/web-app-manifest-192x192.png
new file mode 100644
index 0000000..f320e0c
Binary files /dev/null and b/pkgdown/favicon/web-app-manifest-192x192.png differ
diff --git a/pkgdown/favicon/web-app-manifest-512x512.png b/pkgdown/favicon/web-app-manifest-512x512.png
new file mode 100644
index 0000000..3558c61
Binary files /dev/null and b/pkgdown/favicon/web-app-manifest-512x512.png differ
diff --git a/tests/testthat/test_cers_ref.R b/tests/testthat/test_cers_ref.R
new file mode 100644
index 0000000..4afebc2
--- /dev/null
+++ b/tests/testthat/test_cers_ref.R
@@ -0,0 +1,178 @@
+# calculate_cers_ref() and calculate_cers_ref_psa(): every strategy against a reference (#209)
+
+# Toy example with one strategy in each position relative to the reference "Ref":
+# strategy cost effect vs Ref: inc cost inc effect status
+# Ref 100 1.0 - - Reference
+# More 200 2.0 100 1.0 More costly, more effective (CER 100)
+# Cheaper 50 1.5 -50 0.5 Dominant
+# Worse 300 0.5 200 -0.5 Dominated
+# Less 80 0.8 -20 -0.2 Less costly, less effective (CER 100)
+# Same 100 1.0 0 0.0 Equivalent
+df_toy <- data.frame(strategy = c("Ref", "More", "Cheaper", "Worse", "Less", "Same"),
+ cost = c(100, 200, 50, 300, 80, 100),
+ effect = c(1, 2, 1.5, 0.5, 0.8, 1),
+ stringsAsFactors = FALSE)
+toy_cers <- function(ref_str = "Ref", ...) {
+ calculate_cers_ref(df_toy$cost, df_toy$effect, df_toy$strategy, ref_str = ref_str, ...)
+}
+row_of <- function(x, s) x[x$Strategy == s, ]
+
+test_that("comparisons with the reference match hand calculations", {
+ x <- toy_cers()
+ expect_s3_class(x, "cers_ref")
+ expect_identical(names(x), c("Strategy", "Cost", "Effect", "Inc_Cost", "Inc_Effect", "CER", "Status"))
+ expect_identical(attr(x, "ref_str"), "Ref")
+
+ expected <- list(
+ Ref = list(NA_real_, NA_real_, NA_real_, "Reference"),
+ More = list(100, 1, 100, "More costly, more effective"),
+ Cheaper = list(-50, 0.5, NA_real_, "Dominant"),
+ Worse = list(200, -0.5, NA_real_, "Dominated"),
+ Less = list(-20, -0.2, 100, "Less costly, less effective"),
+ Same = list(0, 0, NA_real_, "Equivalent")
+ )
+ for (s in names(expected)) {
+ r <- row_of(x, s)
+ expect_equal(r$Inc_Cost, expected[[s]][[1]], info = s)
+ expect_equal(r$Inc_Effect, expected[[s]][[2]], info = s)
+ expect_equal(r$CER, expected[[s]][[3]], info = s)
+ expect_equal(r$Status, expected[[s]][[4]], info = s)
+ }
+ expect_type(x$CER, "double")
+})
+
+test_that("the reference comes first, then the other strategies by cost", {
+ x <- toy_cers(ref_str = "More")
+ expect_equal(x$Strategy, c("More", "Cheaper", "Less", "Ref", "Same", "Worse"))
+
+ data(hund_strat)
+ y <- calculate_cers_ref(hund_strat$Cost, hund_strat$QALYs, hund_strat$Strategy, ref_str = "1")
+ v_rest <- hund_strat[hund_strat$Strategy != 1, ]
+ expect_equal(y$Strategy, c("1", as.character(v_rest$Strategy[order(v_rest$Cost)])))
+ r0 <- row_of(y, "1")
+ others <- y$Strategy != "1"
+ expect_equal(y$Inc_Cost[others], y$Cost[others] - r0$Cost)
+ expect_equal(y$Inc_Effect[others], y$Effect[others] - r0$Effect)
+})
+
+test_that("a dominated or the most expensive strategy can be the reference", {
+ x <- toy_cers(ref_str = "Worse") # Worse is dominated and the most expensive strategy
+ expect_equal(row_of(x, "Worse")$Status, "Reference")
+ expect_equal(row_of(x, "Cheaper")$Status, "Dominant")
+ expect_equal(row_of(x, "Cheaper")$Inc_Cost, 50 - 300)
+ expect_true(all(x$Inc_Cost[x$Strategy != "Worse"] < 0))
+})
+
+test_that("wtp adds NMB and its difference from the reference; nhb adds NHB", {
+ x <- toy_cers(wtp = 150)
+ expect_equal(x$NMB, 150 * x$Effect - x$Cost)
+ expect_equal(row_of(x, "More")$Inc_NMB, (150 * 2 - 200) - (150 * 1 - 100))
+ expect_true(is.na(row_of(x, "Ref")$Inc_NMB))
+ expect_false(any(c("NHB", "Inc_NHB") %in% names(x)))
+ expect_identical(attr(x, "wtp"), 150)
+
+ z <- toy_cers(wtp = 150, nhb = TRUE)
+ expect_equal(z$NHB, z$Effect - z$Cost / 150)
+ expect_equal(row_of(z, "Cheaper")$Inc_NHB, (1.5 - 50 / 150) - (1 - 100 / 150))
+})
+
+test_that("edge cases: one strategy, two strategies, names with spaces", {
+ one <- calculate_cers_ref(10, 1, "Standard of care", ref_str = "Standard of care", wtp = 100)
+ expect_equal(one$Status, "Reference")
+ expect_equal(one$NMB, 90)
+
+ two <- calculate_cers_ref(c(10, 30), c(1, 2), c("Standard of care", "New drug (A)"),
+ ref_str = "Standard of care")
+ expect_equal(row_of(two, "New drug (A)")$CER, 20)
+ expect_equal(row_of(two, "New drug (A)")$Status, "More costly, more effective")
+})
+
+test_that("invalid inputs give informative errors", {
+ expect_error(calculate_cers_ref(df_toy$cost, df_toy$effect, df_toy$strategy), "must name the reference")
+ expect_error(toy_cers(ref_str = "Nope"), "must be one of the strategies")
+ expect_error(toy_cers(ref_str = c("Ref", "More")), "single strategy name")
+ expect_error(toy_cers(wtp = c(100, 200)), "single non-negative number")
+ expect_error(toy_cers(wtp = -1), "single non-negative number")
+ expect_error(toy_cers(nhb = TRUE), "requires `wtp`")
+ expect_error(calculate_cers_ref(1:2, 1:3, c("a", "b"), ref_str = "a"), "same length")
+ expect_error(calculate_cers_ref(1:2, 1:2, c("a", "a"), ref_str = "a"), "unique")
+})
+
+test_that("print() names the reference and formats the table", {
+ x <- toy_cers(wtp = 150, currency = "€")
+ out <- capture.output(tbl <- print(x))
+ expect_true(any(grepl("not a fully incremental analysis", out, fixed = TRUE)))
+ expect_true("CER vs Ref (€/QALY)" %in% names(tbl))
+ expect_true("Incremental NMB vs Ref (€)" %in% names(tbl))
+ expect_equal(tbl[["CER vs Ref (€/QALY)"]][1], "-")
+})
+
+# calculate_icers() stays fully incremental: no reference strategy
+test_that("calculate_icers() has no reference strategy", {
+ expect_false("ref_str" %in% names(formals(calculate_icers)))
+ expect_false("ref_str" %in% names(formals(calculate_icers_psa)))
+ expect_false("ref_str" %in% names(formals(summary.psa)))
+ x <- calculate_icers(df_toy$cost, df_toy$effect, df_toy$strategy)
+ expect_identical(names(x), c("Strategy", "Cost", "Effect", "Inc_Cost", "Inc_Effect", "ICER", "Status"))
+ y <- calculate_icers(df_toy$cost, df_toy$effect, df_toy$strategy, wtp = 150, nhb = TRUE)
+ expect_equal(y$NMB, 150 * y$Effect - y$Cost)
+ expect_equal(y$NHB, y$Effect - y$Cost / 150)
+ expect_identical(attr(y, "wtp"), 150)
+ expect_error(calculate_icers(df_toy$cost, df_toy$effect, df_toy$strategy, nhb = TRUE),
+ "requires `wtp`")
+})
+
+# PSA ----------------------------------------------------------------------------------------
+
+# Four PSA samples; the difference "New" - "Ref" falls in a different quadrant in each:
+# sample inc effect inc cost quadrant
+# 1 +0.2 +100 NE (more effective, more costly)
+# 2 +0.2 -50 SE (more effective, less costly)
+# 3 -0.1 -50 SW (less effective, less costly)
+# 4 -0.1 +100 NW (less effective, more costly)
+df_cost <- data.frame(Ref = c(1000, 1000, 1000, 1000), New = c(1100, 950, 950, 1100))
+df_eff <- data.frame(Ref = c(1, 1, 1, 1), New = c(1.2, 1.2, 0.9, 0.9))
+psa_q <- make_psa_obj(df_cost, df_eff, strategies = c("Ref", "New"), currency = "€")
+
+test_that("calculate_cers_ref_psa() uses the means of the PSA and keeps its currency", {
+ s <- summary(psa_q)
+ expected <- calculate_cers_ref(s$meanCost, s$meanEffect, s$Strategy, ref_str = "Ref",
+ wtp = 1000, currency = "€")
+ expect_equal(calculate_cers_ref_psa(psa_q, ref_str = "Ref", wtp = 1000), expected)
+ expect_identical(attr(expected, "currency"), "€")
+})
+
+test_that("uncertainty = TRUE gives quadrant shares and the share of cost-effective samples", {
+ x <- calculate_cers_ref_psa(psa_q, ref_str = "Ref", wtp = 1000, uncertainty = TRUE)
+ r_new <- row_of(x, "New")
+ expect_equal(unlist(r_new[, c("Prop_NE", "Prop_SE", "Prop_SW", "Prop_NW")], use.names = FALSE),
+ rep(0.25, 4))
+ inmb <- 1000 * (df_eff$New - df_eff$Ref) - (df_cost$New - df_cost$Ref) # 100, 250, -50, -200
+ expect_equal(r_new$Prop_CE, mean(inmb > 0))
+ expect_equal(r_new$Lower_95_Inc_NMB, unname(quantile(inmb, 0.025)))
+ r_ref <- row_of(x, "Ref")
+ expect_true(all(is.na(r_ref[, c("Lower_95_Inc_Cost", "Prop_NE", "Prop_CE")])))
+ # each interval follows its point estimate
+ v_names <- names(x)
+ expect_equal(match("Lower_95_Inc_Cost", v_names), match("Inc_Cost", v_names) + 1)
+ expect_identical(attr(x, "ref_str"), "Ref")
+ expect_s3_class(x, "cers_ref")
+})
+
+test_that("uncertainty = TRUE gives intervals of the sample-by-sample differences", {
+ 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)
+ x <- calculate_cers_ref_psa(psa_big, ref_str = "Surgery", wtp = 50000, uncertainty = TRUE)
+ i_chemo <- which(cancer_psa_data$strategies == "Chemo")
+ i_surg <- which(cancer_psa_data$strategies == "Surgery")
+ r <- row_of(x, "Chemo")
+ d_cost <- cancer_psa_data$cost[[i_chemo]] - cancer_psa_data$cost[[i_surg]]
+ d_eff <- cancer_psa_data$effectiveness[[i_chemo]] - cancer_psa_data$effectiveness[[i_surg]]
+ expect_equal(r$Lower_95_Inc_Cost, unname(quantile(d_cost, 0.025)))
+ expect_equal(r$Upper_95_Inc_Cost, unname(quantile(d_cost, 0.975)))
+ expect_equal(r$Lower_95_Inc_Effect, unname(quantile(d_eff, 0.025)))
+ expect_equal(r$Upper_95_Inc_NMB, unname(quantile(50000 * d_eff - d_cost, 0.975)))
+ out <- capture.output(tbl <- print(x))
+ expect_match(tbl$Prop_NE[2], "^0\\.[0-9]{3}$")
+})
diff --git a/tests/testthat/test_elc.R b/tests/testthat/test_elc.R
index cd0eeb1..41751f5 100644
--- a/tests/testthat/test_elc.R
+++ b/tests/testthat/test_elc.R
@@ -68,3 +68,22 @@ test_that("plot.exp_loss(col = 'bw') uses linewidth and builds without warnings"
expect_equal(unique(b$data[[i_line]]$linewidth), 3)
expect_equal(length(unique(b$data[[i_line]]$linetype)), length(unique(el$Strategy)))
})
+
+# with log_y = TRUE, the default y breaks were evenly spaced: they bunched up at the top of
+# the log axis and left the lower orders of magnitude without labels
+test_that("plot.exp_loss(log_y = TRUE) labels every order of magnitude of the y axis", {
+ el <- calc_exp_loss(psa_obj, wtp = seq(0, 2e5, by = 1e4))
+ b <- ggplot2::ggplot_build(plot(el))
+ v_breaks <- b$layout$panel_params[[1]]$y$breaks # on the log10 scale
+ v_breaks <- v_breaks[!is.na(v_breaks)]
+ v_range <- log10(range(el$Expected_Loss))
+ # a labelled break in every order of magnitude the data cover
+ v_decades <- seq(ceiling(v_range[1]), floor(v_range[2]))
+ expect_true(all(v_decades %in% round(v_breaks, 10)))
+ # user-supplied breaks still win, and a linear axis keeps its evenly spaced breaks
+ b2 <- ggplot2::ggplot_build(plot(el, ybreaks = c(1e3, 1e4)))
+ expect_equal(10^b2$layout$panel_params[[1]]$y$breaks[!is.na(b2$layout$panel_params[[1]]$y$breaks)],
+ c(1e3, 1e4))
+ b3 <- ggplot2::ggplot_build(plot(el, log_y = FALSE))
+ expect_equal(diff(range(diff(stats::na.omit(b3$layout$panel_params[[1]]$y$breaks)))), 0)
+})
diff --git a/tests/testthat/test_icers_reference.R b/tests/testthat/test_icers_reference.R
deleted file mode 100644
index 89f9c4b..0000000
--- a/tests/testthat/test_icers_reference.R
+++ /dev/null
@@ -1,136 +0,0 @@
-# calculate_icers() against a reference strategy (#209) and net benefit (#200)
-
-# Toy example with one strategy in each position relative to the reference "Ref":
-# strategy cost effect vs Ref: inc cost inc effect status
-# Ref 100 1.0 - - Reference
-# More 200 2.0 100 1.0 More costly, more effective (ICER 100)
-# Cheaper 50 1.5 -50 0.5 Dominant
-# Worse 300 0.5 200 -0.5 Dominated
-# Less 80 0.8 -20 -0.2 Less costly, less effective (ICER 100)
-# Same 100 1.0 0 0.0 Equivalent
-df_toy <- data.frame(strategy = c("Ref", "More", "Cheaper", "Worse", "Less", "Same"),
- cost = c(100, 200, 50, 300, 80, 100),
- effect = c(1, 2, 1.5, 0.5, 0.8, 1),
- stringsAsFactors = FALSE)
-toy_icers <- function(...) {
- calculate_icers(df_toy$cost, df_toy$effect, df_toy$strategy, ...)
-}
-row_of <- function(x, s) x[x$Strategy == s, ]
-
-test_that("without ref_str or wtp the output is unchanged", {
- x <- toy_icers()
- expect_identical(names(x), c("Strategy", "Cost", "Effect", "Inc_Cost", "Inc_Effect", "ICER", "Status"))
- expect_null(attr(x, "ref_str"))
-})
-
-test_that("reference columns match hand calculations", {
- x <- toy_icers(ref_str = "Ref")
- # sequential (frontier) results are unchanged by ref_str
- x0 <- toy_icers()
- expect_equal(as.data.frame(x)[, names(x0)], as.data.frame(x0))
- expect_identical(attr(x, "ref_str"), "Ref")
-
- expected <- list(
- Ref = list(NA_real_, NA_real_, NA_real_, "Reference"),
- More = list(100, 1, 100, "More costly, more effective"),
- Cheaper = list(-50, 0.5, NA_real_, "Dominant"),
- Worse = list(200, -0.5, NA_real_, "Dominated"),
- Less = list(-20, -0.2, 100, "Less costly, less effective"),
- Same = list(0, 0, NA_real_, "Equivalent")
- )
- for (s in names(expected)) {
- r <- row_of(x, s)
- expect_equal(r$Inc_Cost_ref, expected[[s]][[1]], info = s)
- expect_equal(r$Inc_Effect_ref, expected[[s]][[2]], info = s)
- expect_equal(r$ICER_ref, expected[[s]][[3]], info = s)
- expect_equal(r$Status_ref, expected[[s]][[4]], info = s)
- }
- expect_type(x$ICER_ref, "double")
-})
-
-test_that("a dominated or the most expensive strategy can be the reference", {
- x <- toy_icers(ref_str = "Worse")
- expect_equal(row_of(x, "Worse")$Status_ref, "Reference")
- expect_equal(row_of(x, "Cheaper")$Status_ref, "Dominant")
- expect_equal(row_of(x, "Cheaper")$Inc_Cost_ref, 50 - 300)
- # the frontier itself does not depend on which strategy is the reference
- expect_equal(x$Status, toy_icers()$Status)
-
- y <- toy_icers(ref_str = "Worse") # Worse is also the most expensive strategy
- expect_true(all(y$Inc_Cost_ref[y$Strategy != "Worse"] < 0))
-})
-
-test_that("NMB is added by default with wtp, NHB only on request", {
- x <- toy_icers(wtp = 150)
- expect_equal(x$NMB, 150 * x$Effect - x$Cost)
- expect_false(any(c("NHB", "Inc_NMB_ref", "Inc_NHB_ref") %in% names(x)))
- expect_identical(attr(x, "wtp"), 150)
-
- y <- toy_icers(ref_str = "Ref", wtp = 150)
- expect_equal(row_of(y, "More")$Inc_NMB_ref, (150 * 2 - 200) - (150 * 1 - 100))
- expect_true(is.na(row_of(y, "Ref")$Inc_NMB_ref))
- expect_false("NHB" %in% names(y))
-
- z <- toy_icers(ref_str = "Ref", wtp = 150, nhb = TRUE)
- expect_equal(z$NHB, z$Effect - z$Cost / 150)
- expect_equal(row_of(z, "Cheaper")$Inc_NHB_ref, (1.5 - 50 / 150) - (1 - 100 / 150))
-})
-
-test_that("hund_strat: reference columns equal the difference from the reference", {
- data("hund_strat")
- ref <- hund_strat$Strategy[3]
- x <- calculate_icers(hund_strat$Cost, hund_strat$QALYs, hund_strat$Strategy, ref_str = ref)
- r0 <- row_of(x, ref)
- others <- x$Strategy != ref
- expect_equal(x$Inc_Cost_ref[others], x$Cost[others] - r0$Cost)
- expect_equal(x$Inc_Effect_ref[others], x$Effect[others] - r0$Effect)
-})
-
-test_that("edge cases: one strategy, two strategies, names with spaces", {
- one <- calculate_icers(10, 1, "Standard of care", ref_str = "Standard of care", wtp = 100)
- expect_equal(one$Status_ref, "Reference")
- expect_equal(one$NMB, 90)
-
- two <- calculate_icers(c(10, 30), c(1, 2), c("Standard of care", "New drug (A)"),
- ref_str = "Standard of care")
- expect_equal(row_of(two, "New drug (A)")$ICER_ref, 20)
- expect_equal(row_of(two, "New drug (A)")$Status_ref, "More costly, more effective")
-})
-
-test_that("invalid ref_str, wtp, and nhb give informative errors", {
- expect_error(toy_icers(ref_str = "Nope"), "must be one of the strategies")
- expect_error(toy_icers(ref_str = c("Ref", "More")), "single strategy name")
- expect_error(toy_icers(wtp = c(100, 200)), "single non-negative number")
- expect_error(toy_icers(wtp = -1), "single non-negative number")
- expect_error(toy_icers(nhb = TRUE), "requires `wtp`")
-})
-
-test_that("print.icers shows the sequential table by default and the reference views on request", {
- x <- toy_icers(ref_str = "Ref", wtp = 150, currency = "€")
- out_seq <- capture.output(print(x))
- expect_true(any(grepl("ICER (€/QALY)", out_seq, fixed = TRUE)))
- expect_false(any(grepl("vs Ref", out_seq, fixed = TRUE)))
-
- out_ref <- capture.output(print(x, ref = "reference"))
- expect_true(any(grepl("vs Ref", out_ref, fixed = TRUE)))
- expect_false(any(grepl("Incremental Costs (€)", out_ref, fixed = TRUE)))
-
- out_both <- capture.output(print(x, ref = "both"))
- expect_true(any(grepl("vs Ref", out_both, fixed = TRUE)))
- expect_true(any(grepl("Incremental Costs (€)", out_both, fixed = TRUE)))
-
- expect_error(print(toy_icers(), ref = "reference"), "no reference strategy")
-})
-
-test_that("print(ref = \"reference\") lists the reference first, then by cost", {
- data(hund_strat)
- x <- calculate_icers(hund_strat$Cost, hund_strat$QALYs, hund_strat$Strategy, ref_str = "1")
- expect_true(which(x$Strategy == "1") > 1)
- out <- utils::capture.output(tbl <- print(x, ref = "reference"))
- expect_equal(tbl$Strategy[1], "1")
- v_rest <- hund_strat[hund_strat$Strategy != 1, ]
- expect_equal(tbl$Strategy[-1], as.character(v_rest$Strategy[order(v_rest$Cost)]))
- # the sequential and combined views keep the frontier order of the object
- out <- utils::capture.output(tbl_both <- print(x, ref = "both"))
- expect_equal(tbl_both$Strategy, x$Strategy)
-})
diff --git a/tests/testthat/test_psa_reference.R b/tests/testthat/test_psa_reference.R
deleted file mode 100644
index 047a580..0000000
--- a/tests/testthat/test_psa_reference.R
+++ /dev/null
@@ -1,77 +0,0 @@
-# summary.psa() and calculate_icers_psa() against a reference strategy (#209, #202)
-
-# Four PSA samples; the difference "New" - "Ref" falls in a different quadrant in each:
-# sample inc effect inc cost quadrant
-# 1 +0.2 +100 NE (more effective, more costly)
-# 2 +0.2 -50 SE (more effective, less costly)
-# 3 -0.1 -50 SW (less effective, less costly)
-# 4 -0.1 +100 NW (less effective, more costly)
-df_cost <- data.frame(Ref = c(1000, 1000, 1000, 1000), New = c(1100, 950, 950, 1100))
-df_eff <- data.frame(Ref = c(1, 1, 1, 1), New = c(1.2, 1.2, 0.9, 0.9))
-psa_q <- make_psa_obj(df_cost, df_eff, strategies = c("Ref", "New"))
-
-test_that("summary.psa() is unchanged without ref_str and wtp", {
- expect_identical(names(summary(psa_q)), c("Strategy", "meanCost", "meanEffect"))
-})
-
-test_that("summary.psa(ref_str = ) gives mean differences and quadrant shares", {
- s <- summary(psa_q, ref_str = "Ref")
- r_new <- s[s$Strategy == "New", ]
- r_ref <- s[s$Strategy == "Ref", ]
- expect_equal(r_new$meanIncCost, mean(df_cost$New - df_cost$Ref))
- expect_equal(r_new$meanIncEffect, mean(df_eff$New - df_eff$Ref))
- expect_equal(unlist(r_new[, c("propNE", "propSE", "propSW", "propNW")], use.names = FALSE),
- rep(0.25, 4))
- expect_true(all(is.na(r_ref[, c("meanIncCost", "meanIncEffect", "propNE", "propSE", "propSW", "propNW")])))
- expect_error(summary(psa_q, ref_str = "Nope"), "must be one of the strategies")
-})
-
-test_that("summary.psa(wtp = ) gives mean NMB and the share of cost-effective samples", {
- s <- summary(psa_q, wtp = 1000)
- expect_equal(s$meanNMB, unname(1000 * colMeans(df_eff) - colMeans(df_cost)))
- expect_false(any(c("meanIncNMB", "propCostEffective") %in% names(s)))
-
- s_ref <- summary(psa_q, ref_str = "Ref", wtp = 1000)
- inmb <- 1000 * (df_eff$New - df_eff$Ref) - (df_cost$New - df_cost$Ref) # 100, 250, -50, -200
- r_new <- s_ref[s_ref$Strategy == "New", ]
- expect_equal(r_new$meanIncNMB, mean(inmb))
- expect_equal(r_new$propCostEffective, mean(inmb > 0))
- expect_equal(r_new$propCostEffective, 0.5)
-})
-
-data("cancer_psa_data")
-psa_big <- make_psa_obj(cancer_psa_data$cost, cancer_psa_data$effectiveness,
- cancer_psa_data$parameters, c("Chemotherapy", "Radiation therapy", "Surgery"))
-
-test_that("calculate_icers_psa() passes ref_str, wtp, and nhb to calculate_icers()", {
- s <- summary(psa_big)
- expected <- calculate_icers(s$meanCost, s$meanEffect, s$Strategy,
- ref_str = "Surgery", wtp = 50000, nhb = TRUE, currency = psa_big$currency)
- obtained <- calculate_icers_psa(psa_big, ref_str = "Surgery", wtp = 50000, nhb = TRUE)
- expect_equal(obtained, expected)
-})
-
-test_that("calculate_icers_psa(uncertainty = TRUE) adds intervals for the reference comparison", {
- x <- calculate_icers_psa(psa_big, uncertainty = TRUE, ref_str = "Surgery", wtp = 50000)
- expect_identical(attr(x, "ref_str"), "Surgery")
- r <- x[x$Strategy == "Chemotherapy", ]
- d_cost <- cancer_psa_data$cost[[1]] - cancer_psa_data$cost[[3]]
- d_eff <- cancer_psa_data$effectiveness[[1]] - cancer_psa_data$effectiveness[[3]]
- expect_equal(r$Lower_95_Inc_Cost_ref, unname(quantile(d_cost, 0.025)))
- expect_equal(r$Upper_95_Inc_Cost_ref, unname(quantile(d_cost, 0.975)))
- expect_equal(r$Lower_95_Inc_Effect_ref, unname(quantile(d_eff, 0.025)))
- expect_equal(r$Upper_95_Inc_NMB_ref, unname(quantile(50000 * d_eff - d_cost, 0.975)))
- r_ref <- x[x$Strategy == "Surgery", ]
- expect_true(is.na(r_ref$Lower_95_Inc_Cost_ref))
- # the frontier-based columns and their existing intervals are unchanged
- x0 <- calculate_icers_psa(psa_big, uncertainty = TRUE)
- expect_equal(as.data.frame(x)[, names(x0)], as.data.frame(x0)[, names(x0)])
-})
-
-test_that("print.icers() keeps reference intervals out of the sequential view", {
- x <- calculate_icers_psa(psa_big, uncertainty = TRUE, ref_str = "Surgery")
- out_seq <- capture.output(print(x))
- expect_false(any(grepl("Inc_Cost_ref", out_seq, fixed = TRUE)))
- out_ref <- capture.output(print(x, ref = "reference"))
- expect_true(any(grepl("Lower_95_Inc_Cost_ref", out_ref, fixed = TRUE)))
-})
diff --git a/tests/testthat/test_reference_plots.R b/tests/testthat/test_reference_plots.R
index f252a6e..f0101e4 100644
--- a/tests/testthat/test_reference_plots.R
+++ b/tests/testthat/test_reference_plots.R
@@ -1,4 +1,4 @@
-# reference strategy and WTP lines in plot.icers() and plot.psa() (#209, #202)
+# incremental plane and WTP lines in plot.icers(), plot.psa() and plot.cers_ref() (#209, #202)
df_toy <- data.frame(strategy = c("Standard of care", "New drug (A)", "Cheaper", "Worse"),
cost = c(100, 200, 50, 300),
@@ -21,30 +21,32 @@ test_that("plot.icers() is unchanged by default", {
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")
+test_that("plot.icers(incremental = TRUE) puts the first non-dominated strategy at the origin", {
+ # "Cheaper" (cost 50, effect 1.5) is the least costly strategy on the frontier
+ p <- plot(x_toy, incremental = TRUE)
d <- point_layer(p)
- expect_setequal(d$x, df_toy$effect - 1)
- expect_setequal(d$y, df_toy$cost - 100)
+ expect_setequal(d$x, df_toy$effect - 1.5)
+ expect_setequal(d$y, df_toy$cost - 50)
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")
+ expect_match(p$labels$caption, "Origin: Cheaper", fixed = TRUE)
+ # the frontier and statuses do not change
+ expect_equal(table(d$shape), table(point_layer(plot(x_toy))$shape))
+ expect_error(plot(x_toy, incremental = "yes"), "TRUE or FALSE")
+ expect_false("ref_str" %in% names(formals(plot.icers)))
})
-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)
+test_that("plot.icers(wtp = ) draws the WTP line through the least costly frontier strategy", {
+ p_abs <- plot(x_toy, wtp = 150)
+ i <- abline_layers(p_abs)
expect_length(i, 1)
- d <- ggplot2::layer_data(p_ref, i)
+ d <- ggplot2::layer_data(p_abs, 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)
+ expect_match(p_abs$labels$caption, "WTP = $150/QALY", fixed = TRUE)
+
+ p_inc <- plot(x_toy, incremental = TRUE, wtp = 150)
+ expect_equal(ggplot2::layer_data(p_inc, abline_layers(p_inc))$intercept, 0)
})
test_that("plot.icers() uses the currency stored by calculate_icers()", {
@@ -87,3 +89,37 @@ test_that("plot.psa(wtp = ) without ref_str draws the line through the least cos
expect_equal(d$intercept, mean(df_cost2$A) - 2000 * mean(df_eff2$A))
expect_match(p$labels$caption, "WTP = $2,000/QALY", fixed = TRUE)
})
+
+# plot.cers_ref(): the star around the reference strategy
+segment_layers <- function(p) {
+ which(vapply(p$layers, function(l) inherits(l$geom, "GeomSegment"), logical(1)))
+}
+
+test_that("plot.cers_ref() centers the plane at the reference and draws the star", {
+ x_ref <- calculate_cers_ref(df_toy$cost, df_toy$effect, df_toy$strategy,
+ ref_str = "Standard of care", wtp = 150)
+ p <- plot(x_ref)
+ expect_s3_class(p, "ggplot")
+ d <- point_layer(p)
+ others <- df_toy$strategy != "Standard of care"
+ expect_setequal(d$x, df_toy$effect[others] - 1)
+ expect_setequal(d$y, df_toy$cost[others] - 100)
+ expect_length(segment_layers(p), 1)
+ # the stored threshold draws the WTP line through the origin; NULL removes it
+ d_wtp <- ggplot2::layer_data(p, abline_layers(p))
+ expect_equal(d_wtp$intercept, 0)
+ expect_equal(d_wtp$slope, 150)
+ expect_length(abline_layers(plot(x_ref, wtp = NULL)), 0)
+ expect_match(p$labels$caption, "Reference Strategy (diamond): Standard of care", fixed = TRUE)
+ expect_length(segment_layers(plot(x_ref, lines = FALSE)), 0)
+ expect_no_warning(ggplot2::ggplot_build(plot(x_ref, col = "bw", label = "none")))
+})
+
+test_that("plot.cers_ref() leaves out the segments for many strategies", {
+ data(hund_strat)
+ x_hund <- calculate_cers_ref(hund_strat$Cost, hund_strat$QALYs, hund_strat$Strategy, ref_str = "1")
+ p <- plot(x_hund, label = "none")
+ expect_length(segment_layers(p), 0)
+ expect_length(segment_layers(plot(x_hund, label = "none", lines = TRUE)), 1)
+ expect_no_warning(ggplot2::ggplot_build(p))
+})
diff --git a/vignettes/basic_cea.Rmd b/vignettes/basic_cea.Rmd
index 238ebcd..748e92e 100644
--- a/vignettes/basic_cea.Rmd
+++ b/vignettes/basic_cea.Rmd
@@ -15,7 +15,9 @@ knitr::opts_chunk$set(
comment = "#>",
fig.width = 7,
fig.height = 5,
- fig.align = "center"
+ fig.align = "center",
+ # ragg writes smaller PNGs than the default device, which keeps the installed size down
+ dev = if (requireNamespace("ragg", quietly = TRUE)) "ragg_png" else "png"
)
```
@@ -110,6 +112,13 @@ plot(icer_hiv,
ggtitle("Cost-effectiveness of HIV screening strategies")
```
+Decisions are based on incremental costs and effects, so it can help to plot them directly. With `incremental = TRUE`, the costs and effects of every strategy are shown relative to the first non-dominated strategy, the least costly strategy on the frontier (here, the status quo), which is placed at the origin. A willingness-to-pay line (`wtp`) through the origin shows which strategies are cost-effective compared with it at that threshold.
+```{r}
+plot(icer_hiv,
+ incremental = TRUE,
+ wtp = 100000)
+```
+
***
***
@@ -174,3 +183,32 @@ plot(icer_cdiff, label = "all") # can lead to a 'busy' plot
plot(icer_cdiff, plot_frontier_only = TRUE) # completely removes dominated strategies from plot
plot(icer_cdiff, currency = "USD", effect_units = "quality-adjusted life-years") # customize axis labels
```
+
+***
+***
+
+# Comparing every strategy with a reference strategy
+
+When more than two strategies are compared, health technology assessment guidelines require the fully incremental (sequential) analysis that `calculate_icers()` performs: dominated and extendedly dominated strategies are removed, and each remaining strategy is compared with the next less costly one on the frontier. This is the case in the guidelines of Canada's CDA-AMC ([2017](https://www.cda-amc.ca/sites/default/files/pdf/guidelines_for_the_economic_evaluation_of_health_technologies_canada_4th_ed.pdf)), England's NICE ([2022](https://www.nice.org.uk/process/pmg36/chapter/economic-evaluation-2)), and the Netherlands' Zorginstituut Nederland ([2024](https://english.zorginstituutnederland.nl/documents/2024/01/16/guideline-for-economic-evaluations-in-healthcare)).
+
+Some settings also call for comparing each strategy with a single reference strategy, such as the current standard of care. NICE, for example, states that "pairwise comparisons may be presented when relevant and justified (for example, when the technology is expected to specifically displace individual comparators)". These comparisons complement the fully incremental analysis; they do not replace it.
+
+`calculate_cers_ref()` compares every strategy with a reference strategy given in `ref_str`. For each strategy, it gives the difference in cost and effect from the reference, the cost-effectiveness ratio (CER) of that difference, and its status relative to the reference (dominant, dominated, or in one of the two quadrants where a ratio is meaningful). The reference is listed first, followed by the other strategies in order of increasing cost. With `wtp`, the net monetary benefit and its difference from the reference are added. Using the HIV screening example, with the status quo as the reference:
+```{r}
+cers_hiv <- calculate_cers_ref(cost = v_hiv_costs,
+ effect = v_hiv_qalys,
+ strategies = v_hiv_strat_names,
+ ref_str = "status quo",
+ wtp = 100000)
+cers_hiv
+```
+
+Compared with the status quo, every screening strategy is more costly and more effective, so each has a CER. Annual screening has a CER below $100,000 per QALY and so looks cost-effective compared with the status quo, yet the fully incremental analysis above shows that it is strongly dominated by screening every 3 years, which costs less and gives more QALYs. This is why the comparison with a reference does not replace the fully incremental analysis.
+
+The `plot()` method draws the incremental cost-effectiveness plane centered at the reference strategy, with a segment from the reference to each strategy. The willingness-to-pay line stored in the object goes through the origin: strategies below it are cost-effective compared with the reference at that threshold.
+```{r}
+plot(cers_hiv)
+```
+
+With many strategies, the segments are left out by default; `lines = TRUE` or `lines = FALSE` overrides this. For a PSA, `calculate_cers_ref_psa()` makes the same comparison from the mean costs and effects, and with `uncertainty = TRUE` adds 95% intervals for the differences and the proportion of PSA samples in each quadrant of the incremental plane. `plot.psa()` with `ref_str` shows the PSA samples themselves on the incremental plane.
+
diff --git a/vignettes/dsa_generation.Rmd b/vignettes/dsa_generation.Rmd
index db7a162..1087826 100644
--- a/vignettes/dsa_generation.Rmd
+++ b/vignettes/dsa_generation.Rmd
@@ -15,7 +15,9 @@ knitr::opts_chunk$set(
comment = "#>",
fig.width = 7,
fig.height = 5,
- fig.align = "center"
+ fig.align = "center",
+ # ragg writes smaller PNGs than the default device, which keeps the installed size down
+ dev = if (requireNamespace("ragg", quietly = TRUE)) "ragg_png" else "png"
)
```
diff --git a/vignettes/psa_analysis.Rmd b/vignettes/psa_analysis.Rmd
index 0921ab3..a429712 100644
--- a/vignettes/psa_analysis.Rmd
+++ b/vignettes/psa_analysis.Rmd
@@ -15,7 +15,9 @@ knitr::opts_chunk$set(
comment = "#>",
fig.width = 7,
fig.height = 5,
- fig.align = "center"
+ fig.align = "center",
+ # ragg writes smaller PNGs than the default device, which keeps the installed size down
+ dev = if (requireNamespace("ragg", quietly = TRUE)) "ragg_png" else "png"
)
```
diff --git a/vignettes/psa_generation.Rmd b/vignettes/psa_generation.Rmd
index a870dcb..0daa617 100644
--- a/vignettes/psa_generation.Rmd
+++ b/vignettes/psa_generation.Rmd
@@ -15,7 +15,9 @@ knitr::opts_chunk$set(
comment = "#>",
fig.width = 7,
fig.height = 5,
- fig.align = "center"
+ fig.align = "center",
+ # ragg writes smaller PNGs than the default device, which keeps the installed size down
+ dev = if (requireNamespace("ragg", quietly = TRUE)) "ragg_png" else "png"
)
```
diff --git a/vignettes/voi.Rmd b/vignettes/voi.Rmd
index 0bc40a2..5b8cf2d 100644
--- a/vignettes/voi.Rmd
+++ b/vignettes/voi.Rmd
@@ -15,7 +15,9 @@ knitr::opts_chunk$set(
comment = "#>",
fig.width = 7,
fig.height = 5,
- fig.align = "center"
+ fig.align = "center",
+ # ragg writes smaller PNGs than the default device, which keeps the installed size down
+ dev = if (requireNamespace("ragg", quietly = TRUE)) "ragg_png" else "png"
)
```