The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Explaining a model with SHAP

Overview

The SHAP layer works with a fitted uniml_result or directly with trained mlr3 learners. It returns both the standardised model input and optional raw feature values, so the same explanation can be plotted on the scale the model saw or on a more interpretable display scale.

Model-agnostic explanations are computed with kernelshap; XGBoost and LightGBM models use their native TreeSHAP implementation when the learner package is installed. The example below is deliberately small so the vignette builds quickly.

Fit a workflow

library(uniml)

data <- read.csv(
  system.file("extdata", "uniml-cvd-mortality.csv", package = "uniml")
)
set.seed(123)
data <- data[1:400, ]

spec <- uniml_spec(
  task_type = "binary",
  outcome = "died",
  positive = "yes",
  id = "id"
)
spec <- set_preprocess(
  spec,
  impute = "median_mode",
  scale = "zscore",
  encode = "onehot"
)
spec <- set_feature_selection(spec, methods = "univariate")
spec <- set_learners(spec, "cart", tune = FALSE)
spec <- set_evaluation(spec, ci = "none", calibration = "none")

split <- make_split(
  as_uniml_data(data, spec),
  prop = c(0.8, 0.2),
  stratify = TRUE,
  seed = 123
)
result <- run_workflow(
  spec,
  train = split$train$data,
  validation = split$validation$data
)
length(result$selection$selected_features)
#> [1] 28

Compute SHAP values

explain_shap() explains the training features stored in the result by default. n_explain caps the number of explained rows (they are subsampled with seed) and bg_n controls the background sample used by Kernel SHAP, so the run time stays predictable.

explained <- explain_shap(
  result,
  model = "best",
  n_explain = 30,
  bg_n = 18,
  seed = 123
)

explained$shap
#> <uniml_shap>
#> models: cart
#> importance rows: 28
head(explained$shap$importance, 6)
#>   model              feature mean_abs_shap direction rank
#> 1  cart                 spo2  4.541352e-02         -    1
#> 2  cart               ckd_no  5.559301e-17         -    2
#> 3  cart         diabetes_yes  5.241115e-17         -    3
#> 4  cart             platelet  4.425193e-17         -    4
#> 5  cart admission_quarter_Q3  3.736837e-17         +    5
#> 6  cart                  wbc  3.719125e-17         +    6

A direct learner can be explained the same way:

learner <- result$models[[1L]]$learner
explanation <- explain_shap(
  learner,
  data = result$preprocess$train[, setdiff(
    names(result$preprocess$train), "died"
  )],
  n_explain = 20,
  bg_n = 14,
  seed = 123,
  positive = "yes"
)
explanation$models
#> [1] "classif.rpart"

Importance, beeswarm, dependence, and waterfall

plot_shap_importance(explained)
Mean absolute SHAP value per feature.
Mean absolute SHAP value per feature.
plot_shap_beeswarm(explained, max_display = 8)
Distribution and direction of individual contributions.
Distribution and direction of individual contributions.
plot_shap_dependence(explained, feature = "age")
#> Warning in ggplot2::geom_point(color = color, position =
#> ggplot2::position_jitter(width = jitter_width, : Ignoring empty aesthetic:
#> `colour`.
SHAP dependence for one feature.
SHAP dependence for one feature.
plot_shap_waterfall(explained, row_id = 1)
Single-observation waterfall for the first explained row.
Single-observation waterfall for the first explained row.

The importance plot ranks features by mean absolute SHAP value, the beeswarm shows the distribution and direction of individual contributions, and the dependence plot shows the relationship between a feature and its SHAP value. The waterfall decomposes one prediction into its feature contributions. All of them are also available through plot(result, type = ...).

Clinical thresholds

For a continuous feature with enough observations, extract_thresholds() fits a smoothed SHAP curve and reports zero crossings together with a paper-ready summary table. It needs a reasonable number of rows per feature, so the chunk is not evaluated in this small example.

thresholds <- extract_thresholds(
  explained$shap,
  target = "age",
  min_n = 20,
  min_unique = 8
)

thresholds$zero_crossings
thresholds$paper_ready

The threshold search is descriptive. It should be reviewed against the biological or clinical context and validated in an independent sample before being used as a decision rule.

References

Lundberg SM, Lee SI (2017). A unified approach to interpreting model predictions. Advances in Neural Information Processing Systems, 30.

Lundberg SM, Erion G, Chen H, et al. (2020). From local explanations to global understanding with explainable AI for trees. Nature Machine Intelligence, 2(1), 56-67.

Covert I, Lee SI (2021). Improving KernelSHAP: practical Shapley value estimation using linear regression. Proceedings of AISTATS, PMLR 130, 3457-3465.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.