FAQ

Why does TriadExplainer raise "mode='exact' requires an additive booster"? Exact mode needs per-feature term contributions, which only exist when every tree splits on at most one feature. Fit with fit_lgbm_gam (which enforces this via interaction constraints), or explain the interacting booster with mode="shap" — see approximate mode. Exact mode on a raw booster also requires X_ref (the training data) for bin counts.

Why does approximate mode demand bag_boosters and X_ref? The epistemic variance comes from bag-replica disagreement — at least 2 replicas are required (fit_bagged builds them) — and τ² is estimated on the reference population X_ref. Without either there is no information/epistemic split. If the attributions are strongly off-center on X_ref, a warning signals that the reference population may not match the training data.

Do I need the shap package? No. Approximate mode uses LightGBM's built-in TreeSHAP via predict(pred_contrib=True); triadxai never imports shap.

Why are boosters trained with init_score or zero_as_missing rejected? init_score breaks score reconciliation — channel totals plus the intercept could no longer reproduce the raw score (C2). zero_as_missing produces a missing_type the adapter does not support. Both are rejected at adapter level — see model adapters.

Why does plot_waterfall raise ImportError? Waterfalls live behind the optional viz extra: pip install triadxai[viz]. Importing triadxai itself never requires matplotlib — the error is raised lazily, only when a plot is drawn.

What does RuntimeError: TRIAD reconciliation failed mean? explain guards C2 at runtime: it recomputes the model's raw score and compares it to the channel totals plus the intercept, with tolerance 1e-6. Rather than return a silently wrong decomposition, it raises with the observed maximum error.

Why is my D channel all zeros (or a warning says it "will be degenerate")? D needs a variance signal. With no bag replicas (n_bags=0, or a raw additive booster without bags) per-bin variances are zero; for EBMs, outer_bags=1 makes all outer-bag SDs zero, and a model passed through monotonize() loses standard_deviations_ entirely (the adapter raises). Fit with replicas — fit_lgbm_gam(..., n_bags=8) or outer_bags >= 2 — see epistemic variance.

Can I explain a multiclass model? Not in v0.1. fit_lgbm_gam requires a binary target, and the EBM adapter rejects multiclass models (its intercept must be a single value). Multiclass support is on the roadmap (design decisions, decision 15).