Skip to content

DAAF-Contribution-Community/daaf / .claude/skills/fixest

fixest

Verified

Fast high-dimensional fixed effects in R: feols/fepois/feglm/fenegbin with multi-way FE; IV estimation; DiD (TWFE, Sun-Abraham via sunab); clustered/ heteroskedasticity-robust SEs; etable/coefplot/iplot for reporting. Use when execution language is R. Python equivalent: pyfixest. For panel RE/between use plm; for GLM without FE use r-stats.

FileKindSize
SKILL.mdskill md14.9 KB
references/did.mdmarkdown12.0 KB
references/fixed-effects.mdmarkdown7.6 KB
references/gotchas.mdmarkdown12.4 KB
references/iv.mdmarkdown7.8 KB
references/models.mdmarkdown10.1 KB
references/quickstart.mdmarkdown10.3 KB
references/reporting.mdmarkdown9.1 KB
references/standard-errors.mdmarkdown12.7 KB

references/models.md

View on GitHub
# Model Families

## Contents

- [fepois: Poisson Regression](#fepois-poisson-regression)
- [feglm: Generalized Linear Models with FE](#feglm-generalized-linear-models-with-fe)
- [fenegbin: Negative Binomial](#fenegbin-negative-binomial)
- [feNmlm: Nonlinear Models](#fenmlm-nonlinear-models)
- [Model Selection Guide](#model-selection-guide)

## fepois: Poisson Regression

Poisson regression with absorbed high-dimensional fixed effects. Uses iteratively
reweighted least squares (IRLS/IWLS) for estimation.

### Basic Usage

```r
library(fixest)

# Poisson with FE
fit <- fepois(count_y ~ x1 + x2 | entity + year, data = df)
summary(fit)

# Poisson without FE
fit <- fepois(count_y ~ x1 + x2, data = df)
```

### When to Use fepois

- **Count data**: Outcomes that are non-negative integers (counts)
- **Log-linear models**: Poisson pseudo-maximum likelihood (PPML) is the
  standard estimator for gravity-type models (trade, migration) even when the
  dependent variable is continuous
- **Multiplicative models**: When the conditional expectation is multiplicative
  rather than additive

### Gravity Model Example

```r
data(trade, package = "fixest")

# Santos Silva & Tenreyro (2006) PPML gravity estimator
fit_ppml <- fepois(Euros ~ log(dist_km) | Origin + Destination + Year,
                   data = trade, vcov = ~Origin + Destination)
summary(fit_ppml)

# Compare with log-linear OLS
fit_ols <- feols(log(Euros) ~ log(dist_km) | Origin + Destination + Year,
                 data = trade, vcov = ~Origin + Destination)

etable(fit_ols, fit_ppml, headers = c("Log-OLS", "PPML"))
```

### Convergence Parameters

```r
fit <- fepois(count_y ~ x1 | entity + year, data = df,
              glm.iter = 25,         # Max IRLS iterations (default 25)
              glm.tol = 1e-08)       # Convergence tolerance
```

If convergence fails, see `gotchas.md` for troubleshooting separation and
convergence issues.

### Interpreting Poisson Coefficients

Poisson coefficients are semi-elasticities (in the log-linear model):
- A coefficient of 0.05 on x1 means a one-unit increase in x1 is associated
  with approximately a 5% increase in E[Y|X]
- For exact interpretation: `exp(beta) - 1` gives the proportional change

## feglm: Generalized Linear Models with FE

`feglm()` supports GLM families with absorbed high-dimensional fixed effects.
pyfixest's `feglm()` gained FE support in 0.50 (logit/probit/gaussian); R fixest
retains broader family coverage (e.g., Gamma) and `fenegbin`.

### Supported Families

| Family | Link | Use Case |
|--------|------|----------|
| `binomial` (logit) | logit | Binary outcomes |
| `binomial(link = "probit")` | probit | Binary outcomes (normal CDF) |
| `Gamma` | inverse | Positive continuous, heteroskedastic |
| `gaussian` | identity | Linear model (same as feols) |

### Logit with Fixed Effects

```r
# Logit with entity FE
fit <- feglm(binary_y ~ x1 + x2 | entity, data = df, family = binomial)
summary(fit)

# Logit with two-way FE
fit <- feglm(binary_y ~ x1 + x2 | entity + year, data = df, family = binomial)
```

pyfixest (>= 0.50, DAAF ships 0.60.0) matches this for logit/probit/gaussian via
`pf.feglm("y ~ x1 | entity", family="logit")`; families beyond those (e.g., Gamma)
still require R fixest or manual approaches in Python.

### Probit with Fixed Effects

```r
fit <- feglm(binary_y ~ x1 + x2 | entity, data = df,
             family = binomial(link = "probit"))
summary(fit)
```

### Key Differences from feols

| Aspect | feols (OLS) | feglm (GLM) |
|--------|-------------|-------------|
| Estimation | Closed-form (demeaning + OLS) | Iterative (IRLS) |
| Speed | Very fast | Slower (iterative) |
| Coefficients | Linear effects | Log-odds (logit), z-scores (probit) |
| Marginal effects | Coefficients ARE marginal effects | Need `marginaleffects` package |
| SE switching | Free (post-estimation) | Free (post-estimation) |

### Marginal Effects for feglm

feglm coefficients are not directly interpretable as marginal effects. Use the
`marginaleffects` R package:

```r
library(marginaleffects)

# --- With fixed effects: point estimates only ---
# marginaleffects (0.32.0) CANNOT propagate the uncertainty in absorbed FE
# parameters, so on an feglm with FE it errors unless you set vcov = FALSE.
# The result is the AME point estimate with NO standard error.
fit <- feglm(binary_y ~ x1 + x2 | entity, data = df, family = binomial)

avg_slopes(fit, variables = "x1", vcov = FALSE)                 # point estimate only

slopes(fit, variables = "x1",
       newdata = datagrid(x2 = c(0, 1)), vcov = FALSE)          # point estimates only

# --- FE-free feglm: full inference available ---
# Without absorbed FE, marginaleffects returns AMEs WITH standard errors.
fit_nofe <- feglm(binary_y ~ x1 + x2, data = df, family = binomial)
avg_slopes(fit_nofe, variables = "x1")                          # estimate + std.error
```

> **Caveat.** When the model has fixed effects, `vcov = FALSE` is mandatory and
> you get point estimates without SEs. If you need standard errors on the AMEs,
> either drop the FE (as in `fit_nofe`) or compute marginal effects on a
> comparison model without absorbed FE. This is a limitation of how
> marginaleffects treats fixest's demeaned FE parameters, not of the AME itself.

### Incidental Parameters Problem

With short panels (few time periods per entity), logit/probit with entity FE
suffer from the incidental parameters problem: FE estimates are inconsistent
with fixed T, biasing coefficient estimates. This bias is O(1/T):

| T | Approximate Bias |
|---|-----------------|
| 2 | ~100% |
| 5 | ~20% |
| 10 | ~10% |
| 20 | ~5% |
| 50+ | Negligible |

**Mitigations:**
- Conditional logit (not available in fixest; use `survival::clogit()`)
- Linear probability model (`feols()` with robust/clustered SEs)
- Bias correction (Fernandez-Val & Weidner, 2016)
- Use feglm when T is reasonably large (say, T > 10-20)

## fenegbin: Negative Binomial

Negative binomial regression with FE, for overdispersed count data.

### Basic Usage

```r
# Negative binomial with FE
fit <- fenegbin(count_y ~ x1 + x2 | entity + year, data = df)
summary(fit)
```

### When to Use fenegbin vs fepois

| Criterion | fepois (Poisson) | fenegbin (Neg. Binomial) |
|-----------|-----------------|------------------------|
| Variance = Mean | Yes (equidispersion) | No (overdispersion) |
| Overdispersed counts | Robust but may be inefficient | More efficient |
| Zero-inflated data | Not ideal | Better fit |
| Robust to misspecification | Yes (PPML is consistent) | Less robust |

In practice, Poisson pseudo-ML (fepois) is often preferred because:
- It is consistent for the conditional mean even if the variance is misspecified
- With clustered SEs, inference is valid regardless of overdispersion
- Santos Silva & Tenreyro (2006) show PPML outperforms alternatives for
  gravity-type models

Use fenegbin when modeling the dispersion parameter itself is of interest, or
when the Poisson model shows severe convergence issues due to overdispersion.

## feNmlm: Nonlinear Models

`feNmlm()` is the most general estimation function in fixest, supporting custom
nonlinear specifications with FE.

### Basic Syntax

```r
# Custom nonlinear model
fit <- feNmlm(y ~ x1 + x2, data = df,
              NL.fml = ~ a * exp(b * x3),  # Nonlinear component
              NL.start = list(a = 1, b = 0.5))
```

### Available Families

| Family | Description | Example |
|--------|-------------|---------|
| `"poisson"` | Same as fepois | Count data |
| `"negbin"` | Same as fenegbin | Overdispersed counts |
| `"logit"` | Same as feglm(binomial) | Binary outcomes |
| `"gaussian"` | Same as feols | Linear model |

The `family` argument admits only these four values (`formals(feNmlm)$family` =
`poisson, negbin, logit, gaussian`) — there is no user-supplied-likelihood family.
What makes feNmlm "nonlinear" is the `NL.fml` argument, which lets you specify a
custom nonlinear predictor (e.g. `~ a * exp(b * x3)`) fitted by maximum likelihood
under one of the four families above — not an arbitrary user-defined likelihood.

### When to Use feNmlm

- Nonlinear specifications that don't fit into feols/fepois/feglm/fenegbin
- Custom likelihood functions
- Models combining linear and nonlinear components

For standard models, prefer the specialized functions (feols, fepois, feglm,
fenegbin) — they are faster and have better diagnostics.

## Model Selection Guide

```
What outcome type?
│
├─ Continuous → feols (OLS)
│   ├─ With fixed effects → feols(y ~ x | fe)
│   └─ Without FE → feols(y ~ x) or lm(y ~ x)
│
├─ Count / Non-negative → Consider Poisson first
│   ├─ fepois(count ~ x | fe)
│   ├─ Overdispersed? → fenegbin(count ~ x | fe)
│   └─ Gravity model → fepois (PPML, Santos Silva & Tenreyro 2006)
│
├─ Binary (0/1) → Consider options:
│   ├─ LPM: feols(binary ~ x | fe, vcov = "hetero")
│   │   Pro: Fast, easy interpretation, handles many FE
│   │   Con: Can predict outside [0,1], heteroskedastic by construction
│   ├─ Logit: feglm(binary ~ x | fe, family = binomial)
│   │   Pro: Proper binary model, bounded predictions
│   │   Con: Incidental parameters problem with short panels
│   └─ Probit: feglm(binary ~ x | fe, family = binomial("probit"))
│       Pro: Normal CDF link
│       Con: Same incidental parameters concern as logit
│
├─ Ordinal / Multinomial → Not in fixest
│   └─ Use nnet::multinom() or MASS::polr() (no FE absorption)
│
└─ Custom nonlinear → feNmlm()
```

### Quick Function Reference

| Function | Model | FE Support | IV Support |
|----------|-------|-----------|-----------|
| `feols()` | OLS / linear | Yes | Yes |
| `fepois()` | Poisson | Yes | No |
| `feglm()` | GLM (logit, probit, Gamma, ...) | Yes | No |
| `fenegbin()` | Negative binomial | Yes | No |
| `feNmlm()` | General nonlinear | Yes | No |

## References

- Santos Silva, J.M.C. and Tenreyro, S. (2006). "The Log of Gravity."
  *Review of Economics and Statistics*, 88(4), 641-658.
- Fernandez-Val, I. and Weidner, M. (2016). "Individual and time effects in
  nonlinear panel models with large N, T." *Journal of Econometrics*, 192(1),
  291-312.
- fixest documentation — GLM and nonlinear models:
  https://lrberge.github.io/fixest/reference/feglm.html
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall