Add instrumental-variable LATE example + regression test (#346)

[daimon-pymclabs]

Summary

Closes #346 (part of the IV epic #343). Adds a worked instrumental-variable example and a regression test, demonstrating that pathmc already estimates a continuous-outcome IV model with zero API change through the ~~ correlated-residual operator.

The example reproduces the non-compliance / LATE example from Matheus Facure's Causal Inference for the Brave and True and its PyMC counterpart by Juan Orduz: a randomized push-notification campaign where assignment is random but delivery is not, so engaged customers both receive more pushes and buy more.

The IV spec

spec = """
push_delivered  ~ push_assigned      # first stage (relevance)
in_app_purchase ~ push_delivered     # structural eq — instrument omitted (exclusion)
push_delivered ~~ in_app_purchase    # unobserved-confounder endogeneity
"""
model = pathmc.model(spec, data=df); model.fit()

The ~~ block compiles the two equations into a joint MvNormal with an LKJCholeskyCov residual covariance — the Bayesian limited-information IV structure. The residual correlation soaks up the unobserved engagement confounder; the structural coefficient on push_delivered recovers the LATE.

What the example covers

• What an IV is — relevance, exclusion, exogeneity — and why those last two are untestable assumptions.
• Why it's needed here — non-compliance makes treatment-received endogenous; naive OLS is biased ~2× upward.
• How to implement it in pathmc — the spec mapping, model.graph() / equations(), the PyMC plate, recovery vs. the Wald estimator, the residual-correlation diagnostic, and a do() counterfactual.
• An honest note that is_identifiable is backdoor-only today (false negative for IV), pointing at IV-aware identification: instrument detection & validation #344.

On simulated data with a known true effect, the IV posterior brackets the truth and the frequentist Wald estimate while naive OLS sits far outside the interval.

Regression test

tests/test_instrumental_variable.py — fixed-seed confounded system with a valid instrument; asserts naive OLS is biased, the IV posterior recovers the true effect, beats naive OLS, and yields a positive endogeneity correlation. Robust at the suite's fast-sampling cap.

🤖 Generated with Claude Code