calibrated_explanations.core.CalibratedExplainer¶

class calibrated_explanations.core.CalibratedExplainer(learner, x_cal, y_cal, mode='classification', feature_names=None, categorical_features=None, categorical_labels=None, class_labels=None, bins=None, difficulty_estimator=None, **kwargs)[source]¶

Bases: object

Initialize the explainer with calibration data and metadata.

Parameters:

learner (Any) – Predictive learner that must already expose fit/predict and, for classification, predict_proba.
x_cal (array-like of shape (n_calibration_samples, n_features)) – Calibration feature matrix used to fit interval calibrators.
y_cal (array-like of shape (n_calibration_samples,)) – Calibration targets paired with x_cal.
mode ({"classification", "regression"}, default="classification") – Operating mode controlling which calibrators/plugins are used.
feature_names (Sequence[str] or None, optional) – Optional list of human-readable feature names.
categorical_features (Sequence[int] or None, optional) – Indices describing which features should be treated as categorical.
categorical_labels (Mapping[int, Mapping[int, str]] or None, optional) – Optional mapping translating categorical feature values to labels.
class_labels (Mapping[int, str] or None, optional) – Optional mapping translating class indices to display labels.
bins (array-like or None, optional) – Pre-computed Mondrian categories for fast explanations.
difficulty_estimator (Any or None, optional) – Optional crepes DifficultyEstimator instance for regression tasks.
**kwargs (Any) – Advanced configuration flags preserved for backward compatibility. Includes condition_source (“observed” or “prediction”, default=”prediction”).

Notes

Minimal lifecycle logging is available at INFO level. To enable, run:

import logging
logging.getLogger("calibrated_explanations").setLevel(logging.INFO)

Attributes:

calibration_summary_shape: Return the calibration summary shape.
categorical_value_counts_cache: Return the categorical value counts cache.
explanation_orchestrator: Return the ExplanationOrchestrator provisioned by the PluginManager.
fast: Whether to use fast mode.
feature_filter_config: Return the feature filter configuration.
feature_filter_per_instance_ignore: Return the per-instance feature filter ignore list.
feature_names: Get the feature names.
initialized: Return True if the explainer is initialized.
interval_learner: Access the interval learner managed by the prediction orchestrator.
last_explanation_mode: Return the mode of the last generated explanation.
noise_type: The type of noise to use.
num_features: Get the number of features in the calibration data.
numeric_sorted_cache: Return the numeric sorted cache.
parallel_executor: Return the active parallel executor.
perf_parallel: Public alias for _perf_parallel.
plot_plugin_fallbacks: Return the plot plugin fallback configuration.
plugin_manager: Public accessor for the active PluginManager.
predict_bridge: Return the prediction bridge.
prediction_orchestrator: Return the PredictionOrchestrator provisioned by the PluginManager.
preprocessor_metadata: Return the telemetry-safe preprocessing snapshot if available.
reject_orchestrator: Return the RejectOrchestrator provisioned by the PluginManager.
runtime_telemetry: Return the most recent telemetry payload reported by the explainer.
scale_factor: The scale factor for perturbations.
severity: The severity of perturbations.
x_cal: Get the calibration input data.
y_cal: Get the calibration target data.

Methods

`__call__`(x[, threshold, ...])	Call self as a function to create a `CalibratedExplanations` object for the test data with the already assigned discretizer.
`append_cal`(x, y)	Append new calibration data.
`build_instance_telemetry_payload`(explanations)	Delegate to ExplanationOrchestrator.
`calibrated_confusion_matrix`()	Generate a calibrated confusion matrix.
`close`()	Reset runtime state, then shutdown any provisioned parallel pool.
`discretize`(data)	Apply the discretizer to input data.
`enable_fast_mode`()	Enable fast explanation mode.
`explain_factual`(x[, threshold, ...])	Create a `CalibratedExplanations` object for the test data with the discretizer automatically assigned for factual explanations.
`explain_fast`(x[, threshold, ...])	Create a `CalibratedExplanations` object for the test data.
`explore_alternatives`(x[, threshold, ...])	Create a `AlternativeExplanations` object for the test data with the discretizer automatically assigned for alternative explanations.
`get_calibration_summaries`([x_cal_np])	Return cached categorical counts and sorted numeric calibration values.
`get_plugin_manager`()	Return the active plugin manager, applying any derived defaults.
`get_sigma_test`(x)	Return the difficulty (sigma) of the test instances.
`infer_explanation_mode`()	Infer the explanation mode from runtime state.
`initialize_pool`([n_workers, pool_at_init])	Create a ParallelExecutor for this explainer.
`is_fast`()	Test if the explainer uses fast mode.
`is_mondrian`()	Test if Mondrian (per-bin) calibration is enabled.
`is_multiclass`()	Test if it is a multiclass problem.
`obtain_interval_calibrator`(*, fast, metadata)	Return the interval calibrator from the prediction orchestrator.
`plot`(x[, y, threshold])	Generate plots for the test data.
`predict`(x[, uq_interval, calibrated])	Generate predictions for the test data.
`predict_calibration`()	Predict the target values for the calibration data.
`predict_proba`(x[, uq_interval, calibrated, ...])	Generate probability predictions for the test data.
`reinitialize`(learner[, xs, ys, bins])	Reinitialize the explainer with a new learner.
`require_plugin_manager`()	Return the plugin manager or raise if the explainer is not initialized.
`reset`()	Clear transient runtime state retained between explanation calls.
`resolve_parallel_executor`(explicit_executor)	Resolve the parallel executor honoring overrides and environment config.
`rule_boundaries`(instances[, perturbed_instances])	Extract the rule boundaries for a set of instances.
`set_difficulty_estimator`(difficulty_estimator)	Assign or update the difficulty estimator.
`set_discretizer`(discretizer[, x_cal, y_cal, ...])	Assign the discretizer to be used.
`set_mode`(mode[, initialize])	Assign the mode of the explainer.
`set_preprocessor_metadata`(metadata)	Update the stored preprocessing metadata snapshot.

require_plugin_manager() → PluginManager[source]¶

Return the plugin manager or raise if the explainer is not initialized.

Returns:: The active plugin manager instance.
Return type:: PluginManager
Raises:: NotFittedError – If the plugin manager is not initialized.

get_plugin_manager() → PluginManager[source]¶

Return the active plugin manager, applying any derived defaults.

Wrapper layers must not mutate plugin manager state directly. Any runtime-derived plugin preferences (for example, feature filter execution requirements) are enforced here so orchestration remains centralized in the explainer/manager layers.

resolve_parallel_executor(explicit_executor: Any | None) → Any | None[source]¶: Resolve the parallel executor honoring overrides and environment config.

initialize_pool(n_workers: int | None = None, *, pool_at_init: bool = False) → None[source]¶

Create a ParallelExecutor for this explainer.

Parameters:

n_workers (int | None) – Optional maximum worker count to enforce.
pool_at_init (bool) – If True, enter the pool immediately so worker processes are spawned at initialization time (useful for warm-up and initializer-based harness installation).

close() → None[source]¶: Reset runtime state, then shutdown any provisioned parallel pool.

reset() → None[source]¶: Clear transient runtime state retained between explanation calls.

infer_explanation_mode() → str[source]¶: Infer the explanation mode from runtime state.

property prediction_orchestrator: Any¶: Return the PredictionOrchestrator provisioned by the PluginManager.

property explanation_orchestrator: Any¶: Return the ExplanationOrchestrator provisioned by the PluginManager.

property reject_orchestrator: Any¶: Return the RejectOrchestrator provisioned by the PluginManager.

build_instance_telemetry_payload(explanations: Any) → Dict[str, Any][source]¶: Delegate to ExplanationOrchestrator.

property plot_plugin_fallbacks: Dict[str, Tuple[str, ...]]¶

Return the plot plugin fallback configuration.

Returns:: Mapping of mode to fallback identifiers.
Return type:: Dict[str, Tuple[str, …]]

property plugin_manager: PluginManager¶: Public accessor for the active PluginManager.

property perf_parallel: bool¶: Public alias for _perf_parallel.

property initialized: bool¶: Return True if the explainer is initialized.

property last_explanation_mode: str | None¶: Return the mode of the last generated explanation.

property feature_filter_per_instance_ignore: Any¶: Return the per-instance feature filter ignore list.

property parallel_executor: Any¶: Return the active parallel executor.

property feature_filter_config: Any¶: Return the feature filter configuration.

property predict_bridge: Any¶: Return the prediction bridge.

property categorical_value_counts_cache: Any¶: Return the categorical value counts cache.

property numeric_sorted_cache: Any¶: Return the numeric sorted cache.

property calibration_summary_shape: Any¶: Return the calibration summary shape.

enable_fast_mode() → None[source]¶

Enable fast explanation mode.

This initializes the interval learner for fast explanations if not already done.

property runtime_telemetry: Mapping[str, Any]¶: Return the most recent telemetry payload reported by the explainer.

property preprocessor_metadata: Dict[str, Any] | None¶: Return the telemetry-safe preprocessing snapshot if available.

set_preprocessor_metadata(metadata: Mapping[str, Any] | None) → None[source]¶: Update the stored preprocessing metadata snapshot.

property x_cal¶

Get the calibration input data.

Returns:: The calibration input data.
Return type:: array-like

property y_cal¶

Get the calibration target data.

Returns:: The calibration target data.
Return type:: array-like

append_cal(x, y)[source]¶

Append new calibration data.

Parameters:

x (array-like of shape (n_samples, n_features)) – The new calibration input data to append.
y (array-like of shape (n_samples,)) – The new calibration target data to append.

get_calibration_summaries(x_cal_np: ndarray | None = None) → Tuple[Dict[int, Dict[Any, int]], Dict[int, ndarray]][source]¶

Return cached categorical counts and sorted numeric calibration values.

Delegates to the calibration.summaries module which manages caching of statistical summaries used during explanation generation.

property num_features¶

Get the number of features in the calibration data.

Returns:: The number of features in the calibration data. For dictionary input, returns the number of keys. For array input, returns the number of columns.
Return type:: int

property feature_names¶

Get the feature names.

Returns:: The list of feature names. If no feature names were provided during initialization, returns None.
Return type:: list

property interval_learner: Any¶

Access the interval learner managed by the prediction orchestrator.

Returns:: The interval calibrator (e.g., VennAbers, IntervalRegressor, or list for fast mode).
Return type:: Any

Notes

This is a backward-compatible property that delegates to the interval registry managed by the PredictionOrchestrator. See ADR-001.

get_sigma_test(x: ndarray) → ndarray[source]¶

Return the difficulty (sigma) of the test instances.

Parameters:: x (np.ndarray) – Test instances for which to estimate difficulty.
Returns:: Difficulty estimates (sigma values) for each test instance.
Return type:: np.ndarray

reinitialize(learner, xs=None, ys=None, bins=None)[source]¶

Reinitialize the explainer with a new learner.

This is useful when the learner is updated or retrained and the explainer needs to be reinitialized.

Parameters:

learner (predictive learner) – A predictive learner that can be used to predict the target variable. The learner must be fitted and have a predict_proba method (for classification) or a predict method (for regression).
xs (array-like, optional) – New calibration input data to append
ys (array-like, optional) – New calibration target data to append

Returns:

A CalibratedExplainer object that can be used to explain predictions from a predictive learner.

Return type:

CalibratedExplainer

obtain_interval_calibrator(*, fast: bool, metadata: Mapping[str, Any]) → Tuple[Any, str | None][source]¶: Return the interval calibrator from the prediction orchestrator.

explain_factual(x, threshold=None, low_high_percentiles=(5, 95), bins=None, features_to_ignore=None, *, guarded_options=None, _use_plugin: bool = True, **kwargs) → CalibratedExplanations[source]¶

Create a CalibratedExplanations object for the test data with the discretizer automatically assigned for factual explanations.

This is a thin delegator that sets up the appropriate discretizer and delegates to the orchestrator.

Parameters:

x (array-like) – A set with n_samples of test objects to predict.
threshold (float, int or array-like, default=None) – Target value for probabilistic regression; the explainer returns the calibrated probability P(y ≤ threshold) for each instance. Ignored for classification. Mutually exclusive with confidence_level (per EXCLUSIVE_PARAM_GROUPS). See docs/foundations/concepts/parameter-reference.md for the full disambiguation of threshold, confidence_level, reject_confidence, and GuardedOptions.confidence.
low_high_percentiles (a tuple of floats, default=(5, 95)) – The low and high percentile used to calculate the interval. Applicable to regression.
bins (array-like of shape (n_samples,), default=None) – Mondrian categories
guarded_options (GuardedOptions or None, default=None) – [EXPERIMENTAL] Per-call tuning for the KNN-based in-distribution guard (ADR-038). When provided, the guarded path is activated automatically. Use GuardedOptions to bundle guard tuning parameters (confidence, n_neighbors, normalize, merge_adjacent, verbose).
reject_policy (RejectPolicySpec | None, default=None) – When non-None, activates reject orchestration. Pass a RejectPolicySpec constructed via RejectPolicySpec.flag(), RejectPolicySpec.only_accepted(), or RejectPolicySpec.only_rejected(). When active, the return type is RejectCalibratedExplanations rather than CalibratedExplanations.
multi_labels_enabled (bool, default=False) – [EXPERIMENTAL] When True, generates one explanation per class for multi-class problems (3+ classes). Passed via **kwargs. This parameter surface is under active development; its signature will be promoted to an explicit typed argument before graduation out of experimental status. Unknown additional kwargs are forwarded to the explanation plugin and silently ignored if not recognised (ADR-038 §3 experimental exception).
interval_summary (str or None, default=None) – [EXPERIMENTAL] Controls the interval summary mode forwarded to the explanation plugin. Passed via **kwargs. Subject to the same experimental-graduation constraint as multi_labels_enabled.
**kwargs (dict) – [EXPERIMENTAL] Additional keyword arguments forwarded to the explanation plugin. Silently ignored if not recognised (ADR-038 §3 experimental exception).

Returns:

CalibratedExplanations – A CalibratedExplanations containing one FactualExplanation for each instance. When guarded_options is non-None, per-instance explanations are GuardedFactualExplanation. When reject_policy is non-None, returns RejectCalibratedExplanations.

Return type:

CalibratedExplanations

explore_alternatives(x, threshold=None, low_high_percentiles=(5, 95), bins=None, features_to_ignore=None, *, guarded_options=None, _use_plugin: bool = True, **kwargs) → AlternativeExplanations[source]¶

Create a AlternativeExplanations object for the test data with the discretizer automatically assigned for alternative explanations.

This is a thin delegator that sets up the appropriate discretizer and delegates to the orchestrator.

Parameters:

x (array-like) – A set with n_samples of test objects to predict.
threshold (float, int or array-like, default=None) – Target value for probabilistic regression; the explainer returns the calibrated probability P(y ≤ threshold) for each instance. Ignored for classification. Mutually exclusive with confidence_level (per EXCLUSIVE_PARAM_GROUPS). See docs/foundations/concepts/parameter-reference.md for the full disambiguation of threshold, confidence_level, reject_confidence, and GuardedOptions.confidence.
low_high_percentiles (a tuple of floats, default=(5, 95)) – The low and high percentile used to calculate the interval. Applicable to regression.
bins (array-like of shape (n_samples,), default=None) – Mondrian categories
guarded_options (GuardedOptions or None, default=None) – [EXPERIMENTAL] Per-call tuning for the KNN-based in-distribution guard (ADR-038). When provided, the guarded path is activated automatically. Use GuardedOptions to bundle guard tuning parameters.
reject_policy (RejectPolicySpec | None, default=None) – When non-None, activates reject orchestration. Pass a RejectPolicySpec constructed via RejectPolicySpec.flag(), RejectPolicySpec.only_accepted(), or RejectPolicySpec.only_rejected(). When active, the return type is RejectAlternativeExplanations rather than AlternativeExplanations.
multi_labels_enabled (bool, default=False) – [EXPERIMENTAL] When True, generates one explanation per class for multi-class problems (3+ classes). Passed via **kwargs. This parameter surface is under active development; its signature will be promoted to an explicit typed argument before graduation out of experimental status. Unknown additional kwargs are forwarded to the explanation plugin and silently ignored if not recognised (ADR-038 §3 experimental exception).
interval_summary (str or None, default=None) – [EXPERIMENTAL] Controls the interval summary mode forwarded to the explanation plugin. Passed via **kwargs. Subject to the same experimental-graduation constraint as multi_labels_enabled.
**kwargs (dict) – [EXPERIMENTAL] Additional keyword arguments forwarded to the explanation plugin. Silently ignored if not recognised (ADR-038 §3 experimental exception).

Returns:

AlternativeExplanations – When reject_policy is non-None, returns RejectAlternativeExplanations.

Return type:

AlternativeExplanations

Notes

The explore_alternatives will eventually be used instead of the explain_counterfactual method. When guarded_options is non-None, per-instance explanations are GuardedAlternativeExplanation.

explain_fast(x, threshold=None, low_high_percentiles=(5, 95), bins=None, *, reject_policy: Any | None = None, _use_plugin: bool = True) → CalibratedExplanations[source]¶

Create a CalibratedExplanations object for the test data.

Parameters:

x (array-like) – A set with n_samples of test objects to predict
threshold (float, int or array-like of shape (n_samples,), default=None) – values for which p-values should be returned. Only used for probabilistic explanations for regression.
low_high_percentiles (a tuple of floats, default=(5, 95)) – The low and high percentile used to calculate the interval. Applicable to regression.
bins (array-like of shape (n_samples,), default=None) – Mondrian categories

Raises:

ConfigurationError – If plugin resolution, initialization, or invocation fails for the fast-explanation plugin (for example, an unsupported model, a feature-count mismatch, an invalid threshold value, or an invalid batch returned by the plugin).

Returns:

CalibratedExplanations – A CalibratedExplanations containing one FastExplanation for each instance.

Return type:

CalibratedExplanations

is_multiclass() → bool[source]¶

Test if it is a multiclass problem.

Returns:: True if multiclass (num_classes > 2).
Return type:: bool

is_fast() → bool[source]¶

Test if the explainer uses fast mode.

Returns:: True if fast mode is enabled.
Return type:: bool

is_mondrian() → bool[source]¶

Test if Mondrian (per-bin) calibration is enabled.

Returns:: True if bins are configured, indicating Mondrian calibration.
Return type:: bool

discretize(data: ndarray) → ndarray[source]¶

Apply the discretizer to input data.

Parameters:: data (np.ndarray) – The data to discretize.
Returns:: The discretized data.
Return type:: np.ndarray

rule_boundaries(instances, perturbed_instances=None)[source]¶

Extract the rule boundaries for a set of instances.

Parameters:

instances (array-like) – The instances to extract boundaries for.
perturbed_instances (array-like, optional) – Discretized versions of instances. Defaults to None.

Returns:

Min and max values for each feature for each instance.

Return type:

array-like

set_difficulty_estimator(difficulty_estimator, initialize=True) → None[source]¶

Assign or update the difficulty estimator.

If initialized to a difficulty estimator, the explainer can be used to reject explanations that are deemed too difficult.

Parameters:

difficulty_estimator (crepes.extras.DifficultyEstimator or None):) – A crepes.extras.DifficultyEstimator object from the crepes package. To remove the crepes.extras.DifficultyEstimator, set to None.
(bool (initialize) – If true, then the interval learner is initialized once done. Defaults to True.
optional) – If true, then the interval learner is initialized once done. Defaults to True.

set_mode(mode, initialize=True) → None[source]¶

Assign the mode of the explainer. The mode can be either ‘classification’ or ‘regression’.

Parameters:

(str) (mode)
(bool (initialize)
optional) (If true, then the interval learner is initialized once done. Defaults to True.)

Raises:

ValidationError – If mode is not ‘classification’ or ‘regression’.:

set_discretizer(discretizer, x_cal=None, y_cal=None, features_to_ignore=None, *, condition_source: str | None = None) → None[source]¶

Assign the discretizer to be used.

Parameters:

discretizer (str or discretizer object) – The discretizer to be used.
x_cal (array-like, optional) – The calibration data for the discretizer.
y_cal (array-like, optional) – The calibration target data for the discretizer.

predict(x, uq_interval=False, calibrated=True, **kwargs)[source]¶

Generate predictions for the test data.

Parameters:

x (array-like) – The test data.
uq_interval (bool, default=False) – Whether to return uncertainty intervals.
calibrated (bool, default=True) – If True, the calibrator is used for prediction. If False, the underlying learner is used for prediction.
**kwargs (Various types, optional) –
Additional parameters to customize the explanation process. Supported parameters include:
- thresholdfloat, int, or array-like of shape (n_samples,), optional, default=None
  Specifies the threshold for probabilistic regression. Returns calibrated probabilities P(y <= threshold) for regression tasks. Classification calls with this parameter raise ValidationError.
- low_high_percentilestuple of two floats, optional, default=(5, 95)
  The lower and upper percentiles used to calculate the prediction interval for regression tasks. Determines the breadth of the interval based on the distribution of the predictions. This parameter is only used for regression tasks without threshold=.

Raises:

NotFittedError – If the explainer has not been fitted/calibrated prior to calling predict.
ConfigurationError – If unsupported, removed, or conflicting keyword arguments are supplied.
ValidationError – If threshold or low_high_percentiles is invalid for the configured mode (for example, a classification call with threshold=, or a threshold whose length does not match the number of instances in x).

Returns:

calibrated_prediction (float or array-like, or str) – The calibrated prediction. For regression tasks without threshold, this is the median of the conformal predictive system. For probabilistic regression (with threshold), this is a probability P(y <= threshold). For classification tasks, it is the class label with the highest calibrated probability.
interval (tuple of floats, optional) – A tuple (low, high) representing the lower and upper bounds of the uncertainty interval. This is returned only if uq_interval=True.

Examples

For a prediction without prediction intervals:

w.predict(x)

For a prediction with uncertainty quantification intervals:

w.predict(x, uq_interval=True)

Notes

Classification calls with threshold= raise ValidationError. low_high_percentiles is only used for regression tasks without threshold=.

predict_proba(x, uq_interval=False, calibrated=True, threshold=None, **kwargs)[source]¶

Generate probability predictions for the test data.

This is a wrapper around the predict_proba method which is more similar to the scikit-learn predict_proba method for classification. As opposed to predict_proba, this method may output uncertainty intervals.

Parameters:

x (array-like) – The test data for which predictions are to be made. This should be in a format compatible with sklearn (e.g., numpy arrays, pandas DataFrames).
uq_interval (bool, default=False) – If true, then the prediction interval is returned as well.
calibrated (bool, default=True) – If True, the calibrator is used for prediction. If False, the underlying learner is used for prediction.
threshold (float, int or array-like of shape (n_samples,), optional, default=None) – Threshold values used with regression to get probability of being below the threshold. Classification calls with this parameter raise ValidationError.

Raises:

NotFittedError – If the explainer has not been fitted/calibrated prior to calling predict_proba.
ConfigurationError – If unsupported, removed, or conflicting keyword arguments are supplied.
ValidationError – If threshold is invalid for the configured mode (for example, a classification call with threshold=, or a threshold whose length does not match the number of instances in x).

Returns:

calibrated probability – The calibrated probability of the positive class (or the predicted class for multiclass).
(low, high) (tuple of float lists, corresponding to the lower and upper bound of each prediction interval.)

Examples

For a prediction without uncertainty quantification intervals:

w.predict_proba(x)

For a prediction with uncertainty quantification intervals:

w.predict_proba(x, uq_interval=True)

Notes

Classification calls with threshold= raise ValidationError.

plot(x, y=None, threshold=None, **kwargs)[source]¶: Generate plots for the test data.

calibrated_confusion_matrix()[source]¶

Generate a calibrated confusion matrix.

Generates a confusion matrix for the calibration set to provide insights about model behavior. The confusion matrix is only available for classification tasks. Stratified cross-validation is used on the calibration set to generate the confusion matrix while avoiding quadratic recalibration overhead.

Returns:: The calibrated confusion matrix.
Return type:: array-like

predict_calibration()[source]¶

Predict the target values for the calibration data.

Returns:: Predicted values for the calibration data. For models that expose a hat matrix, this returns updated predictions using that matrix; otherwise it uses the predict_function on the calibration data.
Return type:: array-like

property fast: bool¶

Whether to use fast mode.

Returns:: True if fast mode is enabled.
Return type:: bool

property noise_type: str¶

The type of noise to use.

Returns:: The noise type.
Return type:: str

property scale_factor: float | None¶

The scale factor for perturbations.

Returns:: The scale factor.
Return type:: float | None

property severity: float | None¶

The severity of perturbations.

Returns:: The severity.
Return type:: float | None