Plot Pareto Front on Held-Out Data

Source: R/visualization.R

Fits and evaluates every Pareto-optimal solution from optimize_panel() on held-out validation data and displays the trade-off between two metrics as a scatter plot. The underlying data frame is accessible via $data on the returned ggplot object.

plot_pareto_front(
  optimization_result,
  x = NULL,
  y = NULL,
  cohort = NULL,
  objectives = NULL,
  x_metric = "sensitivity",
  y_metric = "specificity",
  color_by = "n_features",
  point_size = 4,
  point_alpha = 0.7,
  viridis_option = "plasma",
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  color_label = NULL,
  connect = FALSE,
  on_error = c("warn", "stop"),
  regularized = TRUE,
  verbose = interactive()
)

Arguments

optimization_result

An OptimizationResult from optimize_panel().

x

Held-out validation data: a matrix, data.frame, SummarizedExperiment, or list of such objects. When NULL (default), automatically uses held-out data stored on optimization_result by optimize_panel() (present when train_ratio + val_ratio < 1).

y

Held-out validation labels: a factor (or list of factors when x is a list). When NULL (default), automatically uses held-out labels stored the same way.

cohort

Optional cohort factor for single-matrix x; passed to evaluate_pareto_solutions().

objectives

Optional objective override; passed to evaluate_pareto_solutions().

x_metric

Character; column name for the x-axis. Any column of evaluate_pareto_solutions() output, i.e. "sensitivity", "specificity", "auc", "n_features", "n_base_features", or an obj_-prefixed optimisation objective such as "obj_auc". Default "sensitivity".

y_metric

Character; column name for the y-axis. Same options as x_metric. Default "specificity".

color_by

Column name to map to point colour (e.g. "n_features", "auc", an obj_ column), or NULL to disable. Default "n_features".

point_size

Numeric; point size. Default 4.

point_alpha

Numeric; point transparency. Default 0.7.

viridis_option

Character; viridis palette name. Default "plasma".

title

Character or NULL; plot title. Auto-generated when NULL.

xlab

Character or NULL; x-axis label. Defaults to x_metric.

ylab

Character or NULL; y-axis label. Defaults to y_metric.

color_label

Character or NULL; color legend label. Defaults to color_by.

connect

Logical; if TRUE, connect points with a line sorted by the x-axis metric. Default FALSE.

on_error

One of "warn" or "stop". Controls behaviour when a solution fails evaluation. "warn" (default) skips the solution with a warning; "stop" raises an error immediately.

regularized

Logical; passed to fit_panel(). Default TRUE.

verbose

Logical; print progress messages. Default interactive().

Value

A ggplot object. The underlying metrics data frame is accessible via $data.

Examples

if (FALSE) { # \dontrun{
opt <- optimize_panel(x_train, y_train, objectives = define_objectives())
p <- plot_pareto_front(opt, x_test, y_test)
p          # display plot
p$data     # access metrics data.frame
} # }