shap_by_level: Contributions of a categorical feature, by the level each...

In rtemis: Schema-Driven Machine Learning and Visualization

Contributions of a categorical feature, by the level each case has

Description

What a per-feature contribution hides once it is averaged across cases: that one level of a diagnosis drives the prediction and the others do nothing.

Usage

shap_by_level(x, newdata, features = NULL)

Arguments

x	SHAP object.
newdata	tabular data: The cases x explains.
features	Optional Character: Features to summarize. NULL takes every categorical feature in newdata.

Details

This is the right tool for "which level matters", and per-level contributions are not. A case has exactly one level, so its per-feature contribution is the contribution of the level it has – there is nothing to split. What averaging loses is only that cases at different levels were averaged together, and grouping them is what restores it.

Splitting a contribution across the columns of an encoding answers a different and worse question. Those values include a term for every level the case does not have; they depend on the encoding, since a contrast-coded factor's reference level has no column at all and so cannot appear; and for a linear model they are identical for every case at the same level. Grouping has none of those problems and shows the reference level like any other.

newdata must be the data the explanation was computed on, which is checked against its fingerprint: contributions lined up against other rows would produce a plausible but meaningless table.

Value

data.table with columns class, feature, level, n, mean, sd, and mean_abs.

Author(s)

EDG

Examples

x <- data.frame(
  age = rnorm(100),
  dx = factor(sample(c("none", "diabetes"), 100, TRUE))
)
x[["y"]] <- x[["age"]] + 3 * (x[["dx"]] == "diabetes") + rnorm(100, sd = 0.3)
mod <- train(x, hyperparameters = setup_GLM(), verbosity = 0L)
contributions <- explain(
  mod,
  x[, c("age", "dx")],
  background = x[, c("age", "dx")],
  verbosity = 0L
)
shap_by_level(contributions, x[, c("age", "dx")])

rtemis documentation built on Oct. 20, 2026, 1:06 a.m.