calibrated_explanations.explanations.CalibratedExplanations

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

Bases: object

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.

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

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.

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.
build_rules_payload() → List[Dict[str, Any]][source]

Delegate payload materialisation to each stored explanation.

get_guarded_audit() → Dict[str, Any][source]

Return guarded interval audit for the collection and each instance.

Raises:

ValidationError – If called on a non-guarded explanation collection.

copy(deep=False)[source]

Return a copy of the collection.

Parameters:

deep (bool, default=False) – Determines whether to return a shallow or deep copy.

Returns:

A copy of the collection.

Return type:

CalibratedExplanations

to_batch()[source]

Serialise the collection into an ExplanationBatch.

classmethod from_batch(batch)[source]

Reconstruct a collection from an ExplanationBatch.

to_json(*, include_version: bool = True) → Mapping[str, Any][source]

Return a JSON-friendly payload describing this collection.

The payload wraps each explanation using the schema v1 helpers from calibrated_explanations.serialization and adds collection-level metadata (mode, thresholds, feature names, telemetry snapshot).

Parameters:

include_version – When True (default) the schema_version field is included on the top-level payload as well as on each explanation entry.

to_json_stream(*, chunk_size: int = 256, format: str = 'jsonl')[source]

Stream the collection as JSON.

This generator yields either a JSON Lines stream or chunked JSON arrays.

Parameters:

  • chunk_size – Number of explanations per yielded chunk (for “chunked”) or used only for grouping when format==”chunked”.

  • format – Either "jsonl" (default) for JSON Lines or "chunked" for chunked JSON arrays.

Yields:

str – UTF-8 JSON fragments (one per yield). The first yielded fragment is a small metadata object describing the collection and the export telemetry.

classmethod from_json(payload: Mapping[str, Any]) → ExportedExplanationCollection[source]

Materialise domain explanations from a to_json() payload.

collection_metadata() → Mapping[str, Any][source]

Public wrapper around internal collection metadata helper.

legacy_payload(exp) → Mapping[str, Any][source]

Public wrapper to obtain the legacy payload for an explanation.

property prediction_interval: List[Tuple[float | None, float | None]]

Return the prediction intervals for each explanation.

Returns:

A list of tuples containing (low, high) values of the prediction interval.

Return type:

list of tuples

property predict: List[Any]

Return the scalar prediction for every explanation.

Returns:

A list of prediction value.

Return type:

list

property feature_names

Return cached feature names sourced from the underlying explainer.

property class_labels

Return class labels for classification explanations if available.

property predictions

Vector of scalar predictions for the explained instances (cached).

property probabilities

Return cached probability matrices for classification explanations.

property lower

Return cached lower bounds for regression prediction intervals.

property upper

Return cached upper bounds for regression prediction intervals.

property is_probabilistic_regression: bool

Check if the explanations use probabilistic regression (thresholded).

Probabilistic regression and thresholded regression are synonymous terms. See ADR-021 for terminology guidance.

property is_one_sided: bool

Check if the explanations are one-sided.

get_confidence() → float[source]

Return the confidence level of the explanations.

This method calculates the confidence interval for regression tasks by determining the distance between the lower and upper percentiles. By default, these percentiles are set to 5 and 95.

Returns:

The difference between the high and low percentiles, representing the confidence interval.

Return type:

float

Notes

  • This method is only applicable to regression tasks.

  • If the high percentile is infinite, the confidence is calculated as 100 - low_percentile.

  • If the low percentile is infinite, the confidence is calculated as high_percentile.

get_low_percentile() → float[source]

Return the low percentile of the explanations.

This method returns the first element of the low_high_percentiles attribute, which represents the lower bound of the percentile range for the explanation.

Returns:

The low percentile value of the explanation.

Return type:

float

get_high_percentile() → float[source]

Return the high percentile of the explanations.

Returns:

The high percentile value of the explanation.

Return type:

float

finalize(binned, feature_weights, feature_predict, prediction, instance_time=None, total_time=None) → CalibratedExplanations[source]

Finalize the explanation by adding the binned data and the feature weights.

Parameters:

  • binned (array-like) – The binned data for the features.

  • feature_weights (array-like) – The weights of the features.

  • feature_predict (array-like) – The predicted values for the features.

  • prediction (array-like) – The prediction values.

  • instance_time (array-like, optional) – The time taken to explain each instance, by default None.

  • total_time (float, optional) – The total time taken to explain all instances, by default None.

Returns:

self – Returns the instance of the class with explanations finalized.

Return type:

object

finalize_fast(feature_weights, feature_predict, prediction, instance_time=None, total_time=None) → None[source]

Finalize the explanation by adding the binned data and the feature weights.

Parameters:

  • binned (array-like) – The binned data for the features.

  • feature_weights (array-like) – The weights of the features.

  • feature_predict (array-like) – The predicted values for the features.

  • prediction (array-like) – The prediction values.

  • instance_time (array-like, optional) – The time taken to explain each instance, by default None.

  • total_time (float, optional) – The total time taken to explain all instances, by default None.

Notes

  • This method iterates over the test instances and creates a FastExplanation object for each instance.

  • The FastExplanation object is initialized with the provided feature weights, predictions, and other relevant data.

  • The explanation time for each instance is recorded if instance_time is provided.

  • The total explanation time is calculated if total_time is provided.

get_explainer()[source]

Return the underlying CalibratedExplainer instance.

get_rules()[source]

Return the materialised rule payload for each explanation in the collection.

add_conjunctions(n_top_features=5, max_rule_size=2, **kwargs)[source]

Add conjunctive rules to the explanations.

The conjunctive rules are added to the conjunctive_rules attribute of the CalibratedExplanations object.

Parameters:

  • n_top_features (int, optional) – The number of most important factual rules to try to combine into conjunctive rules. Defaults to 5.

  • max_rule_size (int, optional) – The maximum size of the conjunctions. Defaults to 2 (meaning rule_one and rule_two).

Returns:

Returns a self reference, to allow for method chaining.

Return type:

CalibratedExplanations

reset()[source]

Reset the explanations to their original state.

remove_conjunctions()[source]

Remove any conjunctive rules.

filter_rule_sizes(*, rule_sizes: Any | None = None, size_range: Tuple[int, int] | None = None, copy: bool = True)[source]

Filter rules by conjunctive rule size across the collection.

filter_features(*, exclude_features=None, include_features=None, copy: bool = True) → CalibratedExplanations[source]

Filter rules by feature inclusion or exclusion across all explanations.

Parameters:

  • exclude_features (str, int, or sequence of str/int, optional) – Feature names (str) or indices (int) to exclude. Rules containing any of these features will be removed.

  • include_features (str, int, or sequence of str/int, optional) – Feature names (str) or indices (int) to include. Only rules containing these features will be kept.

  • copy (bool, default=True) – If True, return a filtered copy without mutating the original.

Returns:

Filtered explanations object.

Return type:

CalibratedExplanations

is_alternative()[source]

Return True when the collection represents an alternative explanation workflow.

plot(index=None, filter_top=10, show=True, filename='', uncertainty=False, style='regular', rnk_metric=None, rnk_weight=0.5, style_override=None, **kwargs)[source]

Plot explanations for a given instance, with the option to show or save the plots.

Parameters:

  • index (int or None, default=None) – The index of the instance for which you want to plot the explanation. If None, the function will plot all the explanations.

  • filter_top (int or None, default=10) – The number of top features to display in the plot. If set to None, all the features will be shown.

  • show (bool, default=True) – Determines whether the plots should be displayed immediately after they are generated. Suitable to set to False when saving the plots to a file.

  • filename (str, default='') – The full path and filename of the plot image file that will be saved. If empty, the plot will not be saved.

  • uncertainty (bool, default=False) – Determines whether to include uncertainty information in the plots.

  • style (str, default='regular') – The style of the plot. Supported styles are ‘regular’ and ‘triangular’. Use style='ensured' as an alias for style='triangular'.

  • rnk_metric (str, default=None) – The metric used to rank the features. Supported metrics are ‘ensured’, ‘feature_weight’, and ‘uncertainty’. If None, the default from the explanation class is used.

  • rnk_weight (float, default=0.5) – The weight of the uncertainty in the ranking. Used with the ‘ensured’ ranking metric.

Return type:

None

See also

FactualExplanation.plot

Refer to the docstring for plot in FactualExplanation for details on default ranking (‘feature_weight’).

AlternativeExplanation.plot

Refer to the docstring for plot in AlternativeExplanation for details on default ranking (‘ensured’).

FastExplanation.plot

Refer to the docstring for plot in FastExplanation for details on default ranking (‘feature_weight’).

to_narrative(template_path=None, expertise_level=('beginner', 'advanced'), output_format='dataframe', conjunction_separator=' AND ', align_weights=True, **kwargs)[source]

Generate narrative explanations for the collection.

This method provides a clean API for generating human-readable narratives from calibrated explanations using customizable templates.

Parameters:

  • template_path (str or None, default=None) – Path to the narrative template file (YAML or JSON). If None or the file doesn’t exist, the built-in default template is used.

  • expertise_level (str or tuple of str, default=("beginner", "advanced")) – The expertise level(s) for narrative generation. Can be a single level or a tuple of levels. Valid values: “beginner”, “intermediate”, “advanced”.

  • output_format (str, default="dataframe") – Output format. Valid values: “dataframe”, “text”, “html”, “dict”, “markdown”.

  • conjunction_separator (str, default=" AND ") – Separator to use for conjunctive rules. Conjunctive rules combine multiple feature conditions (e.g., “Glucose > 120 AND BMI > 28”).

  • align_weights (bool, default=True) – If True, vertically align weight columns in the narrative output. If False, no alignment is applied.

  • **kwargs (dict) – Additional keyword arguments passed to the narrative plugin.

Returns:

The generated narratives in the requested format: - “dataframe”: pandas DataFrame with columns for each expertise level - “text”: formatted text string with all narratives - “html”: HTML table with all narratives - “dict”: list of dictionaries, one per instance

Return type:

pd.DataFrame or str or list of dict

Raises:

  • FileNotFoundError – If the template file is not found and no default is available.

  • ValueError – If an invalid expertise level or output format is specified.

  • ImportError – If pandas is not available and output_format=”dataframe” is requested.

Examples

>>> from calibrated_explanations import CalibratedExplainer
>>> explainer = CalibratedExplainer(model, x_train, y_train)
>>> explanations = explainer.explain_factual(x_test)
>>> narratives = explanations.to_narrative(
...     expertise_level=("beginner", "advanced"),
...     output_format="dataframe"
... )
>>> print(narratives)

See also

plot()

Plot explanations with various visual styles.

to_dataframe(*args, **kwargs)[source]

Return the narrative output as a pandas DataFrame.

Call to_narrative() with output_format='dataframe' and return the resulting DataFrame. Accepts the same arguments as to_narrative().

as_lime(num_features_to_show=None)[source]

Transform the explanations into LIME explanation objects.

Returns:

List of LIME explanation objects with the same values as the CalibratedExplanations.

Return type:

list of lime.Explanation

as_shap()[source]

Transform the explanations into a SHAP explanation object.

Returns:

SHAP explanation object with the same values as the explanation.

Return type:

shap.Explanation