CE Factual Explain

You are producing factual calibrated explanations rules that explain why the current prediction is what it is.

The CE-First pipeline (fit calibrate) is a prerequisite. If not in place, invoke ce-pipeline-builder first.

For all post-generation interaction (plot, narrative, add_conjunctions, filter_rule_sizes, filter_features) see ce-explain-interact.

---

Two Entry Points

Standard path

explanations = explainer.explain_factual(X_query)

Explaining all classes (multiclass)

# Returns a MultiClassCalibratedExplanations for all class labels
multi_exps = explainer.explain_factual(X_query, multi_labels_enabled=True)

Guarded path (production / unknown input distribution)

from calibrated_explanations.explanations.guarded_options import GuardedOptions
explanations = explainer.explain_factual(X_query, guarded_options=GuardedOptions())

See references/adr-032-guarded-semantics.md for the full guarded semantics. Use the guarded variant when:

• Processing user-submitted data with unknown distribution.
• Building API endpoints that accept arbitrary inputs.
• Calibration set coverage is limited.

API note: explain_guarded_factual(...) was REMOVED in v0.11.3. The guarded=True boolean kwarg was removed in v0.11.5. Always use guarded_options=GuardedOptions().

---

When to Use Standard vs Guarded

Scenario	API
Training / development / research	explain_factual
Production endpoint	explain_factual(..., guarded_options=GuardedOptions())
Unknown input distribution	explain_factual(..., guarded_options=GuardedOptions())
Limited calibration set	explain_factual(..., guarded_options=GuardedOptions())

---

Output Type: FactualExplanation

CalibratedExplanations        (collection)
   [i]  FactualExplanation  (per-instance)

Access the i-th instance: explanations[i]

---

Prediction Dict Structure

exp = explanations[i]
pred = exp.prediction

pred['predict']    # point prediction (probability for classification, y or P(yt) for regression)
pred['low']        # lower bound of calibrated interval
pred['high']       # upper bound of calibrated interval

# Classification only:
pred.get('__full_probabilities__')   # all-class probability cube (Venn-Abers)

Interval invariant (ADR-021 §4 must always hold):

assert pred['low'] <= pred['predict'] <= pred['high']

---

Factual-Specific Rule Access

exp = explanations[i]

# All atomic rules as a list of normalised dicts
rules_list = exp.list_rules()

# Rules for a specific feature
rules_for_age = exp.get_rules_by_feature("age")

# Raw rule payload (dict with 'rule', 'value', 'feature', 'weight', etc.)
rules_dict = exp.get_rules()

---

Factual Conjunctions (Quick Reference)

The primary parameter is max_rule_size; n_top_features limits the search space (optional speed control):

explanations[i].add_conjunctions(max_rule_size=2)          # pairs (default)
explanations[i].add_conjunctions(max_rule_size=3)          # triples
explanations[i].add_conjunctions(max_rule_size=2, n_top_features=5)  # limit search

For the full conjunction + filtering API, see ce-explain-interact.

---

Factual Plot (Quick Reference)

Factual explanations default to rnk_metric="feature_weight" and style="regular":

explanations[i].plot(filter_top=10)
explanations[i].plot(filter_top=5, uncertainty=True)   # show uncertainty bands

• Supported styles for FactualExplanation: 'regular' only.
• Default rnk_metric for factuals: "feature_weight" (differs from alternatives default "ensured").

For the full plot API, see ce-explain-interact.

---

Factual Narrative (Quick Reference)

text = explanations[i].to_narrative(
    expertise_level="beginner",   # or "advanced" or ("beginner", "advanced")
    output_format="text",
)

For the full narrative API including template_path, output_format, and conjunction_separator, see ce-explain-interact.

---

Guarded Audit API

When using explain_factual(..., guarded_options=GuardedOptions()), a dedicated audit is available:

audit = explanations.get_guarded_audit()
# {
#   "intervals_removed_guard": int,   # rules removed because conforming == False
#   "interval_records": [...],        # per-rule details
# }

---

Out of Scope

• Exploring counterfactual / alternative predictions (see ce-alternatives-explore).
• Regression interval configuration (threshold= / low_high_percentiles=) (see ce-regression-intervals).
• Generic plot / narrative / filter API (see ce-explain-interact).
• Building the pipeline (see ce-pipeline-builder).

Evaluation Checklist

• Correct entry point chosen (explain_factual vs explain_factual(..., guarded_options=GuardedOptions())).
• Interval invariant low predict high verified for at least one output.
• list_rules() / get_rules_by_feature() used for rule introspection (not raw dict keys).
• Guarded audit called if guarded_options=GuardedOptions() was used.
• No uncalibrated output returned.