docs(paper): finalize JOSS submission - 20 estimators, required sections, draft-pdf CI

- paper.md: update estimator count 19 -> 20 (LPDiD merged after #564);
  add LPDiD to the staggered-adoption method list with Dube2025 citation
- paper.md: restructure to current JOSS required sections - add State of
  the Field (Python/R/Stata landscape with build-vs-contribute
  justification), Software Design (shared inference core,
  influence-function survey architecture, minimal-dependency policy, Rust
  backend), and Research Impact Statement (companion preprint, golden-file
  R validation, real-data survey validation, community-readiness signals);
  1,269 words, within the 750-1750 target
- paper.bib: add Dube2025 (LP-DiD, J. Applied Econometrics), Binder1983
  (previously cited in-text without a bib entry), pyfixest (software
  citation for State of the Field)
- paper.md: AI disclosure updated to name the Opus, Sonnet, and Fable
  model families
- llms.txt / llms-full.txt: stale counts 19 -> 20 and "13 of 16" -> "13
  of 20" replicate-weight support
- practitioner_decision_tree.rst: stale "17 estimators" -> 20, mention
  Local Projections DiD
- choosing_estimator.rst survey matrix: dCDH replicate weights "--" ->
  "Full (analytical)" (support landed with test_survey_dcdh_replicate_psu
  coverage); add missing SpilloverDiD and SyntheticControl rows; note the
  SyntheticControl NotImplementedError in the intro
- .github/workflows/draft-pdf.yml: SHA-pinned openjournals draft action
  compiles the paper on paper.md/paper.bib changes and uploads the PDF
  artifact

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: igerber

.github/workflows/draft-pdf.yml

@@ -0,0 +1,36 @@
+name: Draft PDF
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - paper.md
+      - paper.bib
+      - .github/workflows/draft-pdf.yml
+  pull_request:
+    paths:
+      - paper.md
+      - paper.bib
+      - .github/workflows/draft-pdf.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Compile JOSS paper draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@85a18372e48f551d8af9ddb7a747de685fbbb01c # v1.0
+        with:
+          journal: joss
+          paper-path: paper.md
+      - name: Upload paper artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: joss-paper
+          path: paper.pdf

diff_diff/guides/llms-full.txt

@@ -2120,7 +2120,7 @@ sd_female, data_female = sd.subpopulation(data, mask=lambda df: df['sex'] == 'F'
 
 **Key features:**
 - Taylor Series Linearization (TSL) variance with strata + PSU + FPC
-- Replicate weight variance: BRR, Fay's BRR, JK1, JKn, SDR (13 of 16 estimators, including dCDH)
+- Replicate weight variance: BRR, Fay's BRR, JK1, JKn, SDR (13 of 20 estimators, including dCDH)
 - Survey-aware bootstrap: multiplier at PSU (Hall-Mammen wild; dCDH, staggered) or Rao-Wu rescaled (SunAbraham, SyntheticDiD, TROP). SyntheticDiD bootstrap composes Rao-Wu rescaled per-draw weights with the weighted Frank-Wolfe variant of `_sc_weight_fw` (PR #355): each draw solves `min ||A·diag(rw)·ω - b||² + ζ²·Σ rw_i ω_i²` and composes `ω_eff = rw·ω/Σ(rw·ω)` for the SDID estimator. Pweight-only fits use constant `rw = w_control`; full designs use Rao-Wu. SDID's placebo (stratified permutation + weighted FW) and jackknife (PSU-level LOO with stratum aggregation, Rust & Rao 1996) paths also support pweight-only and full strata/PSU/FPC designs
 - DEFF diagnostics, subpopulation analysis, weight trimming (`trim_weights`)
 - Repeated cross-sections: `CallawaySantAnna(panel=False)`

diff_diff/guides/llms.txt

@@ -2,7 +2,7 @@
 
 > A Python library for Difference-in-Differences (DiD) causal inference analysis. Provides sklearn-like estimators with statsmodels-style summary output for econometric analysis.
 
-diff-diff offers 19 estimators covering basic 2x2 DiD, modern staggered adoption methods, reversible (non-absorbing) treatments, advanced panel estimators, nonlinear models, and diagnostic tools. It supports robust and cluster-robust standard errors, wild cluster bootstrap, formula and column-name interfaces, fixed effects (dummy and absorbed), complex survey designs (strata/PSU/FPC, replicate weights, design-based variance), and publication-ready output. The optional Rust backend accelerates compute-intensive estimators like Synthetic DiD and TROP.
+diff-diff offers 20 estimators covering basic 2x2 DiD, modern staggered adoption methods, reversible (non-absorbing) treatments, advanced panel estimators, nonlinear models, and diagnostic tools. It supports robust and cluster-robust standard errors, wild cluster bootstrap, formula and column-name interfaces, fixed effects (dummy and absorbed), complex survey designs (strata/PSU/FPC, replicate weights, design-based variance), and publication-ready output. The optional Rust backend accelerates compute-intensive estimators like Synthetic DiD and TROP.
 
 - Install: `pip install diff-diff`
 - License: MIT

docs/choosing_estimator.rst

@@ -771,7 +771,8 @@ If you're unsure which estimator to use:
 Survey Design Support
 ---------------------
 
-All estimators accept an optional ``survey_design`` parameter in ``fit()``.
+All estimators accept an optional ``survey_design`` parameter in ``fit()``
+(``SyntheticControl`` does not yet support it and raises ``NotImplementedError``).
 Pass a :class:`~diff_diff.SurveyDesign` object to get design-based variance
 estimation. The depth of support varies by estimator:
 
@@ -820,7 +821,7 @@ estimation. The depth of support varies by estimator:
    * - ``ChaisemartinDHaultfoeuille``
      - pweight only
      - Full (TSL)
-     - --
+     - Full (analytical)
      - Group-level (warning)
    * - ``TripleDifference``
      - pweight only
@@ -872,6 +873,11 @@ estimation. The depth of support varies by estimator:
      - Via bootstrap
      - --
      - Hybrid pairs-bootstrap + Rao-Wu rescaled (bootstrap only)
+   * - ``SyntheticControl``
+     - --
+     - --
+     - --
+     - --
    * - ``TROP``
      - pweight only
      - Via bootstrap
@@ -887,6 +893,11 @@ estimation. The depth of support varies by estimator:
      - Full (Binder TSL)
      - --
      - --
+   * - ``SpilloverDiD``
+     - pweight only
+     - Full (Binder TSL + Conley)
+     - --
+     - --
    * - ``BaconDecomposition``
      - Diagnostic
      - Diagnostic

docs/practitioner_decision_tree.rst

@@ -463,9 +463,10 @@ At a Glance
 What About the Other Estimators?
 --------------------------------
 
-diff-diff has 17 estimators covering advanced scenarios: Sun-Abraham for
+diff-diff has 20 estimators covering advanced scenarios: Sun-Abraham for
 interaction-weighted estimation, Imputation DiD and Two-Stage DiD for alternative
-staggered approaches, Stacked DiD, Efficient DiD, Triple Difference, TROP, and more.
+staggered approaches, Local Projections DiD, Stacked DiD, Efficient DiD,
+Triple Difference, TROP, and more.
 The six scenarios above cover the most common business use cases.
 
 For the full academic decision tree with all estimators, see :doc:`choosing_estimator`.

paper.bib

@@ -249,3 +249,32 @@ @misc{deChaisemartin2026
   primaryclass  = {econ.EM},
   doi       = {10.48550/arXiv.2405.04465}
 }
+
+@article{Dube2025,
+  author    = {Dube, Arindrajit and Girardi, Daniele and Jord{\`a}, {\`O}scar and Taylor, Alan M.},
+  title     = {A Local Projections Approach to Difference-in-Differences},
+  journal   = {Journal of Applied Econometrics},
+  volume    = {40},
+  number    = {5},
+  pages     = {741--758},
+  year      = {2025},
+  doi       = {10.1002/jae.70000}
+}
+
+@article{Binder1983,
+  author    = {Binder, David A.},
+  title     = {On the Variances of Asymptotically Normal Estimators from Complex Surveys},
+  journal   = {International Statistical Review},
+  volume    = {51},
+  number    = {3},
+  pages     = {279--292},
+  year      = {1983},
+  doi       = {10.2307/1402588}
+}
+
+@misc{pyfixest,
+  author    = {{The PyFixest Authors}},
+  title     = {pyfixest: Fast High-Dimensional Fixed Effect Estimation in Python},
+  year      = {2025},
+  url       = {https://github.com/py-econometrics/pyfixest}
+}

paper.md

@@ -21,7 +21,7 @@ bibliography: paper.bib
 # Summary
 
 `diff-diff` is a Python library for Difference-in-Differences (DiD) causal inference
-analysis. It provides 19 estimators covering the full modern DiD toolkit - from classic
+analysis. It provides 20 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
@@ -41,76 +41,132 @@ modern methods - including Callaway and Sant'Anna [-@Callaway2021], Sun and Abra
 [-@Sun2021], Borusyak, Jaravel, and Spiess [-@Borusyak2024], and others - are now standard
 practice in applied work.
 
-The R ecosystem provides mature implementations across several packages: `did`
-[@Callaway2021], `fixest` [@Berge2018], `synthdid` [@Arkhangelsky2021], and `HonestDiD`
-[@Rambachan2023]. Stata offers `csdid` and `didregress`. Python, however, lacks a unified
-DiD library. Practitioners working in Python-based data science workflows - increasingly
-common in industry settings for marketing measurement, product experimentation, and policy
-evaluation - must either context-switch to R, reimplement methods from scratch, or rely on
-partial implementations scattered across unrelated packages.
+These methods are well served in R and Stata, but Python lacks a unified DiD library.
+Practitioners working in Python-based data science workflows - increasingly common in
+industry settings for marketing measurement, product experimentation, and policy
+evaluation - must either context-switch to another language, 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 19 estimators
+`diff-diff` fills this gap by providing a single-import library that covers 20 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.
 
+# State of the Field
+
+The R ecosystem provides mature implementations across several packages: `did`
+[@Callaway2021], `fixest` [@Berge2018], `synthdid` [@Arkhangelsky2021], and `HonestDiD`
+[@Rambachan2023]; Stata offers `csdid` and `didregress`. Python coverage is partial and
+fragmented. `pyfixest` [@pyfixest] brings `fixest`-style high-dimensional fixed-effects
+regression to Python, including Sun-Abraham, two-stage, and local-projections estimators,
+but is organized around its regression engine rather than the wider DiD taxonomy;
+`differences` implements Callaway-Sant'Anna group-time estimation; `CausalPy` offers
+Bayesian analysis of quasi-experiments, including synthetic control, without
+staggered-adoption support. General-purpose causal inference toolkits such as `DoWhy` and
+`EconML` target other identification strategies.
+
+`diff-diff` was built as a new library, rather than as contributions to these packages,
+because its central contribution is cross-cutting: one estimator contract, one shared
+inference core, and an influence-function architecture that composes design-based survey
+variance with every estimator in the taxonomy. To our knowledge, no existing DiD software
+in any language provides design-based variance estimation for complex survey data, and no
+Python package covers the modern estimator taxonomy end-to-end; `diff-diff` provides
+both, validated against the R reference implementations where they exist.
+
 # Key Features
 
-**Breadth of methods.** `diff-diff` implements 19 estimators organized across the modern
+**Breadth of methods.** `diff-diff` implements 20 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.
+[@Borusyak2024], two-stage [@Gardner2022], stacked [@Wing2024], efficient [@Chen2025], and
+local-projections [@Dube2025] 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 20 estimators - include Goodman-Bacon decomposition [@GoodmanBacon2021], Honest DiD
+sensitivity analysis [@Rambachan2023], placebo tests, and pre-trends power analysis
+[@Roth2022].
 
 **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 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
-core estimators including Callaway-Sant'Anna and basic DiD. Validation includes the
-canonical MPDTA minimum-wage dataset from Callaway and Sant'Anna [-@Callaway2021].
+JKn, SDR), and survey-aware bootstrap. The design-based variance result - that the
+influence functions of modern DiD estimators satisfy the smoothness conditions of
+@Binder1983, so stratified-cluster linearization yields design-consistent standard
+errors - is derived in @Gerber2026. No other DiD package in any language provides
+integrated survey support.
 
 **Practitioner tooling.** Beyond estimation, `diff-diff` includes a practitioner decision
 tree for estimator selection, an 8-step diagnostic workflow based on Baker et al.
 [-@Baker2025], AI agent integration with structured next-steps guidance, and microdata
 aggregation utilities for converting individual-level survey responses into
 geographic-period panels suitable for DiD analysis.
 
+# Software Design
+
+Every estimator implements a common contract: a scikit-learn-style `fit()` with
+`get_params()`/`set_params()` for configuration, R-style formula support, and rich results
+dataclasses with `summary()`, `to_dict()`, and `to_dataframe()`. Numerical work is
+deliberately centralized: all estimators solve their least-squares problems and their
+robust, cluster-robust, and survey variances through a single shared linear-algebra core,
+so numerical hardening - rank-deficiency guards, degrees-of-freedom corrections,
+small-cluster behavior - lands in one place and propagates to every estimator. Inference
+fields (standard error, t-statistic, p-value, confidence interval) are always computed
+together and become NaN together when inference is not identified, rather than silently
+reporting partial results.
+
+Two design choices carry the survey capability and the deployment story. First, estimators
+compute influence functions for their target parameters, so design-based variance - Taylor
+series linearization over strata and clusters, replicate weights, survey-aware
+bootstrap - composes uniformly with estimators as different as Callaway-Sant'Anna and
+synthetic DiD instead of requiring per-estimator derivations. Second, the runtime
+dependency footprint is minimal by policy - numpy, pandas, and scipy only - keeping the
+library easy to install in restricted industry environments; high-dimensional fixed
+effects are handled by within-transformation rather than by delegating to a heavier
+econometrics stack. An optional Rust backend (via PyO3) accelerates compute-intensive
+kernels such as synthetic-control weight solving and fixed-effects absorption; the Python
+implementation remains canonical, equivalence between backends is enforced by the test
+suite, and the library falls back to pure Python automatically when the extension is
+unavailable.
+
+# Research Impact Statement
+
+`diff-diff` is the companion software of the design-based variance preprint [@Gerber2026]:
+the framework derived there is implemented here, and the preprint's numerical results are
+produced with the library. Correctness evidence ships with the repository as reproducible
+material. Golden-file benchmarks pin point estimates against R's `did`, `synthdid`, and
+`fixest` to machine precision (differences < 1e-10), including the canonical MPDTA
+minimum-wage application of Callaway and Sant'Anna [-@Callaway2021], with standard errors
+matching exactly for core estimators such as Callaway-Sant'Anna and basic DiD. Survey
+variance is validated against R's `survey` package [@Lumley2004] on three real
+complex-survey datasets - NHANES, RECS 2020, and the California API school data - with
+test gaps below 1e-8 and typically below 1e-10. The library is distributed on PyPI with
+tagged releases, has six months of continuous public development history (3,000+
+commits), and is exercised by a CI test suite of more than 7,600 tests; 26 tutorial
+notebooks and full API documentation are published on Read the Docs, and machine-readable
+guides bundled in the wheel (`llms.txt`) make the library directly usable by AI-assisted
+analysis workflows.
+
 # AI Usage Disclosure
 
 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.
+Claude models (the Opus, Sonnet, and Fable model 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