calibrated_explanations.core.WrapCalibratedExplainer¶

class calibrated_explanations.core.WrapCalibratedExplainer(learner: Any)[source]¶

Bases: object

Initialize the WrapCalibratedExplainer with a predictive learner.

Parameters:

learner (predictive learner) – A predictive learner that can be used to predict the target variable.

Attributes:

auto_encode: Get the auto_encode configuration.
cfg: Configuration property.
feature_filter_config: Expose the feature-filter configuration if available.
mondrian_categorizer: Descriptive alias for mc (ADR-038 5B); read-only.
parallel_executor: Expose the internal parallel executor if available.
pre_fitted: Check if the preprocessor is pre-fitted.
preprocessor: Get the preprocessor.
preprocessor_metadata: Return the telemetry-safe preprocessing snapshot if available.
runtime_telemetry: Return the most recent telemetry payload reported by the explainer.

Methods

`calibrate`(x_calibration, y_calibration[, ...])	Calibrate the wrapper using calibration data and create an explainer.
`calibrated_confusion_matrix`()	Generate a calibrated confusion matrix.
`explain_factual`(x, **kwargs)	Generate factual explanations for provided instances.
`explain_fast`(x, **kwargs)	Generate fast explanations for the test data.
`explore_alternatives`(x, **kwargs)	Generate alternative explanations for the test data.
`export_preprocessor_mapping`()	Export the current preprocessor mapping snapshot.
`fit`(x_proper_train, y_proper_train, **kwargs)	Fit the underlying learner on training data.
`from_config`(cfg)	Construct a wrapper from an `ExplainerConfig`.
`import_preprocessor_mapping`(mapping)	Attempt to apply a mapping snapshot to the configured preprocessor.
`load_state`(path_or_fileobj)	Load wrapper state from an ADR-031 persisted artifact.
`plot`(x[, y, threshold])	Generate plots for the test data.
`predict`(x[, uq_interval, calibrated, ...])	Generate predictions for the test data.
`predict_proba`(x[, uq_interval, calibrated, ...])	Generate probability predictions for the test data.
`save_state`(path_or_fileobj)	Persist wrapper state using an ADR-031 manifest + checksums.
`set_difficulty_estimator`(difficulty_estimator, *)	Assign or update the difficulty estimator.
`set_preprocessor_metadata`(metadata)	Update the stored preprocessing metadata snapshot.

property parallel_executor: Any¶: Expose the internal parallel executor if available.

property auto_encode: bool | str¶: Get the auto_encode configuration.

property preprocessor: Any¶: Get the preprocessor.

property mondrian_categorizer: Callable[[Any], Any] | MondrianCategorizer | None¶: Descriptive alias for mc (ADR-038 5B); read-only.

classmethod from_config(cfg: ExplainerConfig) → WrapCalibratedExplainer[source]¶

Construct a wrapper from an ExplainerConfig.

Notes

Fields wired during construction: preprocessor, auto_encode, unseen_category_policy; performance primitives (cache, parallel executor) via the perf factory; internal feature-filter config.
Fields applied at explain-time: threshold and low_high_percentiles are stored on the config and forwarded to explain_factual / explore_alternatives via kwargs.setdefault().

fit(x_proper_train: Any, y_proper_train: Any, **kwargs: Any) → WrapCalibratedExplainer[source]¶

Fit the underlying learner on training data.

Parameters:

x_proper_train (array-like of shape (n_samples, n_features)) – Training input samples.
y_proper_train (array-like of shape (n_samples,)) – Training target values.
**kwargs – Additional keyword arguments forwarded to the learner’s fit.

Returns:

The wrapper instance (allows chaining).

Return type:

WrapCalibratedExplainer

Examples

>>> w = WrapCalibratedExplainer(clf)
>>> w.fit(X_train, y_train)
WrapCalibratedExplainer(...)

calibrate(x_calibration: Any, y_calibration: Any, mc: Callable[[Any], Any] | MondrianCategorizer | None = None, reuse_conditional: bool = False, *, mondrian_categorizer: Callable[[Any], Any] | MondrianCategorizer | None = None, **kwargs: Any) → WrapCalibratedExplainer[source]¶

Calibrate the wrapper using calibration data and create an explainer.

Parameters:

x_calibration (array-like of shape (n_samples, n_features)) – Calibration features used to fit internal calibrators.
y_calibration (array-like of shape (n_samples,)) – Calibration targets corresponding to x_calibration.
mc (callable or MondrianCategorizer, optional) – Optional Mondrian categories helper. Defaults to None.
reuse_conditional (bool, default=False) – Reuse the previously configured Mondrian categorizer for this calibration. Mutually exclusive with bins and mc.
mondrian_categorizer (callable or MondrianCategorizer, optional) – Descriptive alias for mc (ADR-038 5B). Resolves to the same value; specifying both mc and mondrian_categorizer raises ConfigurationError.
**kwargs – Forwarded to CalibratedExplainer.__init__ for advanced configuration (e.g. mode, feature_names, bins). Every name accepted by CalibratedExplainer.__init__ is accepted here; for perf_cache/perf_parallel a call-time value overrides the wrapper-level attribute.

Returns:

The wrapper instance with the explainer attribute set to a configured CalibratedExplainer.

Return type:

WrapCalibratedExplainer

Raises:

NotFittedError – If the underlying learner has not been fitted via fit().
ConfigurationError – If both mc and mondrian_categorizer are specified.
ModelNotSupportedError – If the underlying learner does not implement predict.

Examples

>>> w = WrapCalibratedExplainer(clf)
>>> w.fit(X_train, y_train)
>>> w.calibrate(X_cal, y_cal)

Notes

If mode is not provided in kwargs the wrapper will infer classification vs regression from the presence of predict_proba on the underlying learner.

property feature_filter_config: Any¶

Expose the feature-filter configuration if available.

Tests and plugins may access this property on the wrapper; prefer the internally-stored config, otherwise delegate to the explainer.

explain_factual(x: Any, **kwargs: Any) → Any[source]¶

Generate factual explanations for provided instances.

Parameters:

x (array-like) – Instances to explain (single or batch). Shape should match the feature dimensionality used during calibration.
**kwargs – Forwarded to CalibratedExplainer.explain_factual().

Returns:

Explanation collection produced by the underlying explainer.

Return type:

CalibratedExplanations or mapping

Notes

Assumption boundary: This method verifies the API contract — that the call completes and returns a valid explanation collection. It does not guarantee the statistical validity of calibrated feature attributions for any particular instance. The calibration validity depends on the exchangeability assumption: the calibration set must be representative of the test distribution. Feature attribution magnitudes reflect calibrated probability shifts, not causal importances or ground-truth attribution correctness.

See also

CalibratedExplainer.explain_factual(): For full parameter and return semantics.

explore_alternatives(x: Any, **kwargs: Any) → Any[source]¶

Generate alternative explanations for the test data.

Notes

Assumption boundary: Alternative explanations describe feature changes that would shift the predicted probability toward an alternative outcome. They do not guarantee that the described feature changes are physically achievable, distributionally feasible, or actionable in a new model deployment. The exchangeability assumption applies: results depend on the calibration set being representative of the test distribution.

See also

CalibratedExplainer.explore_alternatives(): Refer to the docstring for explore_alternatives in CalibratedExplainer for more details.

explain_fast(x: Any, **kwargs: Any) → Any[source]¶

Generate fast explanations for the test data.

See also

CalibratedExplainer.explain_fast(): Refer to the docstring for explain_fast in CalibratedExplainer for more details.

predict(x: Any, uq_interval: bool = False, calibrated: bool = True, reject_policy: Any | None = None, **kwargs: Any) → Any[source]¶

Generate predictions for the test data.

See also

CalibratedExplainer.predict(): Refer to the docstring for predict in CalibratedExplainer for more details.

predict_proba(x: Any, uq_interval: bool = False, calibrated: bool = True, threshold: float | None = None, reject_policy: Any | None = None, **kwargs: Any) → Any[source]¶

Generate probability predictions for the test data.

See also

CalibratedExplainer.predict_proba(): Refer to the docstring for predict_proba in CalibratedExplainer for more details.

calibrated_confusion_matrix() → Any[source]¶

Generate a calibrated confusion matrix.

See also

CalibratedExplainer.calibrated_confusion_matrix(): Refer to the docstring for calibrated_confusion_matrix in CalibratedExplainer for more details.

set_difficulty_estimator(difficulty_estimator: Any, *, initialize: bool = True) → None[source]¶

Assign or update the difficulty estimator.

Parameters:

difficulty_estimator (Any) – Difficulty estimator to assign, or None to clear it.
initialize (bool, default=True) – Whether to reinitialize calibrated prediction internals after assignment. Use False only for advanced workflows that need to update reject strategy metadata without changing the calibrated probability path.

See also

CalibratedExplainer.set_difficulty_estimator(): Refer to the docstring for set_difficulty_estimator in CalibratedExplainer for more details.

plot(x: Any, y: Any = None, threshold: float | None = None, **kwargs: Any) → Any[source]¶

Generate plots for the test data.

Parameters:

x (array-like) – Test instances to plot explanations for.
y (array-like, optional) – True labels for the test instances.
threshold (float, optional) – Threshold for probabilistic regression.
**kwargs (dict) – Additional keyword arguments passed to the plot method.

Returns:

The value returned by the underlying plot implementation.

Return type:

object or None

See also

CalibratedExplainer.plot(): Refer to the docstring for plot in CalibratedExplainer for more details.

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.

export_preprocessor_mapping() → dict[str, Any] | None[source]¶

Export the current preprocessor mapping snapshot.

Returns:: A mapping snapshot suitable for telemetry or round-tripping, or None when no mapping information is available.
Return type:: dict[str, Any] | None

import_preprocessor_mapping(mapping: Mapping[str, Any]) → None[source]¶

Attempt to apply a mapping snapshot to the configured preprocessor.

This is a best-effort helper: when an attached preprocessor exposes a setter (set_mapping) or a writable mapping_ attribute we will apply the mapping. Otherwise the mapping is stashed on the wrapper as _imported_preprocessor_mapping for potential downstream use.

A warning is emitted when the mapping could not be applied to ensure visibility per the fallback policy.

save_state(path_or_fileobj: Any) → Path[source]¶: Persist wrapper state using an ADR-031 manifest + checksums.

classmethod load_state(path_or_fileobj: Any) → WrapCalibratedExplainer[source]¶: Load wrapper state from an ADR-031 persisted artifact.

property pre_fitted: bool¶

Check if the preprocessor is pre-fitted.

Returns:: True if pre-fitted, False otherwise.
Return type:: bool

property cfg: Any¶

Configuration property.

Returns:: The configuration.
Return type:: Any