R/autoplot.multisimsum.R

In rsimsum: Analysis of Simulation Studies Including Monte Carlo Error

#' @title autoplot method for multisimsum objects
#' @description `autoplot` can produce a series of plot to summarise results of simulation studies. See `vignette("C-plotting", package = "rsimsum")` for further details.
#' @param object An object of class `multisimsum`.
#' @param par The parameter results to plot.
#' @param type The type of the plot to be produced. Possible choices are: `forest`, `lolly`, `zip`, `est`, `se`, `est_ba`, `se_ba`, `est_density`, `se_density`, `est_hex`, `se_hex`, `est_ridge`, `se_ridge`, `heat`, `nlp`, with `forest` being the default.
#' @param stats Summary statistic to plot, defaults to `bias`. See [summary.simsum()] for further details on supported summary statistics.
#' @param target Target of summary statistic, e.g. 0 for `bias`. Defaults to `NULL`, in which case target will be inferred.
#' @param fitted Superimpose a fitted regression line, useful when `type` = (`est`, `se`, `est_ba`, `se_ba`, `est_density`, `se_density`, `est_hex`, `se_hex`). Defaults to `TRUE`.
#' @param scales Should scales be fixed (`fixed`, the default), free (`free`), or free in one dimension (`free_x`, `free_y`)?
#' @param top Should the legend for a nested loop plot be on the top side of the plot? Defaults to `TRUE`.
#' @param density.legend Should the legend for density and hexbin plots be included? Defaults to `TRUE`.
#' @param zoom A numeric value between 0 and 1 signalling that a zip plot should _zoom_ on the top x% of the plot (to ease interpretation). Defaults to 1, where the whole zip plot is displayed.
#' @param zip_ci_colours A string with (1) a hex code to use for plotting coverage probability and its Monte Carlo confidence intervals (the default, with value `zip_ci_colours = "yellow"`), (2) a string vector of two hex codes denoting optimal coverage (first element) and over/under coverage (second element) or (3) a vector of three hex codes denoting optimal coverage (first), undercoverage (second), and overcoverage (third).
#' @param ... Not used.
#'
#' @return A `ggplot` object.
#' @export
#'
#' @examples
#' data("frailty", package = "rsimsum")
#' ms <- multisimsum(
#'   data = frailty,
#'   par = "par", true = c(trt = -0.50, fv = 0.75),
#'   estvarname = "b", se = "se", methodvar = "model",
#'   by = "fv_dist", x = TRUE
#' )
#'
#' library(ggplot2)
#' autoplot(ms, par = "trt")
#' autoplot(ms, par = "trt", type = "lolly", stats = "cover")
#' autoplot(ms, par = "trt", type = "zip")
#' autoplot(ms, par = "trt", type = "est_ba")
autoplot.multisimsum <- function(object, par, type = "forest", stats = "nsim", target = NULL, fitted = TRUE, scales = "fixed", top = TRUE, density.legend = TRUE, zoom = 1, zip_ci_colours = "yellow", ...) {
  ### Manipulate object to make it a simsum-like object
  object[["summ"]] <- object[["summ"]][object[["summ"]][[object[["par"]]]] == par, ]
  object[["true"]] <- object[["true"]][par]
  if (type %in% c("zip", "est", "se", "est_ba", "se_ba", "est_density", "se_density", "est_hex", "se_hex", "est_ridge", "se_ridge")) {
    object[["x"]] <- object[["x"]][object[["x"]][[object[["par"]]]] == par, ]
  }
  #
  if (inherits(object, "summary.multisimsum")) {
    class(object) <- c("summary.simsum", "list")
  } else {
    class(object) <- c("simsum", "list")
  }

  # Call autoplot.simsum on the subset of results for a given parameter:
  plot <- autoplot(object = object, type = type, stats = stats, target = target, fitted = fitted, scales = scales, top = top, density.legend = density.legend, zoom = zoom, zip_ci_colours = zip_ci_colours, ...)

  # Add title with parameter of interest
  plot <- plot +
    ggplot2::labs(title = paste0("Parameter: ", par))

  ### Return plot
  return(plot)
}