Metadata-Version: 2.4
Name: StataFlow
Version: 1.2.0
Summary: StataFlow: A Python econometrics toolkit aligned with Stata 17
Author-email: Zhenhao Fu <zhenhaofu2001@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ZhenHaoFu810/StataFlow
Project-URL: Repository, https://github.com/ZhenHaoFu810/StataFlow
Project-URL: Issues, https://github.com/ZhenHaoFu810/StataFlow/issues
Keywords: econometrics,stata,regression,fixed-effects,panel-data
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.2,>=1.24
Requires-Dist: pandas<3,>=2.0
Requires-Dist: scipy<2,>=1.10
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: scikit-learn<2,>=1.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: statsmodels>=0.14; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# StataFlow

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

[简体中文](README.zh-CN.md)

[![PyPI version](https://img.shields.io/pypi/v/stataflow)](https://pypi.org/project/stataflow/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

```python
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 release is **1.2.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`).
- **Stata-style output**: `result.display()` prints compact regression tables with coefficients, standard errors, test statistics, p-values, and fit statistics.
- **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

```bash
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

```python
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

```python
from stataflow import OLS, AbsorbingOLS, Logit

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

### Programmatic Results

```python
result.display(show_ci=True)

for coef in result.coefficients:
    print(f"{coef.name}: b={coef.beta:.6f}, se={coef.std_err:.6f}, t={coef.t_stat:.2f}")

print(f"R2 = {result.fit.r2:.4f}, N = {result.sample.nobs}")
```

## Supported Models

| Family | Available via | Estimators and VCE |
|--------|---------------|--------------------|
| Linear | `regress`, `areg`, `xtreg_fe`, `reghdfe` | OLS with `ols`, `robust` (HC1), and command-specific clustering; `reghdfe` also supports `dkraay` panel HAC |
| IV | `ivregress_2sls`, `ivreghdfe` | 2SLS, GMM2S, LIML, Fuller/k-class, first-stage diagnostics, weak-IV tests |
| Binary / Count | `logit`, `probit`, `poisson` | MLE with `ols`, `robust`, and `cluster` VCE |
| PPML + HDFE | `ppmlhdfe` | IRLS with fixed effects, offset/exposure, separation checks, `eform`, and common prediction types |
| DID | `did_imputation`, `csdid`, `eventstudyinteract` | BJS imputation, Callaway-Sant'Anna, and Sun-Abraham IW estimators |
| RD | `rdrobust` | Sharp/fuzzy RD, MSE/CER bandwidth selectors, covariates, weights, mass points, and cluster/nncluster VCE |

See the [Command Support Matrix](docs/command-support-matrix/README.md) and [Known Issues](docs/release/known-issues.md) 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)`.

| Family | Covered commands | Stata 17 comparisons | Max coefficient deviation | Max SE deviation |
|---|---|---:|---:|---:|
| Linear / FE | `regress`, `areg`, `xtreg_fe`, `reghdfe` | 18/18 | 2.48e-7 | 2.25e-7 |
| IV | `ivregress_2sls`, `ivreghdfe` | 5/5 | 1.16e-8 | 3.74e-8 |
| Binary / count | `logit`, `probit`, `poisson`, `ppmlhdfe` | 12/12 | 1.33e-7 | 8.42e-8 |
| DID | `did_imputation`, `csdid`, `eventstudyinteract` | 2/2 + 1 functional check | 8.13e-8 | 5.13e-8 |
| RD | `rdrobust` | 3/3 | 9.23e-8 | 2.96e-8 |
| **Total** | **14 public estimation commands** | **40/40** | **2.48e-7** | **2.25e-7** |

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`](research/results/validation/evidence-summary.json).

## Documentation

- [User Guide](docs/USER_GUIDE.md) ([中文](docs/USER_GUIDE.zh-CN.md))
- [Cookbook](docs/cookbook.md) ([中文](docs/cookbook.zh-CN.md))
- [Examples](examples/) — nine deterministic demo scripts covering all 14 public commands; no network or local Stata required
- [Validation Evidence (JSON)](research/results/validation/evidence-summary.json)
- [Validation Evidence (readable)](research/results/validation/evidence-summary.md)
- [Changelog](CHANGELOG.md)

## Running Tests

```bash
# Unit and integration tests
pytest tests/ -v

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

## Community

- [Contributing Guide](CONTRIBUTING.md) — development workflow, testing requirements, and PR checks
- [Security Policy](SECURITY.md) — supported versions and private vulnerability reporting
- [Code of Conduct](CODE_OF_CONDUCT.md)

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
