Empirical Research Standards

English documentation comes first. A concise, detail-equivalent Chinese version follows.

empirical-research-standards is a small, transparent, and testable toolkit for empirical research. It provides Python APIs for data validation, foundational econometrics, diagnostics, reporting, and Agent workflows. Specialist estimators with established R implementations are available through explicit, version-locked R backends behind the same Python-facing workflow.

Status

Version 1.0.0 provides an installable Python package, explicit R estimator backends, and a repository-distributed Agent Skill. Capabilities are grouped by maturity rather than presented as equally complete. The main branch is preparing V1.1 and includes sample-audit and regression-discontinuity increments.

Core building blocks:

• read-only candidate-sample audits with column missingness, complete and finite-case counts, numeric distributions, bounded categorical frequencies, and missingness patterns;
• explicit table schemas, exportable validation reports, cardinality-checked merges, and panel diagnostics;
• validated OLS with classical, HC1, and one-way clustered covariance;
• one-way and two-way fixed effects with robust and one-/two-way clustered covariance;
• classic treated-by-post DID;
• sharp and fuzzy regression discontinuity through the official Python rdrobust package, including robust bias-corrected inference, explicit bandwidth/support tables, fuzzy first-stage output, cutoff-support audit, and an rddensity manipulation diagnostic;
• standardized model tables, plot-ready data, CSV/Excel/LaTeX exports, and reproducibility metadata;
• the apply-empirical-standards Agent Skill for auditable data-to-result workflows;
• research-grade Callaway--Sant'Anna group-time DID through did::att_gt, and Sun--Abraham event studies through fixest::sunab, including support, aggregation weights, confidence intervals, pretrend tests, warnings, provenance, and structured results.

Stable advanced components:

• TWFE event studies with support tables and an explicit staggered-adoption warning boundary;
• categorical FE interaction tests, placebo timing, covariance sensitivity, and leave-one-cluster-out diagnostics;
• production wild-cluster bootstrap through the optional R fwildclusterboot backend;
• explicit IV/2SLS with first-stage, Wu-Hausman, Sargan, and robust Wooldridge score tests;
• multi-endogenous-variable sample-rank and conditional relevance diagnostics;
• high-dimensional fixed-effects panel IV/2SLS through R fixest, plus single-endogenous-variable Anderson-Rubin weak-identification-robust tests and grid-inverted confidence sets;
• Bonferroni, Holm, and Benjamini-Hochberg multiple-testing adjustments;
• deterministic Python-R numerical benchmarks for fixed effects, 2SLS, and RD.

Educational Python staggered-treatment estimators, subgroup fits, generic treatment permutation, and the restricted Python wild bootstrap now live under empirical_standards.experimental. The indicator and pyhdfe panel-IV paths remain internal verification backends rather than the recommended complex-FE workflow.

Deferred: a custom general KP implementation, spatial econometrics, machine-learning validation, data version management, figure rendering, and a complete publication-table framework. See the capability matrix for exact boundaries.

This is a working methodological foundation, not a complete econometrics library.

Principles

• Correctness and explicit specifications before convenience.
• Reproducible environments, deterministic examples, and tested outputs.
• Independent modules that can be adopted and verified separately.
• Small additions driven by concrete research workflows.
• Results that can be cross-checked against R or direct Python library calls.
• Every computational backend is declared, versioned, tested, and recorded in result provenance; see the backend policy.
• No causal or substantive interpretation without defensible research assumptions.

The project does not choose a causal design for the researcher or replace inspection of source data, assignment mechanisms, identification assumptions, and software-specific conventions. Use the bilingual model-selection guide before choosing an estimator.

Install and verify

Install uv, then run:

uv sync
uv run pytest
uv run ruff check .
uv run mypy
uv build

Regression discontinuity is an optional method group because its official upstream packages include plotting dependencies even though this project only prepares plotting data:

uv sync --extra rd

Quick start

OLS

import pandas as pd
from empirical_standards import fit_ols

data = pd.DataFrame({
    "y": [1.0, 2.2, 2.8, 4.1, 5.2, 5.8],
    "x": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0],
    "region": [1, 1, 1, 2, 2, 2],
})

result = fit_ols(
    data,
    outcome="y",
    predictors=["x"],
    covariance="cluster",
    cluster="region",
)
print(result.tidy())

Missing values raise an error by default. Set drop_missing=True to explicitly request complete-case estimation. See the OLS specification.

Panel fixed effects and DID

from empirical_standards import fit_did, fit_fixed_effects

fe = fit_fixed_effects(
    data, "y", ["x"], entity="city", time="year",
    time_effects=True, covariance="cluster_two_way",
)
did = fit_did(
    data, "y", "treated", "post", entity="city", time="year",
    controls=["x"], covariance="cluster_entity",
)

The causal module also includes dynamic TWFE and educational Python reference implementations for inspecting cohort-time comparisons and cohort-interacted design matrices. See panel and DID conventions for identification and inference limits.

For heterogeneous staggered adoption, use the explicit mature backends:

from empirical_standards import fit_staggered_did_r, fit_sun_abraham_r

group_time = fit_staggered_did_r(
    data, "y", entity="city", time="year", treatment_time="treatment_year",
    controls=["x"], method="dr", control_group="not_yet_treated",
)
dynamic = fit_sun_abraham_r(
    data, "y", "treatment_year", entity="city", time="year", controls=["x"],
)

Install R, then from r/ run Rscript -e 'renv::restore()'. Backend failure is explicit; no statistically different Python estimator is substituted. See the strict audit. The complete staggered-treatment example exports every support, weight, inference, warning, specification, and provenance component.

Data validation

from empirical_standards.data import audit_sample, diagnose_panel, merge_validated

merged = merge_validated(panel, attributes, on="city", relationship="many_to_one")
sample = audit_sample(
    merged.data,
    columns=["city", "year", "outcome", "treatment", "region"],
    required_columns=["city", "year", "outcome", "treatment"],
)
sample.export("outputs/sample_audit")

diagnostics = diagnose_panel(
    merged.data, entity="city", time="year", variables=["outcome", "treatment"]
)
print(sample.summary())
print(diagnostics.summary())

The audit is descriptive: it never coerces, imputes, drops rows, or diagnoses a missingness mechanism. See data-validation conventions.

Regression discontinuity

from empirical_standards import (
    audit_regression_discontinuity,
    fit_regression_discontinuity,
    test_rd_density,
)

audit = audit_regression_discontinuity(data, "score", 0.0, treatment="received")
rd = fit_regression_discontinuity(
    data,
    outcome="outcome",
    running="score",
    cutoff=0.0,
    design="fuzzy",
    treatment="received",
    covariates=["baseline"],
    p=1,
    q=2,
    kernel="triangular",
    bwselect="mserd",
    vce="nn",
    masspoints="adjust",
)
density = test_rd_density(data, "score", 0.0)

print(rd.tidy())
print(rd.tidy("first_stage"))
print(rd.tidy("bandwidths"))
print(rd.tidy("support"))
print(density.tidy())

The primary row is the robust bias-corrected interval, while conventional and bias-corrected rows remain visible for audit. Density-test non-rejection does not prove absence of manipulation, and RD estimates are local to the cutoff. The stable fuzzy interface currently requires a binary treatment and always exposes its first stage. See the bilingual RD specification.

IV/2SLS

from empirical_standards import fit_iv_2sls

iv = fit_iv_2sls(
    data,
    "outcome",
    exogenous=["control"],
    endogenous=["treatment"],
    instruments=["instrument_1", "instrument_2"],
    covariance="cluster",
    cluster="region",
)
print(iv.first_stage)

First-stage statistics retain their actual reference distribution; robust Wald statistics are not mislabeled as conventional F statistics. See the IV/2SLS specification.

Complex panel IV uses the same explicit variable roles and delegates high-dimensional fixed effects and covariance handling to R fixest through fit_panel_iv_2sls_r. Anderson-Rubin tests support controls, fixed effects, robust covariance, and clustering; grid inversion retains every accepted value rather than assuming a connected interval. See panel IV and Anderson-Rubin inference.

The Python indicator and pyhdfe within paths remain available for transparent numerical verification. Conditional relevance Wald tests and rank summaries retain their literal names and are not presented as a custom general KP implementation.

Results and exports

Every model result provides tidy(), glance(), model_spec(), sample_info(), and provenance(). The sample metadata includes a deterministic fingerprint of the exact estimation data.

from empirical_standards.reporting import collect_models, export_model_collection

collection = collect_models({"baseline": baseline, "twfe": twfe, "did": did})
export_model_collection(collection, "outputs", prefix="main_results")

See the result contract, reporting specification, and cross-software benchmarks. Python-R fixed-effects, 2SLS, and RD benchmarks are executed and tested.

Runnable examples

uv run python examples/ols_example.py
uv run python examples/fixed_effects_example.py
uv run python examples/did_example.py
uv run python examples/rdd_example.py
uv run python examples/panel_did_example.py
uv run python examples/staggered_did_r_example.py
uv run python examples/data_validation_example.py
uv run python examples/research_workflow.py

The OLS example writes outputs/ols_clustered.csv. Other examples print deterministic model and diagnostic results. The recommended end-to-end workflow writes a design manifest, panel audit, primary models, robustness diagnostics, and standardized result metadata to outputs/research_workflow. See the bilingual workflow guide. The three separate foundational examples and their interpretation limits are documented in the bilingual examples guide.

Agent Skill

The repository includes apply-empirical-standards as a core product for research agents. It guides an agent through data audit, a written design statement, estimator selection, design-matched diagnostics, standardized exports, and cross-software verification. It does not automate identification claims or choose a model from statistical significance.

Copy or symlink skills/apply-empirical-standards into the skill directory used by the target agent, then invoke $apply-empirical-standards. From this checkout, verify its required package APIs with:

uv run python skills/apply-empirical-standards/scripts/check_environment.py

The Skill is versioned with the package so that its workflow and API patterns can evolve with implemented methods. Its references use repository-relative docs/ paths; give the agent access to this checkout when detailed method specifications are required.

Repository layout

src/empirical_standards/  Installable package
  data/                   Sample audits, schemas, merge checks, and panel diagnostics
  models/                 OLS and IV/2SLS
  panel/                  Fixed-effects estimation
  causal/                 DID, event-study, and regression-discontinuity estimators
  diagnostics/            Heterogeneity, robustness, and resampling inference
  experimental/           Teaching and compatibility references outside the stable API
  results/                Shared metadata contract
  reporting/              Tables, plotting data, and exports
tests/                    Numerical, validation, and cross-software tests
benchmarks/               Deterministic Python-R benchmark assets
examples/                 Runnable deterministic workflows
docs/                     Method specifications and limitations
skills/                   Agent workflows and progressive references
r/                        Optional version-locked advanced statistical backends
.github/workflows/        Continuous integration

Roadmap

V1.1 development includes descriptive sample audits and the first stable regression-discontinuity family, verified against both official Python packages and locked R packages. The next RD increment should add prespecified covariate-continuity families and bandwidth sensitivity tables before broadening to another causal design. The project does not render figures. Spatial econometrics, machine-learning validation, and complete publication tables remain deferred.

See CONTRIBUTING.md before proposing a method. Every estimator must document its estimand, assumptions, sample rules, defaults, covariance convention, failure modes, runnable example, numerical tests, and external-comparison strategy.

License

MIT

---

中文说明

empirical-research-standards 是一套小型、透明、可测试的实证研究工具。项目以 Python API 统一数据校验、基础计量、诊断、输出和 Agent 工作流；已有成熟 R 实现的专业估计器通过显式、 锁定版本的 R 后端提供，并纳入相同的 Python 工作流与结果记录。

当前状态

当前版本为 1.0.0，产品包括 Python 包、显式 R 估计后端和 Agent Skill。功能按成熟度区分： 主分支正在开发 V1.1，并已加入样本审计和回归不连续设计增量。

核心功能：

• 只读候选样本审计：列级缺失、完整与有限案例数、数值分布、截断可见的分类频数和缺失模式；
• 显式表级 schema、可导出验证报告、带基数约束的数据合并与面板诊断；
• OLS，以及经典、HC1、单向聚类协方差；
• 单向/双向固定效应，以及稳健、单向/双向聚类协方差；
• 经典 DID；
• 通过官方 Python rdrobust 实现 sharp/fuzzy RD，保留稳健偏误修正推断、左右带宽、有效 样本、fuzzy 第一阶段和断点审计，并通过 rddensity 提供操纵诊断；
• 标准结果、元数据和 CSV/Excel/LaTeX 导出；
• apply-empirical-standards Agent Skill；
• 通过 did::att_gt 实现成熟的 Callaway--Sant'Anna 交错 DID；通过 fixest::sunab 实现 Sun--Abraham 事件研究，并输出支持、聚合权重、置信区间、前趋势检验、warnings 和来源信息。

稳定进阶功能：

• TWFE 事件研究及事件期样本支持表；
• 正式 FE 交互异质性、安慰剂、协方差敏感性和 LOCO；
• 通过可选 R fwildclusterboot 提供正式 wild cluster bootstrap；
• 显式 IV/2SLS，以及第一阶段、Wu-Hausman、Sargan、稳健 Wooldridge score 检验；
• 多内生变量样本秩与条件相关性辅助诊断；
• 通过 R fixest 提供高维固定效应面板 IV/2SLS，并保留单内生变量 AR 检验和网格反演；
• Bonferroni、Holm、Benjamini-Hochberg 多重检验校正；
• 固定效应、2SLS 和 RD 的确定性 Python-R 数值基准。
• Python 教学型交错 DID、cohort-interaction、分组回归、通用置换和受限 Python wild bootstrap 已移入 empirical_standards.experimental。
• Python 指示变量与 pyhdfe 面板 IV 保留作数值核验，不再作为复杂 FE 的推荐工作流。
• 空间计量、机器学习、数据版本管理、实际绘图和完整论文制表暂缓。准确边界见功能矩阵。
• apply-empirical-standards Agent Skill：规范数据审计、估计器选择、设计匹配的诊断、标准输出和跨软件核验。

这仍是方法基础，不是完整计量经济学库。

原则与边界

• 正确性和显式设定优先；环境、示例和输出可复现并经过测试。
• 模块保持独立，按真实研究需求小步扩展，并支持 Python-R 或 Python 底层库交叉验证。
• 项目不替研究者选择因果设计，也不替代对源数据、处理分配机制、识别假设和软件约定的审查，不自动解释实质性或因果含义。
• 选择估计器前请阅读中英文模型选择指南，其中列出适用条件、最低诊断和停止条件。

安装与验证

安装 uv 后运行：

uv sync
uv run pytest
uv run ruff check .
uv run mypy
uv build

RDD 使用可选依赖，运行 uv sync --extra rd 安装。上游包包含绘图库，但本项目仍只输出 绘图前数据，不负责绘图。

使用方式

上方英文部分给出了完整可运行代码。核心入口如下：

• fit_ols：OLS；默认拒绝缺失值，仅在 drop_missing=True 时进行完整案例估计，详见 OLS 规范。
• fit_fixed_effects、fit_did：固定效应和经典 DID；因果模块还包括 TWFE 动态效应、带实体聚类 bootstrap 的 cohort-time ATT、Sun-Abraham，识别与推断限制见 面板与 DID 规范。
• fit_staggered_did_r、fit_sun_abraham_r：复杂交错处理的推荐入口，分别对接 R 的 did 与 fixest。在 r/ 运行 Rscript -e 'renv::restore()' 恢复锁定依赖；后端不可用时会明确失败，不会静默换模型。严格差异见交错 DID 审计。
• 完整交错处理示例会导出支持、权重、推断、warnings、模型设定和来源信息。
• audit_sample：估计前只读报告候选样本的缺失、有限值、分布和分类频数；不转换、插补、删行 或判断缺失机制。merge_validated、diagnose_panel 约束合并关系并检查面板覆盖、重复键、 singleton 和 within/between 变异，详见数据规范。
• fit_iv_2sls：显式区分外生变量、内生变量和排除工具；第一阶段保留真实参考分布，不把稳健 Wald 统计量误称为传统 F，详见 IV/2SLS 规范。
• fit_panel_iv_2sls_r：推荐的高维固定效应面板 IV 后端；fit_panel_iv_2sls 的指示变量与 pyhdfe 路径保留作核验。anderson_rubin_test 支持单内生变量、控制、固定效应和 稳健/聚类协方差，详见面板 IV 与 AR 规范。
• wild_cluster_bootstrap_fe_r：通过 R fwildclusterboot 执行正式 wild cluster 推断； Python 受限版本仅在 experimental 中保留。
• fit_regression_discontinuity：官方 Python rdrobust 的 sharp/fuzzy 局部多项式 RD； audit_regression_discontinuity 检查断点两侧支持、唯一值、ties 和 mass points； test_rd_density 对接官方 rddensity。主推断是 robust bias-corrected 区间，同时保留 conventional 与 bias-corrected 行；密度检验不拒绝不能证明无操纵，RD 效应不能无依据外推。 当前 fuzzy 接口限二元处理并始终输出第一阶段，详见 RDD 规范。
• collect_models、export_model_collection：统一收集并导出模型结果。

所有模型结果都提供 tidy()、glance()、model_spec()、sample_info()、provenance()；样本元数据包含实际估计数据的确定性指纹。详见 结果协议和输出规范。

跨软件基准见 benchmarks：Python-R 固定效应、2SLS 和 RD 已实际运行并纳入测试。

示例与结构

uv run python examples/ols_example.py
uv run python examples/fixed_effects_example.py
uv run python examples/did_example.py
uv run python examples/rdd_example.py
uv run python examples/panel_did_example.py
uv run python examples/staggered_did_r_example.py
uv run python examples/data_validation_example.py
uv run python examples/sample_audit_example.py
uv run python examples/research_workflow.py

OLS、固定效应和经典 DID 现有独立可运行示例，均导出设计说明、标准结果和针对性诊断，详见中英文基础示例指南。推荐的端到端示例会在 outputs/research_workflow 生成完整审计链，详见工作流指南。

Agent Skill

仓库将 apply-empirical-standards 作为核心产品：引导 Agent 依次完成数据审计、书面设计声明、估计器选择、匹配研究设计的诊断、标准导出与跨软件核验；它不会自动宣称识别成立，也不会按显著性选模型。

将 skills/apply-empirical-standards 复制或链接到目标 Agent 的 Skill 目录后，以 $apply-empirical-standards 调用。当前仓库内可运行：

uv run python skills/apply-empirical-standards/scripts/check_environment.py

Skill 与 Python 包同步版本管理；其中详细方法链接相对于本仓库，因此需要深读规范时应让 Agent 访问本仓库。

后续方向

V1.1 已加入描述性样本审计和首个稳定 RDD 家族，并用官方 Python 包和锁定 R 包双重核验。 下一步先补预先声明的协变量连续性检验族和带宽敏感性表，再扩展新的因果设计。项目不负责 绘图；空间计量、机器学习和完整论文制表继续暂缓。

贡献新方法前请阅读 CONTRIBUTING.md。每个估计器必须说明估计目标、假设、样本规则、默认值、协方差约定、失败条件、可运行示例、数值测试和外部比较策略。

许可证

MIT