SyntheticControl: cv (out-of-sample) + inverse-variance V-selection (ADH 2015 / Abadie 2021)

[igerber]

Summary

• Adds two v_method values to SyntheticControl, completing the ADH-2015 / Abadie-2021 predictor-importance V-selection menu, each threaded through the in-space / leave-one-out / in-time placebo refits (a diagnostic uses the same estimator as the headline fit).
• v_method="cv" — out-of-sample cross-validation (ADH 2015 §; Abadie 2021 Eq. 9). New v_cv_t0 param splits the pre-period (default len(pre)//2). Each predictor spec is re-aggregated per window (a separate dataprep/standardization per window), so the V-search is genuinely out-of-sample for every predictor type: V minimizes the validation-window outcome MSPE of the training-window fit, then the final weights are re-estimated on the validation-window predictors (step 4). v_weights reproduce donor_weights; predictor_balance is reported on the validation-window basis; mspe_v is the held-out validation MSPE. Deterministic, convergence-aware flat-MSPE tie-break (fn. 7).
• v_method="inverse_variance" — closed-form v_h = 1/Var(X_h) (Abadie 2021 §3.2(a)) applied to the raw predictors (the standardize pre-scaling is intentionally bypassed — inverse-variance weighting is unit-variance rescaling). Exact for every positive variance; zero-variance rows → 0 weight; all-zero/overflow → uniform + warn.
• Fail-closed identification gates (cv): every predictor must span both windows; each window must have cross-donor variation (a donor-indistinguishable window leaves X0·W constant in W → unidentified). Violations raise on the headline fit; in-space placebos drop the affected refit; in-time-truncated dates → infeasible. Single-donor fits force w=[1] → V unidentified → uniform v_weights + mspe_v=None (documented).

Methodology references (required if estimator / math changes)

• Method name(s): SyntheticControl V-selection — out-of-sample cross-validation; inverse-variance V.
• Paper / source link(s): Abadie, Diamond & Hainmueller (2015, Am. J. Pol. Sci.) §; Abadie (2021, JEL) §3.2(a), Eq. 9. On-file reviews: docs/methodology/papers/abadie-diamond-hainmueller-2015-review.md, abadie-2021-review.md.
• Intentional deviations (documented as REGISTRY **Note:** / **Deviation from R:**): R Synth has no built-in CV (ADH-2015's CV is a manual two-dataprep re-run) — our per-window re-aggregation reproduces it for absolute-period spec aggregates; deterministic densest-V tie-break for fn.7 non-uniqueness; single-donor uniform-V degeneracy. All in docs/methodology/REGISTRY.md §SyntheticControl.

Validation

• Tests added/updated: tests/test_methodology_synthetic_control.py — config validation, exact inverse-variance (incl. tiny-positive-variance), the spanning / donor-variation / training-convergence fail-closed gates, single-donor degeneracy, and placebo/LOO/in-time propagation + self-consistency for both methods. R-anchored: cv by deterministic equivalence to the R-anchored custom_v path on the per-window re-aggregated predictors (step-3 criterion + step-4 weights) + cv self-consistency (in-time == fresh backdated fit, 1e-7); inverse-variance bit-for-bit vs custom_v=1/Var(X).
• Backtest / simulation / notebook evidence: N/A (no tutorial change in this PR).

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

🤖 Generated with Claude Code

[github-actions]

Overall assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive summary

• Cross-checking the new cv branch in diff_diff/synthetic_control.py against abadie-diamond-hainmueller-2015-review.md and abadie-2021-review.md, it follows the documented 4-step train/validation/refit procedure.
• The new inverse-variance branch in diff_diff/synthetic_control.py correctly applies 1/Var(X) on raw predictors, avoiding the incorrect 1/Var^2 double-rescaling path.
• The main deviations from baseline R / paper defaults are explicitly documented in docs/methodology/REGISTRY.md, so they are mitigated rather than review defects.
• Parameter propagation for v_cv_t0 is complete through config validation, results, summary/serialization, and refit snapshots in diff_diff/synthetic_control.py and diff_diff/synthetic_control_results.py.
• One low-priority follow-up is correctly tracked in TODO.md: in_space_placebo() and leave_one_out() still expose structurally infeasible CV refits as generic status="failed".

Methodology

No findings. The changed estimator behavior is aligned with the on-file methodology reviews and the corresponding registry notes in docs/methodology/REGISTRY.md. The key implementation choices that differ from paper/R defaults, including per-window re-aggregation, deterministic CV tie-breaking, raw-scale inverse-variance weighting, and single-donor uniform-V handling, are documented at docs/methodology/REGISTRY.md.

Code Quality

No findings.

Performance

No findings. The added CV guards do extra predictor-matrix work, but only on the new v_method="cv" path and they prevent arbitrary-weight fits.

Maintainability

No findings. The new helper split around _inverse_variance_v(), _outer_solve_V_cv(), and the CV window checks keeps the new logic localized and reuses the same refit path for placebo/LOO/in-time diagnostics.

Tech Debt

• P3 Impact: in_space_placebo() and leave_one_out() still report structurally infeasible CV refits with generic status="failed" instead of a separate machine-readable infeasible status in diff_diff/synthetic_control_results.py and diff_diff/synthetic_control_results.py. Concrete fix: implement the already-tracked follow-up in TODO.md by threading a reason code out of _outer_solve_V_cv() / _placebo_fit_unit() and surfacing separate status="infeasible" plus counts. This is tracked, so it does not block approval.

Security

No findings.

Documentation/Tests

No findings in the changed docs/tests. The added coverage in tests/test_methodology_synthetic_control.py is strong on the new branches: non-spanning predictors, donor-indistinguishable CV windows, single-donor degeneracy, fail-closed training solves, and propagation through placebo/LOO/in-time.

Residual risk: I could not execute the tests in this environment because pytest and numpy are not installed here.