diff --git a/NEWS.md b/NEWS.md index 626c49a..5d3ad80 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,7 @@ ## New features +- `plot.psa()` gains `xtrans` and `ytrans` to put the effectiveness and cost axes on, for example, a log scale. The ellipses are computed on the transformed scale, so they keep their shape instead of breaking where they cross zero; values a log axis cannot show give an informative error (#201). - 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). diff --git a/R/psa.R b/R/psa.R index 8f98e8e..4bfc556 100644 --- a/R/psa.R +++ b/R/psa.R @@ -188,6 +188,11 @@ summary.psa <- function(object, calc_sds = FALSE, ref_str = NULL, wtp = NULL, .. #' cost-effectiveness plane. Without \code{ref_str}, the line goes through the mean cost and effect #' of the least costly strategy, as in \code{\link{plot.icers}}. Samples below the line are #' cost-effective compared with that strategy at this threshold. +#' @param xtrans,ytrans transformation of the effectiveness (x) and cost (y) axes, such as +#' \code{"log10"}, passed to \code{\link[ggplot2]{scale_continuous}}. Defaults to +#' \code{"identity"}. The ellipses are computed on the transformed scale, so they keep their +#' shape on a log axis; the center points stay at the arithmetic means. A log axis needs every +#' value on it to be positive, which on the incremental plane (\code{ref_str}) is rarely the case. #' @inheritParams add_common_aes #' #' @importFrom ellipse ellipse @@ -211,6 +216,8 @@ plot.psa <- function(x, ref_axis = TRUE, ref_caption = TRUE, wtp = NULL, + xtrans = "identity", + ytrans = "identity", ...) { Effectiveness <- Cost <- Strategy <- Eff.mean <- Cost.mean <- y <- group <- NULL @@ -243,6 +250,7 @@ plot.psa <- function(x, # make strategies in psa object into ordered factors df_ce$Strategy <- factor(df_ce$Strategy, levels = v_strategies, ordered = TRUE) + check_axis_transform(df_ce, xtrans, ytrans) psa_plot <- ggplot(df_ce, aes(x = Effectiveness, y = Cost, color = Strategy)) + geom_point(size = 0.7, alpha = alpha, shape = 21) + ylab(paste("Cost (", currency, ")", sep = "")) @@ -263,15 +271,7 @@ plot.psa <- function(x, if (ellipse) { # make points for ellipse plotting - l_ell <- lapply(v_strategies, function(s) { - df_strat_specific <- df_ce[df_ce$Strategy == s, ] - els <- with(df_strat_specific, - ellipse(cor(Effectiveness, Cost), - scale = c(sd(Effectiveness), sd(Cost)), - centre = c(mean(Effectiveness), mean(Cost)))) - data.frame(els, group = s, stringsAsFactors = FALSE) - }) - df_ell <- bind_rows(l_ell) + df_ell <- psa_ellipses(df_ce, v_strategies, xtrans, ytrans) # draw ellipse lines psa_plot <- psa_plot + geom_path(data = df_ell, aes(x = x, y = y, colour = group), @@ -299,6 +299,7 @@ plot.psa <- function(x, n_x_ticks = n_x_ticks, n_y_ticks = n_y_ticks, xbreaks = xbreaks, ybreaks = ybreaks, xlim = xlim, ylim = ylim, + xtrans = xtrans, ytrans = ytrans, v_str = v_strategies) } else { @@ -333,6 +334,7 @@ plot.psa <- function(x, df_ice$Strategy <- factor(df_ice$Strategy, levels = v_comp_strategies, ordered = TRUE) + check_axis_transform(df_ice, xtrans, ytrans, incremental = TRUE) psa_plot <- ggplot(df_ice, aes(x = Effectiveness, y = Cost, color = Strategy)) + geom_point(size = 0.7, alpha = alpha, shape = 21) + ylab(paste("Incremental Cost (", currency, ")", sep = "")) + @@ -372,15 +374,7 @@ plot.psa <- function(x, if (ellipse) { # make points for ellipse plotting - l_ell <- lapply(v_comp_strategies, function(s) { - df_strat_specific <- df_ice[df_ice$Strategy == s, ] - els <- with(df_strat_specific, - ellipse(cor(Effectiveness, Cost), - scale = c(sd(Effectiveness), sd(Cost)), - centre = c(mean(Effectiveness), mean(Cost)))) - data.frame(els, group = s, stringsAsFactors = FALSE) - }) - df_ell <- bind_rows(l_ell) + df_ell <- psa_ellipses(df_ice, v_comp_strategies, xtrans, ytrans) # draw ellipse lines psa_plot <- psa_plot + geom_path(data = df_ell, aes(x = x, y = y, colour = group), @@ -396,7 +390,59 @@ plot.psa <- function(x, n_x_ticks = n_x_ticks, n_y_ticks = n_y_ticks, xbreaks = xbreaks, ybreaks = ybreaks, xlim = xlim, ylim = ylim, + xtrans = xtrans, ytrans = ytrans, v_str = v_strategies) } } + +#' Ellipses around each strategy's PSA samples +#' +#' Each ellipse is computed from the mean, standard deviation and correlation of the samples on +#' the transformed scale of the axes and mapped back, so that it keeps its shape when the axes +#' are, for example, on a log scale. With identity transformations this is the usual ellipse. +#' +#' @param df_samples data frame with columns \code{Strategy}, \code{Effectiveness} and \code{Cost}. +#' @param v_str strategies to draw an ellipse for. +#' @inheritParams plot.psa +#' @return a data frame with columns \code{x}, \code{y} and \code{group}. +#' @keywords internal +psa_ellipses <- function(df_samples, v_str, xtrans, ytrans) { + tr_x <- scales::as.transform(xtrans) + tr_y <- scales::as.transform(ytrans) + l_ell <- lapply(v_str, function(s) { + v_sel <- df_samples$Strategy == s + # samples on the scale of the axes + v_x <- tr_x$transform(df_samples$Effectiveness[v_sel]) + v_y <- tr_y$transform(df_samples$Cost[v_sel]) + m_ell <- ellipse(cor(v_x, v_y), scale = c(sd(v_x), sd(v_y)), centre = c(mean(v_x), mean(v_y))) + # back to the data scale, where ggplot2 applies the axis transformation again + data.frame(x = tr_x$inverse(m_ell[, 1]), y = tr_y$inverse(m_ell[, 2]), + group = s, stringsAsFactors = FALSE) + }) + bind_rows(l_ell) +} + +#' Check that the PSA samples can be shown on transformed axes +#' +#' @param df_samples data frame with columns \code{Effectiveness} and \code{Cost}. +#' @param incremental whether the samples are differences from a reference strategy. +#' @inheritParams plot.psa +#' @return \code{NULL}, invisibly; called for the error. +#' @keywords internal +check_axis_transform <- function(df_samples, xtrans, ytrans, incremental = FALSE) { + l_axes <- list(list(xtrans, df_samples$Effectiveness, "xtrans", "effectiveness"), + list(ytrans, df_samples$Cost, "ytrans", "cost")) + for (axis in l_axes) { + tr <- scales::as.transform(axis[[1]]) + if (!all(is.finite(suppressWarnings(tr$transform(axis[[2]]))))) { + tr_name <- if (is.character(axis[[1]])) axis[[1]] else tr$name + stop("`", axis[[3]], " = \"", tr_name, "\"` cannot show every ", + if (incremental) "incremental ", axis[[4]], " value: some are outside its domain ", + "(zero or negative, for a log scale)", + if (incremental) ". Differences from the reference strategy are often negative", + ".", call. = FALSE) + } + } + invisible(NULL) +} diff --git a/man/check_axis_transform.Rd b/man/check_axis_transform.Rd new file mode 100644 index 0000000..f6065f1 --- /dev/null +++ b/man/check_axis_transform.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/psa.R +\name{check_axis_transform} +\alias{check_axis_transform} +\title{Check that the PSA samples can be shown on transformed axes} +\usage{ +check_axis_transform(df_samples, xtrans, ytrans, incremental = FALSE) +} +\arguments{ +\item{df_samples}{data frame with columns \code{Effectiveness} and \code{Cost}.} + +\item{xtrans, ytrans}{transformation of the effectiveness (x) and cost (y) axes, such as +\code{"log10"}, passed to \code{\link[ggplot2]{scale_continuous}}. Defaults to +\code{"identity"}. The ellipses are computed on the transformed scale, so they keep their +shape on a log axis; the center points stay at the arithmetic means. A log axis needs every +value on it to be positive, which on the incremental plane (\code{ref_str}) is rarely the case.} + +\item{incremental}{whether the samples are differences from a reference strategy.} +} +\value{ +\code{NULL}, invisibly; called for the error. +} +\description{ +Check that the PSA samples can be shown on transformed axes +} +\keyword{internal} diff --git a/man/plot.psa.Rd b/man/plot.psa.Rd index ac144a5..67391ea 100644 --- a/man/plot.psa.Rd +++ b/man/plot.psa.Rd @@ -21,6 +21,8 @@ ref_axis = TRUE, ref_caption = TRUE, wtp = NULL, + xtrans = "identity", + ytrans = "identity", ... ) } @@ -66,6 +68,12 @@ cost-effectiveness plane. Without \code{ref_str}, the line goes through the mean of the least costly strategy, as in \code{\link{plot.icers}}. Samples below the line are cost-effective compared with that strategy at this threshold.} +\item{xtrans, ytrans}{transformation of the effectiveness (x) and cost (y) axes, such as +\code{"log10"}, passed to \code{\link[ggplot2]{scale_continuous}}. Defaults to +\code{"identity"}. The ellipses are computed on the transformed scale, so they keep their +shape on a log axis; the center points stay at the arithmetic means. A log axis needs every +value on it to be positive, which on the incremental plane (\code{ref_str}) is rarely the case.} + \item{...}{further arguments to plot. This is not used by \code{dampack} but required for generic consistency.} } diff --git a/man/psa_ellipses.Rd b/man/psa_ellipses.Rd new file mode 100644 index 0000000..0bd5f29 --- /dev/null +++ b/man/psa_ellipses.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/psa.R +\name{psa_ellipses} +\alias{psa_ellipses} +\title{Ellipses around each strategy's PSA samples} +\usage{ +psa_ellipses(df_samples, v_str, xtrans, ytrans) +} +\arguments{ +\item{df_samples}{data frame with columns \code{Strategy}, \code{Effectiveness} and \code{Cost}.} + +\item{v_str}{strategies to draw an ellipse for.} + +\item{xtrans, ytrans}{transformation of the effectiveness (x) and cost (y) axes, such as +\code{"log10"}, passed to \code{\link[ggplot2]{scale_continuous}}. Defaults to +\code{"identity"}. The ellipses are computed on the transformed scale, so they keep their +shape on a log axis; the center points stay at the arithmetic means. A log axis needs every +value on it to be positive, which on the incremental plane (\code{ref_str}) is rarely the case.} +} +\value{ +a data frame with columns \code{x}, \code{y} and \code{group}. +} +\description{ +Each ellipse is computed from the mean, standard deviation and correlation of the samples on +the transformed scale of the axes and mapped back, so that it keeps its shape when the axes +are, for example, on a log scale. With identity transformations this is the usual ellipse. +} +\keyword{internal} diff --git a/tests/testthat/test_psa.R b/tests/testthat/test_psa.R index f627bbe..8ec331e 100644 --- a/tests/testthat/test_psa.R +++ b/tests/testthat/test_psa.R @@ -108,3 +108,44 @@ test_that("make_psa_obj() names other_outcome columns after the strategies", { p <- make_psa_obj(df_cost, df_cost, strategies = c("A", "B", "C"), other_outcome = df_other) expect_identical(names(p$other_outcome), c("A", "B", "C")) }) + +# log axes (#201): the ellipse is computed on the scale of the axes +test_that("plot.psa(xtrans, ytrans) draws the ellipses on log axes", { + p <- plot(psa_big, xtrans = "log10", ytrans = "log10") + expect_no_warning(b <- ggplot2::ggplot_build(p)) + expect_equal(b$layout$panel_scales_x[[1]]$trans$name, "log-10") + expect_equal(b$layout$panel_scales_y[[1]]$trans$name, "log-10") + i_path <- which(vapply(p$layers, function(l) inherits(l$geom, "GeomPath"), logical(1))) + df_ell <- ggplot2::layer_data(p, i_path) + # layer data are on the axis scale (log10) and finite: no part of an ellipse falls below 0 + expect_true(all(is.finite(df_ell$x) & is.finite(df_ell$y))) + # each ellipse is the usual ellipse of the log10 samples + v_lcost <- log10(psa_big$cost[["Chemo"]]) + v_leff <- log10(psa_big$effectiveness[["Chemo"]]) + m_ell <- ellipse::ellipse(cor(v_leff, v_lcost), scale = c(sd(v_leff), sd(v_lcost)), + centre = c(mean(v_leff), mean(v_lcost))) + df_chemo <- df_ell[df_ell$group == which(psa_big$strategies == "Chemo"), ] + expect_equal(unname(as.matrix(df_chemo[, c("x", "y")])), unname(m_ell)) +}) + +test_that("plot.psa() with the default identity axes keeps the usual ellipse", { + p <- plot(psa_big) + i_path <- which(vapply(p$layers, function(l) inherits(l$geom, "GeomPath"), logical(1))) + df_ell <- p$layers[[i_path]]$data + v_cost <- psa_big$cost[["Chemo"]] + v_eff <- psa_big$effectiveness[["Chemo"]] + m_ell <- ellipse::ellipse(cor(v_eff, v_cost), scale = c(sd(v_eff), sd(v_cost)), + centre = c(mean(v_eff), mean(v_cost))) + expect_equal(unname(as.matrix(df_ell[df_ell$group == "Chemo", c("x", "y")])), unname(m_ell)) +}) + +test_that("plot.psa() explains when values cannot be shown on a log axis", { + expect_error(plot(psa_big, ref_str = "Chemo", ytrans = "log10"), + "`ytrans = \"log10\"` cannot show every incremental cost value") + df_cost_zero <- psa_big$cost + df_cost_zero[1, 1] <- 0 + psa_zero <- make_psa_obj(df_cost_zero, psa_big$effectiveness, psa_big$parameters, + psa_big$strategies) + expect_error(plot(psa_zero, ytrans = "log10"), "cannot show every cost value") + expect_s3_class(plot(psa_zero, xtrans = "log10"), "ggplot") +})