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.
`as_lime`([num_features_to_show])	Transform the explanations into LIME explanation objects.
`as_shap`()	Transform the explanations into a SHAP explanation object.
`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_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.
`legacy_payload`(exp)	Public wrapper to obtain the legacy payload for an explanation.
`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.

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

Return a copy with only semi-explanations.

Semi-explanations are individual rules with lower 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 semi-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 semi-factual or semi-potential explanations.

Return type:

AlternativeExplanations

Notes

Semi-explanations are only available for AlternativeExplanation explanations.

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

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

Return a copy with only counter-explanations.

Counter-explanations are individual rules that do not 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 counter-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 counter-factual or counter-potential explanations.

Return type:

AlternativeExplanations

Notes

Counter-explanations are only available for AlternativeExplanation explanations.

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

ensured_explanations(include_potential=True, copy=True)[source]¶

Return a copy with only ensured explanations.

Ensured explanations are individual rules that have a narrower uncertainty interval.

Parameters:

include_potential (bool, default=True) – Determines whether to include potential explanations in the ensured 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 ensured explanations.

Return type:

AlternativeExplanations

ensured(include_potential=True, copy=True)[source]¶: Shorthand delegator for ensured_explanations().

pareto_explanations(include_potential: bool = True, copy: bool = True, *, pareto_cost: str = 'uncertainty_width')[source]¶

Return a copy with only output-envelope Pareto alternatives.

Parameters:

include_potential (bool, default=True) – Determines whether to include potential explanations before extracting the Pareto frontier.
copy (bool, default=True) – Determines whether to return a copy of the explanations or modify them in place.
pareto_cost (str, default="uncertainty_width") – The Pareto cost dimension minimized along the output axis.

Returns:

A new AlternativeExplanations object containing Pareto-front alternatives.

Return type:

AlternativeExplanations

pareto(include_potential: bool = True, copy: bool = True, *, pareto_cost: str = 'uncertainty_width')[source]¶: Shorthand delegator for pareto_explanations().