Calibrated Explainer API¶

This reference documents the public API for the calibrated_explanations package. It includes the main explainer classes, the explanation containers, and the specific explanation types.

Core Explainers¶

The core of the library is the CalibratedExplainer, which handles the calibration of the underlying model. For a scikit-learn compatible interface, use WrapCalibratedExplainer.

CalibratedExplainer¶

The CalibratedExplainer is the core class of the library. It takes a machine learning model (classifier or regressor) and a calibration dataset. It fits Venn-Abers calibrators (for classification) or Conformal Predictive Systems (for regression) to the model’s predictions. This process ensures that the explanations generated are calibrated, meaning the predicted probabilities or intervals reflect the true underlying uncertainty.

For a task-oriented view of the same capabilities (classification, conformal interval regression via CPS, and probabilistic/thresholded regression), see Tasks and capabilities.

Example Usage:

from calibrated_explanations import CalibratedExplainer
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split

# Load data
X, y = load_iris(return_X_y=True)
x_train, x_cal, y_train, y_cal = train_test_split(X, y, test_size=0.2)

# Train model
model = RandomForestClassifier()
model.fit(x_train, y_train)

# Initialize explainer
explainer = CalibratedExplainer(model, x_cal, y_cal, mode='classification')

# Explain a test instance
x_test = x_cal[:1]
explanations = explainer.explain(x_test)

{eval-rst} .. autoclass:: calibrated_explanations.core.calibrated_explainer.CalibratedExplainer :members: :undoc-members: :show-inheritance: :inherited-members:

WrapCalibratedExplainer¶

The WrapCalibratedExplainer acts as a wrapper around CalibratedExplainer to provide a standard scikit-learn interface (fit, predict, predict_proba). It simplifies the workflow by handling the splitting of data into calibration and training sets (if needed) and managing the underlying CalibratedExplainer instance.

Example Usage:

from calibrated_explanations import WrapCalibratedExplainer
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import load_iris

# Load data
X, y = load_iris(return_X_y=True)

# Initialize wrapper with a base model
model = RandomForestClassifier()
wrapper = WrapCalibratedExplainer(model)

# Fit and calibrate (automatically handles data splitting if not provided)
wrapper.fit(X, y)

# Explain
x_test = X[:1]
explanations = wrapper.explain(x_test)

{eval-rst} .. autoclass:: calibrated_explanations.core.wrap_explainer.WrapCalibratedExplainer :members: :undoc-members: :show-inheritance: :inherited-members:

Explanation Containers¶

When you request explanations for a set of instances, the result is returned in a CalibratedExplanations object. This collection holds the individual explanations and provides methods for visualization and export.

CalibratedExplanations¶

A CalibratedExplanations object is returned when you call explain() on a CalibratedExplainer. It is a collection of explanations for the provided test instances. It serves as a container that allows you to iterate over individual explanations, visualize them, or export them.

Example Usage:

# Assuming 'explanations' is a CalibratedExplanations object
# Iterate over explanations
for explanation in explanations:
    print(explanation.prediction)

# Plot all explanations
explanations.plot()

# Get a specific explanation
first_explanation = explanations[0]

Metadata Attributes:

When FAST-based feature filtering is enabled (experimental), the CalibratedExplanations object may include additional metadata for transparency and debugging:

features_to_ignore_per_instance: A list of numpy arrays, one per instance, containing the feature indices ignored for that instance due to filtering. This is best-effort metadata and not part of the stable API.
feature_filter_per_instance_ignore: (On the CalibratedExplainer instance) The raw ignore masks from the most recent filtered batch.

{eval-rst} .. autoclass:: calibrated_explanations.explanations.explanations.CalibratedExplanations :members: :undoc-members: :show-inheritance: :inherited-members:

Explanation Types¶

Individual explanations are represented by specific classes depending on the type of explanation requested.

CalibratedExplanation¶

This is the abstract base class for a single explanation. It contains the instance data, the prediction, and the feature weights (rules) that explain the prediction. It provides methods for plotting the explanation.

{eval-rst} .. autoclass:: calibrated_explanations.explanations.explanation.CalibratedExplanation :members: :undoc-members: :show-inheritance: :inherited-members:

FactualExplanation¶

A FactualExplanation explains why a model made a specific prediction for an instance. It identifies the feature values (conditions) that, if changed, would most likely alter the prediction. It focuses on the features present in the instance.

Example Usage:

# Plot a factual explanation
factual_explanation.plot()

# Add a conjunction to the explanation
factual_explanation.add_conjunctions()

{eval-rst} .. autoclass:: calibrated_explanations.explanations.explanation.FactualExplanation :members: :undoc-members: :show-inheritance: :inherited-members:

AlternativeExplanation¶

An AlternativeExplanation (often called a counterfactual explanation) explores what if scenarios. It suggests changes to the feature values that would result in a different prediction (e.g., flipping a classification label or moving a regression prediction into a different range).

Example Usage:

# Plot an alternative explanation
alternative_explanation.plot()

{eval-rst} .. autoclass:: calibrated_explanations.explanations.explanation.AlternativeExplanation :members: :undoc-members: :show-inheritance: :inherited-members: