XAI evaluation framework (scientific validation)

[breimanntools]

🔄 Revisit — resolve scope before coding. A scoped fidelity/stability metrics
slice can live in core (aaanalysis/metrics/); cross-method DL-XAI benchmarking is
downstream. Agree the split first.

Problem

Explanation quality is asserted, not measured: there is no fidelity or stability
metric to say an explanation is faithful to the model or robust to perturbation,
so AAanalysis cannot benchmark XAI methods or build scientific credibility for its
explanations.

Goal

Land an in-core XAI evaluation metrics slice — fidelity (explanation-vs-model
consistency) and stability (importance robustness under perturbation) — in
aaanalysis/metrics/ using existing deps, and route cross-method DL-XAI
benchmarking to ProtXplain (#26).

Requirements

Metrics slice (in-core)

• Implement fidelity metrics (prediction consistency)
• Implement stability metrics (feature robustness)
• Perform perturbation tests
• Validate against known motifs / functional regions

Cross-method benchmarking (→ ProtXplain / pro)

• Compare methods (CPP vs SHAP vs DL-XAI)

KPIs / Acceptance criteria

• Decision gate: metrics-slice (core) vs DL-XAI benchmarking (ProtXplain)
  boundary agreed and recorded before code lands.
• ≥1 fidelity metric AND ≥1 stability metric implemented in
  aaanalysis/metrics/ with 0 new required dependencies, each returning a
  scalar score.
• Validated on DOM_GSEC: metrics are deterministic for a fixed random_state
  and a deliberately degraded explanation scores strictly worse than the true one
  (binary pass/fail).
• Covered by ≥1 unit test (golden values) and an example notebook that runs
  under the nbmake CI gate.

Scope / non-goals

• In core: fidelity + stability metrics + perturbation tests in
  aaanalysis/metrics/ (NumPy/sklearn only) — they fit the existing comp_*
  metrics family with no new dep.
• Not in core / → ProtXplain (Prepare AAanalysis interface for ProtXplain integration #26) or pro: head-to-head benchmarking that
  must run SHAP/DL-XAI methods (those deps live in pro/downstream per
  pro-core-boundary.md + sharp-edges). Core supplies the metrics; downstream runs
  the bake-off.

Dependencies

• relates Prepare AAanalysis interface for ProtXplain integration #26 (ProtXplain owns cross-method benchmarking incl. DL-XAI)
• new ADR for the evaluation core/downstream boundary

Standards checklist

• Frontend/backend split honored; validation block; backend trusts frontend
• CONFIRM-FIRST: new public comp_* symbol → re-export in __init__.py (confirm)
• numpydoc docstring (named Returns, per-method Examples include)
• tests (unit; golden metric values, degraded-vs-true); reproducibility contract
• no print() (use ut.print_out); bare ValueError/RuntimeError;
  no aaanalysis._utils.* imports outside utils.py