From d0691fc2db432bc79cee1d94a8dcf0218a2bbd7a Mon Sep 17 00:00:00 2001 From: igerber Date: Sat, 27 Jun 2026 19:47:23 -0400 Subject: [PATCH] docs(paper): refresh JOSS paper for current library and submission requirements Update paper.md and paper.bib so the JOSS submission reflects the current library and meets current JOSS requirements. - Correct estimator count 17 -> 19; enumerate all 19 by name and list diagnostics (Goodman-Bacon, Honest DiD, placebo, pre-trends power) separately - Add a mandatory AI Usage Disclosure section (tool/version, scope of assistance, human-verification affirmation) - Cite the companion arXiv preprint Gerber (2026, 2605.04124) in the Summary, Statement of Need, and Survey-weighted inference section - Soften an overstated survey-validation tolerance (<1e-10 -> test gaps <1e-8, typically <1e-10) and correct "three federal datasets" (the API dataset is California state data, not federal) - Add 4 bib entries (Gerber2026, Abadie2010, Butts2021, deChaisemartin2026) and add arXiv/Springer DOIs across the bibliography - Remove the Acknowledgments section (Wenli Xu remains credited in CONTRIBUTORS.md) - Update date to 3 July 2026 Docs-only change to the paper files; no library code touched. Co-Authored-By: Claude Opus 4.8 (1M context) --- paper.bib | 65 ++++++++++++++++++++++++++++++++++++++++++----- paper.md | 76 +++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 106 insertions(+), 35 deletions(-) diff --git a/paper.bib b/paper.bib index 898da4a86..6aa53f0d1 100644 --- a/paper.bib +++ b/paper.bib @@ -37,7 +37,8 @@ @misc{Gardner2022 year = {2022}, eprint = {2207.05943}, archiveprefix = {arXiv}, - primaryclass = {econ.EM} + primaryclass = {econ.EM}, + doi = {10.48550/arXiv.2207.05943} } @article{Arkhangelsky2021, @@ -102,7 +103,8 @@ @article{Wooldridge2025 volume = {69}, number = {5}, pages = {2545--2587}, - year = {2025} + year = {2025}, + doi = {10.1007/s00181-025-02807-z} } @article{Wooldridge2023, @@ -132,14 +134,18 @@ @techreport{Callaway2024 institution = {National Bureau of Economic Research}, type = {Working Paper}, number = {32117}, - year = {2024} + year = {2024}, + url = {https://www.nber.org/papers/w32117} } @misc{Chen2025, author = {Chen, Xun and Sant'Anna, Pedro H. C. and Xie, Haitian}, title = {Efficient Difference-in-Differences and Event Study Estimators}, year = {2025}, - note = {Working paper} + eprint = {2506.17729}, + archiveprefix = {arXiv}, + primaryclass = {econ.EM}, + doi = {10.48550/arXiv.2506.17729} } @misc{Athey2025, @@ -148,7 +154,8 @@ @misc{Athey2025 year = {2025}, eprint = {2508.21536}, archiveprefix = {arXiv}, - primaryclass = {econ.EM} + primaryclass = {econ.EM}, + doi = {10.48550/arXiv.2508.21536} } @misc{OrtizVillavicencio2025, @@ -157,7 +164,8 @@ @misc{OrtizVillavicencio2025 year = {2025}, eprint = {2505.09942}, archiveprefix = {arXiv}, - primaryclass = {econ.EM} + primaryclass = {econ.EM}, + doi = {10.48550/arXiv.2505.09942} } @article{Roth2023, @@ -177,7 +185,8 @@ @misc{Baker2025 year = {2025}, eprint = {2503.13323}, archiveprefix = {arXiv}, - primaryclass = {econ.EM} + primaryclass = {econ.EM}, + doi = {10.48550/arXiv.2503.13323} } @article{Lumley2004, @@ -198,3 +207,45 @@ @manual{Berge2018 note = {R package}, url = {https://CRAN.R-project.org/package=fixest} } + +@misc{Gerber2026, + author = {Gerber, Isaac}, + title = {Design-Based Variance Estimation for Modern Heterogeneity-Robust Difference-in-Differences Estimators}, + year = {2026}, + eprint = {2605.04124}, + archiveprefix = {arXiv}, + primaryclass = {stat.ME}, + doi = {10.48550/arXiv.2605.04124} +} + +@article{Abadie2010, + author = {Abadie, Alberto and Diamond, Alexis and Hainmueller, Jens}, + title = {Synthetic Control Methods for Comparative Case Studies: Estimating the Effect of California's Tobacco Control Program}, + journal = {Journal of the American Statistical Association}, + volume = {105}, + number = {490}, + pages = {493--505}, + year = {2010}, + doi = {10.1198/jasa.2009.ap08746} +} + +@misc{Butts2021, + author = {Butts, Kyle}, + title = {Difference-in-Differences with Spatial Spillovers}, + year = {2023}, + note = {Originally posted 2021}, + eprint = {2105.03737}, + archiveprefix = {arXiv}, + primaryclass = {econ.EM}, + doi = {10.48550/arXiv.2105.03737} +} + +@misc{deChaisemartin2026, + author = {{de Chaisemartin}, Cl\'{e}ment and Ciccia, Diego and D'Haultf{\oe}uille, Xavier and Knau, Felix}, + title = {Difference-in-Differences Estimators When No Unit Remains Untreated}, + year = {2026}, + eprint = {2405.04465}, + archiveprefix = {arXiv}, + primaryclass = {econ.EM}, + doi = {10.48550/arXiv.2405.04465} +} diff --git a/paper.md b/paper.md index 8ef255497..a20d75deb 100644 --- a/paper.md +++ b/paper.md @@ -14,20 +14,22 @@ authors: affiliations: - name: Independent Researcher index: 1 -date: 12 April 2026 +date: 3 July 2026 bibliography: paper.bib --- # Summary `diff-diff` is a Python library for Difference-in-Differences (DiD) causal inference -analysis. It provides 17 estimators covering the full modern DiD toolkit - from classic +analysis. It provides 19 estimators covering the full modern DiD toolkit - from classic two-group/two-period designs through heterogeneity-robust staggered adoption methods, synthetic control hybrids, and sensitivity analysis - under a consistent scikit-learn-style API. Most estimators accept an optional `SurveyDesign` object for design-based variance estimation with complex survey data, a capability absent from existing DiD software in any -language. Point estimates are validated against established R packages to machine precision, -with standard errors matching exactly or to sub-percent relative differences. +language; the underlying design-based variance methodology is derived in the companion +preprint [@Gerber2026]. Point estimates are validated against established R packages to +machine precision, with standard errors matching exactly or to sub-percent relative +differences. # Statement of Need @@ -47,34 +49,46 @@ common in industry settings for marketing measurement, product experimentation, evaluation - must either context-switch to R, reimplement methods from scratch, or rely on partial implementations scattered across unrelated packages. -`diff-diff` fills this gap by providing a single-import library that covers 17 estimators -with a consistent API, survey-weighted inference, and numerical validation against R. It targets both applied researchers who need rigorous econometric methods -and data science practitioners who need accessible causal inference tools integrated into -Python workflows. +`diff-diff` fills this gap by providing a single-import library that covers 19 estimators +with a consistent API, survey-weighted inference, and numerical validation against R. It +is also the companion software for the design-based variance framework of @Gerber2026, +which establishes design-consistent standard errors for modern DiD estimators under +complex survey designs. It targets both applied researchers who need rigorous econometric +methods and data science practitioners who need accessible causal inference tools +integrated into Python workflows. # Key Features -**Breadth of methods.** `diff-diff` implements 17 estimators organized across the modern -DiD taxonomy: classic DiD and TWFE; heterogeneity-robust staggered estimators including -Callaway-Sant'Anna [@Callaway2021], Sun-Abraham [@Sun2021], imputation -[@Borusyak2024], two-stage [@Gardner2022], stacked [@Wing2024], and efficient -[@Chen2025] approaches; extended designs including synthetic DiD [@Arkhangelsky2021], -triple difference [@OrtizVillavicencio2025], continuous treatment [@Callaway2024], -nonlinear ETWFE [@Wooldridge2025; @Wooldridge2023], and triply robust panel estimation [@Athey2025]; -reversible-treatment DiD for non-absorbing interventions [@deChaisemartin2020]; and -diagnostics including Goodman-Bacon decomposition [@GoodmanBacon2021], Honest DiD -sensitivity analysis [@Rambachan2023], and pre-trends power analysis [@Roth2022]. All -estimators share a consistent `fit()` interface with `get_params()`/`set_params()` for -configuration, R-style formula support, and rich results objects with `summary()` output. -An optional Rust backend via PyO3 accelerates compute-intensive operations. +**Breadth of methods.** `diff-diff` implements 19 estimators organized across the modern +DiD taxonomy. Classic designs include two-group/two-period DiD, two-way fixed effects, and +event-study estimation with period-specific effects. Heterogeneity-robust staggered-adoption +estimators include Callaway-Sant'Anna [@Callaway2021], Sun-Abraham [@Sun2021], imputation +[@Borusyak2024], two-stage [@Gardner2022], stacked [@Wing2024], and efficient [@Chen2025] +approaches, together with reversible-treatment DiD for non-absorbing interventions +[@deChaisemartin2020] and a ring-indicator estimator for spatial spillovers [@Butts2021]. +Synthetic-control hybrids include synthetic DiD [@Arkhangelsky2021] and the classic +synthetic control method [@Abadie2010]. Extended designs include triple-difference and +staggered triple-difference estimators [@OrtizVillavicencio2025], continuous-treatment DiD +with dose-response curves [@Callaway2024], heterogeneous-adoption designs where no unit +remains untreated [@deChaisemartin2026], nonlinear ETWFE [@Wooldridge2025; @Wooldridge2023], +and triply robust panel estimation [@Athey2025]. Separate diagnostic and sensitivity tools - +outside the 19 estimators - include Goodman-Bacon decomposition [@GoodmanBacon2021], Honest +DiD sensitivity analysis [@Rambachan2023], placebo tests, and pre-trends power analysis +[@Roth2022]. All estimators share a consistent `fit()` interface with +`get_params()`/`set_params()` for configuration, R-style formula support, and rich results +objects with `summary()` output. An optional Rust backend via PyO3 accelerates +compute-intensive operations. **Survey-weighted inference.** A `SurveyDesign` class supports stratification, primary sampling units, finite population corrections, and probability weights. Variance estimation includes Taylor series linearization, five replicate weight methods (BRR, Fay's BRR, JK1, JKn, SDR), and survey-aware bootstrap. Survey variance is validated against R's `survey` -package [@Lumley2004] on three federal datasets (NHANES, RECS, API) to machine precision -(differences < 1e-10). No other DiD package in any language provides integrated survey -support. +package [@Lumley2004] on three real complex-survey datasets - NHANES, RECS 2020, and the +California API school dataset - to a tight tolerance (test gaps < 1e-8, typically below +1e-10). The design-based variance result - that the influence functions of modern DiD +estimators satisfy Binder's (1983) smoothness conditions, so stratified-cluster +linearization yields design-consistent standard errors - is derived in @Gerber2026. No +other DiD package in any language provides integrated survey support. **Validation against R.** Point estimates match the R `did`, `synthdid`, and `fixest` packages to machine precision (differences < 1e-10). Standard errors match exactly for @@ -87,10 +101,16 @@ tree for estimator selection, an 8-step diagnostic workflow based on Baker et al aggregation utilities for converting individual-level survey responses into geographic-period panels suitable for DiD analysis. -# Acknowledgments +# AI Usage Disclosure -Wenli Xu (Faculty of Finance, City University of Macau) implemented the WooldridgeDiD -(ETWFE) estimator, including saturated OLS, logit, and Poisson QMLE paths with ASF-based -ATT and delta-method standard errors. Development was assisted by Claude Code (Anthropic). +Generative AI tools were used in developing this software and manuscript. Anthropic's +Claude models (the Opus and Sonnet families, via the Claude Code CLI) assisted with code +generation and refactoring, test scaffolding, documentation, and drafting and editing of +this manuscript. The author reviewed, modified, and validated all AI-generated code and +text and made all primary architectural and methodological decisions. Numerical results +were independently verified against established R reference packages (`did`, `synthdid`, +`fixest`, `survey`) for every estimator with an R equivalent, and against the author's +reference derivations or simulation otherwise. The author takes full responsibility for the +accuracy and integrity of the software and this paper. # References