From 64c6584328c38e3b95f63f4bec653075c897a593 Mon Sep 17 00:00:00 2001 From: Fernando Alarid-Escudero Date: Fri, 13 Nov 2026 17:11:39 -0800 Subject: [PATCH] plot.psa(): xtrans/ytrans, with ellipses computed on the transformed scale (#201) The ellipses were computed on the data scale, so on log axes (added with scale_*_log10()) they lost their shape and any part below zero became NaN. plot.psa() now takes xtrans and ytrans, passes them to its own scales, and computes each ellipse from the transformed samples before mapping it back. Values a transformation cannot show (zero or negative on a log scale, common on the incremental plane) give an informative error. With the default identity transformations the plots are unchanged. The duplicated ellipse code of the two planes is now one helper, psa_ellipses(). --- NEWS.md | 1 + R/psa.R | 82 +++++++++++++++++++++++++++++-------- man/check_axis_transform.Rd | 26 ++++++++++++ man/plot.psa.Rd | 8 ++++ man/psa_ellipses.Rd | 28 +++++++++++++ tests/testthat/test_psa.R | 41 +++++++++++++++++++ 6 files changed, 168 insertions(+), 18 deletions(-) create mode 100644 man/check_axis_transform.Rd create mode 100644 man/psa_ellipses.Rd 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") +})