Method semantics by feature type
What every global method returns from eval (mean effect), eval_heter (heterogeneity
curve h), heter_score (scalar H), and plot, for continuous, ordinal, and
nominal features. This is the exactness contract of the package: implementations must
match these formulas.
Notation. Model \(f\), data \(\{x^{(i)}\}_{i=1}^N\), feature of interest \(s\), the rest \(c\).
Continuous: interval \([a,b]\) (= axis_limits). Ordinal/nominal: observed levels
\(v_1,\dots,v_K\) with counts \(N_k\) and frequencies \(w_k = N_k/N\). Ordinal levels are in
their natural numeric order. Nominal levels are indexed by an order \(\pi\): declared
(order=[...]), induced (order="similarity"), or by default ascending encoded value.
Shared rules
- Discrete features are evaluated only at levels.
eval/eval_heterat any other value raisesValueError; the model is never queried at non-existing category values. - Centering (applies to
evalonly; h is centering-invariant):zero_integralsubtracts \(c = \frac{1}{30}\sum_{j=1}^{30}\hat\mu(x_j)\) (uniform grid) for continuous, \(c = \sum_k w_k\, \hat\mu(v_k)\) (frequency-weighted level mean) for discrete.zero_startsubtracts \(c=\hat\mu(a)\) for continuous, \(c=\hat\mu(v_1)\) for discrete (reference level = 0, as in dummy coding). - heter_score: \(H = \frac{1}{30}\sum_{j=1}^{30} h(x_j)\) (uniform grid) for continuous; \(H = \sum_k w_k\, h(v_k)\) (frequency-weighted) for discrete. H is what regional splitting consumes.
- Plots: continuous → curve with ±\(\sqrt{h}\) band (or ICE curves). Ordinal → bars at
the true numeric positions \(v_k\) with whiskers \(\sqrt{h(v_k)}\);
heterogeneity="ice"→ per-level jittered dots. Nominal → same bars at positions \(1..K\) with level labels as ticks; bar order follows \(\pi\); PDP/ShapDP may reorder for display (order="effect").
PDP
ICE curve: \(\hat f^{(i)}(x) = f(x,\, x^{(i)}_c)\).
| eval (uncentered) | eval_heter | |
|---|---|---|
| continuous | \(\hat\mu(x)=\frac{1}{N}\sum_i \hat f^{(i)}(x)\) | \(h(x)=\mathrm{Var}_i\big[\tilde f^{(i)}(x)\big]\), each ICE centered by its own grid mean |
| ordinal / nominal | same, defined at \(v_k\) only | same at \(v_k\); ICE centered by its frequency-weighted level mean |
\(H\): continuous \(= \frac{1}{30}\sum_j \mathrm{Var}_i[\tilde f^{(i)}(x_j)]\) (uniform grid); ordinal/nominal \(= \sum_k w_k\, \mathrm{Var}_i[\tilde f^{(i)}(v_k)]\).
Ordinal vs nominal: identical math — only axis semantics and display order differ.
DerPDP
Continuous only: \(\hat\mu(x)=\frac{1}{N}\sum_i \partial_s f(x,\,x^{(i)}_c)\),
\(h(x)=\mathrm{Var}_i[\partial_s f(x, x_c^{(i)})]\) (d-ICE variance, no centering),
\(H = \frac{1}{30}\sum_j h(x_j)\) (uniform grid).
Ordinal/nominal → ValueError: a derivative needs a continuous axis; adjacent
differences of the PDP bars carry the same information. (\(H\) undefined — the feature is
excluded from H-based rankings rather than scored 0.)
ALE
Continuous (bins \(z_0<\dots<z_M\), \(S_k\) = instances in bin \(k\)):
\(\mathrm{eval}\): \(\widehat{ALE}(x) = \sum_{k \le k(x)} \mu_k\,\Delta z_k\) (last bin truncated at \(x\)), then centered. \(\mathrm{eval\_heter}\): \(h(x) = \sigma^2_{k(x)}\) (step function). \(H = \frac{1}{30}\sum_j \sigma^2_{k(x_j)} \approx \sum_k \frac{\Delta z_k}{b-a}\,\sigma_k^2\) — the width-weighted mean of the per-bin variances.
Ordinal — bin edges are the observed values themselves; transitions \(t=2,\dots,K\) between \(v_{t-1}\) and \(v_t\); contributors \(S_t = \{i : x^{(i)}_s \in \{v_{t-1}, v_t\}\}\):
\(\widehat{ALE}(v_j) = \sum_{t=2}^{j} \mu_t\,(v_t - v_{t-1})\) — the gap normalization cancels, so accumulated values equal the sum of mean raw adjacent differences and do not depend on level spacing. \(h(v_j) = \sigma^2_j\), the variance of the step into level \(j\) (convention: \(h(v_1)\) = first transition's variance). \(H = \sum_k w_k\, h(v_k)\) (frequency-weighted). Exact: the model is only queried at real levels.
Nominal — identical after reindexing levels by \(\pi\). Caveat (documented wherever plotted): the accumulated curve's shape depends on \(\pi\); the meaningful quantities are the adjacent differences \(\mu_t\).
RHALE
Continuous: as ALE but \(d^{(i)} = \partial_s f(x^{(i)})\) evaluated at the data points, and bin limits chosen by Greedy/DP minimizing a variance-based cost. \(h\) and \(H\) as in ALE (per-bin variance step function; width-weighted grid mean).
Ordinal: \(d^{(i)}_t\) as in ALE-ordinal (the discrete derivative); Greedy/DP merges adjacent transitions → adaptive level grouping; within a merged bin, \(\mu_B, \sigma_B^2\) over its pooled contributors; accumulation as in ALE over merged bins. \(h(v_j) = \sigma^2_{B(v_j)}\) (the merged bin containing level \(j\)'s transition); \(H = \sum_k w_k\, h(v_k)\) (frequency-weighted).
Nominal → ValueError: no derivative exists and grouping over an arbitrary order is
not meaningful — use ALE or PDP.
ShapDP
\(\phi^{(i)}\) = SHAP value of feature \(s\) for instance \(i\) (computed at data points).
| eval (uncentered) | eval_heter | |
|---|---|---|
| continuous | linear interpolation of per-bin means \(\big(\bar z_k,\ \mu_k = \mathrm{mean}_{i \in S_k} \phi^{(i)}\big)\) | interpolation of per-bin variances \(\sigma_k^2\) |
| ordinal / nominal | step lookup: \(\hat s(v_k) = \bar\phi_k = \frac{1}{N_k}\sum_{i:\,x^{(i)}_s = v_k} \phi^{(i)}\) | \(h(v_k) = \mathrm{Var}_{i:\,x^{(i)}_s=v_k}\,\phi^{(i)}\) |
\(H\): continuous \(= \frac{1}{30}\sum_j h(x_j)\) (uniform grid over the interpolated variance); ordinal/nominal \(= \sum_k w_k\,\mathrm{Var}_{i:\,x^{(i)}_s=v_k}\,\phi^{(i)}\).
No order enters the math (coalitional); nominal vs ordinal differ in display only. Plot: bars + jittered per-level \(\phi\) dots (continuous: curve + scatter, as now).
Capability matrix
| method | continuous | ordinal | nominal |
|---|---|---|---|
| PDP / ICE | ✓ (as now) | ✓ levels, bars | ✓ levels, bars |
| DerPDP | ✓ (as now) | error | error |
| ALE | ✓ (as now) | ✓ exact, value-edged bins | ✓ with order caveat |
| RHALE | ✓ (as now) | ✓ discrete derivative + level grouping | error |
| ShapDP | ✓ (as now) | ✓ per-level, step lookup | ✓ per-level, step lookup |