PR-A: WooldridgeDiD primary-source review (Wooldridge 2025 EmpEcon)#484
Conversation
Adds the primary-source methodology review for Wooldridge, J. M. (2025). Two-way fixed effects, the two-way mundlak regression, and difference-in-differences estimators. Empirical Economics, 69(5), 2545-2587. DOI 10.1007/s00181-025-02807-z. Covers Sections 2 (TWFE foundation), 3 (two-way Mundlak + Theorem 3.1 / Corollary 3.2), 4 (staggered identification + Procedure 4.1 cohort imputation), 5 (POLS / extended TWFE + Propositions 5.1 / 5.2 equivalence chain), 6 (event study), 7 (aggregation — Eq. 7.2-7.4 cohort-share weights), 8 (heterogeneous cohort-specific trends), and 10 (extensions). Cross-links the existing 2023 secondary review for nonlinear extensions (logit / Poisson / ASF). Deviations section separates documented deviations (Eqs. 7.2-7.4 simple-overall aggregation already tracked in REGISTRY + TODO; R / Stata small-sample-correction items) from untracked findings (Eq. 7.6 event-time aggregation extension of the simple-overall deviation — new finding from this review, not yet in REGISTRY or TODO). First of two PRs for the WooldridgeDiD (ETWFE) methodology-review- tracker promotion. The second PR (methodology test file + R `etwfe` parity + implementation fixes if any + tracker promotion consolidation) will follow. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Overall AssessmentExecutive Summary
Methodology
Code QualityNo findings in scope. PerformanceNo findings in scope. MaintainabilityNo findings beyond the documentation cross-reference issue below. Tech DebtNo additional deferrable tech-debt findings. The blocker above is methodological and needs Registry documentation rather than TODO-only tracking. SecurityNo findings in scope. Documentation/Tests
Path to Approval
|
CI audit found the Eq. 7.6 event-time aggregation deviation was a real methodology mismatch not yet documented in REGISTRY/TODO. Both `simple` and `event` aggregations reuse the same `_gt_weights` cell-count array, so the deviation form is identical across paths. - REGISTRY § Aggregations Note: extend the cell-vs-cohort-share text to name both Eq. 7.4 (simple-overall) and Eq. 7.6 (event-time) - TODO.md row 95: widen the deferred `weights="cohort_share"` follow-up to cover both paths in one parameter addition - Wooldridge 2025 review: consolidate the prior split (documented vs untracked) into a single Deviations entry covering both paths now that REGISTRY documents both; fix WooldridgeResults reference Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good Executive Summary
Methodology
Code Quality
Performance
Maintainability
Tech Debt
Security
Documentation/Tests
|
CI R2 P3 (documentation): the review's intro to its Deviations section listed only `**Note (deviation from R/Stata):**` and `**Deviation from R:**` as accepted REGISTRY label forms, but the plain `**Note:**` form is also accepted (and is what the corresponding REGISTRY:1495 aggregation note uses). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good Executive Summary
Methodology
Code Quality
Performance
Maintainability
Tech Debt
Security
Documentation/Tests
|
CI R3 P3 (methodology): the prior wording said the cell-vs-cohort-share gap appears in "imbalanced or staggered panels with heterogeneous cohort sizes." Codex correctly notes that balanced staggered panels with uniform within-cohort cell counts still match exactly (cell-count reduces to N_g per cell, recovering the cohort-share form). Rewording to "post-treatment cell counts vary within cohort or exposure horizon" captures the actual divergence trigger (unbalanced panels, missing cells, sample-filter drops). CI R3 P3 (documentation): align the review's `weighting="cohort_share"` prose with the TODO row's tracked API name `weights="cohort_share"`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good Executive Summary
Methodology
Code Quality
Performance
Maintainability
Tech Debt
Security
Documentation/Tests
|
CI R4 P3 (methodology): the prior wording asserted the paper's cohort-share form universally "down-weights short-exposure cohorts relative to the cell-count scheme." That direction isn't universal — it depends on which post-treatment cells are sparse, missing, or filtered. Replace with a direction-agnostic statement and keep the mechanical contrast between Eq. 7.4's exposure-multiplier denominator and the cell-count scheme. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good Executive Summary
Methodology
Code Quality
Performance
Maintainability
Tech Debt
Security
Documentation/Tests
|
CI R5 P3 (documentation): the ordered list jumped from 2 to 4 after the R2 removal of a stale Section 8 coverage gap entry. Renumber 4-14 → 3-13 so the list reads as a complete, contiguous edit. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment ✅ Looks good Executive Summary
Methodology
Code Quality
Performance
Maintainability
Tech Debt
Security
Documentation/Tests
|
Closes the WooldridgeDiD (ETWFE) methodology-review-tracker promotion in METHODOLOGY_REVIEW.md (In Progress → Complete), following the primary-source review for Wooldridge (2025) merged in PR-A (#484). Adds two paper-driven implementation surfaces and extends R-parity goldens to the nonlinear paths. Implementation: - `aggregate(weights="cohort_share")` on WooldridgeDiDResults implements paper Eqs. 7.4 (simple-overall) and 7.6 (event-time, restricted to k>=0) cohort-share aggregation weights as an opt-in alternative to the default cell-count weighting (matching Stata `jwdid_estat`). Inference fields fail-closed to NaN with UserWarning per paper Section 7.5 conditional-on-shares semantics; raises on `survey_design` (design-consistent totals deferred); raises on `type ∈ {"group","calendar"}` (no paper closed-form); raises on bootstrap fits (no matching bootstrap variant). Closes TODO row 95. - `cohort_trends=True` on `WooldridgeDiD.__init__` adds linear `dg_i · t` cohort-specific trend interactions (paper Section 8 / Eq. 8.1) for the OLS path. Rejects on logit/poisson per paper Section 8 OLS scope; rejects on survey_design pending full-dummy/TSL validation; enforces per-cohort pre-period identification check (≥ 2 observed pre-periods per treated cohort). Auto-routes to full-dummy mode regardless of vcov_type. Closes the PR-A Requirements Checklist heterogeneous-trends gap. Tests: - `tests/test_methodology_wooldridge.py` extended with 6 paper-equation-numbered methodology classes (Theorem 3.1, Proposition 5.1, Section 6 event study, Section 7 aggregation paths, Section 8 heterogeneous trends, Section 10 unbalanced panels) + `TestW2025LibraryDeviations` consolidating 5 surviving deviations. Mirrors the HAD PR #473 precedent. - Two new R-parity surface classes (`TestWooldridgeParityRPoisson`, `TestWooldridgeParityRLogit`) lock the structural surface against R `etwfe(family=...)` log-link goldens. - 209 tests total (60 methodology + 149 R-parity + unit regressions). R Goldens: - `benchmarks/R/generate_wooldridge_golden.R` extended with Poisson + logit DGPs via R `etwfe`; augmented panel CSV retains the same seed-generated `y_pois` + `y_logit` columns for cross-language reproducibility. - `benchmarks/R/requirements.R` pins `etwfe >= 0.5.0`. Tracker promotion: - METHODOLOGY_REVIEW.md L52 status flip with merge date; detail section L583-605 rewritten to the Verified Components / Test Coverage / Corrections Made / Deviations / Outstanding Concerns template mirroring HAD / ContinuousDiD / DCDH. L27 example re-pointed; priority queue items #7-#10 renumbered to #6-#9. - REGISTRY.md `## WooldridgeDiD (ETWFE)` extended with `### Deviations from the paper / from R / library extensions` block consolidating 7 surviving deviations + opt-in notes for cohort_share + cohort_trends + survey rejection + bootstrap cohort_share rejection contracts. - CHANGELOG.md `[Unreleased]` `### Added` documents the new parameters, R-parity extension, and tracker flip. - `docs/methodology/papers/wooldridge-2025-review.md` Requirements Checklist + Gaps & Uncertainties items 1 + 11 marked `**Status:** Closed in PR-B`. - `docs/api/wooldridge_etwfe.rst` updated with weighting-scheme notes alongside the existing aggregation table. Second of two PRs for the WooldridgeDiD methodology-review-tracker promotion. PR-A merged at e416aed (#484). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Summary
WooldridgeDiD (ETWFE)atdocs/methodology/papers/wooldridge-2025-review.md(single new file, 771 lines).docs/methodology/papers/wooldridge-2023-review.mdfor nonlinear extensions (logit / Poisson / ASF), which Wooldridge (2025) defers to (p. 2554).## WooldridgeDiD (ETWFE)§ Aggregations Note documents only the Eqs. 7.2-7.4 simple-overall cell-vs-cohort-share weighting deviation; the same deviation extends to the Eq. 7.6 event-time path viaaggregate("event")but is not yet in REGISTRY or TODO. Documented in the review's Deviations § "Untracked findings" subsection; lifting it into REGISTRY + TODO is intentionally deferred to the follow-up PR.etwfeparity + implementation fixes if any + tracker promotion consolidation) will land after this paper review.Methodology references (required if estimator / math changes)
WooldridgeDiD(ETWFE) — OLS / Mundlak / POLS-on-cohort-dummies / aggregation (simple, group, calendar, event-time) / event study / heterogeneous-trends Section 8.n_{g,t}aggregation weights vs the paper's cohort-shareω̂_gweights at Eq. 7.2-7.4; already tracked) and a NEW untracked extension of the same deviation under Eq. 7.6 event-time. Both are tagged in the Deviations section but no REGISTRY / TODO surfaces are modified in this PR; consolidation is deferred to the follow-up PR.Validation
Security / privacy