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/covariance-inference.md
View on GitHub# Covariance Estimation and Inference
Reference for all standard error and covariance types in linearmodels across panel,
IV, and system model families. For methodology guidance on when to use which SE type,
see the data-scientist skill's `statistical-modeling.md` reference.
## Contents
- [Overview](#overview)
- [Panel Model Covariance Types](#panel-model-covariance-types)
- [IV Model Covariance Types](#iv-model-covariance-types)
- [System Model Covariance Types](#system-model-covariance-types)
- [GMM Weight Matrices](#gmm-weight-matrices)
- [The debiased Parameter](#the-debiased-parameter)
- [SE Type Decision Guide](#se-type-decision-guide)
- [Comparison with pyfixest and statsmodels](#comparison-with-pyfixest-and-statsmodels)
- [Key Differences from pyfixest](#key-differences-from-pyfixest)
- [References and Further Reading](#references-and-further-reading)
## Overview
linearmodels provides rich covariance estimation across all model types. Key points:
- **Panel-aware clustering**: entity and time dimensions are built into the API
(`cluster_entity`, `cluster_time`) -- no need to pass cluster variables manually
- **Driscoll-Kraay SEs**: kernel-based covariance robust to cross-sectional dependence,
available for PanelOLS, PooledOLS, RandomEffects and FirstDifferenceOLS (BetweenOLS
accepts only `unadjusted`, `robust` and `clustered`; FamaMacBeth's `kernel` is a HAC
on the per-period estimates). statsmodels offers DK as `cov_type="hac-groupsum"`.
- **Small-sample corrections**: all covariance estimators accept a `debiased` parameter
- **SE type is specified at `.fit()` time**, not post-estimation -- unlike pyfixest's
`.vcov()` method, you must re-fit to change the covariance type
## Panel Model Covariance Types
All panel estimators (`PanelOLS`, `RandomEffects`, `BetweenOLS`, `FirstDifferenceOLS`,
`PooledOLS`, `FamaMacBeth`) accept `cov_type` in `.fit()`.
### Homoskedastic (Unadjusted)
```python
res = mod.fit(cov_type="unadjusted") # or "homoskedastic"
```
Assumes homoskedastic, uncorrelated errors. Rarely appropriate for panel data --
use only as a baseline or when you have strong theoretical justification.
### Heteroskedasticity-Robust
```python
res = mod.fit(cov_type="robust") # or "heteroskedastic"
```
White's heteroskedasticity-consistent estimator. Corrects for non-constant error
variance but does NOT account for within-entity serial correlation or
cross-sectional dependence. Typically insufficient for panel data.
### Clustered (One-Way and Two-Way)
```python
# Cluster by entity (most common for panel data)
res = mod.fit(cov_type="clustered", cluster_entity=True)
# Cluster by time
res = mod.fit(cov_type="clustered", cluster_time=True)
# Two-way clustering (entity AND time)
res = mod.fit(cov_type="clustered", cluster_entity=True, cluster_time=True)
# Cluster by a custom variable (must align with the data index)
res = mod.fit(cov_type="clustered", clusters=df["state_id"])
```
- Entity clustering accounts for arbitrary within-entity serial correlation
- Time clustering accounts for cross-sectional correlation within time periods
- Two-way clustering accounts for both simultaneously (Cameron, Gelbach, Miller 2011)
- When clustering by the same variable as a single FE (e.g. entity FE with
entity clusters), the covariance scale does not count the nested effects, but
p-values still use t(n-k-effects), not t(G-1) (see
[The debiased Parameter](#the-debiased-parameter))
- Custom `clusters` variable must have the same index as the dependent variable
### Driscoll-Kraay (Kernel)
```python
res = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=5)
```
Robust to heteroskedasticity, serial correlation, AND cross-sectional dependence.
This is the key covariance type that linearmodels offers beyond what most Python
packages provide.
- Appropriate when T is large relative to N (unlike clustered SEs which assume
large N, fixed T)
- Kernel options: `"bartlett"` (Newey-West), `"parzen"`, `"qs"` (Quadratic Spectral)
- `bandwidth`: number of lags included (larger = more serial correlation accounted for)
- Bandwidth rule of thumb for Bartlett: `floor(4 * (T/100)^(2/9))`
```python
import math
# Automatic bandwidth selection (Bartlett kernel)
T = df.index.get_level_values(1).nunique()
bw = math.floor(4 * (T / 100) ** (2 / 9))
print(f"Suggested Bartlett bandwidth for T={T}: {bw}")
res = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=bw)
```
### Fama-MacBeth Covariance
Only available for the `FamaMacBeth` estimator. Adjusts inference for time-series
dependence in the averaged cross-sectional regression coefficients.
```python
from linearmodels.panel import FamaMacBeth
mod = FamaMacBeth.from_formula("ret ~ 1 + beta + size + bm", data=df)
# Standard FM SEs (assumes independence across time periods)
res = mod.fit(cov_type="unadjusted")
# HAC-adjusted FM SEs (accounts for serial dependence in coefficient averages)
res = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=5)
```
With the default `debiased=True`, p-values and CIs use t(`df_resid`), and
`df_resid` is all observations minus k, not the T-1 periods the averages rest
on. For t(T-1) p-values, recompute from the t-statistics:
```python
from scipy import stats
T = res.all_params.dropna().shape[0] # periods with a cross-sectional fit
p_T1 = 2 * stats.t.sf(res.tstats.abs(), T - 1)
```
## IV Model Covariance Types
All IV estimators (`IV2SLS`, `IVLIML`, `IVGMM`, `IVGMMCUE`) accept `cov_type`
in `.fit()`. IV models work with flat DataFrames (no MultiIndex).
### Homoskedastic
```python
res = mod.fit(cov_type="unadjusted")
```
Classical (homoskedastic) standard errors. Textbook settings only.
### Heteroskedasticity-Robust
```python
res = mod.fit(cov_type="robust")
```
Eicker-Huber-White heteroskedasticity-consistent SEs. The default choice for
cross-sectional IV applications.
### Clustered
```python
res = mod.fit(cov_type="clustered", clusters=df["group"])
```
Cluster-robust SEs. Pass the grouping variable directly -- IV models do not have
`cluster_entity`/`cluster_time` shortcuts (those are panel-only).
### HAC / Kernel
```python
res = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=5)
```
HAC (Newey-West style) covariance for time-series or spatial correlation in
cross-sectional IV data. Same kernel options as panel models: `"bartlett"`,
`"parzen"`, `"qs"`.
## System Model Covariance Types
System models (`SUR`, `IV3SLS`, `IVSystemGMM`) support covariance estimation on
top of their cross-equation error structure. The system sigma matrix (cross-equation
covariance) is always estimated; `cov_type` controls within-equation inference.
```python
from linearmodels.system import SUR
mod = SUR(equations)
# Homoskedastic (GLS with estimated sigma)
res = mod.fit(cov_type="unadjusted")
# Heteroskedasticity-robust
res = mod.fit(cov_type="robust")
# HAC kernel
res = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=5)
# Clustered
res = mod.fit(cov_type="clustered", clusters=df["group"])
```
For `IVSystemGMM`, the `weight_type` parameter controls the GMM weight matrix
independently of `cov_type`, following the same pattern as single-equation `IVGMM`.
IVSystemGMM supports `unadjusted`, `robust`, `kernel` only.
## GMM Weight Matrices
For `IVGMM` and `IVSystemGMM`, the weight matrix determines estimator efficiency
while `cov_type` determines inference. These should generally match.
```python
from linearmodels.iv import IVGMM
formula = "np.log(wage) ~ 1 + exper + [educ ~ motheduc + fatheduc]"
# weight_type and its options go to the model; fit() takes cov_type and its own options (kernel, bandwidth, clusters are not inherited)
# Homoskedastic weight matrix
mod = IVGMM.from_formula(formula, data=df, weight_type="unadjusted")
res = mod.fit(cov_type="unadjusted")
# Robust weight matrix (heteroskedastic-efficient)
mod = IVGMM.from_formula(formula, data=df, weight_type="robust")
res = mod.fit(cov_type="robust")
# HAC weight matrix (serial-correlation-efficient)
mod = IVGMM.from_formula(formula, data=df, weight_type="kernel",
kernel="bartlett", bandwidth=5)
res = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=5)
# Clustered weight matrix
mod = IVGMM.from_formula(formula, data=df, weight_type="clustered",
clusters=df["group"])
res = mod.fit(cov_type="clustered", clusters=df["group"])
```
| `weight_type` | Efficient Under | Pair with `cov_type` |
|---------------|-----------------|----------------------|
| `"unadjusted"` | Homoskedastic errors | `"unadjusted"` |
| `"robust"` | Heteroskedastic errors | `"robust"` |
| `"kernel"` | Serial/spatial correlation | `"kernel"` |
| `"clustered"` | Clustered dependence | `"clustered"` |
Mismatching `weight_type` and `cov_type` is legal but produces a less efficient
estimator. The main case for intentional mismatch: use `weight_type="robust"` for
point estimates but `cov_type="clustered"` for conservative inference.
## The debiased Parameter
```python
# Apply small-sample correction
res = mod.fit(cov_type="clustered", cluster_entity=True, debiased=True)
# No correction (default for some models)
res = mod.fit(cov_type="clustered", cluster_entity=True, debiased=False)
```
- When `True`: scales by n/(n-k) and reports t(df_resid) p-values and CIs; when
`False`, normal (z)
- Absorbed effects are counted separately (and not at all when a single FE is
nested in the cluster variable). For the G/(G-1) cluster factor in panel
models add `group_debias=True`; IV `clustered` + `debiased=True` already
applies it
- Default value varies by model type -- always specify explicitly for
reproducibility
```python
# Explicit debiased across different SE types
res_robust = mod.fit(cov_type="robust", debiased=True)
res_cluster = mod.fit(cov_type="clustered", cluster_entity=True, debiased=True)
res_kernel = mod.fit(cov_type="kernel", kernel="bartlett", bandwidth=5, debiased=True)
```
The impact of `debiased` shrinks as sample size grows. For small panels (N < 50
entities or T < 20 periods), the correction can meaningfully affect inference.
## SE Type Decision Guide
| Situation | Recommended Type | Code |
|-----------|-----------------|------|
| Panel: within-entity correlation | Clustered by entity | `cov_type="clustered", cluster_entity=True` |
| Panel: cross-sectional dependence (large T) | Driscoll-Kraay | `cov_type="kernel", kernel="bartlett"` |
| Panel: both within-entity and cross-sectional | Two-way clustering | `cluster_entity=True, cluster_time=True` |
| Cross-section: heteroskedasticity only | Robust | `cov_type="robust"` |
| Cross-section: group structure | Clustered | `cov_type="clustered", clusters=df["group"]` |
| Time series: serial correlation | Kernel (HAC) | `cov_type="kernel", kernel="bartlett"` |
| Fama-MacBeth: time-series averaging | FM kernel | `cov_type="kernel"` (on FamaMacBeth) |
| Assumed homoskedastic + independent | Unadjusted | `cov_type="unadjusted"` |
Default recommendation for most panel applications: **entity-clustered SEs**.
They are robust to arbitrary within-entity correlation patterns and are the
most widely reported in applied econometrics.
## Comparison with pyfixest and statsmodels
| SE Type | linearmodels | pyfixest | statsmodels |
|---------|-------------|----------|-------------|
| Robust (HC1) | `cov_type="robust"` (HC1 only with `debiased=True`, the panel default; IV default is HC0) | `vcov="hetero"` | `cov_type="HC1"` |
| Cluster (1-way) | `cov_type="clustered", cluster_entity=True` | `vcov={"CRV1": "entity"}` | `cov_type="cluster"` |
| Cluster (2-way) | `cluster_entity=True, cluster_time=True` | `vcov={"CRV1": "e+t"}` | `cov_type="cluster"` (2-column `groups`) |
| Driscoll-Kraay | `cov_type="kernel", kernel="bartlett"` | `vcov="DK"` | `cov_type="hac-groupsum"` |
| HAC (Newey-West) | `cov_type="kernel", kernel="bartlett"` | `vcov="NW"` | `cov_type="HAC"` |
| CRV3 | Not available | `vcov={"CRV3": "g"}` | Not available |
| Wild bootstrap | Not available | `.wildboottest()` | Not available |
| Post-estimation switch | Not available (must re-fit) | `.vcov("hetero")` | `get_robustcov_results()` |
## Key Differences from pyfixest
- **Fit-time vs post-estimation**: linearmodels requires SE choice at `.fit()` time;
pyfixest allows post-estimation switching via `.vcov()`. To compare SE types in
linearmodels, you must call `.fit()` multiple times.
- **Kernel options**: linearmodels offers three kernels for Driscoll-Kraay (Bartlett,
Parzen, Quadratic Spectral) with explicit bandwidth control; pyfixest has basic
DK support with `vcov="DK"`.
- **Bootstrap**: pyfixest offers CRV3 and wild bootstrap inference that linearmodels
does not provide. Use pyfixest when bootstrap-based inference is needed.
- **Two-way clustering**: both support it; linearmodels uses `cluster_entity=True,
cluster_time=True`; pyfixest uses `vcov={"CRV1": "entity+time"}`.
- **Panel-aware shortcuts**: linearmodels provides `cluster_entity` and `cluster_time`
booleans that automatically use the MultiIndex levels; pyfixest references variable
names from the formula or data.
## References and Further Reading
- Driscoll, J.C. and Kraay, A.C. (1998). "Consistent Covariance Matrix Estimation with Spatially Dependent Panel Data." *Review of Economics and Statistics*, 80(4), 549-560.
- Cameron, A.C. and Miller, D.L. (2015). "A Practitioner's Guide to Cluster-Robust Inference." *Journal of Human Resources*, 50(2), 317-372.
- Newey, W.K. and West, K.D. (1987). "A Simple, Positive Semi-definite, Heteroskedasticity and Autocorrelation Consistent Covariance Matrix." *Econometrica*, 55(3), 703-708.
- Petersen, M.A. (2009). "Estimating Standard Errors in Finance Panel Data Sets: Comparing Approaches." *Review of Financial Studies*, 22(1), 435-480.
- Sheppard, K. linearmodels Covariance documentation. https://bashtage.github.io/linearmodels/panel/reference.html
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 |