PEAXAI_global_importance: Global feature importance for efficiency classifiers

Description

Computes global feature importance for a fitted classification model that separates Pareto-efficient DMUs, using one of three XAI backends:

"SA" — Sensitivity Analysis via rminer.
"SHAP" — Model-agnostic SHAP approximations via fastshap.
"PI" — Permutation Importance via iml.

You can evaluate the model on either the training domain (background = "train") or the real-world domain (background = "real") and compute importance on a chosen target set ("train" or "real"). Importances are returned normalized to sum to 1.

Usage

PEAXAI_global_importance(
  data,
  x,
  y,
  final_model,
  background = "train",
  target = "train",
  importance_method
)

Value

A named numeric vector (or 1-row data.frame) of normalized importances, with names matching the predictor columns; the values sum to 1.

Arguments

data

A data.frame (or matrix) with predictors and outcomes. The function will internally reorder columns to c(x, y).

x

Integer or character vector with the columns used as inputs (predictors).

y

Integer or character vector with the columns used as outputs (targets used to define class_efficiency in training; not included in X when explaining).

final_model

A fitted model. If it is a base-glm binomial, probabilities are obtained with type = "response"; otherwise the function expects predict(type = "prob") with a column named "efficient".

background

Character, "train" (default) or "real". Background data define the distribution used for the reference model behaviour.

target

Character, "train" (default) or "real". Dataset on which importance is computed.

importance_method

A named list (or data.frame-like) with the backend and its args:

name: One of "SA", "SHAP", "PI".

method

(SA) One of "1D-SA", "sens", "DSA", "MSA", "CSA", "GSA".

measures

(SA) e.g. "AAD", "gradient", "variance", "range".

levels

(SA) Discretization levels used by rminer::Importance.

baseline

(SA) Baseline value for SA, if applicable.

nsim

(SHAP) Number of Monte Carlo samples for fastshap::explain.

n.repetitions

(PI) Number of permutations per feature for iml::FeatureImp.

Details

Internally, the function builds background/target sets with xai_prepare_sets(). For glm models, the positive class is assumed to be the second level ("efficient") and probabilities are extracted with type = "response". For other models (e.g., caret), predict(type = "prob")[, "efficient"] is used.

Examples

Run this code

# \donttest{
  data("firms", package = "PEAXAI")

  data <- subset(
    firms,
    autonomous_community == "Comunidad Valenciana"
  )

  x <- 1:4
  y <- 5
  RTS <- "vrs"
  imbalance_rate <- NULL

  trControl <- list(
    method = "cv",
    number = 3
  )

  # glm method
  methods <- list(
    "glm" = list(
      weights = "dinamic"
     )
   )

  metric_priority <- c("Balanced_Accuracy", "ROC_AUC")

  models <- PEAXAI_fitting(
    data = data, x = x, y = y, RTS = RTS,
    imbalance_rate = imbalance_rate,
    methods = methods,
    trControl = trControl,
    metric_priority = metric_priority,
    seed = 1,
    verbose = FALSE
  )

  final_model <- models[["best_model_fit"]][["glm"]]

  imp <- PEAXAI_global_importance(
    data = data, x = x, y = y,
    final_model = final_model,
    background = "real", target = "real",
    importance_method = list(name = "PI", n.repetitions = 5)
  )

  head(imp)
# }