Use external plugins

Plugins are optional. Start with the calibrated explanations workflow first; only opt in to plugins (like FAST) when you need speed-ups or custom plots. This page shows how to install, register, and wire plugins without changing your core modeling code.

When to opt in

  • Your calibrated factual/alternative runs are validated and you want lower latency.

  • You need a different plot style or visualization backend via PlotSpec.

  • Your team maintains a vetted plugin aligned to the CE contract.

Note: FAST-mode plugins are opt-in only. By design the runtime will not include FAST implementations in the default fallback chains for factual or alternative explanations — you must explicitly request FAST via the fast_plugin argument or CE_EXPLANATION_PLUGIN_FAST / CE_INTERVAL_PLUGIN_FAST.

FAST Explanations

Status: Experimental

FAST explanations are an experimental feature. Use them only after validating your standard factual/alternative workflows. They are not recommended for production without thorough testing.

FAST explanations provide accelerated rule generation through sampling strategies, trading some detail for significantly improved speed.

When to Use FAST

  • Large batch processing: When explaining thousands of instances

  • Real-time applications: When latency constraints are tight

  • Exploratory analysis: When approximate explanations suffice

Trade-offs

Aspect

Standard Explanations

FAST Explanations

Speed

Baseline

2-10x faster

Detail

Full perturbation analysis

Sampled perturbations

Calibration

Full conformal guarantees

Approximate coverage

Stability

Deterministic

May vary between runs

Quick Start

# Method 1: Use fast=True kwarg (preferred)
explanation = explainer.explain_factual(x_test, fast=True)

# Method 2: Use explain_fast directly
fast_explanation = explainer.explain_fast(x_test)

Research Background

FAST explanations are documented in:

Löfström, H., et al. (2024). Fast Calibrated Explanations: Efficient and Uncertainty-Aware Explanations for Machine Learning Models. In: xAI 2024. Lecture Notes in Computer Science. DOI: 10.1007/978-3-031-44064-9_18

Install and register

Install the curated bundle and register the FAST plugins when needed:

pip install "calibrated-explanations[external-plugins]"
python -m external_plugins.fast_explanations register

See External plugins for listings and notes.

Wire it into your run

Prefer explicit, local configuration for development, and use environment variables for CI/CD.

Method A — Explainer parameters (highest priority)

For modality-aware plugin selection (for example vision and audio plugin discovery), see Modality plugin selection.

from calibrated_explanations import CalibratedExplainer

explainer = CalibratedExplainer(
    model, x_cal, y_cal,
    # Explanation plugin choice by mode
    factual_plugin="core.explanation.factual",   # or an external id
    alternative_plugin="core.explanation.alternative",
    # Interval calibrator and plot style
    interval_plugin="core.interval.legacy",  # or external interval id
    plot_style="plot_spec.default",                 # or a custom style id
)

explanations = explainer.explain_factual(x_test)
explanations.plot()  # uses plot_style and fallbacks

from calibrated_explanations import CalibratedExplainer

explainer = CalibratedExplainer(
    model, x_cal, y_cal,
    # To activate FAST mode globally
    fast=True,
    # or select a specific FAST plugin
    fast_plugin="core.explanation.fast",
    # Interval calibrator and plot style
    interval_plugin="core.interval.fast",  # or external interval id
    plot_style="plot_spec.default",                 # or a custom style id
)

# Use the fast mode to invoke the fast execution path
fast_batch = explainer.explain_fast(x_test)
fast_batch.plot()

Notes

  • If your chosen explanation plugin declares plot_dependency or interval_dependency, the explainer seeds those into the fallback chain automatically.

  • You can override plot style at render time: explanations.plot(style_override="legacy").

Method C — Environment variables

Use when you need to switch plugins without code changes (e.g., CI/CD):

# Plot style and fallbacks
$env:CE_PLOT_STYLE = "plot_spec.default"
$env:CE_PLOT_STYLE_FALLBACKS = "legacy"

# Explanation plugin fallbacks by mode
$env:CE_EXPLANATION_PLUGIN = "core.explanation.factual"
$env:CE_EXPLANATION_PLUGIN_FAST = "core.explanation.fast"
$env:CE_EXPLANATION_PLUGIN_FACTUAL_FALLBACKS = "core.explanation.factual"
$env:CE_EXPLANATION_PLUGIN_ALTERNATIVE_FALLBACKS = "core.explanation.alternative"
$env:CE_EXPLANATION_PLUGIN_FAST_FALLBACKS = "core.explanation.fast"

# Interval plugin defaults + fallback chain
$env:CE_INTERVAL_PLUGIN = "core.interval.fast"
$env:CE_INTERVAL_PLUGIN_FAST = "core.interval.fast"
$env:CE_INTERVAL_PLUGIN_FALLBACKS = "core.interval.fast,core.interval.legacy"

Then construct your explainer without explicit plugin arguments and rely on the configured defaults.

Troubleshooting and governance

  • Trust/deny controls: set CE_TRUST_PLUGIN and CE_DENY_PLUGIN to allow or block specific identifiers during discovery.

  • CLI discovery and audits:

python -m calibrated_explanations.plugins.cli list all