Developer function for plotting summary of evaluation results.

A helper function for developing new Visualizer plotting functions that plot the summarized evaluation results as a boxplot, scatter plot, line plot, or bar plot with or without 1 SD error bars/ribbons. This function accepts either (1) a pre-computed tibble containing the summarized evaluation results or (2) the Evaluator function and its corresponding function arguments for computing the evaluation results within this function call.

Usage

plot_eval_summary(
  fit_results,
  eval_tib = NULL,
  eval_id = NULL,
  eval_fun = paste0("summarize_", eval_id),
  vary_params = NULL,
  show = c("boxplot", "point", "line", "bar", "errorbar", "ribbon"),
  x_str = "auto",
  y_str = "auto",
  err_sd_str = "auto",
  color_str = "auto",
  linetype_str = "auto",
  facet_formula = NULL,
  facet_type = c("grid", "wrap"),
  plot_by = "auto",
  add_ggplot_layers = NULL,
  boxplot_args = NULL,
  point_args = NULL,
  line_args = NULL,
  bar_args = NULL,
  errorbar_args = NULL,
  ribbon_args = NULL,
  facet_args = NULL,
  interactive = FALSE,
  ...
)

Arguments

fit_results: A tibble, as returned by the fit method.
eval_tib: (Optional) Tibble (typically from the output of eval_summary_constructor) containing the summarized evaluation results to plot. If not provided, the evaluation results will be automatically computed by calling eval_fun(). If the summarized evaluation results have already been computed previously, eval_tib should be specified to avoid duplicate computations.
eval_id: Character string. ID used as the suffix for naming columns in eval_summary_constructor(). Should be the same as the eval_id argument in eval_summary_constructor().
eval_fun: Function used to compute evaluation results summary. This function is only used (and required) if necessary results have not already been computed in eval_tib.
vary_params: A vector of parameter names that are varied across in the Experiment.
show: Character vector with elements being one of "boxplot", "point", "line", "bar", "errorbar", "ribbon" indicating what plot layer(s) to construct.
x_str: (Optional) Name of column in eval_tib to plot on the x-axis. Default "auto" chooses what to plot on the x-axis automatically.
y_str: (Optional) Name of column in eval_tib to plot on the y-axis if show is anything but "boxplot". Default "auto" chooses what to plot on the y-axis automatically.
err_sd_str: (Optional) Name of column in eval_tib containing the standard deviations of y_str. Used for plotting the errorbar and ribbon ggplot layers. Default "auto" chooses what column to use for the standard deviations automatically.
color_str: (Optional) Name of column in eval_tib to use for the color and fill aesthetics when plotting. Default "auto" chooses what to use for the color and fill aesthetics automatically. Use NULL to avoid adding any color and fill aesthetic.
linetype_str: (Optional) Name of column in eval_tib to use for the linetype aesthetic when plotting. Used only when show = "line". Default "auto" chooses what to use for the linetype aesthetic automatically. Use NULL to avoid adding any linetype aesthetic.
facet_formula: (Optional) Formula for ggplot2::facet_wrap() or ggplot2::facet_grid() if need be.
facet_type: One of "grid" or "wrap" specifying whether to use ggplot2::facet_wrap() or ggplot2::facet_grid() if need be.
plot_by: (Optional) Name of column in eval_tib to use for subsetting data and creating different plots for each unique value. Default "auto" chooses what column to use for the subsetting automatically. Use NULL to avoid creating multiple plots.
add_ggplot_layers: List of additional layers to add to a ggplot object via +.
boxplot_args: (Optional) Additional arguments to pass into ggplot2::geom_boxplot().
point_args: (Optional) Additional arguments to pass into ggplot2::geom_point().
line_args: (Optional) Additional arguments to pass into ggplot2::geom_line().
bar_args: (Optional) Additional arguments to pass into ggplot2::geom_bar().
errorbar_args: (Optional) Additional arguments to pass into ggplot2::geom_errorbar().
ribbon_args: (Optional) Additional arguments to pass into ggplot2::geom_ribbon().
facet_args: (Optional) Additional arguments to pass into ggplot2::facet_grid() or ggplot2::facet_wrap().
interactive: Logical. If TRUE, returns interactive plotly plots. If FALSE, returns static ggplot plots.
...: Additional arguments to pass to eval_fun(). This is only used if necessary results have not already been computed in eval_tib.

Value

If interactive = TRUE, returns a plotly object if plot_by is NULL and a list of plotly objects if plot_by is not NULL. If interactive = FALSE, returns a ggplot object if plot_by is NULL and a list of ggplot objects if plot_by is not NULL.

Examples

# generate example fit results data
fit_results <- tibble::tibble(
  .rep = rep(1:2, times = 2),
  .dgp_name = c("DGP1", "DGP1", "DGP2", "DGP2"),
  .method_name = c("Method"),
  # true response
  y = lapply(1:4, FUN = function(x) rnorm(100)),
  # predicted response
  predictions = lapply(1:4, FUN = function(x) rnorm(100))
)

# generate example evaluation results data
eval_results <- list(
  `Prediction Errors` = summarize_pred_err(
    fit_results = fit_results, 
    truth_col = "y", 
    estimate_col = "predictions", 
    eval_id = "pred_err"
  )
)

# create plot using pre-computed evaluation results
plt <- plot_eval_summary(fit_results = fit_results, 
                         eval_tib = eval_results[["Prediction Errors"]],
                         eval_id = "pred_err",
                         show = c("point", "errorbar"),
                         facet_formula = ~ .metric)
# can customize plots using additional arguments or ggplot2::`+`
plt <- plot_eval_summary(fit_results = fit_results, 
                         eval_tib = eval_results[["Prediction Errors"]],
                         eval_id = "pred_err",
                         show = c("point", "errorbar"),
                         facet_formula = ~ .metric,
                         facet_type = "wrap",
                         errorbar_args = list(width = 0.5),
                         facet_args = list(scales = "free")) +
  ggplot2::labs(y = "Mean Prediction Error")
# can return interactive plotly plot
plt <- plot_eval_summary(fit_results = fit_results, 
                         eval_tib = eval_results[["Prediction Errors"]],
                         eval_id = "pred_err",
                         show = c("point", "errorbar"),
                         facet_formula = ~ .metric,
                         interactive = TRUE)

# create plot without pre-computing evaluation results; instead, need to 
# pass in summarize_* function and its arguments
plt <- plot_eval_summary(fit_results = fit_results,
                         eval_id = "pred_err",
                         eval_fun = "summarize_pred_err",
                         truth_col = "y", 
                         estimate_col = "predictions",
                         show = c("point", "errorbar"),
                         facet_formula = ~ .metric)