lgbm

LightGBM adapter: exact GAM mode and approximate SHAP mode.

Exact mode requires an additive-constrained booster (every tree splits on at most one feature); shape functions are reconstructed from dump_model() and reconcile with predict(raw_score=True) exactly. Approximate mode uses LightGBM's native TreeSHAP (pred_contrib=True) on any booster. Per-bin / per-instance variances come from bagged replicas.

Boosters trained with init_score or zero_as_missing are not supported.

LGBMGamAdapter

LGBMGamAdapter(result: LGBMGamResult, *, lam: float = 1.0)

Exact-mode extraction from an additive-constrained LightGBM booster.

Source code in src/triadxai/lgbm.py

def __init__(self, result: LGBMGamResult, *, lam: float = 1.0) -> None:
    booster = _as_booster(result.booster)
    dump = booster.dump_model()
    trees_by_feature, const = _group_trees(dump)  # raises if not additive
    bag_groups = [_group_trees(_as_booster(b).dump_model())[0] for b in result.bag_boosters]
    if not result.bag_boosters:
        logger.warning("no bag replicas: per-bin variances are zero; D will be degenerate")
    feature_names = tuple(dump["feature_names"])
    X_train = result.X_train
    self._lam = float(lam)
    self._feature_names = feature_names

    terms: list[TermData] = []
    specs: list[_BinSpec] = []
    intercept = const
    for j in range(len(feature_names)):
        trees = trees_by_feature.get(j)
        if not trees:
            continue  # feature never split on: contributes 0 (C8)
        name = feature_names[j]
        col = X_train[name] if name in X_train.columns else X_train.iloc[:, j]
        if isinstance(col.dtype, pd.CategoricalDtype):
            spec, f_raw, n = self._extract_categorical(j, trees, col)
        else:
            spec, f_raw, n = self._extract_numeric(j, trees, col)
        pi = n / n.sum()
        mu = float((pi * f_raw).sum())
        v = self._bin_variances(bag_groups, j, spec, pi, f_raw.shape[0])
        terms.append(
            TermData(
                term_idx=len(terms),
                feature_idxs=(j,),
                f=f_raw - mu,
                v=v,
                n=n,
            )
        )
        specs.append(spec)
        intercept += mu
    self.model_data = ModelData(
        terms=tuple(terms), intercept=float(intercept), feature_names=feature_names
    )
    self._specs = specs

bin

bin(X: DataFrame) -> list[BinnedTerm]

Bin new instances into each term's TermData layout.

Source code in src/triadxai/lgbm.py

def bin(self, X: pd.DataFrame) -> list[BinnedTerm]:
    """Bin new instances into each term's TermData layout."""
    out: list[BinnedTerm] = []
    for term, spec in zip(self.model_data.terms, self._specs, strict=True):
        name = self._feature_names[spec.feature_idx]
        col = X[name] if name in X.columns else X.iloc[:, spec.feature_idx]
        if spec.kind == "numeric":
            out.append(self._bin_numeric(term, spec, col))
        else:
            out.append(self._bin_categorical(term, spec, col))
    return out

LGBMGamResult dataclass

LGBMGamResult(
    booster: Booster,
    bag_boosters: tuple[Booster, ...],
    X_train: DataFrame,
)

A fitted additive-constrained booster plus its bag replicas.

fit_lgbm_gam

fit_lgbm_gam(
    X: DataFrame,
    y: ndarray,
    *,
    n_bags: int = 8,
    seed: int = 0,
    **lgbm_params: Any
) -> LGBMGamResult

Fit an additive-constrained (GAM-mode) LightGBM classifier with bags.

Every tree is restricted to a single feature via interaction constraints, so the booster is an additive model and exact-mode TRIAD applies.

Source code in src/triadxai/lgbm.py

def fit_lgbm_gam(
    X: pd.DataFrame,
    y: np.ndarray,
    *,
    n_bags: int = 8,
    seed: int = 0,
    **lgbm_params: Any,
) -> LGBMGamResult:
    """Fit an additive-constrained (GAM-mode) LightGBM classifier with bags.

    Every tree is restricted to a single feature via interaction constraints,
    so the booster is an additive model and exact-mode TRIAD applies.
    """
    y = np.asarray(y)
    if len(np.unique(y)) != 2:
        raise ValueError("fit_lgbm_gam requires a binary target in v0.1")
    if "init_score" in lgbm_params:
        raise ValueError("init_score is not supported: it breaks score reconciliation")
    params: dict[str, Any] = {
        "objective": "binary",
        "learning_rate": 0.05,
        "verbosity": -1,
        "interaction_constraints": [[j] for j in range(X.shape[1])],
    }
    params.update(lgbm_params)
    num_boost_round = int(params.pop("n_estimators", 300))

    def _fit(X_boot: pd.DataFrame, y_boot: np.ndarray, bag_seed: int) -> lgb.Booster:
        dataset = lgb.Dataset(X_boot, label=y_boot)
        return lgb.train({**params, "seed": bag_seed}, dataset, num_boost_round=num_boost_round)

    booster = _fit(X, y, seed)
    bags = fit_bagged(_fit, X, y, n_bags=n_bags, seed=seed)
    return LGBMGamResult(booster=booster, bag_boosters=tuple(bags), X_train=X)

is_additive

is_additive(booster: Any) -> bool

True iff every tree in the booster splits on at most one feature.

Source code in src/triadxai/lgbm.py

def is_additive(booster: Any) -> bool:
    """True iff every tree in the booster splits on at most one feature."""
    dump = _as_booster(booster).dump_model()
    for info in dump["tree_info"]:
        feats: set[int] = set()
        _collect_features(info["tree_structure"], feats)
        if len(feats) > 1:
            return False
    return True

lgbm_shap_data

lgbm_shap_data(
    booster: Any,
    X: DataFrame,
    *,
    bag_boosters: tuple[Any, ...] | list[Any]
) -> ShapData

Approximate-mode contract from any LightGBM booster via native TreeSHAP.

Source code in src/triadxai/lgbm.py

def lgbm_shap_data(
    booster: Any, X: pd.DataFrame, *, bag_boosters: tuple[Any, ...] | list[Any]
) -> ShapData:
    """Approximate-mode contract from any LightGBM booster via native TreeSHAP."""
    booster = _as_booster(booster)
    if len(bag_boosters) < 2:
        raise ValueError("need at least 2 bag replicas to estimate attribution variance")
    if len(X) == 0:
        raise ValueError("X is empty")
    dump = booster.dump_model()
    feature_names = tuple(dump["feature_names"])
    X = X[list(feature_names)] if all(n in X.columns for n in feature_names) else X
    contrib = booster.predict(X, pred_contrib=True)
    phi, base = contrib[:, :-1], float(contrib[0, -1])

    def _contrib_fn(bag: Any) -> Any:
        replica = _as_booster(bag)
        return lambda Xq: np.asarray(replica.predict(Xq, pred_contrib=True))[:, :-1]

    fns = [_contrib_fn(bag) for bag in bag_boosters]
    v = phi_variance(fns, X)
    missing = X.isna().to_numpy()

    oov = np.zeros_like(missing)
    infos = dump.get("feature_infos", {})
    pandas_categorical = booster.pandas_categorical or []
    cat_pos = 0
    for j, name in enumerate(feature_names):
        col = X.iloc[:, j]
        if isinstance(col.dtype, pd.CategoricalDtype) or col.dtype == object:
            if cat_pos < len(pandas_categorical):
                levels = set(pandas_categorical[cat_pos])
                seen = np.array([val in levels for val in col.to_numpy(dtype=object)])
                oov[:, j] = ~seen & ~missing[:, j]
            cat_pos += 1
            continue
        info = infos.get(name, {})
        lo, hi = info.get("min_value"), info.get("max_value")
        if lo is not None and hi is not None:
            x = col.to_numpy(dtype=float)
            oov[:, j] = ~missing[:, j] & ((x < lo) | (x > hi))
    return ShapData(phi=phi, base=base, v=v, missing=missing, oov=oov, feature_names=feature_names)