Causal XAI (intervention-based biology)

[breimanntools]

🔄 Revisit — resolve scope before coding. Research-scoped. Causal XAI relies on
DoWhy / causal-learn / EconML / gCastle — heavy deps belonging downstream. Confirm
the downstream home and a research plan before any code lands.

Problem

Current explanations are correlation-based: "feature X is associated with function"
does not tell a protein engineer whether changing X causes the functional
change. Without causal structure and intervention simulation, AAanalysis cannot
support "mutation at position X causes loss of function" claims.

Goal

Decide and document the downstream home (ProtXplain #26 / pro) for causal
discovery and inference over CPP features, and deliver one scoped, validated causal
slice there — core will not gain DoWhy/causal-learn/EconML/gCastle.

Requirements

• Implement causal discovery (causal-learn, gCastle)
• Build causal graphs: feature → mechanism → function
• Apply causal inference (DoWhy, EconML)
• Simulate interventions (mutations → prediction changes)
• Estimate causal effects of CPP features

KPIs / Acceptance criteria

• Decision gate: confirm causal XAI lives in ProtXplain / behind the pro
  extra (recorded as an ADR) before code lands — no new core dep.
• ≥1 causal-effect estimation method implemented behind the downstream/pro
  boundary, producing per-CPP-feature causal-effect estimates.
• Validated on a controlled DOM_GSEC-derived intervention: a simulated
  mutation that perturbs a known driver feature produces a prediction change of
  the expected sign, reproducibly for a fixed random_state (binary pass/fail).
• Covered by ≥1 unit test and an example notebook that runs under the nbmake
  CI gate.

Scope / non-goals

• Not in core: DoWhy/causal-learn/EconML/gCastle are heavy research deps. Per
  pro-core-boundary.md + sharp-edges, causal XAI belongs in ProtXplain (Prepare AAanalysis interface for ProtXplain integration #26) or
  the pro extra, gated via missing_feature_stub.
• Research-scoped: identifiability assumptions must be stated; do not promise
  general causal guarantees. Start with intervention simulation (mutation →
  prediction delta), which needs no causal-graph dep, as the smallest validatable
  slice.

Dependencies

• relates Prepare AAanalysis interface for ProtXplain integration #26 (ProtXplain owns DoWhy/causal-learn); relates protein-design (AAMut/SeqMut)
  for intervention simulation
• new ADR for the causal-XAI downstream placement

Standards checklist

• Frontend/backend split honored; validation block; backend trusts frontend
• CONFIRM-FIRST: __init__.py re-export + pro gating (missing_feature_stub)
• numpydoc docstring (named Returns, per-method Examples include)
• tests (unit; intervention-sign, seed-stable); reproducibility (random_state)
• no print() (use ut.print_out); bare ValueError/RuntimeError;
  no aaanalysis._utils.* imports outside utils.py