calibrated_explanations.explanations.AlternativeExplanations¶

class calibrated_explanations.explanations.AlternativeExplanations(calibrated_explainer, x, y_threshold, bins, features_to_ignore=None, *, condition_source: str = 'prediction')[source]¶

Bases: CalibratedExplanations

Initialize the explanation collection for a calibrated explainer.

Parameters:

calibrated_explainer (CalibratedExplainer) – The calibrated explainer object.
x (array-like) – The test data.
y_threshold (float or tuple) – The threshold for regression explanations.
bins (array-like) – The bins for conditional explanations.

Attributes:

class_labels: Return class labels for classification explanations if available.
feature_names: Return cached feature names sourced from the underlying explainer.
is_one_sided: Check if the explanations are one-sided.
is_probabilistic_regression: Check if the explanations use probabilistic regression (thresholded).
lower: Return cached lower bounds for regression prediction intervals.
predict: Return the scalar prediction for every explanation.
prediction_interval: Return the prediction intervals for each explanation.
predictions: Vector of scalar predictions for the explained instances (cached).
probabilities: Return cached probability matrices for classification explanations.
upper: Return cached upper bounds for regression prediction intervals.

Methods

`add_conjunctions`([n_top_features, max_rule_size])	Add conjunctive rules to the explanations.
`build_rules_payload`()	Delegate payload materialisation to each stored explanation.
`collection_metadata`()	Public wrapper around internal collection metadata helper.
`copy`([deep])	Return a copy of the collection.
`counter`([only_ensured, include_potential, copy])	Shorthand delegator for `counter_explanations()`.
`counter_explanations`([only_ensured, ...])	Return a copy with only counter-explanations.
`ensured`([include_potential, copy])	Shorthand delegator for `ensured_explanations()`.
`ensured_explanations`([include_potential, copy])	Return a copy with only ensured explanations.
`filter_by_target_confidence`([confidence])	Return a new collection keeping only intervals with a singleton conformal prediction set.
`filter_features`(*[, exclude_features, ...])	Filter rules by feature inclusion or exclusion across all explanations.
`filter_rule_sizes`(*[, rule_sizes, ...])	Filter rules by conjunctive rule size across the collection.
`finalize`(binned, feature_weights, ...[, ...])	Finalize the explanation by adding the binned data and the feature weights.
`finalize_fast`(feature_weights, ...[, ...])	Finalize the explanation by adding the binned data and the feature weights.
`from_batch`(batch)	Reconstruct a collection from an `ExplanationBatch`.
`from_collection`(collection)	Create an AlternativeExplanations instance from an existing collection.
`from_json`(payload)	Materialise domain explanations from a `to_json()` payload.
`get_confidence`()	Return the confidence level of the explanations.
`get_explainer`()	Return the underlying `CalibratedExplainer` instance.
`get_guarded_audit`()	Return guarded interval audit for the collection and each instance.
`get_high_percentile`()	Return the high percentile of the explanations.
`get_low_percentile`()	Return the low percentile of the explanations.
`get_rules`()	Return the materialised rule payload for each explanation in the collection.
`is_alternative`()	Return True when the collection represents an alternative explanation workflow.
`narrate`(args, *kwargs)	Alias for `to_narrative()`.
`pareto`([include_potential, copy, pareto_cost])	Shorthand delegator for `pareto_explanations()`.
`pareto_explanations`([include_potential, ...])	Return a copy with only output-envelope Pareto alternatives.
`plot`([index, filter_top, show, filename, ...])	Plot explanations for a given instance, with the option to show or save the plots.
`remove_conjunctions`()	Remove any conjunctive rules.
`reset`()	Reset the explanations to their original state.
`semi`([only_ensured, include_potential, copy])	Shorthand delegator for `semi_explanations()`.
`semi_explanations`([only_ensured, ...])	Return a copy with only semi-explanations.
`super`([only_ensured, include_potential, copy])	Shorthand delegator for `super_explanations()`.
`super_explanations`([only_ensured, ...])	Return a copy with only super-explanations.
`to_batch`()	Serialise the collection into an `ExplanationBatch`.
`to_dataframe`(args, *kwargs)	Return the narrative output as a pandas DataFrame.
`to_json`(*[, include_version])	Return a JSON-friendly payload describing this collection.
`to_json_stream`(*[, chunk_size, format])	Stream the collection as JSON.
`to_narrative`([template_path, ...])	Generate narrative explanations for the collection.

super_explanations(only_ensured=False, include_potential=True, copy=True)[source]¶

Return a copy with only super-explanations.

Super-explanations are individual rules with higher probability that support the predicted class.

Parameters:

only_ensured (bool, default=False) – Determines whether to return only ensured explanations.
include_potential (bool, default=True) – Determines whether to include potential explanations in the super-explanations.
copy (bool, default=True) – Determines whether to return a copy of the explanations or modify them in place.

Returns:

A new AlternativeExplanations object containing only super-factual or super-potential explanations.

Return type:

AlternativeExplanations

Notes

Super-explanations are only available for AlternativeExplanation explanations.

super(only_ensured=False, include_potential=True, copy=True)[source]¶: Shorthand delegator for super_explanations().

classmethod from_collection(collection: CalibratedExplanations)[source]¶

Create an AlternativeExplanations instance from an existing collection.

This provides a safe public API for tests and callers that previously constructed an instance via low-level hacks like __new__ and direct __dict__ assignment.

filter_by_target_confidence(confidence: float = 0.8) → AlternativeExplanations[source]¶

Return a new collection keeping only intervals with a singleton conformal prediction set.

Applies conformal classification to each alternative interval using the hinge non-conformity function (NCF) and the calibration set to compute proper conformal p-values for each class:

α₁ = 1 − predict (NCF for class 1: 1 − P(class 1 | x))
α₀ = predict (NCF for class 0: 1 − P(class 0 | x) = predict)
p_val_k = (|{i : α_cal_i ≥ α_k}| + 1) / (n_cal + 1) (conformal p-value)
epsilon = 1 - confidence (conformal significance level)

The calibration NCF scores are computed as α_cal[i] = 1 − P(true_class_i | x_cal_i), i.e. 1 − proba_cal for positive-class samples and proba_cal for negative-class samples.

An interval is retained only when exactly one class has p_val_k >= epsilon — i.e. the conformal prediction set is a singleton. When both p-values exceed the threshold (ambiguity rejection) or neither does (novelty rejection), the interval is discarded.

Parameters:

confidence (float, default=0.8) – Conformal confidence level in [0.0, 1.0]. Maps to significance epsilon = 1 - confidence. Higher values tighten the filter by widening the ambiguity zone.

Returns:

A new collection of the same concrete type as self containing only the intervals whose conformal prediction set is a singleton at the given confidence level. The original is not mutated.

Return type:

AlternativeExplanations

Raises:

ValidationError – If confidence is outside [0.0, 1.0].
ValidationError – If the underlying model does not produce probability outputs (is_probabilistic() is False).

Notes

This filter operates at the interval level and complements reject_policy (source-instance-level conformal rejection) and guarded (in-distribution plausibility filter). It answers: “Would acting on this suggested change land in an outcome the model would confidently accept?”

At confidence=1.0 (epsilon=0.0), every class is always in the prediction set, so all intervals are discarded. At confidence=0.0 (epsilon=1.0), only intervals with the most extreme calibration-consistent predictions survive.