linearmodels

linearmodels fills the gap left by statsmodels for econometricians and applied researchers who need estimators beyond ordinary least squares. It provides panel-data models (fixed effects, first-difference, between, pooled, and Fama-MacBeth), instrumental-variable estimators (2SLS, LIML, k-class, and GMM including continuously-updating GMM), system regression (SUR, three-stage least squares, and system GMM), and factor asset-pricing models (2- and 3-step, time-series, and GMM estimation).

Every estimator accepts NumPy arrays, pandas DataFrames, or xarray objects, and supports both direct array construction and an R-style formula interface built on the formulaic package, including special formula tokens like EntityEffects and TimeEffects for panel fixed effects. Results objects follow the same fit/results split as statsmodels, with rich HTML repr for Jupyter and model-comparison utilities for building side-by-side result tables.

What You Get

• Panel-data estimators: PanelOLS (with up to two-way fixed effects), PooledOLS, BetweenOLS, FirstDifferenceOLS, RandomEffects, and FamaMacBeth
• Instrumental-variable estimators: IV2SLS, IVLIML, IVGMM, and IVGMMCUE (continuously-updating GMM) plus AbsorbingLS for high-dimensional fixed-effect absorption
• System regression estimators: SUR (seemingly unrelated regression), IV3SLS (three-stage least squares), and IVSystemGMM
• Factor asset-pricing models: LinearFactorModel, LinearFactorModelGMM, and TradedFactorModel with 2-step, 3-step, time-series, and GMM estimation
• An R-style formula API via formulaic, including EntityEffects/TimeEffects tokens for specifying panel fixed effects directly in a formula string
• Multiple covariance estimators per model family (clustered, heteroskedasticity-robust, Driscoll-Kraay, Fama-MacBeth) selectable via a cov_type argument on .fit()

Common Use Cases

• Estimating fixed-effects or random-effects panel regressions on firm/entity-time data with clustered standard errors
• Running two-stage least squares or GMM instrumental-variable regressions to address endogeneity in observational data
• Fitting seemingly unrelated regression or three-stage least squares systems of equations that share correlated errors
• Estimating and testing linear factor asset-pricing models (Fama-French style) via time-series or GMM approaches
• Reproducing textbook econometrics results (e.g. Greene) with a documented, tested, versioned implementation instead of hand-rolled code

Under The Hood

Architecture linearmodels organizes estimators into four parallel subpackages (panel, iv, system, asset_pricing), each following a consistent model/results split: panel/model.py defines the six panel estimator classes while panel/results.py holds their corresponding Results classes, panel/covariance.py houses the covariance estimator classes, and panel/data.py wraps input data into a PanelData abstraction. Shared cross-cutting concerns (hypothesis tests, typed getters, linear algebra helpers, exceptions, base summary mixins) live under linearmodels/shared and are imported directly by all four verticals — shared/base.py’s summary and model-comparison mixins are inherited across panel, iv, and system results classes to give consistent repr and HTML output. Formula parsing is delegated to the external formulaic library and wrapped in formula.py. Each top-level class is a self-contained estimator that receives data in init and exposes a .fit() returning a typed Results object, mirroring statsmodels’ fit/results split rather than a plugin or dependency-injection system.

Tech Stack A pure Python 3.10+ library (99%+ Python) with a small Cython/Meson slice for performance-critical panel utility routines, compiled via the meson-python build backend. Core runtime dependencies are numpy, pandas, scipy, and statsmodels (the library it extends), plus pyhdfe for high-dimensional fixed-effect absorption and formulaic for formula parsing. Build tooling combines meson, ninja, Cython, and setuptools_scm for git-tag-based versioning, with optional xarray input support. Distributed as compiled wheels across an OS/Python-version matrix via a GitHub Actions build-wheels workflow, with documentation built through Sphinx, sphinx-immaterial, and nbsphinx from Jupyter notebook examples.

Code Quality An extensive test suite under linearmodels/tests mirrors the source layout one-to-one (tests/panel, tests/iv, tests/system, tests/asset_pricing, tests/shared, tests/datasets), run with pytest plus pytest-xdist, pytest-randomly, and pytest-cov, with coverage tracked through Codecov. Type checking is enforced via mypy with the numpy.typing plugin and per-module override rules, and style is enforced via black and ruff with detailed per-file ignore rules. CI runs on Azure Pipelines plus a scheduled cron-test workflow, alongside GitHub CodeQL security scanning. Error handling favors typed, package-specific warning and exception classes defined in shared/exceptions.py and shared/hypotheses.py rather than generic exceptions, and the package ships a py.typed marker so consumers get inline type checking.

API Design The API mirrors statsmodels’ familiar fit/results pattern, which lowers the learning curve for anyone coming from statsmodels, while extending it into panel, IV, system, and asset-pricing territory statsmodels doesn’t cover. Every estimator supports both positional array/DataFrame construction and an R-style formula interface via .from_formula(), with special formula tokens like EntityEffects and TimeEffects for panel fixed effects baked directly into the formula grammar. Results objects implement rich HTML rendering for Jupyter and expose model-comparison utilities for side-by-side result tables. It isn’t a novel algorithmic approach — it’s a well-executed, consistent packaging of established econometric estimators (2SLS, LIML, GMM, SUR, Fama-MacBeth) that are individually well documented in econometrics textbooks.