ce-alternatives-explore

name	ce-alternatives-explore
description	Generate and interpret CE alternative and counterfactual explanations, including ensured filters and alternatives-specific plot workflows.

CE Alternatives Explorer

You are producing alternative calibrated explanations — counterfactual rules that show what feature changes would produce a different prediction.

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.

Load references/alternatives_api_reference.md for the ensured framework, plot styles, ranking controls, and conjunction API.

---

Two Entry Points

Standard path

alternatives = explainer.explore_alternatives(X_query)

Explaining all classes (multiclass)

multi_alts = explainer.explore_alternatives(X_query, multi_labels_enabled=True)

Guarded path (production / unknown distributions — ADR-032)

alternatives = explainer.explore_guarded_alternatives(X_query)

Guarded variant: out-of-distribution instances are flagged rather than silently included. Use in production or when the input distribution is unknown.

---

Threshold Semantics

For classification — change the decision boundary:

alternatives = explainer.explore_alternatives(X_query, threshold=0.7)

For regression — see ce-regression-intervals for full semantics:

alternatives = explainer.explore_alternatives(X_query, threshold=50.0)
alternatives = explainer.explore_alternatives(X_query, threshold=(40.0, 60.0))

---

Output Types

AlternativeExplanations      (collection — returned by explore_alternatives)
   [i] -> AlternativeExplanation  (per-instance)

The prediction dict structure and interval invariant are identical to factual explanations (pred['low'] <= pred['predict'] <= pred['high']), but the direction of the rules is counterfactual (opposing, not supporting).

---

Out of Scope

• Factual / supporting rule generation (see ce-factual-explain).
• Regression interval configuration (see ce-regression-intervals).
• Generic plot / narrative / filter API (see ce-explain-interact).
• Building the pipeline (see ce-pipeline-builder).

Evaluation Checklist

• Correct variant (explore_alternatives vs explore_guarded_alternatives).
• Threshold provided if the user wants boundary-crossing alternatives for regression.
• Ensured-framework filter selected appropriately for the use case.
• only_ensured=True used when narrower-uncertainty alternatives are required.
• include_potential set to True/False per user intent.
• Plot style is "triangular" or "ensured" (not "regular") when showing alternatives in a confidence-uncertainty view.
• rnk_metric="ensured" with appropriate rnk_weight when ranking by output/uncertainty trade-off.
• Interval invariant low <= predict <= high verified on at least one output.