perf(linalg): scores-based CR2 Bell-McCaffrey DOF (PT2018 Appendix B)

[igerber]

Summary

• Closes the CR2-BM Heavy TODO row: the unweighted per-contrast Satterthwaite DOF materialized the dense n×n residual-maker M = I − X(X'X)⁻¹X' and contracted it over all cluster pairs — O(n²) time per contrast and O(n²) memory (3.2 GB at n=20k). Per Pustejovsky-Tipton (2018) Appendix B, with Ω the (n, G) matrix stacking ω_g on disjoint cluster supports, the pairwise matrix collapses to B = Ω'MΩ = diag(‖ω_g‖²) − P'M_U P with P = X'Ω — O(nk + G²k) per contrast, no n×n allocation.
• Measured: ~32x at n=5k/G=50 (0.57s → 0.018s); n=20k/G=100 completes in 0.12s where the old path would allocate 3.2 GB. Algebraically identical: a frozen pair-loop oracle (the previous implementation reimplemented verbatim in-test) agrees at rtol 1e-10 across balanced, unbalanced (cluster sizes 3–60), and compound-contrast designs. Both NaN-reliability guards (noise floor via max|B|, cluster-count bound DOF ≤ G) operate unchanged on the same B values.
• The weighted clubSandwich P-array path is untouched (it never built the n×n M). All 432 consumer tests (linalg, vcov-type incl. the CI-inversion dof_hc2_bm pins, stacked-DiD methodology, estimators) pass unmodified. REGISTRY: per-fit setup wording updated + an Appendix-B evaluation sentence on the existing unweighted-DOF-guard Note.

Methodology references (required if estimator / math changes)

• Method name(s): CR2 Bell-McCaffrey Satterthwaite DOF (Pustejovsky & Tipton 2018, Section 4 / Appendix A formula; Appendix B scores-based evaluation) — evaluation change only, same estimand
• Paper / source link(s): REGISTRY.md DiD/MPD hc2_bm Notes (updated); PT2018 J. Bus. Econ. Statist.
• Any intentional deviations from the source (and why): None — algebraically identical evaluation, oracle-locked.

Validation

• Tests added/updated: tests/test_linalg.py::TestCR2BMScoresBasedDOF (3 frozen-oracle parity tests).
• Backtest / simulation / notebook evidence (if applicable): timing table above (in-session measurements).

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

• Method affected: unweighted CR2 Bell-McCaffrey Satterthwaite DOF in diff_diff/linalg.py.
• The scores-based B = Omega' M Omega expansion is algebraically consistent with the previous residual-maker contraction and with the project’s REGISTRY note.
• Existing NaN/noise-floor and cluster-count guards remain in place.
• P2 performance issue: the implementation materializes P_all for all contrasts, so batched per-coefficient DOF can allocate O(G*k*m) memory, contradicting the stated O(G*k) memory bound.
• I could not run tests: numpy, scipy, and pytest are not installed in this environment.

Methodology

No blocking findings.

Severity: P3 informational
Impact: This is an evaluation rewrite, not a methodology change. The affected method is CR2 Bell-McCaffrey Satterthwaite DOF. PT2018 covers BRL/CRVE with Satterthwaite degrees of freedom, and clubSandwich’s Satterthwaite_df reduces to (trace P)^2 / sum(P^2), matching the registry/code contract. (arxiv.org)
Concrete fix: No required change.

Code Quality

No findings.

Performance

Severity: P2
Impact: diff_diff/linalg.py:L2151-L2168 allocates P_all = np.zeros((G, k, m)). For _compute_cr2_bm(..., contrasts=np.eye(k)), m == k, so this becomes O(G*k^2) memory. That can be worse than intended on full-dummy/absorbed-FE-style designs with many clusters and coefficients, and it contradicts the O(G*k) memory claim in diff_diff/linalg.py:L2124-L2126, CHANGELOG.md:L453-L456, and docs/methodology/REGISTRY.md:L246.
Concrete fix: Stream or chunk contrasts. Inside the for j in range(m) loop, build P_j from each cluster’s omega_all[g][:, j] instead of storing all P_all; alternatively chunk m so peak memory is bounded. Update the documented memory bound to include the G x G B_j matrix if it remains materialized.

Maintainability

No blocking findings.

Severity: P3
Impact: diff_diff/linalg.py:L1856-L1858 still says the shared core precomputes the unweighted residual-maker M, but this PR removes that allocation.
Concrete fix: Remove the stale M reference from the docstring.

Tech Debt

No new untracked correctness debt found. The old TODO row for CR2-BM dense residual-maker allocation is reasonably removed, subject to the P2 memory follow-up above.

Security

No findings.

Documentation/Tests

Severity: P3
Impact: The added oracle tests cover balanced, unbalanced, and compound-contrast parity, but I could not execute them locally because test dependencies are unavailable.
Concrete fix: Run tests/test_linalg.py::TestCR2BMScoresBasedDOF and the existing CR2-BM NaN-guard tests in CI.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 47d22ddf5dd39948e8843f0e460e4ef6286ff9b6

---

Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

• Affected method: unweighted CR2 Bell-McCaffrey Satterthwaite DOF in diff_diff/linalg.py.
• The prior P2 P_all = O(G*k*m) memory issue is addressed by contrast chunking at diff_diff/linalg.py:L2236-L2245.
• The prior stale docstring reference to the dense residual-maker is fixed at diff_diff/linalg.py:L1919-L1921.
• No methodology or inference correctness blockers found.
• Tests could not be run here: numpy and pytest are not installed.

Methodology

Severity: P3
Impact: The implementation remains an algebraically equivalent evaluation of the existing unweighted CR2-BM Satterthwaite DOF. The paper’s Satterthwaite t-test DOF is the model-assisted moment ratio in §3.1, and the code preserves that contract via the same (tr B)^2 / tr(B^2) structure while replacing the explicit residual-maker contraction with Omega' M Omega. (arxiv.org)
Concrete fix: No required change.

Severity: P2
Impact: The new code/docs repeatedly cite “PT2018 Appendix B” for the scores-based evaluation, but the accessible arXiv text labels Appendix B as simulation-study details; the Satterthwaite DOF formula is in §3.1 and the relevant residual-projection efficiency discussion is in §2.2. This is a source-attribution issue, not a numerical defect. docs/methodology/REGISTRY.md:L246, diff_diff/linalg.py:L2187-L2203. (arxiv.org)
Concrete fix: Reword to cite PT2018 §3.1 / Eq. 13 plus the algebraic identity Omega' M Omega = diag(||omega_g||^2) - P' M_U P, rather than Appendix B.

Code Quality

No findings.

Performance

Severity: P3
Impact: The prior review’s main performance concern is resolved: P_all is now chunked under _CR2_BM_CONTRAST_CHUNK_BYTES, with a regression test forcing one-contrast chunks at tests/test_linalg.py:L2810-L2828.
Concrete fix: No required change.

Maintainability

No findings. The stale shared-core docstring was corrected.

Tech Debt

No new untracked correctness debt found. Removing the old CR2-BM dense residual-maker TODO is reasonable given the current implementation.

Security

No findings.

Documentation/Tests

Severity: P3
Impact: Added parity coverage is well targeted: balanced, unbalanced, compound contrast, and chunking bit-identity cases are covered in tests/test_linalg.py:L2719-L2828. I could not execute them locally because numpy and pytest are missing.
Concrete fix: Run tests/test_linalg.py::TestCR2BMScoresBasedDOF and existing CR2-BM CI/NaN guard tests in CI.