23 Variable importance and explanations

Variable importance summarizes a fitted model across predictors. Shapley contributions describe the prediction for an individual case relative to a background distribution. Both describe the fitted predictive relationship; causal interpretation requires additional assumptions and study design.

23.1 Inspect an importance measure

dat <- set_outcome(mtcars[, c("mpg", "wt", "hp", "disp")], "mpg")
mod <- train(
  dat,
  hyperparameters = setup_GLM(),
  execution_config = setup_SerialExecution(seed = 2026L)
)

2026-10-08 02:54:01 Checking data is ready for training... ✔ [check_supervised]
2026-10-08 02:54:01 ▶ [train]
2026-10-08 02:54:02 Training set: 32 cases x 3 features. [summarize_supervised]
2026-10-08 02:54:02 // CPU | serial | 1 worker: algorithm 1 thread, tuning 1, outer resampling 1 [msg_resources]
2026-10-08 02:54:02 Shared memory (auto): not sharing training data (4.5 kB) -- this run transfers nothing to workers. [report_shared_memory]
2026-10-08 02:54:02 Training GLM Regression... [train]
2026-10-08 02:54:02 Checking data is ready for training... ✔ [check_supervised]

<Regression>
GLM (GLM (generalized linear model))

  <Training Regression Metrics>
   MAE: 1.91
   MSE: 6.09
  RMSE: 2.47
    R²: 0.83


2026-10-08 02:54:02 Done in 0.94 seconds. [train]

importance <- get_varimp(mod)
importance

<VariableImportance>
  Coefficient (coefficient, 4 entries): Estimated coefficient of each model term, including the intercept, on the scale of the linear predictor, per unit of the term as the model received it.

varimp_table(importance)

     variable   Coefficient
1 (Intercept) 37.1055052690
2          wt -3.8008905826
3          hp -0.0311565508
4        disp -0.0009370091

plot_varimp(mod)

VariableImportance stores named measures, each with metadata describing its meaning, evaluation sample, sign, dependence on predictor units, and ranking direction. varimp_table() combines the measures into a data frame. plot_varimp(measure = ...) selects a measure and uses its ranking direction. Coefficient magnitudes, split gain, permutation scores, and cross-validated risk represent different quantities.

23.2 Explain individual predictions

x <- features(dat)
explanation <- explain(
  mod,
  newdata = x[1:5, ],
  background = x,
  config = setup_SHAP(seed = 2026L)
)

2026-10-08 02:54:03 Background differs from the training data; contributions are relative to it. [shap_background]

shap_case(explanation, x[1:5, ], case = 1L)

$steps
   feature  value contribution
    <char> <char>        <num>
1:      wt   2.62   2.27008190
2:      hp    110   1.14305596
3:    disp    160   0.06626704

$baseline
[1] 20.09062

$predicted
[1] 23.57003

$case
[1] "Mazda RX4"

$class
[1] "outcome"

shap_long(explanation, x[1:5, ])

                 case feature  value numeric_value contribution
               <char>  <char> <char>         <num>        <num>
 1:         Mazda RX4      wt   2.62         2.620  2.270081900
 2:     Mazda RX4 Wag      wt  2.875         2.875  1.300854802
 3:        Datsun 710      wt   2.32         2.320  3.410349075
 4:    Hornet 4 Drive      wt  3.215         3.215  0.008552004
 5: Hornet Sportabout      wt   3.44         3.440 -0.846648377
 6:         Mazda RX4      hp    110       110.000  1.143055959
 7:     Mazda RX4 Wag      hp    110       110.000  1.143055959
 8:        Datsun 710      hp     93        93.000  1.672717323
 9:    Hornet 4 Drive      hp    110       110.000  1.143055959
10: Hornet Sportabout      hp    175       175.000 -0.882119845
11:         Mazda RX4    disp    160       160.000  0.066267039
12:     Mazda RX4 Wag    disp    160       160.000  0.066267039
13:        Datsun 710    disp    108       108.000  0.114991511
14:    Hornet 4 Drive    disp    258       258.000 -0.025559851
15: Hornet Sportabout    disp    360       360.000 -0.121134777

The background defines the reference against which contributions are measured. setup_SHAP() controls estimator, perturbation, output scale, background sample size, and coalitions. explanation_methods() lists the automatic estimator for each algorithm and whether it is exact.

rowSums(explanation@phi[["outcome"]]) + explanation@baseline[, 1L]

        Mazda RX4     Mazda RX4 Wag        Datsun 710    Hornet 4 Drive 
         23.57003          22.60080          25.28868          21.21667 
Hornet Sportabout 
         18.24072

predict(mod, x[1:5, ])

        Mazda RX4     Mazda RX4 Wag        Datsun 710    Hornet 4 Drive 
         23.57003          22.60080          25.28868          21.21667 
Hornet Sportabout 
         18.24072

For this linear example, baseline plus contributions reconstructs the prediction. Other methods report contributions on the configured output scale. Approximate estimators also introduce estimation error.

shap_by_level() summarizes factor levels. get_varimp(explanation) aggregates contributions across the explained cases. explain() on a resampled model supports averaged or per-model explanations through type.