StataFlow 0.1.0__py3-none-any.whl

stataflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: StataFlow
+Version: 0.1.0
+Summary: Stata2Python: 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 :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Stata2Python
+
+Stata2Python (`statapy`) is a Python econometrics toolkit that reproduces Stata 17 estimation results with high precision. It provides both a **Stata-compatible command layer** (for researchers migrating from Stata) and a **native Python estimator layer** (for advanced users who want direct control).
+
+## What you can do today
+
+- Run Stata-style commands in Python: `regress`, `reghdfe`, `ivregress 2sls`, `logit`, `ppmlhdfe`, `did_imputation`, `csdid`, `rdrobust`, and more.
+- Obtain coefficients, standard errors, t/z-statistics, p-values, and confidence intervals that are field-level verified against Stata 17.
+- Work with high-dimensional fixed effects (HDFE), IV/2SLS, binary/count models, and DID/event-study estimators.
+- Use Stata-style factor-variable syntax (`i.group##c.post`, `c.x1#c.x2`, `x1##x2`) and space-separated absorb strings directly in wrapper commands. Bare variables inside `#` / `##` are treated as continuous, matching common Stata usage.
+
+## What is not yet supported
+
+- **Multi-way clustering** — only single-cluster robust inference is available.
+- **Direct post-estimation on wrapper returns** — the `compat.stata` wrappers return `ResultSchema` result objects. `predict` and `margins` are available on the core estimator layer only.
+- **Full command surfaces for community commands** — `reghdfe`, `ivreghdfe`, `ppmlhdfe`, `did_imputation`, `eventstudyinteract`, `csdid`, and `rdrobust` are implemented as **verified high-frequency subsets**, not complete Stata command reproductions. Unsupported options are explicitly rejected rather than silently ignored.
+
+### Completeness legend
+
+- **Stable** — synthetic + real-data dual-run verified; core API is unlikely to change.
+- **Alpha** — high-frequency paths are implemented and verified, but the command surface is still a subset of the full Stata community command.
+- **Alpha — Partial** — a verifiable implementation exists, but large functional areas are still missing (e.g., fuzzy RD for `rdrobust`, multi-way clustering).
+
+See the [Command Support Matrix](./docs/command-support-matrix/README.md) for the per-command detailed status.
+For the public Stata-vs-Python evidence book, see [Validation Overview](./docs/validation/overview.md).
+
+---
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Requirements: Python 3.10+, NumPy, pandas, SciPy.
+
+---
+
+## Quick start
+
+### Stata-compatible command layer (recommended)
+
+All `compat.stata` wrappers return a `ResultSchema` object with coefficients, standard errors, and fit statistics. They do **not** expose `.predict()` or `.margins()` directly—use the core estimator layer below for post-estimation.
+
+```python
+import pandas as pd
+from statapy.compat.stata import regress, reghdfe, ivregress_2sls, logit
+
+# OLS with robust standard errors
+result = regress(df, y="wage", x=["edu", "exper"], vce="robust")
+
+# High-dimensional fixed effects (reghdfe)
+result = reghdfe(
+    df, y="wage", x=["edu", "exper"],
+    absorb="firm_id year_id", vce="cluster", cluster="industry"
+)
+
+# Factor-variable syntax in HDFE
+result = reghdfe(
+    df, y="wage", x=["i.industry##c.post"], absorb="firm_id year_id"
+)
+
+# 2SLS
+result = ivregress_2sls(
+    df, y="lwage", x_exog=["edu"], x_endog=["exper"],
+    instruments=["age", "kidslt6"], vce="robust"
+)
+
+# Logit
+result = logit(df, y="inlf", x=["nwifeinc", "educ", "exper"])
+```
+
+For runnable examples, see the [`examples/`](./examples/) directory:
+- [`examples/demo_regress.py`](./examples/demo_regress.py)
+- [`examples/demo_reghdfe.py`](./examples/demo_reghdfe.py)
+- [`examples/demo_ppmlhdfe.py`](./examples/demo_ppmlhdfe.py)
+- [`examples/demo_ivregress_2sls.py`](./examples/demo_ivregress_2sls.py)
+
+### Native Python estimator layer (advanced)
+
+```python
+from statapy import OLS, FixedEffectsOLS, AbsorbingOLS, Logit, IV2SLS
+
+model = OLS(data=df, y="wage", x=["edu", "exper"])
+result = model.fit(vce="robust")
+```
+
+---
+
+## Supported commands
+
+| Command | Python entry | Core capabilities |
+|---------|--------------|-------------------|
+| `regress` | `statapy.compat.stata.regress` | OLS, robust, cluster, aweight |
+| `xtreg, fe` | `statapy.compat.stata.xtreg_fe` | Fixed effects (within), cluster |
+| `areg` | `statapy.compat.stata.areg` | Single absorb variable FE |
+| `reghdfe` | `statapy.compat.stata.reghdfe` | 1-2 group HDFE, cluster, singleton drop |
+| `ivregress 2sls` | `statapy.compat.stata.ivregress_2sls` | 2SLS, robust, cluster |
+| `ivreghdfe` | `statapy.compat.stata.ivreghdfe` | IV + 1-2 group HDFE, cluster |
+| `logit` | `statapy.compat.stata.logit` | MLE, robust, cluster |
+| `probit` | `statapy.compat.stata.probit` | MLE, robust, cluster |
+| `poisson` | `statapy.compat.stata.poisson` | MLE, robust, cluster |
+| `ppmlhdfe` | `statapy.compat.stata.ppmlhdfe` | PPML + 1-2 group HDFE |
+| `did_imputation` | `statapy.compat.stata.did_imputation` | BJS DID imputation |
+| `eventstudyinteract` | `statapy.compat.stata.eventstudyinteract` | Sun & Abraham IW estimator |
+| `csdid` | `statapy.compat.stata.csdid` | Callaway-Sant'Anna DID (`method="reg"` only) |
+| `rdrobust` | `statapy.compat.stata.rdrobust` | Sharp RD local polynomial (`bwselect="mserd"`, `covs`) |
+
+Full details: [`docs/command-support-matrix/README.md`](./docs/command-support-matrix/README.md)
+
+---
+
+## Validation philosophy
+
+Every public command is validated with **two lines of evidence**:
+
+1. **Synthetic / controlled cases** — formula, degrees of freedom, sample screening, edge cases.
+2. **Real public datasets** — field-level comparison against Stata 17 on openly available economic/financial data.
+
+A command is considered "done" only when both lines pass and the source-to-Python mapping is documented. We do not accept "statistical equivalence" without explicit mathematical or source-code justification.
+
+Public evidence entry points:
+
+- [Validation Overview](./docs/validation/overview.md)
+- [Evidence Matrix](./docs/validation/evidence-matrix.md)
+- [Dataset Registry](./docs/validation/dataset-registry.md)
+- [Validation Policy](./docs/validation/validation-policy.md)
+
+### Running tests
+
+```bash
+# Unit and integration tests (fast)
+pytest tests/ -v --ignore=tests/golden/
+
+# Golden dual-run tests (require Stata 17)
+pytest tests/golden/ -v
+```
+
+---
+
+## Project structure
+
+- **`src/statapy/estimators/`** — Core Python estimators (`OLS`, `AbsorbingOLS`, `Logit`, `PPMLHDFE`, `DIDImputation`, etc.)
+- **`src/statapy/compat/stata/`** — Stata command wrappers (`regress()`, `reghdfe()`, `ivregress_2sls()`, etc.)
+- **`docs/research/`** — Source-to-Python mapping documents for community commands
+- **`docs/command-support-matrix/`** — Per-command support matrices
+- **`tests/golden/`** — Stata-Python dual-run tests
+- **`research/vendor/stata_community/`** — Local mirrors of open-source Stata community packages (for research only)
+
+---
+
+## Default target version
+
+**Stata 17**
+
+---
+
+## Documentation
+
+- [Project charter](./docs/project-charter.md)
+- [Architecture overview](./docs/architecture/overview.md)
+- [Public API specification](./docs/architecture/public-api.md)
+- [Command support matrices](./docs/command-support-matrix/README.md)
+- [Validation overview](./docs/validation/overview.md)
+- [Validation evidence matrix](./docs/validation/evidence-matrix.md)
+- [Open-source roadmap](./docs/next-round-open-source-plan.md)
+
+---
+
+## Governance
+
+- **Codex** — project goals, architecture, review gates, and statistical-dispute arbitration.
+- **Claude Code** — implementation, testing, and evidence backfill.

stataflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+stataflow-0.1.0.dist-info/licenses/LICENSE,sha256=5TXa9okNO3fzbq7a1xXt3UDr9EuyTNubGoEVe5nZhkk,1067
+statapy/__init__.py,sha256=YIF_oMVUROS6PkRMLaLvdFg8YIMwROacjZkHaqFyCyY,1282
+statapy/postestimation.py,sha256=HTQIoQJwvgobb1XwVO1vbij1lDY-mOQ7AyOOA9E0qZI,5053
+statapy/compat/__init__.py,sha256=adn0FmgFGTZACXQKTBps4GQfWOks5ArrWt8_-x3Upis,62
+statapy/compat/stata/__init__.py,sha256=c_VSYmJa9XkEeBpMtIhYKiOvk1xjKLGVcub021ODxA4,553
+statapy/compat/stata/did.py,sha256=LZq1JQZSBiCiwndG8MrP-vI0Mw4EDyQpa8GAIqA3Tbs,3715
+statapy/compat/stata/factor_variables.py,sha256=Q77FJHxtKA01Qi0-PnFBfpatfJ2DUshjc38Q1G2zY9M,12848
+statapy/compat/stata/glm.py,sha256=1ISOca1ep1FM0asIZkWKaw0DYyCrNR7pgvPPC7L2C0I,2507
+statapy/compat/stata/hdfe.py,sha256=r16hKEYqoFeq3lgyrmv198IjnWHF0oFaYydTPSvn9Wc,2460
+statapy/compat/stata/iv.py,sha256=GgV6PLExt-JZZjOb-OeISMgywVEKyFv338b_Yx8vN2c,2632
+statapy/compat/stata/linear.py,sha256=IF4YlksLIoIVp4gz_YZx0Yj7U0wWGcwHvLQbwQJlvvc,2665
+statapy/compat/stata/rdrobust.py,sha256=K2CoACF11_ewBFwPvXHwDAP164g90JoHtoWgzpbOPzY,2994
+statapy/estimators/__init__.py,sha256=wRSG4eHCPBxh2QH2KhECmMqqv8Ai-1raqT_R89SqfpQ,562
+statapy/estimators/absorbing_ols.py,sha256=sUhjhNr1eSNctu1l92OmXPRtuuJSqLENLoUv26feyyw,22634
+statapy/estimators/csdid.py,sha256=zJ0aQircVG49apA3VdYyfObe3YQFdG55aDqR2jy5Pzs,13073
+statapy/estimators/did_imputation.py,sha256=reomGLMozcj9NuwMu7_acT68FR0GPZK7v8gdCbrvQaI,13443
+statapy/estimators/eventstudyinteract.py,sha256=EycYGLohKVm2KEVZY-TjWL7CEdvKn1Vmwd5h_7Ifpr0,11391
+statapy/estimators/fe.py,sha256=Xje_lTi6-WyVGkVT2oYS1bEI4ukL0a8GHhT9sp8E5OA,18209
+statapy/estimators/glm.py,sha256=6eucthcwzj8S-VybDjgE-m9sO72HVZNhBAg-YYtvU64,21966
+statapy/estimators/iv.py,sha256=fTANtgAS9UklTmgf71Z0nGErGnekJYDwQVxBn_1uAXI,35461
+statapy/estimators/ols.py,sha256=Bp361VmzDNCbgg4pp7EbYpl0PJzFB454ZLGglvrkdbA,21082
+statapy/estimators/ppmlhdfe.py,sha256=H_zNTa1RIy2f_FJbyfweqn7QntYx_OcUecQ9RbYjm4U,19253
+statapy/estimators/rdrobust.py,sha256=BL640j4u-aC7RfvWLnbh1hrXwT-iGT94er724Q0KvLM,29895
+statapy/results/__init__.py,sha256=2SscS-GXX9jaBiAOGcYBY7HW2XgxkLKTTF2tq3RIrDM,129
+statapy/results/result.py,sha256=-5iSo9QZcY43png0U8hB1sq8T_-nGJ2_iETn-Q9PYI4,6666
+statapy/stata_runner/__init__.py,sha256=eT9p_rD-oLJhktoxCBAfgQqmIHeRtQoQQkZxxrjN2Pg,121
+statapy/stata_runner/runner.py,sha256=FoSnGu2t71pMTBCVluaU-C-7EoMW8HMhIeEKHWo_ios,6893
+stataflow-0.1.0.dist-info/METADATA,sha256=sSW9UTXZYpbxkWHnBiZU-QFhQCCEIXCyB0yrFLNY9Rc,8912
+stataflow-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+stataflow-0.1.0.dist-info/top_level.txt,sha256=CTAQy1sKi_620Uyq2UtGJYax126Pr4USUG369LAXglM,8
+stataflow-0.1.0.dist-info/RECORD,,

stataflow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stataflow-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhenhao Fu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stataflow-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+statapy

statapy/__init__.py

@@ -0,0 +1,74 @@
+"""
+Stata2Python (statapy) — A Python econometrics toolkit aligned with Stata 17.
+Provides a Stata-compatible command layer and native Python estimators,
+with field-level dual-run verification.
+"""
+
+__version__ = "0.1.0"
+
+# Core estimators (Python-native API)
+from .estimators import (
+    OLS,
+    FixedEffectsOLS,
+    AbsorbingOLS,
+    IV2SLS,
+    IVAbsorbingOLS,
+    Logit,
+    Probit,
+    Poisson,
+    PPMLHDFE,
+    DIDImputation,
+    EventStudyInteract,
+    CSDID,
+    RDRobust,
+)
+
+# Stata compatibility commands
+from .compat.stata import (
+    regress,
+    xtreg_fe,
+    areg,
+    reghdfe,
+    ivregress_2sls,
+    ivreghdfe,
+    logit,
+    probit,
+    poisson,
+    ppmlhdfe,
+    did_imputation,
+    eventstudyinteract,
+    csdid,
+    rdrobust,
+)
+
+__all__ = [
+    # Core estimators
+    "OLS",
+    "FixedEffectsOLS",
+    "AbsorbingOLS",
+    "IV2SLS",
+    "IVAbsorbingOLS",
+    "Logit",
+    "Probit",
+    "Poisson",
+    "PPMLHDFE",
+    "DIDImputation",
+    "EventStudyInteract",
+    "CSDID",
+    "RDRobust",
+    # Stata compatibility commands
+    "regress",
+    "xtreg_fe",
+    "areg",
+    "reghdfe",
+    "ivregress_2sls",
+    "ivreghdfe",
+    "logit",
+    "probit",
+    "poisson",
+    "ppmlhdfe",
+    "did_imputation",
+    "eventstudyinteract",
+    "csdid",
+    "rdrobust",
+]

statapy/compat/__init__.py

@@ -0,0 +1 @@
+"""Compatibility layers for external statistical software."""

statapy/compat/stata/__init__.py

@@ -0,0 +1,25 @@
+"""Stata command compatibility layer for statapy."""
+
+from .linear import regress, xtreg_fe, areg
+from .hdfe import reghdfe, ppmlhdfe
+from .iv import ivregress_2sls, ivreghdfe
+from .glm import logit, probit, poisson
+from .did import did_imputation, eventstudyinteract, csdid
+from .rdrobust import rdrobust
+
+__all__ = [
+    "regress",
+    "xtreg_fe",
+    "areg",
+    "reghdfe",
+    "ivregress_2sls",
+    "ivreghdfe",
+    "logit",
+    "probit",
+    "poisson",
+    "ppmlhdfe",
+    "did_imputation",
+    "eventstudyinteract",
+    "csdid",
+    "rdrobust",
+]

statapy/compat/stata/did.py

@@ -0,0 +1,142 @@
+"""Stata DID command wrappers."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from statapy.estimators import DIDImputation, EventStudyInteract, CSDID
+
+
+def did_imputation(
+    data,
+    y: str,
+    id: str,
+    time: str,
+    first_treat: str,
+    *,
+    cluster: Optional[str] = None,
+    allhorizons: bool = False,
+    autosample: bool = False,
+    **kwargs,
+) -> object:
+    """
+    Stata-compatible wrapper for ``did_imputation``.
+
+    Maps to :class:`statapy.estimators.DIDImputation`.
+    """
+    if kwargs:
+        raise ValueError(f"Unsupported arguments: {list(kwargs.keys())}")
+
+    model = DIDImputation(
+        data=data,
+        y=y,
+        id=id,
+        time=time,
+        first_treat=first_treat,
+    )
+    return model.fit(cluster=cluster, allhorizons=allhorizons, autosample=autosample)
+
+
+def eventstudyinteract(
+    data,
+    y: str,
+    *,
+    cohort: str,
+    control_cohort: str,
+    absorb: list[str],
+    event_dummies: Optional[list[str]] = None,
+    time: Optional[str] = None,
+    first_treat: Optional[str] = None,
+    horizons: Optional[list[int]] = None,
+    omit: Optional[int] = None,
+    vce: str = "ols",
+    cluster: Optional[str] = None,
+    **kwargs,
+) -> object:
+    """
+    Stata-compatible wrapper for ``eventstudyinteract``.
+
+    Maps to :class:`statapy.estimators.EventStudyInteract`.
+
+    Parameters
+    ----------
+    event_dummies : list[str], optional
+        Pre-generated relative-time dummy variable names. If provided,
+        ``time``, ``first_treat``, and ``horizons`` are ignored.
+    time, first_treat, horizons, omit
+        Alternative auto-generation mode. The wrapper creates dummy
+        variables ``Dm{h}`` (for ``h < 0``), ``D0``, or ``Dp{h}``
+        (for ``h > 0``) on a copy of ``data``. The horizon ``omit``
+        is excluded as the reference category.
+    """
+    if kwargs:
+        raise ValueError(f"Unsupported arguments: {list(kwargs.keys())}")
+
+    df = data.copy()
+
+    if event_dummies is not None:
+        used_event_dummies = list(event_dummies)
+    else:
+        if time is None or first_treat is None or horizons is None:
+            raise ValueError(
+                "Either event_dummies or (time, first_treat, horizons) must be provided."
+            )
+        if omit is not None and omit not in horizons:
+            raise ValueError("omit must be one of the horizons.")
+
+        used_event_dummies = []
+        rel_time = df[time] - df[first_treat]
+        rel_time = rel_time.where(df[first_treat] > 0, -1000)
+
+        for h in horizons:
+            if h == omit:
+                continue
+            if h < 0:
+                col = f"Dm{abs(h)}"
+            elif h == 0:
+                col = "D0"
+            else:
+                col = f"Dp{h}"
+            df[col] = (rel_time == h).astype(float)
+            used_event_dummies.append(col)
+
+    model = EventStudyInteract(
+        data=df,
+        y=y,
+        event_dummies=used_event_dummies,
+        cohort=cohort,
+        control_cohort=control_cohort,
+        absorb=absorb,
+    )
+    return model.fit(vce=vce, cluster=cluster)
+
+
+def csdid(
+    data,
+    y: str,
+    id: str,
+    time: str,
+    first_treat: str,
+    *,
+    method: str = "reg",
+    vce: Optional[str] = None,
+    cluster: Optional[str] = None,
+    **kwargs,
+) -> object:
+    """
+    Stata-compatible wrapper for ``csdid``.
+
+    Maps to :class:`statapy.estimators.CSDID`.
+    """
+    if kwargs:
+        raise ValueError(f"Unsupported arguments: {list(kwargs.keys())}")
+
+    model = CSDID(
+        data=data,
+        y=y,
+        id=id,
+        time=time,
+        first_treat=first_treat,
+    )
+    model.fit(method=method, vce=vce, cluster=cluster)
+    return model.estat_event()