API Reference / algorithms / glassbox /

ebm.py

Explainable Boosting Machine (EBM / GA2M): additive glassbox models.

An Explainable Boosting Machine learns an additive model of per-feature shape functions. Each feature is binned, and a boosting procedure learns a score for every bin, so the whole model is a lookup table that a human can read directly:

\hat{y} = g\Big(\beta_0 + f_1(x_1) + f_2(x_2) + \cdots + f_m(x_m)\Big)

where f_j is a step function over the quantile bins of feature j and g is the identity (regression), the sigmoid (binary classification), or the softmax (multiclass). Because the model is additive, its predictions can be decomposed exactly into one contribution per feature via explain.

This module implements the GA1M (generalised additive model) form. Pairwise-interaction terms (the "GA2M" extension) are not yet included.

Classes

ExplainableBoostingRegressor

class algorithms.glassbox.ebm.ExplainableBoostingRegressor(Regressor, _BaseEBM)

Explainable Boosting Machine for regression (additive shape functions).

An interpretable additive model that learns one shape function per feature by boosting per-bin mean residuals. Each feature is quantile binned and each bin is assigned a score, so the fitted model is a set of lookup tables whose sum -- plus an intercept -- is the prediction.
Constructor 
__init__(
    self,
    n_bins: int = 32,
    max_rounds: int = 100,
    learning_rate: float = 0.01,
    feature_names: Optional[List[str]] = None,
)

Overview

  1. Quantile-bin each feature into (up to) n_bins bins
  2. Initialize the intercept to the mean target and every bin score to zero
  3. For each boosting round, cycle over features and add the learning-rate
scaled mean residual of each bin to that bin's score
  1. Center each shape function and fold the offsets into the intercept
  2. Predict as intercept_ + sum_j shape_j(x_j)

Theory

The model is the additive expansion

\hat{y}(x) = \beta_0 + \sum_{j=1}^{m} f_j(x_j)

where f_j is constant over each quantile bin of feature j. Training minimises squared error by gradient boosting: at each step the negative gradient y - \hat{y} is averaged per bin and added to the bin score, exactly the optimal leaf value for a squared-error stump.

Parameters

n_bins
int = 32
Number of quantile bins per feature (fewer when quantiles tie).
max_rounds
int = 100
Number of boosting rounds. Each round updates every feature once.
learning_rate
float = 0.01
Shrinkage applied to each per-bin update.
feature_names
list of str
Names used when reporting shape functions. Defaults to feature_0, feature_1, ....

Attributes

intercept_
np.ndarray of shape (1,)
Additive intercept (the mean target plus the centered bin offsets).
shape_functions_
list of np.ndarray
Per-feature bin scores, each of shape (n_bins, 1).
bin_edges_
list of np.ndarray
Per-feature quantile bin boundaries.
n_bins_per_feature_
list of int
Actual number of bins per feature after deduplicating tied quantiles.
feature_importance_
np.ndarray of shape (n_features,)
Mean absolute bin score per feature (interpretable magnitude).
n_features_
int
Number of features seen during fit.

Notes

Complexity:

  • Training: O(R \cdot m \cdot n) where R = max_rounds,
m = features, n = samples.
  • Prediction: O(m) per sample (one bin lookup per feature).
When to use ExplainableBoostingRegressor:
  • When you need a model a human can audit feature-by-feature
  • When the signal is roughly additive (no strong interactions)
  • When you want exact, per-feature prediction decompositions via
explain

References

Nori2019
Nori, H., Jenkins, S., Koch, P., and Caruana, R. (2019). InterpretML: A Unified Framework for Machine Learning Interpretability. arXiv preprint arXiv:1909.09223.
Lou2012
Lou, Y., Caruana, R., Gehrke, J., and Hooker, G. (2012). Accurate Intelligible Models with Pairwise Interactions. KDD 2012, pp. 623-631. DOI: 10.1145/2339530.2339657

See Also

ExplainableBoostingClassifier

Classification counterpart.
LinearRegression

Non-additive linear baseline.
python 
>>> from tuiml.algorithms.glassbox import ExplainableBoostingRegressor
>>> import numpy as np
>>> X = np.array([[0.], [1.], [2.], [3.], [4.], [5.], [6.], [7.]])
>>> y = 2.0 * X.ravel() + 1.0
>>> reg = ExplainableBoostingRegressor(n_bins=8, max_rounds=200, learning_rate=0.1)
>>> _ = reg.fit(X, y)
>>> np.allclose(reg.predict(np.array([[2.0], [6.0]])), [5.0, 13.0], atol=1e-3)
True
>>> np.allclose(reg.predict(X), reg.intercept_[0] + reg.explain(X).sum(axis=1), atol=1e-12)
True

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for constructor parameters.

get_capabilities (cls) -> List[str]

Return regressor capabilities.

get_complexity (cls) -> str

Return time/space complexity.

get_references (cls) -> List[str]

Return academic references.

fit (self, X: np.ndarray, y: np.ndarray) -> 'ExplainableBoostingRegressor'

Fit the additive model.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Training features.
y
np.ndarray of shape (n_samples,)
Target values.
Returns
self
ExplainableBoostingRegressor
Fitted regressor.
predict (self, X: np.ndarray) -> np.ndarray

Predict target values.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
y_pred
np.ndarray of shape (n_samples,)
Predicted values.
score (self, X: np.ndarray, y: np.ndarray) -> float

Return the R-squared score on the given data.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Test samples.
y
np.ndarray of shape (n_samples,)
True target values.
Returns
r2
float
R-squared score.
__repr__ (self) -> str

ExplainableBoostingClassifier

class algorithms.glassbox.ebm.ExplainableBoostingClassifier(Classifier, _BaseEBM)

Explainable Boosting Machine for classification (additive shape functions).

An interpretable additive classifier that learns one shape function per feature by boosting per-bin mean residuals. It supports binary (sigmoid link) and multiclass (softmax link) targets, and every prediction decomposes exactly into per-feature contributions.
Constructor 
__init__(
    self,
    n_bins: int = 32,
    max_rounds: int = 100,
    learning_rate: float = 0.01,
    feature_names: Optional[List[str]] = None,
)

Overview

  1. Quantile-bin each feature into (up to) n_bins bins
  2. Initialize an intercept and zero bin scores
  3. For each boosting round, cycle over features and add the learning-rate
scaled mean residual (log-loss gradient) of each bin to its score
  1. Center each shape function and fold offsets into the intercept
  2. Map the additive score through the sigmoid (binary) or softmax
(multiclass) link to obtain class probabilities

Theory

The additive score is

s(x) = \beta_0 + \sum_{j=1}^{m} f_j(x_j)

For binary classification the probability is p = \sigma(s) with the logistic function, and the negative gradient used for boosting is y - p. For multiclass, a score vector per class is used and the negative gradient is the one-hot target minus the softmax output.

Parameters

n_bins
int = 32
Number of quantile bins per feature (fewer when quantiles tie).
max_rounds
int = 100
Number of boosting rounds. Each round updates every feature once.
learning_rate
float = 0.01
Shrinkage applied to each per-bin update.
feature_names
list of str
Names used when reporting shape functions.

Attributes

intercept_
np.ndarray
Additive intercept (log-odds / logits).
shape_functions_
list of np.ndarray
Per-feature bin scores of shape (n_bins, 1) (binary) or (n_bins, n_classes) (multiclass).
bin_edges_
list of np.ndarray
Per-feature quantile bin boundaries.
classes_
np.ndarray
Unique class labels.
feature_importance_
np.ndarray of shape (n_features,)
Mean absolute bin score per feature.
n_features_
int
Number of features seen during fit.

Notes

Complexity:

  • Training: O(R \cdot m \cdot n \cdot K) where R =
max_rounds, m = features, n = samples, K = classes (1 for binary).
  • Prediction: O(m \cdot K) per sample.
When to use ExplainableBoostingClassifier:
  • When a human must be able to audit how each feature drives the score
  • When the signal is roughly additive
  • When you want exact per-feature log-odds contributions via
explain

References

Nori2019
Nori, H., Jenkins, S., Koch, P., and Caruana, R. (2019). InterpretML: A Unified Framework for Machine Learning Interpretability. arXiv preprint arXiv:1909.09223.
Lou2012
Lou, Y., Caruana, R., Gehrke, J., and Hooker, G. (2012). Accurate Intelligible Models with Pairwise Interactions. KDD 2012, pp. 623-631. DOI: 10.1145/2339530.2339657

See Also

ExplainableBoostingRegressor

Regression counterpart.
LogisticRegression

Non-additive logistic baseline.
python 
>>> from tuiml.algorithms.glassbox import ExplainableBoostingClassifier
>>> import numpy as np
>>> X = np.array([[0.], [1.], [2.], [3.], [4.], [5.], [6.], [7.]])
>>> y = np.array([0, 0, 0, 0, 1, 1, 1, 1])
>>> clf = ExplainableBoostingClassifier(n_bins=8, max_rounds=200, learning_rate=0.5)
>>> _ = clf.fit(X, y)
>>> clf.predict(np.array([[2.0], [6.0]])).tolist()
[0, 1]
>>> bool(clf.predict_proba(np.array([[6.0]]))[0, 1] > 0.5)
True

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for constructor parameters.

get_capabilities (cls) -> List[str]

Return classifier capabilities.

get_complexity (cls) -> str

Return time/space complexity.

get_references (cls) -> List[str]

Return academic references.

fit (self, X: np.ndarray, y: np.ndarray) -> 'ExplainableBoostingClassifier'

Fit the additive classifier.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Training features.
y
np.ndarray of shape (n_samples,)
Target class labels.
Returns
self
ExplainableBoostingClassifier
Fitted classifier.
predict (self, X: np.ndarray) -> np.ndarray

Predict class labels.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
y_pred
np.ndarray of shape (n_samples,)
Predicted class labels.
predict_proba (self, X: np.ndarray) -> np.ndarray

Predict class probabilities.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
proba
np.ndarray of shape (n_samples, n_classes)
Class probabilities (sigmoid for binary, softmax for multiclass).
__repr__ (self) -> str