Add observational ITE benchmark DGP + all-CI demo notebook

[oduerr]

Adds a confounded-treatment individual-treatment-effect (ITE) benchmark to
the simulation portfolio (like VACA/CAREFL) plus a demo notebook training an
all-CI TRAM-DAG that recovers per-individual effects.

DGP ported from code/ITE_observational_simulation.R in
mikekr97/MA_Mike (the master's-thesis repo).

The DGP — simulations.ITEObservational (ite-observational)

A 7-variable mediation SCM, topological order X1 X2 X3 Tr X5 X6 Y:

X1, X2, X3 ~ N(0, Σ)            correlated, ρ=0.1
Tr ~ Bernoulli(sigmoid(0.5 - 0.5·X1 + 0.3·X2))      # treatment confounded by X1,X2
X5 :  2.5·X5 = logit(U5) - 0.8·Tr                    # Colr mediator
X6 :  4·X6   = logit(U6) + 0.5·X5                    # Colr mediator
Y  :  h_y(Y) = logit(U7) - [1.5·Tr + X·β + (-0.9·X2 + 0.7·X3)·Tr]

with β = (-0.5, 0.5, 0.2, -0.6, 0.4) on (X1,X2,X3,X5,X6) and a nonlinear
baseline h_y(y) = tan(y/2)/0.2 on [-2,2] (slope-matched linear tails, so
h_y⁻¹(z) = 2·atan(0.2·z) in the core). All latents are logistic → the DGP sits
inside the flow's family; the shapes and the (X2,X3)·Tr interaction are what
must be learned.

Treatment flows through a direct path and a mediated path X5 → X6 → Y, and
the interaction makes effects heterogeneous. Four scenarios toggle
main/interaction effects (scenario=1..4); scenario 1 (main + interaction)
is the frozen/featured dataset. The generator exposes per-individual ground
truth — ITE_true (observed latent) and ITE_median (median latent) — and the
Monte-Carlo ATE. Frozen data/ite-observational/{obs.csv,truth.json} + CLI,
mirroring the other portfolio DGPs.

The demo — notebooks/ite_observational.py

An all-CI S-learner (every child node a joint complex intercept over its
parents) fitted once on 20k observational rows, then queried per individual:

1. the naive observational contrast is biased (−0.671 vs true ATE −0.576) —
   confounding by X1,X2;
2. L1 sanity: fitted marginals match the data;
3. L3 ITEs via abduction + do(Tr=0/1) (recomputing the mediators under each
   counterfactual treatment) — recovers the true ITEs at r ≈ 0.99, MAE 0.045,
   ATE −0.575 vs true −0.573;
4. the learned heterogeneity (effect modified by X2, X3) matches the DGP.

Tests — tests/test_ite_observational.py

Generator pinning (reproducibility, frozen-CSV contract, the TRAM
latent identities as KS-logistic, h_y round-trip, treatment rate, ITE_median
definition, null-scenario sanity, ATE pin) — 10 fast tests — plus a slow
all-CI fit/ITE-recovery test (ATE within 0.05, ITE corr > 0.8).

uv run pytest tests/test_ite_observational.py tests/test_paper_dgps.py -q -m "not slow"
→ 35 passed. Notebook verified headless end-to-end (figure attached in the
description above is reproduced by the .py).

CHANGELOG 0.3.1 + README/notebooks docs updated.

🤖 Generated with Claude Code