Classification (Binary & Multiclass)¶

Calibrated Explanations wraps standard scikit-learn classifiers to produce uncertainty-aware predictions and explanations.

Classification semantics note¶

Calibration prerequisites: fit on x_proper, y_proper and calibrate on held-out x_cal, y_cal.
Mode-specific guarantees: Venn-Abers provides calibrated class probabilities with interval bounds.
Assumptions: calibration and deployment data are exchangeable or distribution-matched.
Explicit non-guarantees: no guarantee under drift or regime shift.
Explanation-envelope limits: rule and feature-level intervals summarize model behavior, not causal effects.
Formal semantics: Calibrated interval semantics.

Supported signatures¶

Method	Description
`predict(x)`	Point prediction (class label)
`predict_proba(x)`	Calibrated probabilities (n_samples, n_classes)
`predict_proba(x, uq_interval=True)`	Calibrated probabilities plus uncertainty intervals
`explain_factual(x)`	Factual explanation (rules + uncertainty)
`explore_alternatives(x)`	Alternative explanations (counterfactuals)

ℹ️ Note: predict() and predict_proba() match the scikit-learn API but return calibrated values.

Examples¶

1. Calibrated probabilities with uncertainty¶

# Predict probabilities for the positive class (binary) or all classes (multiclass)
probs, (low, high) = explainer.predict_proba(x_test, uq_interval=True)

print(f"Probability: {probs[0, 1]:.3f} (Interval: {low[0, 1]:.3f} – {high[0, 1]:.3f})")

2. Factual explanation¶

Returns the rules explaining why the model made this prediction, with epistemic and aleatoric explanation envelopes on the feature weights.

explanation = explainer.explain_factual(x_test)

3. Explore alternatives¶

Finds what feature changes would be necessary to flip the prediction or increase confidence.

alternatives = explainer.explore_alternatives(x_test)

Multiclass Semantics: What is Explained¶

For multiclass classification, explanations are generated for the predicted class by default:

Factual explanations: Show why the model predicted the specific class it chose
Alternative explanations: Show what would change the prediction to a different class
Probability intervals: Returned per-class via predict_proba(x, uq_interval=True)

# Get probabilities for all classes with uncertainty
probs, (low, high) = explainer.predict_proba(x_test, uq_interval=True)
# probs.shape = (n_samples, n_classes)

# Explanation focuses on the argmax class by default
factual = explainer.explain_factual(x_test)

Set multi_labels_enabled=True to generate a true multiclass explanation that returns one explanation per class (all-classes view):

multi_factual = explainer.explain_factual(x_test, multi_labels_enabled=True)
multi_alternative = explainer.explore_alternatives(x_test, multi_labels_enabled=True)

Multi-label mode support matrix (`multi_labels_enabled=True`)¶

Capability	Status	Notes
Per-class factual explanations	Supported	Returns one explanation per class for each instance
Per-class alternative explanations	Supported	Same container shape as factual mode
`predict_proba(..., uq_interval=True)` per-class intervals	Supported	Returns calibrated probability intervals per class
Collection operations (`add_conjunctions`, `reset`, filtering)	Supported	Applied across class-specific explanations
`reject_policy` orchestration	Supported	Reject handling applies in multiclass branch
`features_to_ignore` forwarding	Supported	Forwarded in multiclass explain paths
Narrative/dataframe export	Supported	Collection-level multiclass narrative/dataframe output
JSON export/import	Supported	`to_json` + multiclass-aware `from_json` restore grouped structure
Binary datasets with `multi_labels_enabled=True`	Limited	Allowed with compatibility warning; use default mode when all-classes output is unnecessary

ℹ️ Note: The rule table shows contributions toward the predicted class. Negative weights reduce confidence in the prediction; positive weights increase it.

Key parameters¶

bins: Supply Mondrian categories/bins for conditional calibration.
uq_interval: Set to True to receive uncertainty intervals (tuples of lower/upper bounds).

Entry-point tier: Tier 2.