Baselines and CBaseline#

A baseline defines the comparison in an attribution. Changing it changes the question, even when the model and observation stay fixed.

A reference population for a specified prediction#

CBaseline separates two decisions: which prediction defines the reference, and which observed cases form a relevant population around it. Choose a reference output f0, localize observed rows near it in prediction space, and calibrate their weights so the mean output matches f0 to numerical tolerance. UnifiedIG then averages the complete IG paths from those rows.

This gives the explanation a coherent total, f(x) - f0, and an explicit reference population for allocating that total to features. Several input rows can represent the reference, retaining variation among observed cases instead of making the entire explanation depend on one selected point.

Why localization and calibration both matter#

Localization selects rows whose predictions are near the reference. It does not require proximity to the evaluation observation in input space. Calibration then constrains the weighted mean output. Matching the mean alone is weaker: very high and very low predictions can average to f0 while representing a broad, heterogeneous reference population.

Reference choice	What it supplies	What it does not enforce
A single reference point	One definite starting input and prediction	Variation among reference cases or a specified population-level output
A full background sample or random subset	A distribution of reference cases	Localization near a chosen `f0`, or calibration to it
A calibrated CBaseline distribution	Observed rows localized near `f0`, with a weighted mean output matching it	Exact neutrality of every row or proximity in input space

A single point remains appropriate when that particular input is the intended comparison. A broad background is appropriate when the intended question is relative to that full population. CBaseline is designed for the more specific question: what changes the prediction from a localized reference population centered on a chosen output?

Broad background samples are common in SHAP workflows, but localization is a property of background construction, not an inherent limitation of SHAP. CBaseline can also construct backgrounds for SHAP. UnifiedIG makes localized, calibrated distributions a direct part of the IG workflow through its weighted baseline interface. CBaseline’s guide explains the reference-distribution construction in more detail.

Calibration may need to widen the localized support or reject an infeasible reference. Inspect its diagnostics: a weighted mean of f0 does not imply that every retained row predicts exactly f0. Observed baseline endpoints also do not guarantee that every interpolated point along an IG path is an observed or plausible input.

Point, population, or calibrated distribution#

Input to `Explainer`	Meaning
One feature vector	Compare every observation with this single reference input
A matrix of reference rows	Average each observation’s paths from all rows, with equal weights
Matrix plus `baseline_weights`	Average paths using the supplied normalized weights
CBaseline background object	Use its aligned `rows` and `weights` directly

A scalar baseline broadcasts across input features. Use it only when that constant has a meaningful interpretation. A matrix remains a shared population even if it has exactly as many rows as the evaluation batch.

explanation = uig.Explainer(
    model, reference_rows, baseline_weights=[0.2, 0.3, 0.5]
)(X_eval)

Weights must be finite, nonnegative, have a positive sum, and align with the reference rows. UnifiedIG normalizes them. Do not also pass baseline_weights when supplying a background object that already carries weights.

For a scalar output, the baseline value is the weighted average of model outputs on the reference rows. It is generally not the model output at the weighted mean input. Nonlinear models require averaging the paths themselves.

Choose a reference prediction with CBaseline#

Sometimes it is easier to specify an output reference, such as the average prediction of a population. CBaseline constructs a distribution of observed inputs whose weighted output matches that reference. There is no unique inverse input corresponding to an output value.

The getting-started example uses a regression prediction. For classification, attribute scores, not probabilities, and construct the background on the same score scale that UnifiedIG explains. This binary example uses decision_function:

import numpy as np
from sklearn.linear_model import LogisticRegression

from cbaseline import background
import unifiedig as uig

training = np.array([[-2.0, 0.0], [-1.0, 1.0], [1.0, -1.0], [2.0, 0.0]])
model = LogisticRegression().fit(training, np.array([0, 0, 1, 1]))
scores = model.decision_function(training)
f0 = float(scores.mean())
bg = background(
    predictions=scores,
    f0=f0,
    features=training,
    weighting="calibrated",
)

# A deliberate single starting point is also valid: uig.Explainer(model, x0).
explanation = uig.Explainer(model, bg)([[0.5, -0.25]])
print(explanation.values)
print(explanation.base_values)

For multiclass models use the complete centered score vector, as in the multiclass example. A requested reference must be feasible for the observed prediction support; inspect CBaseline’s diagnostics and its reference-prediction guide.

Practical choices#

Use reference cases representing the population or decision threshold relevant to your analysis. Keep that choice fixed when comparing explanations across models, and record any calibration weights. For pipelines, supply original input rows even when attributing in a transformed feature space.

Larger reference populations increase work because every evaluation point is compared with every reference row. Start with a substantively meaningful, manageable population and examine whether changing it alters your conclusions.