Getting started

Install once

UnifiedIG requires Python 3.10 or newer:

python -m pip install unifiedig

This also installs CBaseline, skgrad, and TreeIG. You do not select or install an attribution backend separately. Install your model’s framework separately when using PyTorch, JAX, TensorFlow, CatBoost, XGBoost, or LightGBM. SHAP is optional and is needed only for the plotting conversion.

Explain a fitted model

This complete example fits a Ridge model, builds a distribution of observed baseline rows whose weighted prediction equals the training mean, and explains five observations. There is one public attribution call for all supported model families.

import numpy as np
from sklearn.linear_model import Ridge

from cbaseline import background
import unifiedig as uig

rng = np.random.default_rng(0)
X_train = rng.normal(size=(200, 4))
y_train = 2.0 * X_train[:, 0] - X_train[:, 1] + 0.5 * X_train[:, 2]
model = Ridge(alpha=0.5).fit(X_train, y_train)

# Choose a reference prediction and construct observed baseline inputs whose
# weighted mean model prediction equals that reference.
f_train = model.predict(X_train)
f0 = float(f_train.mean())
bg = background(
    predictions=f_train,
    f0=f0,
    features=X_train,
    weighting="calibrated",
)
X_eval = X_train[100:105]

explanation = uig.Explainer(model, bg)(X_eval)

np.testing.assert_allclose(
    explanation.base_values + explanation.values.sum(axis=1),
    model.predict(X_eval),
)

explanation.values holds feature contributions. For this scalar regressor, its shape is (5, 4). The shared baseline output is repeated in explanation.base_values, which has shape (5,). The assertion checks that baseline output plus feature contributions reconstructs each prediction.

This example explains training observations to keep setup compact. For model assessment, explain held-out observations and choose a reference population that matches the comparison you intend to make.

Choose the reference deliberately

Pass a vector for one reference observation, a matrix for a shared reference population, or a CBaseline object for a calibrated weighted distribution:

one_point = uig.Explainer(model, X_train[0])(X_eval)
shared_population = uig.Explainer(model, X_train[:20])(X_eval)

A matrix is never interpreted as one baseline per evaluation row. Read baselines before changing the reference distribution.

Next steps

• Interpret outputs and class scores.

• Find a worked example or check model support.

• Check accuracy and unexpected results.

Once you are comfortable explaining predictions, the optional loss-attribution chapter shows how to analyze prediction loss when observed targets are available.