Explanation retrieval

Instructions for retrieving factual and alternative rules

Overview

  • The FactualExplanation and AlternativeExplanation classes expose simple retrieval helpers to make rule inspection easy for users and automated agents.

API methods

  • get_rule_by_index(index: int) -> dict — Return a single normalized rule by zero-based index. Raises IndexError when out of range.

  • get_rules_by_feature(feature: str) -> list[dict] — Return all normalized rules that mention the given feature name. Raises KeyError when no match.

  • list_rules() -> list[dict] — Return all rules in normalized form.

Factual rule schema (returned dict)

  • index (int)

  • feature (str) — human-readable feature name

  • condition (str) — textual condition, e.g. “age > 50”

  • weight (float)

  • uncertainty_interval (tuple|dict) — interval for the weight (lower/upper)

  • optional: support

Alternative rule schema (returned dict)

  • index (int)

  • feature (str)

  • condition (str)

  • alternative_prediction (any) — prediction under the alternative condition

  • uncertainty_interval (tuple|dict) — interval for the alternative prediction

Usage examples

  • By index:

    expl = my_calibrated_explanations.explanations[0]  # instance-level explanation
factual = expl.factual  # a FactualExplanation
rule = factual.get_rule_by_index(0)

  • By feature name:

    alternatives = expl.alternative.get_rules_by_feature("age")

Filtering rules by size (filter_rule_sizes)

When you add conjunctive rules (for example via add_conjunctions(...)), rules can have different sizes:

  • Size 1: an atomic (single-feature) rule.

  • Size k > 1: a conjunctive rule built from k atomic conditions.

You can filter an explanation down to only the sizes you care about using filter_rule_sizes(...).

How rule size is computed

Rule size is inferred from the rule’s feature payload:

  • If feature is a scalar (e.g. 0 or "age"), the size is 1.

  • If feature is a sequence/array (e.g. [0, 1]), the size is the number of elements.

API

filter_rule_sizes exists on both a single instance-level explanation and on the collection:

  • CalibratedExplanation.filter_rule_sizes(rule_sizes=..., size_range=..., copy=True)

  • CalibratedExplanations.filter_rule_sizes(rule_sizes=..., size_range=..., copy=True)

Exactly one of the following must be provided:

  • rule_sizes: an int or a sequence of int sizes to keep.

  • size_range=(min_size, max_size): an inclusive range of sizes to keep.

If copy=True (default), the original object is not mutated.

Examples

Keep only atomic rules (exclude conjunctions):

expl = calibrated_explanations[0]
atomic_only = expl.filter_rule_sizes(rule_sizes=1)

Keep only conjunctions of size 2 and 3:

expl = calibrated_explanations[0].add_conjunctions(max_rule_size=3)
pair_and_triple = expl.filter_rule_sizes(rule_sizes=[2, 3])

Keep a size range (inclusive):

expl = calibrated_explanations[0].add_conjunctions(max_rule_size=4)
up_to_triples = expl.filter_rule_sizes(size_range=(1, 3))

Filter the entire collection in one call:

filtered = calibrated_explanations.filter_rule_sizes(rule_sizes=[1, 2])

Filtering rules by features (filter_features)

You can filter explanations to include or exclude rules based on the features they contain, either by feature name (str) or index (int). This is useful for focusing on explanations that involve certain features or avoiding others.

API

filter_features exists on both a single instance-level explanation and on the collection:

  • CalibratedExplanation.filter_features(exclude_features=..., copy=True)

  • CalibratedExplanation.filter_features(include_features=..., copy=True)

  • CalibratedExplanations.filter_features(exclude_features=..., copy=True)

  • CalibratedExplanations.filter_features(include_features=..., copy=True)

Exactly one of exclude_features or include_features must be provided. Both parameters accept:

  • A single str or int

  • A sequence (list/tuple) of str and/or int

If copy=True (default), the original object is not mutated.

Examples

Exclude rules containing feature “age” (by name):

expl = calibrated_explanations[0]
filtered = expl.filter_features(exclude_features="age")

Include only rules containing features by index or mixed:

filtered = expl.filter_features(include_features=[0, "income"])

Filter the entire collection to include only rules with “age” or “gender”:

filtered_collection = calibrated_explanations.filter_features(include_features=["age", "gender"])

Notes for conjunctive rules

For conjunctive rules (rules with multiple features combined):

  • When excluding: a rule is excluded if it contains ANY of the specified features

  • When including: a rule is included if it contains ANY of the specified features

For disjunctive rules (single feature):

  • When excluding: a rule is excluded if it matches the specified feature

  • When including: a rule is included if it matches the specified feature

Notes for agents

  • Prefer explicit exceptions for control flow: use try/except around get_rule_by_index and get_rules_by_feature.

  • If non-raising behavior is desired, call list_rules() and filter in the agent.

Change log

  • Added retrieval helpers for FactualExplanation and AlternativeExplanation to simplify programmatic access to rules.