Plot explanations with PlotSpec

Optional plotting extra

PlotSpec stays opt-in for v0.9.0. The quickstarts and notebooks render calibrated explanations without it; enable the PlotSpec extras only when you need uncertainty-aware visuals for reports or audits.

PlotSpec is the optional plotting backend introduced alongside the governance refresh. It produces telemetry-aware renderings that document interval sources and fallbacks while keeping the calibrated workflow unchanged.

Requirements

pip install "calibrated_explanations[viz]"

Render a regression explanation

from pathlib import Path
from calibrated_explanations.viz import (
    build_regression_bars_spec,
    matplotlib_adapter,
)

predict = {"predict": 3.2, "low": 2.7, "high": 3.8}
feature_weights = {
    "predict": [0.8, -0.4, 0.2],
    "low": [0.5, -0.7, 0.0],
    "high": [1.1, -0.1, 0.4],
}
features_to_plot = [0, 1, 2]
column_names = ["feat_a", "feat_b", "feat_c"]
instance = [1.2, 0.3, -0.1]

spec = build_regression_bars_spec(
    title="Regression feature contributions",
    predict=predict,
    feature_weights=feature_weights,
    features_to_plot=features_to_plot,
    column_names=column_names,
    instance=instance,
    y_minmax=(2.0, 4.0),
    interval=True,
    sort_by="abs",  # one of: none|value|abs|width|label
    ascending=False,
)

output = Path("plotspec_example.png")
matplotlib_adapter.render(spec, show=False, save_path=str(output))

sort_by accepts none, value, abs, width, or label. When intervals cross zero the adapter falls back to translucent bars that match legacy output.

Runtime telemetry

When you opt into PlotSpec, the library documents the chosen builder and renderer. PlotSpec identifiers are recorded on both the batch telemetry and explainer.runtime_telemetry as plot_source and plot_fallbacks. Use these fields to verify whether the PlotSpec adapter or a legacy fallback rendered the chart.

CLI discovery

Use the plugin CLI when you need to audit optional plot routes. List registered plot styles and identify defaults:

python -m calibrated_explanations.plugins.cli list plots
python -m calibrated_explanations.plugins.cli show plot_spec.default.factual --kind plots

The CLI output includes builder/renderer IDs, fallback chains, and compatibility flags.