DAAF-Contribution-Community/daaf / .claude/skills/linearmodels
linearmodels
VerifiedPanel data, IV/GMM, system regression. PanelOLS (FE/RE), BetweenOLS, Fama-MacBeth, IV2SLS/LIML/GMM, SUR, 3SLS, Driscoll-Kraay SEs. Use for RE/between, system estimation, or GMM. Complements pyfixest (FE + DiD) and statsmodels (GLM + time series). R equivalent (use when execution language is R): plm for panel RE/between/FD/Fama-MacBeth, fixest for panel FE; LIML, non-panel GMM-IV, SUR and 3SLS have no installed R equivalent.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.3 KB |
| references/asset-pricing.md | markdown | 8.9 KB |
| references/covariance-inference.md | markdown | 13.6 KB |
| references/gotchas.md | markdown | 12.6 KB |
| references/iv-models.md | markdown | 15.8 KB |
| references/panel-models.md | markdown | 14.1 KB |
| references/quickstart.md | markdown | 18.3 KB |
| references/system-models.md | markdown | 12.0 KB |
references/iv-models.md
View on GitHub# Instrumental Variable and GMM Models
Reference for all IV estimators in linearmodels.iv. For methodology guidance on when IV
is appropriate, instrument validity, and identification, see the data-scientist skill's
causal-inference.md reference.
## Contents
- [Data Requirements](#data-requirements)
- [IV2SLS (Two-Stage Least Squares)](#iv2sls-two-stage-least-squares)
- [IVLIML (Limited Information Maximum Likelihood)](#ivliml-limited-information-maximum-likelihood)
- [IVGMM (Generalized Method of Moments)](#ivgmm-generalized-method-of-moments)
- [IVGMMCUE (Continuously Updating Estimator)](#ivgmmcue-continuously-updating-estimator)
- [AbsorbingLS](#absorbingls)
- [Diagnostics and Tests](#diagnostics-and-tests)
- [Covariance Options](#covariance-options)
- [Estimator Selection Guide](#estimator-selection-guide)
- [Common Pitfalls](#common-pitfalls)
- [References and Further Reading](#references-and-further-reading)
## Data Requirements
- IV models do **not** require a MultiIndex (unlike panel models)
- Accept regular pandas DataFrames
- Terms: dependent, exog (exogenous regressors), endog (endogenous regressors),
instruments (excluded instruments)
- The model automatically distinguishes between included exogenous variables and
excluded instruments
- The order of identification requires at least as many excluded instruments as
endogenous regressors
## IV2SLS (Two-Stage Least Squares)
The workhorse IV estimator. Nests OLS when there are no endogenous variables
(`endog=None`). Consistent under heteroskedasticity with robust covariance.
### Formula API
```python
from linearmodels.iv import IV2SLS
# Basic IV: educ is endogenous, instrumented by motheduc and fatheduc
mod = IV2SLS.from_formula(
"np.log(wage) ~ 1 + exper + exper_sq + [educ ~ motheduc + fatheduc]",
data=df
)
res = mod.fit(cov_type="robust")
print(res.summary)
```
### Array API
```python
from linearmodels.iv import IV2SLS
import statsmodels.api as sm
dependent = df["log_wage"]
exog = sm.add_constant(df[["exper", "exper_sq"]]) # Included exogenous (with constant)
endog = df[["educ"]] # Endogenous variable(s)
instruments = df[["motheduc", "fatheduc"]] # Excluded instruments
mod = IV2SLS(dependent, exog, endog, instruments)
res = mod.fit(cov_type="robust")
```
### Formula Bracket Syntax
Brackets enclose the `endogenous ~ instruments` mapping:
```python
# Single endogenous, two instruments
"y ~ 1 + exog1 + exog2 + [endog1 ~ inst1 + inst2]"
# Multiple endogenous variables
"y ~ 1 + exog1 + [endog1 + endog2 ~ inst1 + inst2 + inst3]"
# Constants: include "1" in the exogenous part, NOT inside brackets
"y ~ 1 + exog1 + [endog1 ~ inst1]" # Correct
"y ~ exog1 + [endog1 ~ 1 + inst1]" # Wrong — constant goes outside brackets
# No constant unless you add "1 +" (formulas never add one)
"y ~ exog1 + [endog1 ~ inst1]"
```
Compare with pyfixest pipe-separated syntax:
```python
# pyfixest: "y ~ exog | 0 | endog ~ inst"
# linearmodels: "y ~ 1 + exog + [endog ~ inst]"
```
### Interpreting IV2SLS Output
`res.summary` prints two tables, the estimation summary (R², overall
F-statistic, covariance estimator) and the parameter estimates (coefficients,
standard errors, t-stats, p-values, CIs), then a footer naming the endogenous
variables, the instruments and the covariance type. It does **not** print
first-stage, overidentification or endogeneity diagnostics (checked on
linearmodels 7.0 for IV2SLS and IVGMM). Request each one separately:
- **First-stage diagnostics** (per endogenous variable): `res.first_stage.summary`
shows the first-stage R², the partial R² of the excluded instruments, Shea's
R² and the partial F-statistic with its distribution (a chi2 Wald under
robust/clustered/kernel covariance; see First-Stage Statistics below). Rule of
thumb: F > 10 suggests instruments are not weak (Staiger-Stock), a threshold
stated for the F form.
- **Sargan/Hansen J-test**: `res.sargan` (or the robust `res.wooldridge_overid`);
`res.j_stat` on IVGMM fits. Test of overidentifying restrictions (only when
`# instruments > # endogenous`). H0: instruments are valid. Rejection suggests
at least one instrument is endogenous.
- **Wooldridge regression test for endogeneity**: `res.wooldridge_regression`
(or `res.wu_hausman()`). Durbin-Wu-Hausman equivalent.
H0: the endogenous variable is actually exogenous. Failure to reject means OLS
may be consistent and IV is unnecessary.
## IVLIML (Limited Information Maximum Likelihood)
Alternative to 2SLS with better finite-sample properties. Less biased than 2SLS
when instruments are weak. LIML is a k-class estimator: 2SLS uses k=1; LIML uses
k=lambda_min (smallest eigenvalue of a particular matrix).
```python
from linearmodels.iv import IVLIML
# Standard LIML
mod = IVLIML.from_formula(
"np.log(wage) ~ 1 + exper + [educ ~ motheduc + fatheduc]",
data=df
)
res = mod.fit(cov_type="robust")
```
### Fuller's Modified LIML
Subtracts `alpha / (n - L)` from k for finite-sample bias correction, where L
counts all instrument columns, including the exogenous regressors. The `fuller`
parameter controls alpha.
```python
# Fuller's modified LIML (alpha=1 is the standard choice)
mod = IVLIML.from_formula(
"np.log(wage) ~ 1 + exper + [educ ~ motheduc + fatheduc]",
data=df,
fuller=1
)
res = mod.fit(cov_type="robust")
```
### When to Use LIML vs 2SLS
- Many instruments: LIML is less biased (2SLS bias is proportional to
`# instruments / n`)
- Weak instruments: LIML is more robust (but still problematic with very weak
instruments)
- Fuller's LIML with `alpha=1`: approximately unbiased with very small efficiency
loss — a good default when instrument strength is uncertain
- Single endogenous variable + single instrument: 2SLS and LIML are numerically
identical (k=1 in both cases)
## IVGMM (Generalized Method of Moments)
Most efficient IV estimator when instruments are valid and the model is
overidentified. Estimates an optimal weight matrix from a first-step estimation,
then re-estimates.
```python
from linearmodels.iv import IVGMM
# 2-step efficient GMM with robust weight matrix
mod = IVGMM.from_formula(
"np.log(wage) ~ 1 + exper + [educ ~ motheduc + fatheduc]",
data=df,
weight_type="robust"
)
res = mod.fit(cov_type="robust")
```
### Weight Matrix Options
`weight_type` and its options (`kernel`, `bandwidth`, `clusters`) go to
`IVGMM(...)`/`IVGMM.from_formula(...)`, not to `fit()`.
| Weight Type | Use When | Code |
|-------------|----------|------|
| `"unadjusted"` | Homoskedastic errors assumed | `weight_type="unadjusted"` |
| `"robust"` | Heteroskedastic errors | `weight_type="robust"` |
| `"kernel"` | HAC (time-series dependence) | `weight_type="kernel", kernel="bartlett"` |
| `"clustered"` | Clustered dependence | `weight_type="clustered", clusters=df["group"]` |
### iter_limit Parameter
```python
# weight_type is set on the model (above); iter_limit sets the number of steps
# 1-step GMM (uses initial weight matrix only)
res = mod.fit(iter_limit=1)
# 2-step GMM (default iter_limit=2 — efficient under correct specification)
res = mod.fit()
# Iterative GMM (repeats until weight matrix converges)
res = mod.fit(iter_limit=100)
```
### When to Use GMM vs 2SLS
- Just-identified (# instruments = # endogenous): 2SLS and efficient GMM produce
identical estimates. Use 2SLS for simplicity.
- Overidentified with heteroskedasticity: GMM with `weight_type="robust"` is more
efficient than 2SLS.
- Overidentified with homoskedasticity: 2SLS is already efficient; GMM gains nothing.
## IVGMMCUE (Continuously Updating Estimator)
Jointly optimizes parameters and weight matrix in a single objective function
(non-linear optimization). Can be more robust to weak instruments than 2-step GMM,
but is more computationally expensive and may not converge.
```python
from linearmodels.iv import IVGMMCUE
mod = IVGMMCUE.from_formula(
"np.log(wage) ~ 1 + exper + [educ ~ motheduc + fatheduc]",
data=df
)
res = mod.fit(cov_type="robust")
```
Use CUE when:
- Concerned about finite-sample bias from sequential 2-step estimation
- Moderate number of moment conditions (CUE becomes unstable with many)
- Willing to accept higher computation time and possible convergence issues
## AbsorbingLS
OLS/WLS with high-dimensional absorbed fixed effects. Uses pyhdfe for FE absorption
when the model is unweighted and absorbs only categoricals, and LSMR otherwise
(similar to Stata's `reghdfe` or pyfixest). Lives in the IV module but is
fundamentally an OLS estimator — does not support endogenous variables.
```python
from linearmodels.iv import AbsorbingLS
# Absorb entity and year fixed effects
# Non-categorical columns are absorbed as continuous variables, not as effects
mod = AbsorbingLS(
dependent=df["y"],
exog=df[["x1", "x2"]],
absorb=df[["entity_id", "year"]].astype("category")
)
res = mod.fit()
```
### Interacted Fixed Effects
```python
import pandas as pd
# Entity-by-industry interacted FE: one categorical with a level per cell
cell = (df["entity_id"].astype(str) + "_" + df["industry"].astype(str)).astype("category")
mod = AbsorbingLS(
dependent=df["y"],
exog=df[["x1"]],
absorb=pd.DataFrame({"cell": cell})
)
res = mod.fit()
```
Passed as `interactions=`, `Interaction(cat, cont)` (from `linearmodels.iv.absorbing`)
adds category-specific slopes on `cont`. Passed as `absorb=`, `cat` is absorbed as
additive effects and `cont` with one common slope, so
`absorb=Interaction(cat=df[["a", "b"]])` absorbs a + b, not a×b.
### AbsorbingLS vs PanelOLS vs pyfixest
| Feature | AbsorbingLS | PanelOLS | pyfixest |
|---------|-------------|----------|----------|
| Max FE dimensions | Unlimited | 2 | Unlimited |
| Requires MultiIndex | No | Yes | No |
| Speed (large data) | Moderate (pyhdfe or LSMR) | Moderate | Fast (numba/JAX) |
| IV support | No | No | Yes (with FE) |
| Interacted FE | Yes (combined categorical column) | No | Yes (native `^`) |
**Recommendation:** For most absorbed-FE work, prefer pyfixest for speed and
formula convenience. Use AbsorbingLS when you need to stay within the linearmodels
ecosystem or need `Interaction` (via `interactions=`) for category-specific slopes.
## Diagnostics and Tests
### First-Stage Statistics
```python
res = mod.fit(cov_type="robust")
# Per-endogenous-variable partial first-stage statistics
diag = res.first_stage.diagnostics
for name, row in diag.iterrows():
print(f"--- First stage for {name} ---")
print(f" Partial R²: {row['partial.rsquared']:.4f} Shea's R²: {row['shea.rsquared']:.4f}")
# f.stat is an F under cov_type="unadjusted", a chi2 Wald under robust/clustered/kernel (see f.dist)
print(f" Partial test: {row['f.stat']:.2f} (p={row['f.pval']:.4f}, {row['f.dist']})")
```
### Overidentification Test (Sargan / Hansen J-Test)
Available only when `# instruments > # endogenous`:
```python
# Sargan test (assumes homoskedastic errors)
print(f"Sargan J-stat: {res.sargan.stat:.3f}")
print(f"Sargan p-value: {res.sargan.pval:.3f}")
# Wooldridge overidentification test (robust to heteroskedasticity)
print(f"Wooldridge overid stat: {res.wooldridge_overid.stat:.3f}")
print(f"Wooldridge overid p-val: {res.wooldridge_overid.pval:.3f}")
```
### Endogeneity Test (Wu-Hausman)
Tests H0: the suspected endogenous variable is actually exogenous.
```python
wh = res.wu_hausman()
print(f"Wu-Hausman F-stat: {wh.stat:.3f}")
print(f"Wu-Hausman p-val: {wh.pval:.3f}")
```
### Wooldridge Regression-Based Endogeneity Test
```python
endo_test = res.wooldridge_regression
print(f"Wooldridge stat: {endo_test.stat:.3f}")
print(f"Wooldridge pval: {endo_test.pval:.3f}")
```
### Weak Instrument Warning Signs
- First-stage partial F < 10 (Staiger-Stock rule of thumb)
- Large difference between 2SLS and LIML estimates (suggests weak instrument bias
in 2SLS — LIML is median-unbiased, so divergence from 2SLS indicates 2SLS bias)
- Wide confidence intervals relative to OLS
- Anderson-Rubin confidence sets (not built in — construct manually or use
alternative packages if needed)
## Covariance Options
All IV estimators accept `cov_type` in `.fit()`:
| `cov_type` | Description | When to Use |
|-------------|-------------|-------------|
| `"unadjusted"` | Classical (homoskedastic) | Textbook settings only |
| `"robust"` | Eicker-Huber-White | Default for cross-sectional data |
| `"kernel"` | HAC (Newey-West style) | Time-series or spatial correlation |
| `"clustered"` | Cluster-robust | Grouped/panel-like data |
```python
# Robust (heteroskedasticity-consistent)
res = mod.fit(cov_type="robust")
# Clustered by state
res = mod.fit(cov_type="clustered", clusters=df["state"])
# HAC with Bartlett kernel, bandwidth 5
res = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=5)
```
For GMM models, `weight_type` and `cov_type` are separate arguments. The weight
matrix determines efficiency; the covariance type determines inference. They should
generally match (e.g., `weight_type="robust"` with `cov_type="robust"`).
## Estimator Selection Guide
```
How to choose an IV estimator?
├─ Just-identified (# inst = # endog)
│ ├─ All estimators give identical point estimates
│ └─ Use IV2SLS for simplicity
├─ Overidentified (# inst > # endog)
│ ├─ Instruments strong (F > 10)?
│ │ ├─ Yes, homoskedastic → IV2SLS
│ │ ├─ Yes, heteroskedastic → IVGMM (2-step, weight_type="robust")
│ │ └─ Yes, clustered → IVGMM (2-step, weight_type="clustered")
│ └─ Instruments possibly weak (F ~ 10)?
│ ├─ Few instruments → IVLIML or Fuller (fuller=1)
│ └─ Many instruments → Fuller (fuller=1) preferred
├─ Concerned about finite-sample bias?
│ ├─ IVLIML (less biased than 2SLS)
│ ├─ Fuller LIML (approximately unbiased)
│ └─ IVGMMCUE (if willing to accept computation cost)
└─ Just want a robust default?
└─ IV2SLS with cov_type="robust" (widely understood, easy to report)
```
## Common Pitfalls
**Constant term placement:**
The constant (`1`) goes in the exogenous part, never inside the brackets.
```python
# Correct
"y ~ 1 + exper + [educ ~ motheduc + fatheduc]"
# Wrong — do not put constant inside brackets
"y ~ exper + [educ ~ 1 + motheduc + fatheduc]"
```
**Forgetting to check first-stage strength:**
Always inspect `res.first_stage` before interpreting second-stage results. Weak
first stages invalidate standard inference even with large samples.
**Using Sargan test with heteroskedastic data:**
The Sargan test assumes homoskedasticity. Use `res.wooldridge_overid` for
heteroskedasticity-robust overidentification testing.
**Confusing weight_type and cov_type in GMM:**
`weight_type` determines the GMM weight matrix (affects point estimates in
overidentified models). `cov_type` determines standard errors (affects inference
only). They should generally be set to the same value.
**Mixing up with panel IV:**
linearmodels does not have a combined panel-IV estimator. If you need IV with
entity/time fixed effects, use pyfixest:
```python
# pyfixest: IV with entity and time FE
import pyfixest as pf
fit = pf.feols("log_wage ~ 1 + exper | entity + year | educ ~ motheduc + fatheduc", data=df)
```
## References and Further Reading
- Sheppard, K. linearmodels IV documentation. https://bashtage.github.io/linearmodels/iv/introduction.html
- Angrist, J.D. and Pischke, J.-S. (2009). *Mostly Harmless Econometrics*. Princeton University Press.
- Baum, C.F., Schaffer, M.E., and Stillman, S. (2007). "Enhanced Routines for Instrumental Variables/Generalized Method of Moments Estimation and Testing." *Stata Journal*, 7(4), 465-506.
- Stock, J.H. and Yogo, M. (2005). "Testing for Weak Instruments in Linear IV Regression." In Andrews, D.W.K. and Stock, J.H. (eds.), *Identification and Inference for Econometric Models*. Cambridge University Press.
- Hansen, L.P. (1982). "Large Sample Properties of Generalized Method of Moments Estimators." *Econometrica*, 50(4), 1029-1054.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |