Core Panel Evaluation — evaluate

Functions for evaluating biomarker panel performance including confusion matrices, ROC curves, and objective computation.

Compute objective values and additional summary statistics for a fitted panel on validation data. This function extracts the selected features from the validation set and computes predictions using the default scoring function: a logistic regression fit on the selected features (with a centred/standardised fallback if the model fails to converge). When evaluating multiple cohorts, feature alignment is performed via the simple intersection of shared column names; future releases will offer more flexible strategies.

evaluate_panel(
  panel,
  x,
  y,
  objectives = define_objectives(metrics = c("sensitivity", "specificity", "auc")),
  cohort = NULL,
  assay = NULL,
  scoring_fn = NULL,
  feature_transform = NULL,
  cutoff_prob = 0.5,
  positive = NULL
)

Arguments

panel: A BiomarkerPanelResult.
x: Validation feature matrix, data.frame, SummarizedExperiment, or a list of such objects for multi-cohort evaluation.
y: Validation binary response factor (or list of factors when x is a list).
objectives: Optional override for objectives. Defaults to sensitivity, specificity, and auc.
cohort: Optional factor identifying cohort membership for each sample when x represents a single cohort. Ignored when x is provided as a list.
assay: For SummarizedExperiment inputs, assay name or index to use.
scoring_fn: Optional custom scoring function. If NULL, uses the default row-mean aggregation. Must have signature function(x_selected, selected_features, truth, ...).
feature_transform: Optional transformation applied to base features before evaluation. Defaults to the transform stored in the fitted panel, keeping training and validation pipelines aligned. Must be a registered transform name (see feature_transform_registry()). Built-in options include "pairwise_ratios", "pairwise_log_ratios", "reference_norm", and "none".
cutoff_prob: Classification probability threshold used for confusion matrix summaries and highlight point on the ROC curve. Defaults to 0.5.
positive: Label treated as the positive class when computing confusion matrices. Defaults to the positive class stored during training (typically "Yes"). Specify explicitly to override.

Value

A list with metrics (named numeric vector), objectives (data.frame with columns objective, value, direction), confusion (2x2 matrix of counts), and roc (list containing a curve data.frame, highlight point, optional plot, and evalm helper data).