diff --git a/DESCRIPTION b/DESCRIPTION index e663f54..0328a5f 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -62,6 +62,7 @@ Imports: viridis, RColorBrewer Suggests: + BCEA, testthat, knitr, rmarkdown, diff --git a/NAMESPACE b/NAMESPACE index 7958a75..2839779 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -16,6 +16,7 @@ S3method(print,sa) S3method(summary,ceac) S3method(summary,metamodel) S3method(summary,psa) +export(bcea_to_psa) export(beta_params) export(calc_evpi) export(calc_evppi) @@ -36,6 +37,7 @@ export(number_ticks) export(owsa) export(owsa_opt_strat) export(owsa_tornado) +export(psa_to_bcea) export(run_owsa_det) export(run_psa) export(run_twsa_det) diff --git a/NEWS.md b/NEWS.md index 345246e..49676fc 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,7 @@ ## New features +- New `bcea_to_psa()` and `psa_to_bcea()` convert between BCEA objects (`BCEA::bcea()`) and dampack `psa` objects, so an analysis can move between the two packages. BCEA is a suggested package, needed only for `psa_to_bcea()`. Thanks to Eline Krijkamp for the suggestion (#204). - `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"`. diff --git a/R/bcea.R b/R/bcea.R new file mode 100644 index 0000000..971dee3 --- /dev/null +++ b/R/bcea.R @@ -0,0 +1,75 @@ +#' Convert between BCEA and dampack objects +#' +#' @description +#' [bcea_to_psa()] turns the output of [BCEA::bcea()] into a dampack `psa` object, so the +#' dampack analyses and plots (CEAC, expected loss curves, EVPI, ICERs with uncertainty, and so on) +#' can be used on it. [psa_to_bcea()] does the reverse, so a dampack PSA can be analyzed with +#' the BCEA package. +#' +#' @param bcea an object of class `bcea`, created with [BCEA::bcea()]. +#' @param currency currency symbol or word used to label costs (e.g., `"$"`, `"£"`, `"€"`). +#' @param parameters optional data frame with the parameter values of each PSA sample (one row per +#' sample, in the same order as in `bcea`). BCEA objects do not store parameter values; supply them +#' to use parameter-based analyses such as [calc_evppi()] or [owsa()]. +#' +#' @return [bcea_to_psa()] returns a `psa` object (see [make_psa_obj()]) with one strategy per +#' intervention in `bcea`, keeping the intervention names. [psa_to_bcea()] returns a `bcea` object. +#' +#' @details BCEA stores the costs and effects of each simulation and intervention, which is what a +#' dampack `psa` object needs. BCEA's own results (for example its incremental benefits at each +#' willingness to pay) are not carried over; dampack computes its own from the costs and effects. +#' +#' @examples +#' if (requireNamespace("BCEA", quietly = TRUE)) { +#' data(Vaccine, package = "BCEA") +#' m <- BCEA::bcea(eff, cost, ref = 2, interventions = treats, Kmax = 50000) +#' +#' # BCEA -> dampack +#' psa_vaccine <- bcea_to_psa(m, currency = "£") +#' plot(ceac(psa_vaccine, wtp = seq(0, 50000, by = 5000))) +#' +#' # dampack -> BCEA +#' m2 <- psa_to_bcea(psa_vaccine, ref_str = "Vaccination", Kmax = 50000) +#' } +#' @seealso [make_psa_obj()], [BCEA::bcea()] +#' @md +#' @export +bcea_to_psa <- function(bcea, currency = "$", parameters = NULL) { + if (!inherits(bcea, "bcea")) { + stop("`bcea` must be an object of class \"bcea\", created with BCEA::bcea().", call. = FALSE) + } + if (is.null(bcea$c) || is.null(bcea$e) || is.null(bcea$interventions)) { + stop("`bcea` must contain the costs (`c`), effects (`e`), and intervention names ", + "(`interventions`) of each simulation.", call. = FALSE) + } + df_cost <- as.data.frame(as.matrix(bcea$c)) + df_effect <- as.data.frame(as.matrix(bcea$e)) + make_psa_obj(cost = df_cost, + effectiveness = df_effect, + parameters = parameters, + strategies = as.character(bcea$interventions), + currency = currency) +} + +#' @rdname bcea_to_psa +#' @param psa a `psa` object, created with [make_psa_obj()]. +#' @param ref_str name of the reference strategy, passed to [BCEA::bcea()] as `ref`. Defaults to +#' the first strategy. +#' @param ... further arguments passed to [BCEA::bcea()], for example `Kmax` or `k`. +#' @export +psa_to_bcea <- function(psa, ref_str = NULL, ...) { + rlang::check_installed("BCEA", reason = "to create a bcea object.") + check_psa_object(psa) + if (is.null(ref_str)) { + ref_str <- psa$strategies[1] + } + if (length(ref_str) != 1 || !ref_str %in% psa$strategies) { + stop("`ref_str` must be one of the strategies: ", + paste0("\"", psa$strategies, "\"", collapse = ", "), ".", call. = FALSE) + } + BCEA::bcea(eff = as.matrix(psa$effectiveness), + cost = as.matrix(psa$cost), + ref = match(ref_str, psa$strategies), + interventions = psa$strategies, + ...) +} diff --git a/_pkgdown.yml b/_pkgdown.yml index 2219e97..64c7730 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -59,6 +59,7 @@ reference: - summary.psa - plot.psa - print.sa + - bcea_to_psa - title: Cost-effectiveness acceptability curves and expected loss contents: diff --git a/man/bcea_to_psa.Rd b/man/bcea_to_psa.Rd new file mode 100644 index 0000000..2ecc2eb --- /dev/null +++ b/man/bcea_to_psa.Rd @@ -0,0 +1,58 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bcea.R +\name{bcea_to_psa} +\alias{bcea_to_psa} +\alias{psa_to_bcea} +\title{Convert between BCEA and dampack objects} +\usage{ +bcea_to_psa(bcea, currency = "$", parameters = NULL) + +psa_to_bcea(psa, ref_str = NULL, ...) +} +\arguments{ +\item{bcea}{an object of class \code{bcea}, created with \code{\link[BCEA:bcea]{BCEA::bcea()}}.} + +\item{currency}{currency symbol or word used to label costs (e.g., \code{"$"}, \code{"£"}, \code{"€"}).} + +\item{parameters}{optional data frame with the parameter values of each PSA sample (one row per +sample, in the same order as in \code{bcea}). BCEA objects do not store parameter values; supply them +to use parameter-based analyses such as \code{\link[=calc_evppi]{calc_evppi()}} or \code{\link[=owsa]{owsa()}}.} + +\item{psa}{a `psa` object, created with [make_psa_obj()].} + +\item{ref_str}{name of the reference strategy, passed to [BCEA::bcea()] as `ref`. Defaults to +the first strategy.} + +\item{...}{further arguments passed to [BCEA::bcea()], for example `Kmax` or `k`.} +} +\value{ +\code{\link[=bcea_to_psa]{bcea_to_psa()}} returns a \code{psa} object (see \code{\link[=make_psa_obj]{make_psa_obj()}}) with one strategy per +intervention in \code{bcea}, keeping the intervention names. \code{\link[=psa_to_bcea]{psa_to_bcea()}} returns a \code{bcea} object. +} +\description{ +\code{\link[=bcea_to_psa]{bcea_to_psa()}} turns the output of \code{\link[BCEA:bcea]{BCEA::bcea()}} into a dampack \code{psa} object, so the +dampack analyses and plots (CEAC, expected loss curves, EVPI, ICERs with uncertainty, and so on) +can be used on it. \code{\link[=psa_to_bcea]{psa_to_bcea()}} does the reverse, so a dampack PSA can be analyzed with +the BCEA package. +} +\details{ +BCEA stores the costs and effects of each simulation and intervention, which is what a +dampack \code{psa} object needs. BCEA's own results (for example its incremental benefits at each +willingness to pay) are not carried over; dampack computes its own from the costs and effects. +} +\examples{ +if (requireNamespace("BCEA", quietly = TRUE)) { + data(Vaccine, package = "BCEA") + m <- BCEA::bcea(eff, cost, ref = 2, interventions = treats, Kmax = 50000) + + # BCEA -> dampack + psa_vaccine <- bcea_to_psa(m, currency = "£") + plot(ceac(psa_vaccine, wtp = seq(0, 50000, by = 5000))) + + # dampack -> BCEA + m2 <- psa_to_bcea(psa_vaccine, ref_str = "Vaccination", Kmax = 50000) +} +} +\seealso{ +\code{\link[=make_psa_obj]{make_psa_obj()}}, \code{\link[BCEA:bcea]{BCEA::bcea()}} +} diff --git a/tests/testthat/test_bcea.R b/tests/testthat/test_bcea.R new file mode 100644 index 0000000..6e5467e --- /dev/null +++ b/tests/testthat/test_bcea.R @@ -0,0 +1,51 @@ +context("converting between BCEA and dampack objects (#204)") + +# a minimal object with the structure of BCEA::bcea() output, so bcea_to_psa() can be tested +# without BCEA installed +fake_bcea <- function() { + set.seed(204) + m_e <- cbind(rnorm(50, 1, 0.1), rnorm(50, 1.2, 0.1)) + m_c <- cbind(rnorm(50, 100, 10), rnorm(50, 150, 10)) + structure(list(e = m_e, c = m_c, interventions = c("Status Quo", "Vaccination")), + class = c("bcea", "list")) +} + +test_that("bcea_to_psa() builds a psa object with the intervention names and outcomes", { + m <- fake_bcea() + p <- bcea_to_psa(m, currency = "£") + expect_is(p, "psa") + expect_identical(p$strategies, c("Status Quo", "Vaccination")) + expect_equal(unname(as.matrix(p$cost)), m$c) + expect_equal(unname(as.matrix(p$effectiveness)), m$e) + expect_identical(p$currency, "£") + expect_null(p$parameters) + + df_par <- data.frame(p_a = runif(50), c_b = runif(50)) + expect_identical(bcea_to_psa(m, parameters = df_par)$parnames, c("p_a", "c_b")) +}) + +test_that("bcea_to_psa() rejects objects that are not bcea output", { + expect_error(bcea_to_psa(list(e = 1, c = 1)), "must be an object of class \"bcea\"") + broken <- structure(list(e = matrix(1, 2, 2)), class = "bcea") + expect_error(bcea_to_psa(broken), "must contain the costs") +}) + +test_that("BCEA and dampack round-trip, and their EVPI agree", { + skip_if_not_installed("BCEA") + data(Vaccine, package = "BCEA", envir = environment()) + m <- BCEA::bcea(eff, cost, ref = 2, interventions = treats, Kmax = 50000) + p <- bcea_to_psa(m) + expect_identical(p$strategies, m$interventions) + + m2 <- psa_to_bcea(p, ref_str = "Vaccination", Kmax = 50000) + expect_is(m2, "bcea") + expect_equal(unname(m2$e), unname(m$e)) + expect_equal(unname(m2$c), unname(m$c)) + expect_equal(m2$ref, m$ref) + + # an independent check of calc_evpi(): BCEA computes the EVPI from the same samples + v_idx <- c(1, 101, 251, 501) + expect_equal(calc_evpi(p, m$k[v_idx])$EVPI, m$evi[v_idx], tolerance = 1e-8) + + expect_error(psa_to_bcea(p, ref_str = "Nope"), "must be one of the strategies") +})