R/plotting.R

Defines functions log_axis_breaks plot_learning_curve mlpwr_results_to_dataframe plot.pmsims

Documented in plot.pmsims

#' Plot sample-size learning curves for `pmsims` outputs
#'
#' Produces a ggplot showing the simulated points and the fitted learning
#' curve (the learning-curve fit for `method = "curve"`, the Gaussian-process
#' surrogate for the mlpwr engines) stored inside a `pmsims` object.
#' Optionally returns the underlying data instead of drawing the plot.
#'
#' @param x A `pmsims` object returned by `simulate_binary()`,
#'   `simulate_continuous()`, `simulate_survival()`, or `simulate_custom()`.
#' @param metric_label Optional string used for the y-axis label when the object
#'   does not already record the metric name.
#' @param plot Logical; if `TRUE` (default) the function prints the plot.
#'   If `FALSE`, the data used to build the plot are returned instead of
#'   drawing anything.
#' @param ... Currently unused.
#'
#' @return Invisibly returns the `ggplot` object when `plot = TRUE`. When
#'   `plot = FALSE`, returns a list with two data frames: for the mlpwr
#'   engines, `observed_data` (simulated points) and `predicted_data`
#'   (Gaussian-process predictions); for `method = "curve"`, `observed_data`
#'   (the criterion at each simulated sample size, with replicates, standard
#'   error and a +/- 2 SE interval) and `fitted_curve` (the fitted learning
#'   curve, or `NULL` when none was fitted).
#' @keywords internal
#' @importFrom ggplot2 .data
#' @export
plot.pmsims <- function(x, metric_label = NULL, plot = TRUE, ...) {
  if (identical(x$method, "curve")) {
    return(plot_learning_curve(x, metric_label = metric_label, plot = plot))
  }
  ds <- x$mlpwr_ds
  # The learning curve comes from the mlpwr search; a search that stopped
  # early, or the bisection engine, has none to draw.
  if (is.null(ds) || !length(ds$data %||% ds$dat)) {
    stop(
      "No learning curve to plot: ",
      if (!is.null(x$status) && !identical(x$status, "ok")) {
        sprintf("the search stopped (status '%s').", x$status)
      } else {
        "this result has no Gaussian-process search data (e.g. method = 'bisection')."
      },
      call. = FALSE
    )
  }
  design <- NULL

  dat <- if (!is.null(ds$data)) ds$data else ds$dat
  fit <- ds$fit
  aggregate_fun <- ds$aggregate_fun

  dat_obs <- mlpwr_results_to_dataframe(
    dat,
    aggregate = TRUE,
    aggregate_fun = aggregate_fun
  )

  boundaries <- ds$boundaries
  if (!is.null(design)) {
    namesx <- names(boundaries)
    specified <- !sapply(design, is.na)
    boundariesx <- unlist(boundaries[!specified])
    ns <- seq(boundariesx[1], boundariesx[2])
    nsx <- lapply(ns, function(x) {
      a <- c()
      a[specified] <- as.numeric(design[specified])
      a[!specified] <- x
      a
    })
    ind <- dat_obs[c(specified, FALSE, FALSE)] == as.numeric(design[specified])
    dat_obs <- dat_obs[ind, ]
    a1 <- names(ds$final$design)[!specified]
    a2 <- paste(
      names(design)[specified],
      "=",
      design[specified],
      sep = " ",
      collapse = ","
    )
    xlab <- paste0(a1, " (", a2, ")")
  }
  if (is.null(design)) {
    boundariesx <- unlist(boundaries)
    xlab <- names(ds$final$design)
    ns <- seq(boundariesx[1], boundariesx[2])
    nsx <- ns
  }

  obs_n_col <- setdiff(names(dat_obs), "y")[1]
  if (is.na(obs_n_col) || is.null(obs_n_col)) {
    obs_n_col <- names(dat_obs)[1]
  }

  dat_pred <- data.frame(
    n = ns,
    y = sapply(nsx, fit$fitfun),
    type = "Prediction"
  )

  # A search routed through CSSE internally leaves its curve on the CSSE scale,
  # while perf_n, target_performance and the metric name have already been
  # translated back by restore_calibration_slope_scale(). Left alone, the target
  # line and the min_n marker would sit around 0.9 above a curve living near 0.
  # Convert after aggregation, matching how perf_n was derived from the
  # aggregated CSSE rather than from individual replicates.
  if (isTRUE(x$internal_csse)) {
    csse_direction <- if (is.null(x$csse_direction)) {
      "below"
    } else {
      x$csse_direction
    }
    to_slope <- function(v) {
      vapply(
        v,
        csse_to_calibration_slope,
        numeric(1),
        direction = csse_direction
      )
    }
    dat_obs$y <- to_slope(dat_obs$y)
    dat_pred$y <- to_slope(dat_pred$y)
  }

  # Plot annotations
  min_n <- if (!is.null(x$min_n)) as.numeric(x$min_n) else NA_real_
  perf_n <- if (!is.null(x$perf_n)) {
    as.numeric(x$perf_n)
  } else {
    if (
      !is.na(min_n) && nrow(dat_obs) > 0 && any(dat_obs[[obs_n_col]] == min_n)
    ) {
      dat_obs$y[dat_obs[[obs_n_col]] == min_n][1]
    } else {
      NA_real_
    }
  }

  target_perf <- if (!is.null(x$target_performance)) {
    as.numeric(x$target_performance)
  } else {
    NA_real_
  }
  metric_name <- if (!is.null(metric_label)) {
    metric_label
  } else if (!is.null(x$metric)) {
    as.character(x$metric)
  } else {
    "performance"
  }
  metric_summary <- if (!is.null(x$mean_or_assurance)) {
    as.character(x$mean_or_assurance)
  } else {
    "performance"
  }

  p <- ggplot2::ggplot()

  p <- p +
    ggplot2::geom_line(ggplot2::aes(x = dat_pred$n, y = dat_pred$y)) +
    ggplot2::geom_point(ggplot2::aes(x = dat_obs[[obs_n_col]], y = dat_obs$y)) +
    ggplot2::theme_bw() +
    ggplot2::scale_color_brewer(palette = "Set1") +
    ggplot2::theme(legend.title = ggplot2::element_blank()) +
    ggplot2::xlab(xlab) +
    ggplot2::ylab("Power") +
    ggplot2::theme(legend.position = "bottom")

  p <- p +
    ggplot2::geom_point(
      ggplot2::aes(x = min_n, y = perf_n),
      data = data.frame(n = min_n, mean = perf_n),
      size = 3
    )
  p <- p +
    ggplot2::annotate(
      "text",
      x = min_n,
      y = perf_n,
      label = sprintf("min_n = %s\nperf = %.3f", min_n, perf_n),
      hjust = -0.05,
      vjust = -0.5,
      size = 3.5
    )

  if (!is.na(target_perf) && nrow(dat_obs) > 0) {
    x_right <- max(dat_pred$n, na.rm = TRUE)
    p <- p +
      ggplot2::annotate(
        "text",
        x = x_right,
        y = target_perf,
        label = sprintf("target = %.3f", target_perf),
        hjust = 1.05,
        vjust = -0.5,
        size = 3.5
      )
  }

  p <- p +
    ggplot2::labs(
      x = "Sample size (n)",
      y = paste0("Performance (", metric_summary, "[", metric_name, "]", ")"),
      title = "Sample size vs performance"
    ) +
    ggplot2::theme_bw() +
    ggplot2::theme(plot.title = ggplot2::element_text(hjust = 0.5))

  if (!is.na(target_perf)) {
    p <- p + ggplot2::geom_hline(yintercept = target_perf, linetype = "dashed")
  }

  if (!is.na(min_n)) {
    p <- p + ggplot2::geom_vline(xintercept = min_n, linetype = "dotted")
  }

  if (plot) {
    invisible(print(p))
  } else {
    observed_data <- dat_obs[, c(obs_n_col, "y"), drop = FALSE]
    predicted_data <- dat_pred[, -3]
    colnames(observed_data) <- colnames(predicted_data) <- c("n", metric_name)
    plot_data <- list(
      observed_data = observed_data,
      predicted_data = predicted_data
    )
    plot_data
  }
}

#' Convert stored mlpwr results to a plotting data frame
#'
#' @param dat List of sampled designs and associated performance values.
#' @param aggregate Logical; if `TRUE`, reduce each `y` vector to one value.
#' @param aggregate_fun Summary function used when `aggregate = TRUE`.
#'
#' @return A data frame with one row per sampled design.
#' @keywords internal
#' @noRd
mlpwr_results_to_dataframe <- function(dat, aggregate = TRUE, aggregate_fun) {
  rows <- lapply(dat, function(entry) {
    x_vals <- entry$x
    if (is.null(names(x_vals))) {
      names(x_vals) <- if (length(x_vals) == 1) {
        "n"
      } else {
        paste0("x", seq_along(x_vals))
      }
    }

    y_vals <- entry$y
    y_out <- if (aggregate) {
      aggregate_fun(y_vals)
    } else {
      y_vals
    }

    data.frame(
      as.list(x_vals),
      y = y_out,
      check.names = FALSE
    )
  })

  do.call(rbind, rows)
}

# Plot for the learning-curve engine (method = "curve"): the criterion at
# each simulated sample size (point size = replicates, bars = +/- 2 SE), the
# fitted learning curve, the target, and the answer with its interval and the
# shape-free cross-check. Also works when the search stopped without an
# answer, where it shows where the curve levels off.
plot_learning_curve <- function(
  x,
  metric_label = NULL,
  plot = TRUE,
  subtitle = NULL
) {
  curve <- x$diagnostics$curve
  moa <- tolower(as.character(x$mean_or_assurance %||% "assurance")[1])
  crit <- criterion_function(moa, type = 8L)
  se_factor <- if (identical(moa, "mean")) 1 else curve$se_factor %||% 1.4

  obs <- do.call(
    rbind,
    lapply(x$data, function(p) {
      data.frame(
        n = as.numeric(p$x),
        reps = length(p$y),
        y = crit(p$y),
        se = se_factor * stats::sd(p$y) / sqrt(length(p$y))
      )
    })
  )
  ns <- exp(seq(log(min(obs$n) / 1.2), log(max(obs$n) * 1.2), length.out = 200))
  fit <- if (!is.null(curve$a)) {
    data.frame(n = ns, y = curve$a - curve$b * ns^(-curve$c))
  }
  target <- as.numeric(x$csse_target_performance %||% x$target_performance)
  min_n <- suppressWarnings(as.numeric(x$min_n))

  # Searches run on the CSSE scale are shown on the calibration slope scale.
  if (isTRUE(x$internal_csse)) {
    direction <- x$csse_direction %||% "below"
    to_slope <- function(v) {
      vapply(v, csse_to_calibration_slope, numeric(1), direction = direction)
    }
    lo <- to_slope(obs$y - 2 * obs$se)
    hi <- to_slope(pmin(obs$y + 2 * obs$se, 0))
    obs$y <- to_slope(obs$y)
    obs$lo <- pmin(lo, hi)
    obs$hi <- pmax(lo, hi)
    if (!is.null(fit)) {
      fit$y <- to_slope(fit$y)
    }
    target <- as.numeric(x$target_performance)
  } else {
    obs$lo <- obs$y - 2 * obs$se
    obs$hi <- obs$y + 2 * obs$se
  }

  if (!isTRUE(plot)) {
    return(list(observed_data = obs, fitted_curve = fit))
  }

  label <- metric_label %||%
    pmsims_metric_label(x$metric, x$outcome) %||%
    "Performance"
  subtitle <- subtitle %||%
    if (is.finite(min_n)) {
      ci <- curve$n_ci
      sprintf(
        "Minimum sample size %s (interval %s to %s)",
        format(round(min_n), big.mark = ","),
        format(round(ci[1]), big.mark = ","),
        if (is.finite(ci[2])) format(round(ci[2]), big.mark = ",") else "Inf"
      )
    } else {
      sprintf(
        "No sample size found (status: %s)",
        gsub("_", " ", x$status %||% "unknown")
      )
    }

  x_breaks <- log_axis_breaks(range(ns))

  p <- ggplot2::ggplot(obs, ggplot2::aes(x = .data$n, y = .data$y)) +
    ggplot2::geom_hline(
      yintercept = target,
      linetype = "dashed",
      colour = "grey40"
    )
  if (
    is.finite(min_n) && length(curve$n_ci) == 2L && all(is.finite(curve$n_ci))
  ) {
    p <- p +
      ggplot2::annotate(
        "rect",
        xmin = curve$n_ci[1],
        xmax = curve$n_ci[2],
        ymin = -Inf,
        ymax = Inf,
        alpha = 0.12,
        fill = "steelblue"
      )
  }
  if (!is.null(fit)) {
    p <- p +
      ggplot2::geom_line(data = fit, colour = "steelblue", linewidth = 0.8)
  }
  p <- p +
    ggplot2::geom_errorbar(
      ggplot2::aes(ymin = .data$lo, ymax = .data$hi),
      width = 0,
      colour = "grey50"
    ) +
    ggplot2::geom_point(
      ggplot2::aes(size = .data$reps),
      shape = 21,
      fill = "white"
    ) +
    ggplot2::scale_x_log10(breaks = x_breaks, labels = function(b) {
      format(b, big.mark = ",", scientific = FALSE)
    }) +
    ggplot2::scale_size_area(max_size = 4, name = "Replicates") +
    ggplot2::labs(
      x = "Training sample size (log scale)",
      y = sprintf(
        "%s (%s)",
        label,
        if (identical(moa, "mean")) "mean" else "20th percentile"
      ),
      title = "Learning curve",
      subtitle = subtitle
    ) +
    ggplot2::theme_bw()
  if (is.finite(min_n)) {
    p <- p + ggplot2::geom_vline(xintercept = min_n, colour = "steelblue")
    xc <- x$diagnostics$crosscheck_n
    if (is.numeric(xc) && is.finite(xc)) {
      p <- p +
        ggplot2::geom_vline(
          xintercept = xc,
          colour = "darkorange",
          linetype = "dotted"
        )
    }
  }
  print(p)
  invisible(p)
}

# Breaks for the log-scale sample-size axis. ggplot2's default (1, 2 and 5
# times powers of ten) leaves few labels when a search spans a narrow range
# (none above 1,000 for 660 to 1,700), so finer sets of round numbers are tried
# in turn until at least five fall inside the range. Each set is spread
# roughly evenly on the log scale.
log_axis_breaks <- function(limits) {
  steps <- list(
    1,
    c(1, 3),
    c(1, 2, 5),
    c(1, 2, 3, 5),
    c(1, 1.5, 2, 3, 5, 7),
    c(1, 1.2, 1.5, 2, 2.5, 3, 4, 5, 6, 8)
  )
  powers <- 10^(floor(log10(limits[1])):ceiling(log10(limits[2])))
  for (s in steps) {
    b <- sort(unique(as.vector(outer(s, powers))))
    b <- b[b >= limits[1] & b <= limits[2]]
    if (length(b) >= 5L) {
      return(b)
    }
  }
  if (length(b) >= 3L) b else pretty(limits)
}

Try the pmsims package in your browser

Any scripts or data that you put into this service are public.

pmsims documentation built on Nov. 15, 2026, 5:07 p.m.