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.
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

`build_preprocessor_metadata`()	Build metadata for the preprocessor.
`calibrate`(x_calibration, y_calibration[, mc])	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.
`explain_guarded_factual`(x, **kwargs)	Generate guarded factual explanations that only use in-distribution perturbations.
`explore_alternatives`(x, **kwargs)	Generate alternative explanations for the test data.
`explore_guarded_alternatives`(x, **kwargs)	Generate guarded alternative explanations that only use in-distribution perturbations.
`export_preprocessor_mapping`()	Export the current preprocessor mapping snapshot.
`extract_preprocessor_snapshot`(preprocessor)	Extract a snapshot of the preprocessor state.
`finalize_fit`(reinitialize)	Finalize the fitting process.
`fit`(x_proper_train, y_proper_train, **kwargs)	Fit the underlying learner on training data.
`format_proba_output`(proba, uq_interval)	Format the probability output.
`from_config`(cfg)	Construct a wrapper from an `ExplainerConfig`.
`import_preprocessor_mapping`(mapping)	Attempt to apply a mapping snapshot to the configured preprocessor.
`initialize_reject_learner`([threshold, ncf, w])	Initialize the reject learner with a threshold value.
`load_state`(path_or_fileobj)	Load wrapper state from an ADR-031 persisted artifact.
`maybe_preprocess_for_inference`(X)	Preprocess data for inference if needed.
`normalize_auto_encode_flag`([auto_encode])	Normalize the auto encode flag.
`normalize_public_kwargs`([payload])	Normalize public keyword arguments.
`plot`(x[, y, threshold])	Generate plots for the test data.
`pre_fit_preprocess`(x)	Preprocess data before fitting.
`pre_transform`(X)	Preprocess data for transformation.
`predict`(x[, uq_interval, calibrated, ...])	Generate predictions for the test data.
`predict_proba`(x[, uq_interval, calibrated, ...])	Generate probability predictions for the test data.
`predict_reject`(x[, bins, confidence])	Predict whether to reject the explanations for the test data.
`save_state`(path_or_fileobj)	Persist wrapper state using an ADR-031 manifest + checksums.
`serialise_preprocessor_value`(value)	Serialise a preprocessor value for storage.
`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.

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

Construct a wrapper from an ExplainerConfig.

Notes

Intentionally minimal and only uses the provided model.
Further wiring of preprocessing and knobs will be added later.
Private API to avoid public snapshot changes.

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, **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.
**kwargs – Forwarded to CalibratedExplainer.__init__ for advanced configuration (e.g. mode, feature_names, bins).

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().

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

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.

See also

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

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

Generate guarded factual explanations that only use in-distribution perturbations.

See also

CalibratedExplainer.explain_guarded_factual(): Refer to the docstring for full parameter documentation.

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

Generate guarded alternative explanations that only use in-distribution perturbations.

See also

CalibratedExplainer.explore_guarded_alternatives(): Refer to the docstring for full parameter documentation.

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) → None[source]¶

Assign or update the difficulty estimator.

See also

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

initialize_reject_learner(threshold: float | None = None, ncf=None, w: float = 0.5) → Any[source]¶

Initialize the reject learner with a threshold value.

Deprecated since version 0.11.1: Use reject_orchestrator.initialize_reject_learner on the calibrated explainer instead. This wrapper will be removed no earlier than v0.13.0.

Parameters:

threshold (float or None) – Decision threshold (regression only). Defaults to None.
ncf (str or None, default None) – Non-conformity function type: 'default' or 'ensured'. The internal default score is task-dependent (margin for multiclass, hinge for binary/regression). Legacy 'entropy' is accepted and mapped to 'default'.
w (float, default 0.5) – Blending weight in [0, 1] used only when ncf='ensured'. Ignored for ncf='default'.

See also

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

predict_reject(x: Any, bins: Any = None, confidence: float = 0.95) → Any[source]¶

Predict whether to reject the explanations for the test data.

Deprecated since version 0.11.1: Use reject_orchestrator.predict_reject on the calibrated explainer instead. This wrapper will be removed no earlier than v0.13.0.

See also

CalibratedExplainer.predict_reject(): Refer to the docstring for predict_reject 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.

Return type:

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.

serialise_preprocessor_value(value: Any) → Any[source]¶

Serialise a preprocessor value for storage.

Parameters:: value (Any) – The value to serialise.
Returns:: The serialised value.
Return type:: Any

extract_preprocessor_snapshot(preprocessor: Any) → dict[str, Any] | None[source]¶

Extract a snapshot of the preprocessor state.

Parameters:: preprocessor (Any) – The preprocessor to snapshot.
Returns:: The snapshot dictionary or None.
Return type:: dict[str, Any] | None

build_preprocessor_metadata() → Dict[str, Any][source]¶

Build metadata for the preprocessor.

Returns:: The metadata dictionary.
Return type:: Dict[str, Any]

pre_fit_preprocess(x: Any) → Any[source]¶

Preprocess data before fitting.

Parameters:: x (Any) – The input data.
Returns:: The preprocessed data.
Return type:: Any

pre_transform(X: Any) → Any[source]¶

Preprocess data for transformation.

Parameters:: X (Any) – The input data.
Returns:: The preprocessed data.
Return type:: Any

maybe_preprocess_for_inference(X: Any) → Any[source]¶

Preprocess data for inference if needed.

Parameters:: X (Any) – The input data.
Returns:: The preprocessed data.
Return type:: Any

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

finalize_fit(reinitialize: bool) → WrapCalibratedExplainer[source]¶

Finalize the fitting process.

Parameters:: reinitialize (bool) – Whether to reinitialize.
Returns:: The finalized explainer.
Return type:: WrapCalibratedExplainer

format_proba_output(proba: Any, uq_interval: bool) → Any[source]¶

Format the probability output.

Parameters:

proba (Any) – The probability values.
uq_interval (bool) – Whether to include uncertainty interval.

Returns:

The formatted output.

Return type:

Any

normalize_auto_encode_flag(auto_encode: Any = None) → bool[source]¶

Normalize the auto encode flag.

Parameters:: auto_encode (Any, optional) – The auto encode value.
Returns:: The normalized flag.
Return type:: bool

normalize_public_kwargs(payload: Any = None, **kwargs: Any) → Dict[str, Any][source]¶

Normalize public keyword arguments.

Parameters:

payload (Any, optional) – The payload.
**kwargs (Any) – Additional keyword arguments.

Returns:

The normalized kwargs.

Return type:

Dict[str, Any]

property cfg: Any¶

Configuration property.

Returns:: The configuration.
Return type:: Any