StataFlow

A Python econometrics toolkit designed to reproduce Stata 17 estimation results with field-level validation.

简体中文

from stataflow.compat.stata import reghdfe

result = reghdfe(
    df,
    y="lwage",
    x=["exper", "edu"],
    absorb="firm_id year_id",
    vce="cluster",
    cluster="firm_id",
)
result.display()

Why StataFlow

StataFlow is for researchers who want Python workflows without giving up the empirical conventions they rely on in Stata. The project is not a generic statistics library: public capabilities are backed by synthetic cases, public real-data cases, and field-level Stata 17 comparisons.

The current development version is 1.3.0, covering 14 Stata-style commands.

Features

• 14 estimation commands in Python: regress, xtreg_fe, areg, reghdfe, ivregress_2sls, ivreghdfe, logit, probit, poisson, ppmlhdfe, did_imputation, eventstudyinteract, csdid, and rdrobust. The exported rdplot companion is a helper and is not counted as an estimation command.
• Two API layers: a Stata-compatible command layer (stataflow.compat.stata) and a Python-native estimator layer (stataflow.estimators).
• Command-aware Stata-style output: result.display() prints a complete, adaptive result table with the statistics and diagnostics relevant to each command; notebooks receive the same content as escaped HTML.
• High-dimensional fixed effects: MAP absorption for large FE designs, multi-FE workflows, singleton handling, individual slopes, and cluster-aware VCE paths.
• Instrumental variables: 2SLS, GMM2S, LIML, Fuller/k-class, first-stage diagnostics, weak-instrument tests, and overidentification tests.
• Binary, count, and PPML models: Logit, Probit, Poisson, and PPML-HDFE with robust and clustered covariance estimators.
• Causal inference: BJS DID imputation, Sun-Abraham event-study interactions, Callaway-Sant'Anna DID, and sharp/fuzzy regression discontinuity.
• Stata-compatible syntax subsets: factor variables, command-specific analytic-weight support, multiple fixed effects, common VCE choices, and hard rejection of unsupported parameters.
• Validation-first development: public commands are backed by field-level Stata 17 comparison evidence.

Installation

pip install StataFlow

Python 3.10, 3.11, or 3.12 is required. Core dependencies are NumPy, pandas, SciPy, scikit-learn, and PyYAML.

Quick Start

Stata-Compatible API

from stataflow.compat.stata import regress, reghdfe, logit, ivregress_2sls, ppmlhdfe

# OLS with robust standard errors
result = regress(df, y="wage", x=["edu", "exper"], vce="robust")
result.display()

# High-dimensional fixed effects
result = reghdfe(
    df,
    y="wage",
    x=["edu", "exper"],
    absorb="firm_id year_id",
    vce="cluster",
    cluster="industry",
)

# Logit
result = logit(df, y="inlf", x=["nwifeinc", "educ", "exper"])
result.display()

# 2SLS with robust VCE
result = ivregress_2sls(
    df,
    y="lwage",
    x_exog=["educ"],
    x_endog=["exper"],
    instruments=["age", "kidslt6"],
    vce="robust",
)

# PPML with high-dimensional fixed effects
result = ppmlhdfe(
    df,
    y="trade",
    x=["lndist", "contig", "fta"],
    absorb=["exporter", "importer", "year"],
    vce="cluster",
    cluster="exporter",
)

Native Python API

from stataflow import OLS, AbsorbingOLS, Logit

model = OLS(data=df, y="wage", x=["edu", "exper"])
result = model.fit(vce="robust")
result.display()

Working with Results

result.display()                         # Full output with 95% CI
result.display(detail="compact")        # Header, coefficients, core fit
result.display(show_ci=False)           # Hide confidence intervals
text = result.summary(width=100)        # Return the same table as text
html = result.to_html()                 # Escaped HTML for reports/notebooks

Supported Models

See the Command Support Matrix and Known Issues for exact support boundaries.

Validation

The July 2026 release scope is frozen to the cases summarized below. Relative deviation is |Python - Stata| / max(|Stata|, 1e-15).

Full local Stata validation checks: 856 passed, 12 skipped. The public, self-contained suite passes 10/10 reproducible validation cases with Stata 17. The values above are stored in evidence-summary.json.

Documentation

• User Guide (中文)
• Cookbook (中文)
• Examples — nine deterministic demo scripts covering all 14 public commands; no network or local Stata required
• Validation Evidence (JSON)
• Validation Evidence (readable)
• Changelog

Running Tests

# Unit and integration tests
pytest tests/ -v

# Reproducible Stata validation cases (require local Stata 17)
pytest tests/stata_validation/ -v -s

Community

• Contributing Guide — development workflow, testing requirements, and PR checks
• Security Policy — supported versions and private vulnerability reporting
• Code of Conduct

License

This project is licensed under the MIT License. See LICENSE for details.