/pyfixest¶
Python guide to pyfixest for high-dimensional fixed-effects OLS, Poisson and IV, difference-in-differences via TWFE, did2s and Sun-Abraham, clustered standard errors and etable or iplot reporting.
analysisLGPL-3.0-or-later (as declared in the README, badge and CITATION.cff; the repo ships the GPL-3.0 text as LICENSE plus COPYING.LESSER)data-analysis · code-generation
pyfixest Skill¶
pyfixest: fast high-dimensional fixed effects estimation for Python. Covers OLS, Poisson, and IV regression with multi-way fixed effects; difference-in-differences estimators (TWFE, did2s, lpdid, Sun-Abraham); clustered standard errors; wild bootstrap; and publication output (etable regression tables, coefplot, iplot event study plots). Use when running fixed effects regressions, difference-in-differences designs, Poisson count models with FE, or producing publication-ready regression tables. For panel random/between effects, use linearmodels; for GLM/time series without FE, use statsmodels.
Comprehensive skill for fixed effects regression, instrumental variables, and difference-in-differences estimation with pyfixest. Use decision trees below to find the right guidance, then load detailed references.
What is pyfixest?¶
pyfixest is a Python implementation of the R fixest package (Berge, Butts, & McDermott, 2026):
- Fast: Multi-way FE demeaning via alternating projections; since 0.60 the default backend is a compiled Rust extension shipped in the wheel (numba is now optional), with PyTorch/CuPy/SciPy LSMR backends available for GPU/large problems
- Concise formula syntax: Fixed effects after |, IV after second |, multiple estimation via sw()/csw()
- Modern DiD: Built-in did2s, local projections DiD (lpdid), and Sun-Abraham saturated estimator
- Flexible inference: Switch SE types post-estimation; wild bootstrap, randomization inference, CCV
- Publication output: etable() for regression tables, coefplot() and iplot() for coefficient visualization
Version Notes¶
This skill targets pyfixest 0.60.0 (pre-installed in the DAAF container). Only three release lines sit between the previous target and this one — 0.40.0/0.40.1, 0.50.0/0.50.1, and 0.60.0 (there are no 0.41–0.49 releases). The cumulative changes that matter for existing code, oldest first:
0.40.0 (aligned with R fixest 0.13) — silent result changes:
- Default standard errors changed from "cluster by first FE" to "iid" — old code silently produces different SEs
- ssc() arguments renamed: adj → k_adj, fixef_k → k_fixef, cluster_adj → G_adj, cluster_df → G_df; the old names still work but raise a DeprecationWarning (verified live). The option value "nested" was renamed to "nonnested" — passing "nested" now errors
- fixef_rm default changed from "none" to "singleton" — singletons now dropped by default
- Multicollinearity tolerance reduced from 1e-10 to 1e-09; Gelbach decompose() reworked to return a GelbachDecomposition object (arg param → decomp_var)
0.50.0 — table backend + FE-GLMs:
- etable()/dtable() moved to the maketables backend (the great_tables dependency was replaced). The public etable() API is unchanged and, in this install, the default and type="gt" still return a great_tables.gt.GT object rendered via maketables (verified live)
- feglm() now supports fixed effects (logit/probit/gaussian) — the pre-0.50 "feglm does not support FE" limitation is gone (verified live: pf.feglm("ybin ~ X1 | f1", family="logit") fits)
0.60.0 — Rust demeaner default, numba optional, typed backend API:
- The Rust MAP demeaner is now the default; numba is an optional extra (pyfixest[numba]). numba is still used for MapDemeaner(backend="numba") and fast randomization inference (ritest(..., choose_algorithm="fast")). DAAF's image ships numba transitively (via umap-learn/wildboottest), so the numba paths remain available here
- The loose demeaner_backend, fixef_tol, and fixef_maxiter kwargs are deprecated in favor of a typed demeaner=MapDemeaner(...) / LsmrDemeaner(...) object; the old kwargs still work but raise a DeprecationWarning (verified live)
- etable(type="typst") added; fepois(offset=...) exposure terms added
See gotchas.md for the full cumulative breaking-change detail and migration notes.
How to Use This Skill¶
Reference File Structure¶
Each topic in ./references/ contains focused documentation:
| File | Purpose | When to Read |
|---|---|---|
quickstart.md |
Installation, first regression, formula syntax | Starting with pyfixest |
fixed-effects.md |
Multi-way FE, SE types, clustering, wild bootstrap | FE models and inference |
instrumental-variables.md |
IV syntax, first stage, weak instruments | IV/2SLS estimation |
difference-in-differences.md |
TWFE, did2s, lpdid, Sun-Abraham, event studies | DiD designs |
tables-and-plots.md |
etable, coefplot, iplot, dtable | Reporting results |
advanced-inference.md |
Wild bootstrap, randomization inference, MHT corrections, Gelbach | Advanced statistical inference |
integration.md |
Multiple estimation, Poisson, GLM, marginaleffects, online learning | Advanced features |
gotchas.md |
Common errors, 0.40→0.60 cumulative breaking changes, fixest vs pyfixest | Debugging issues |
Reading Order¶
- New to pyfixest? Start with
quickstart.mdthenfixed-effects.md - Running DiD? Read
quickstart.md, thendifference-in-differences.md - Need IV? Read
quickstart.md, theninstrumental-variables.md - Making tables? Check
tables-and-plots.md - Coming from R fixest? Read
quickstart.mdthengotchas.md
The reference-file routing in this skill applies to advisory and brainstorming turns as much as implementation. Recommending an approach, reviewing a plan, or answering a question that touches a routed topic calls for reading the routed reference file just as much as writing code does — the reference files carry curated caveats and environment-specific constraints that this overview and general knowledge lack.
Related Skills¶
| Skill | Relationship |
|---|---|
data-scientist |
Methodology guidance — load for "why and when" behind methods |
statsmodels |
Complement for non-FE models: GLM, time series, diagnostics |
linearmodels |
Random effects, GMM, system estimation when pyfixest's FE-only approach is insufficient |
svy |
Survey-weighted regression with complex survey designs. pyfixest's clustered SEs account for within-group correlation but do NOT handle full survey design features (stratification, unequal probability weights, FPC). If your data comes from a complex probability survey, use svy for design-based inference |
polars |
Data preparation before estimation (convert to pandas before passing to pyfixest) |
plotnine |
Custom visualization beyond pyfixest's built-in plots |
Quick Decision Trees¶
"I need to run a regression"¶
What kind of regression?
├─ OLS with fixed effects → ./references/quickstart.md
├─ OLS without fixed effects → ./references/quickstart.md
├─ IV / 2SLS → ./references/instrumental-variables.md
├─ Poisson (count data) → ./references/integration.md
├─ Logit / Probit → ./references/integration.md
├─ Quantile regression → ./references/integration.md
└─ Multiple models at once → ./references/integration.md
"I need difference-in-differences"¶
DiD design?
├─ Simple 2x2 DiD (one treatment date) → ./references/difference-in-differences.md
├─ Staggered treatment timing → ./references/difference-in-differences.md
│ ├─ did2s (Gardner imputation) → ./references/difference-in-differences.md
│ ├─ Local projections DiD → ./references/difference-in-differences.md
│ └─ Sun-Abraham saturated → ./references/difference-in-differences.md
├─ Event study plot → ./references/difference-in-differences.md
├─ Visualize treatment patterns → ./references/difference-in-differences.md
└─ Parallel trends assessment → ./references/difference-in-differences.md
"I need to choose standard errors"¶
What inference?
├─ Heteroskedasticity-robust (HC1) → ./references/fixed-effects.md
├─ Clustered (one-way / two-way) → ./references/fixed-effects.md
├─ Few clusters (<20) → ./references/advanced-inference.md
│ └─ Wild cluster bootstrap → ./references/advanced-inference.md
├─ HAC / Newey-West → ./references/fixed-effects.md
├─ Randomization inference → ./references/advanced-inference.md
├─ Multiple hypothesis testing → ./references/advanced-inference.md
└─ Causal cluster variance (CCV) → ./references/advanced-inference.md
"I need to present results"¶
Presenting results?
├─ Regression table (multiple models) → ./references/tables-and-plots.md
├─ Coefficient plot → ./references/tables-and-plots.md
├─ Event study plot → ./references/tables-and-plots.md
├─ Descriptive statistics table → ./references/tables-and-plots.md
└─ LaTeX output → ./references/tables-and-plots.md
"Something isn't working"¶
Having issues?
├─ Different results from old code → ./references/gotchas.md
├─ feglm / GLM with fixed effects → ./references/gotchas.md
├─ numba / demeaner backend questions → ./references/gotchas.md
├─ CRV3 memory issues → ./references/gotchas.md
├─ Poisson convergence → ./references/gotchas.md
├─ Formula parsing errors → ./references/gotchas.md
├─ R fixest vs pyfixest differences → ./references/gotchas.md
└─ Singleton warnings → ./references/gotchas.md
File-First Execution in Research Workflows¶
Important: In data research pipelines (see CLAUDE.md), pyfixest regressions are executed through script files, not interactively. This ensures auditability and reproducibility.
The pattern:
1. Write regression code to scripts/stage8_analysis/{step}_{task-name}.py
2. Execute via Bash with automatic output capture wrapper script
3. Validation results get automatically embedded in scripts as comments
4. If failed, create versioned copy for fixes
Closely read agent_reference/SCRIPT_EXECUTION_REFERENCE.md for the mandatory file-first execution protocol covering complete code file writing, output capture, and file versioning rules. All regression scripts must follow the Inline Audit Trail (IAT) standard — see agent_reference/INLINE_AUDIT_TRAIL.md. For regression code, document model specification choices (why this estimator, why this clustering level, what identifying assumptions) with # INTENT:, # REASONING:, and # ASSUMES: comments.
See:
- agent_reference/WORKFLOW_PHASE4_ANALYSIS.md — Stage 8 (Analysis & Visualization)
- agent_reference/INLINE_AUDIT_TRAIL.md — IAT documentation standard
The examples below show pyfixest syntax. In research workflows, wrap them in scripts following the file-first pattern.
Quick Reference¶
Essential Import¶
Core Estimation Functions¶
| Function | Purpose |
|---|---|
pf.feols("Y ~ X \| fe", data=df) |
OLS with fixed effects |
pf.fepois("Y ~ X \| fe", data=df) |
Poisson with fixed effects |
pf.feglm("Y ~ X \| fe", data=df, family="logit") |
GLM (logit/probit/gaussian) with fixed effects (since 0.50) |
pf.feols("Y ~ X2 \| fe \| X1 ~ Z1", data=df) |
IV / 2SLS |
pf.did2s(data, yname, first_stage, second_stage, treatment, cluster) |
Gardner (2022) DiD |
pf.event_study(data, yname, idname, tname, gname, estimator) |
Unified event study |
pf.lpdid(data, yname, idname, tname, gname) |
Local projections DiD |
Formula Syntax Quick Reference¶
| Pattern | Meaning | Example |
|---|---|---|
Y ~ X1 + X2 |
No FE | "wage ~ educ + exper" |
Y ~ X \| fe1 + fe2 |
With FE | "wage ~ educ \| state + year" |
Y ~ X \| fe \| endog ~ inst |
FE + IV | "wage ~ exper \| state \| educ ~ college_prox" |
i(factor, ref=val) |
Categorical with ref | "Y ~ i(year, ref=2000) \| state" |
sw(X1, X2) |
Stepwise alternatives | "Y ~ sw(educ, exper) \| state" |
csw0(X1, X2) |
Cumulative stepwise | "Y ~ csw0(educ, exper) \| state" |
Y1 + Y2 ~ X |
Multiple outcomes | "wage + hours ~ educ \| state" |
Post-Estimation Essentials¶
fit = pf.feols("Y ~ X1 + X2 | fe", data=df)
fit.summary() # Print results
fit.tidy() # DataFrame of coefficients
fit.vcov("hetero") # Re-estimate with robust SEs (requires arg)
fit.vcov({"CRV1": "state"}) # Re-estimate with clustered SEs
fit.coef() # Coefficient values
fit.se() # Standard errors
fit.confint() # Confidence intervals
fit.predict() # Fitted values
fit.resid() # Residuals
fit.fixef() # Dict of FE name → numpy array (not a DataFrame)
Reporting¶
pf.etable([fit1, fit2, fit3]) # Regression table
pf.coefplot([fit1, fit2]) # Coefficient plot
pf.iplot(fit) # Event study / interaction plot
pf.panelview(data, unit, time, treat) # Treatment pattern visualization
Topic Index¶
| Topic | Reference File |
|---|---|
| Installation | ./references/quickstart.md |
| First regression | ./references/quickstart.md |
| Formula syntax | ./references/quickstart.md |
| SE comparison table | ./references/quickstart.md |
| Multi-way fixed effects | ./references/fixed-effects.md |
| Standard error types | ./references/fixed-effects.md |
| Clustered SEs | ./references/fixed-effects.md |
| HAC / Newey-West | ./references/fixed-effects.md |
| Backend options | ./references/fixed-effects.md |
| IV formula syntax | ./references/instrumental-variables.md |
| First-stage diagnostics | ./references/instrumental-variables.md |
| Weak instrument tests | ./references/instrumental-variables.md |
| TWFE | ./references/difference-in-differences.md |
| did2s | ./references/difference-in-differences.md |
| Local projections DiD | ./references/difference-in-differences.md |
| Sun-Abraham | ./references/difference-in-differences.md |
| Event study plots | ./references/difference-in-differences.md |
| Parallel trends | ./references/difference-in-differences.md |
| panelview | ./references/difference-in-differences.md |
| etable | ./references/tables-and-plots.md |
| coefplot | ./references/tables-and-plots.md |
| iplot | ./references/tables-and-plots.md |
| dtable | ./references/tables-and-plots.md |
| Wild cluster bootstrap | ./references/advanced-inference.md |
| Randomization inference | ./references/advanced-inference.md |
| Multiple testing corrections | ./references/advanced-inference.md |
| Gelbach decomposition | ./references/advanced-inference.md |
| CCV | ./references/advanced-inference.md |
| Multiple estimation | ./references/integration.md |
| Poisson regression | ./references/integration.md |
| GLM (logit/probit) | ./references/integration.md |
| Quantile regression | ./references/integration.md |
| marginaleffects | ./references/integration.md |
| Online learning | ./references/integration.md |
| Performance tuning | ./references/integration.md |
| Polars DataFrame input | ./references/gotchas.md |
| Polars-to-pandas conversion | ./references/quickstart.md |
| DiD clustering level | ./references/difference-in-differences.md |
| 0.40→0.60 breaking changes | ./references/gotchas.md |
| feglm with fixed effects | ./references/gotchas.md |
| numba / Rust demeaner backend | ./references/gotchas.md |
| Formula parsing | ./references/gotchas.md |
| R fixest differences | ./references/gotchas.md |
Citation¶
When this library is used as a primary analytical tool, include in the report's Software & Tools references:
Berge, L., Butts, K., & McDermott, G. (2026). pyfixest: Fast high-dimensional fixed effects estimation [Computer software]. Based on fixest (R).
Cite when: pyfixest is used for regression estimation (OLS, Poisson, IV) or difference-in-differences analysis. Do not cite when: Only imported but no estimation performed.
For method-specific citations (e.g., individual DiD estimators or inference techniques),
consult the reference files in this skill and agent_reference/CITATION_REFERENCE.md.