Instrumental variables and 2SLS in Python¶
Short answer. sp.ivreg("y ~ (d ~ z) + controls", data=df) runs two-stage
least squares and prints the first-stage F, partial R² and a Hausman test with
the coefficients. When the first stage is not strong, add a
weak-instrument-robust interval with sp.anderson_rubin_ci. On StatsPAI's
cross-language suite sp.ivreg matches R's AER::ivreg and Stata's
ivregress 2sls, small (sp.parity_status("ivreg")).
When this applies¶
- Estimand: with a binary instrument and heterogeneous effects, 2SLS identifies a local average treatment effect for compliers, not the ATE.
- Assumptions: relevance (check the first stage), exclusion (the instrument affects the outcome only through the treatment) and, for the LATE reading, monotonicity. Only relevance can be tested from the data.
- Not the right tool when the instrument plausibly has a direct effect, or
when you have many weak instruments (consider
sp.limlorsp.jive).
Example: returns to schooling (Card 1995)¶
The instrument is growing up near a four-year college (nearc4); the data are
the real NLSYM extract.
import statspai as sp
card = sp.datasets.card_1995()
iv = sp.ivreg("lwage ~ (educ ~ nearc4) + exper + expersq + black + south + smsa",
data=card)
print(iv.summary())
educ 0.1323 0.0492 2.6870 0.0072 0.0358 0.2288
...
First-stage F (educ) : 16.7176
...
Hausman p-value : 0.2149
The IV estimate (0.132) is larger than OLS (0.074) and far less precise. The first-stage F of 16.7 is above the old rule of thumb of 10 but not comfortably so, so report an interval that stays valid under weak instruments:
ar = sp.anderson_rubin_ci(y="lwage", endog="educ", instruments=["nearc4"],
exog=["exper", "expersq", "black", "south", "smsa"],
data=card)
print(ar.summary())
OLS and IV side by side, robust standard errors¶
ols = sp.regress("lwage ~ educ + exper + expersq + black + south + smsa",
data=card, vce="robust")
iv_r = sp.ivreg("lwage ~ (educ ~ nearc4) + exper + expersq + black + south + smsa",
data=card, robust="hc1")
print(sp.regtable([ols, iv_r], model_labels=["OLS", "2SLS"], keep=["educ"]))
With robust="hc1" the first-stage F uses the same robust variance, as
Stata's estat firststage does after vce(robust).
Check before you report¶
- First-stage strength (F, effective F via
sp.effective_f_test) and a weak-IV-robust interval (sp.anderson_rubin_ci). - An argument for exclusion: it cannot be tested, so it has to be made.
sp.iv_diagcollects the post-2022 reporting checklist (first stage, effective F, AR test, OLS comparison) in one call; the IV chooser covers LIML, JIVE, shift-share and judge designs.
Stata and R equivalents¶
| Task | Stata | R | StatsPAI |
|---|---|---|---|
| 2SLS | ivregress 2sls lwage (educ = nearc4) exper ..., small |
AER::ivreg(lwage ~ educ + exper ... \| nearc4 + exper ...) |
sp.ivreg("lwage ~ (educ ~ nearc4) + exper ...", data=df) |
| Robust SE | , vce(robust) |
sandwich::vcovHC(fit, "HC1") |
robust="hc1" |
| First stage | estat firststage |
summary(fit, diagnostics = TRUE) |
printed by .summary() |
| AR interval | weakiv |
ivmodel::AR.test() |
sp.anderson_rubin_ci() |
Other Python options¶
linearmodels has the most complete set of IV estimators and first-stage
diagnostics in the Python ecosystem besides StatsPAI (2SLS, LIML, GMM, CUE,
Kleibergen–Paap); pyfixest supports IV with fixed effects and an effective
F. See the library comparison.
Tested with StatsPAI 1.43.1 on 2026-11-12. The code and numbers on this page
are run by tests/test_docs_task_pages.py.
Report a problem.