Skip to content

docs(paper): refresh JOSS paper for current library and submission requirements #564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
igerber merged 1 commit into from
Jun 27, 2026
Merged

docs(paper): refresh JOSS paper for current library and submission requirements #564

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 58 additions & 7 deletions paper.bib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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}
}
76 changes: 48 additions & 28 deletions paper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Loading