Calculate training explanation paths — calculate_explanation

Identify recurrent SHAP explanation paths among the training samples of one or more fitted POWERUP models. Path discovery is intentionally restricted to training SHAP values; prediction samples are not used to define paths. Within each response class, average-linkage hierarchical clustering is cut once at the requested dendrogram height; undersized branches are retained as outliers. Silhouette is calculated only after the fixed-height paths have been defined and is reported as a descriptive quality diagnostic; it is never used to select, reject, or tune the paths.

Usage

calculate_explanation_paths(
  models,
  targets = NULL,
  min_mean_r = NULL,
  response_cutoff = NULL,
  dendrogram_cut_height = 0.7,
  min_path_size = 10,
  min_path_fraction = 0.05,
  driver_thresholds = c(0.5, 0.7, 0.9),
  top_n_features = 10,
  distance = c("correlation", "cosine"),
  verbose = TRUE
)

Arguments

models: A named list of fitted POWERUP model objects.
targets: Optional character vector of target names. NULL analyzes all models containing training SHAP values.
min_mean_r: Optional minimum mean cross-validation Pearson correlation.
response_cutoff: Optional finite cutoff overriding each model's stored response cutoff.
dendrogram_cut_height: Dendrogram height used to define explanation paths within each response class. The default is 0.70.
min_path_size: Minimum number of training samples required for a supported path.
min_path_fraction: Minimum fraction of a response class required for a supported path.
driver_thresholds: Cumulative between-path SHAP-dispersion thresholds summarized for each response class.
top_n_features: Number of predominant, distinguishing, and driver features retained in compact summaries.
distance: SHAP-profile distance metric. Correlation distance is the default.
verbose: If TRUE, report progress.

Value

A powerup_explanation_paths object containing training-sample path assignments, class and path results, diagnostics, and analysis parameters.

Examples

if (FALSE) { # \dontrun{
paths <- calculate_explanation_paths(my_models, targets = c("CTNNB1", "FGFR1"))
} # }