factor-factory

What It Is#

factor-factory is a domain-agnostic Python framework for panel data analysis and causal inference. It defines two stable contracts — the Panel (unit × period × treatment structure) and the Engine (a Protocol for fitting a single estimator family) — and ships 20 engine families behind that contract.

Why It Matters#

Research code usually grows a custom did_helpers.py per project. Those helpers drift between papers, miss diagnostics, and silently disagree when you cross-check estimators. factor-factory centralizes the econometric engine surface so the same Panel goes into TWFE, Callaway-Sant'Anna, Sun-Abraham, and Borusyak-Jaravel-Spiess with one function call — and reports returned as frozen dataclasses with ATT, SE, 95% CI, p-value, n, and a method-specific diagnostics dict.

What Ships in 1.0#

Engine families (organized by research task):

• DiD — twfe, cs, sa, bjs staggered-adoption-safe estimators; multi-method calls; event-study plots
• RDD — rd_robust wrapping the NSF-funded Calonico-Cattaneo-Farrell-Titiunik rdrobust package
• SCM — vanilla + augmented synthetic control
• Spatial — morans_i, lisa, spatial_lag, spatial_error
• Inequality — Theil decomposition, Gini, Oaxaca-Blinder
• Changepoint — PELT, binary segmentation, sliding window
• STL — seasonal-trend-loess with significance tests
• Survival, mediation, event-study (Fama-French), DML for heterogeneous treatment effects

Panel contract — Panel.from_records(records, dimension=..., treatment_events=(...)) aggregates records to balanced panels with cell counts; TreatmentEvent declares treated units + treatment date; Panel.validate() catches schema drift early.

First-class jellycell integration — factor_factory.jellycell.cells, figure, notebooks.scaffold, tearsheets — every engine result has a canonical tearsheet shape for rendered artifacts.

Ecosystem Fit#

factor-factory is domain-neutral. nyc311 >= 1.0 ships a PanelDataset.to_factor_factory_panel() adapter and a Pipeline.as_factor_factory_estimate() dispatcher across 17 engine families. subway-access >= 0.5 uses factor-factory in its engine-audit-as-appendix pattern for its CASESTUDY. The blaise-website packages/python-showcase/ package routes every causal/inferential claim through factor-factory.

When to Reach For It#

• Any research panel with ≥ 2 periods and a treatment indicator
• When you need multiple estimators to cross-check a causal claim
• Reproducible diagnostics (parallel-trends, MDE, placebo, BH correction) without hand-wiring scipy each time