SyntheticControl: conformal inference (Chernozhukov-Wüthrich-Zhu 2021)

Add the CWZ (2021, JASA 116(536)) conformal-inference layer for SyntheticControl
— valid p-values for the post-period effect trajectory and pointwise confidence
intervals, which the in-space placebo and Firpo-Possebom test-inversion paths
cannot give. The final SCM-roadmap inference item (PR-B style; paper review was
already on disk).

Unlike the Firpo path (re-ranks cross-unit placebo gaps), the conformal layer
fits its OWN time-permutation-invariant constrained-LS synthetic-control proxy
(CWZ §2.3 eqs 3-4 — simplex weights on raw outcomes over ALL periods under the
null, no V-matrix, no intercept) and permutes residuals OVER TIME for the single
treated unit. CWZ exactness (Lemma 1; Appendix D exchangeability) requires a
time-symmetric proxy, which the headline ADH pre-period V-fit is not — so the
conformal counterfactual is documented as distinct from the headline weights.

New module diff_diff/conformal.py (pure, reuses utils._sc_weight_fw) +
three opt-in SyntheticControlResults methods:
- conformal_test(effect, q, scheme, n_iid, seed): joint sharp-null permutation
  p-value (eqs 1-2) of S_q (q in {1,2,inf}); proxy fit once, residuals permuted
  (footnote 7).
- conformal_confidence_intervals(alpha, scheme, bounds, n_grid, seed): pointwise
  per-period CIs by test inversion (Algorithm 1 — each period t uses Z=(pre, t),
  the other post-periods dropped, a T*=1 test).
- conformal_average_effect(alpha, scheme, bounds, n_grid, seed): average-effect
  CI by collapsing into non-overlapping T*-blocks and permuting block residuals
  (Appendix A.1).
Permutation schemes: moving-block (default, serial-dependence-robust) and iid;
both include the identity so the p-value floor is 1/|Pi| (no extra +1).
Accessors get_conformal_grid_df() / get_conformal_ci_df() + conformal_inference
summary. Analytical se/t/p/conf_int/is_significant stay NaN throughout.

Fail-closed: <1 donor / unpickled / non-finite panel / <2 periods raise; single
donor + T*>=T0 warn; non-converged grid points are indeterminate (not rejected);
grid-edge -> "grid_limited"; nothing accepted -> "empty"; alpha<1/|Pi| ->
"unbounded" with (-inf,+inf). All five paper-pending mechanics confirmed against
arXiv:1712.09089v10.

Surfaced through DiagnosticReport (_scm_native conformal block) and wired across
REGISTRY (subsection + deviation Notes + checklist), doc-deps, references, the
LLM guides, api rst, REPORTING, CHANGELOG, README, TODO. Validated by a numpy
oracle, a brute-force permutation-equivalence test, a proxy-vs-scipy check, and a
coverage simulation. Deferred (TODO): one-sided variants (§7), covariates in the
proxy, AR/innovation permutation (Lemmas 5-7).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: igerber

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **`SyntheticControl` conformal inference (Chernozhukov, Wüthrich & Zhu 2021, *JASA* 116(536)).** Three opt-in `SyntheticControlResults` methods give valid p-values for the post-period effect trajectory and pointwise confidence intervals — what the in-space placebo / Firpo-Possebom test-inversion paths cannot. Unlike the Firpo path (which re-ranks the cross-unit placebo gaps), the conformal layer fits its **own** time-permutation-invariant constrained-LS synthetic-control proxy (CWZ §2.3 eqs 3–4 — simplex weights on raw outcomes over **all** periods under the null, no `V`-matrix, no intercept) and permutes residuals **over time** for the single treated unit (CWZ's exactness theory requires a time-symmetric proxy, which the headline ADH `V`-matrix fit is not). **`conformal_test(effect, q=1, scheme="moving_block", n_iid=10000, seed=None)`** computes the joint sharp-null permutation p-value (eqs 1–2) of `S_q(û) = ((1/√T*)·Σ_{t>T0}|û_t|^q)^{1/q}` (`q ∈ {1, 2, ∞}`); the proxy is fit once and only residuals are permuted (footnote 7). **`conformal_confidence_intervals(alpha=0.1, scheme="moving_block", bounds=None, n_grid=100, seed=None)`** returns pointwise per-period CIs by test inversion (Algorithm 1 — each period `t` uses `Z = (pre-periods, t)` with the other post-periods dropped, a clean `T*=1` test). **`conformal_average_effect(alpha=0.1, scheme="moving_block", bounds=None, n_grid=200, seed=None)`** returns a CI for the average post-period effect by collapsing the panel into non-overlapping `T*`-blocks and permuting the block residuals (Appendix A.1). Permutation schemes: `"moving_block"` (`Π_→` cyclic shifts, valid under serial dependence — the default) and `"iid"` (`Π_all`, sampled, finer p-values); both include the identity so the p-value floor is `1/|Π|` (no extra `+1`). Fail-closed handling for `<1` donor / unpickled result / non-finite panel / non-converged grid points (treated as indeterminate, not rejected) / grid-limited / empty / unbounded sets; a single donor and `T*≥T0` warn. Surfaced under `conformal_inference` / `get_conformal_grid_df()` and `DiagnosticReport`'s `estimator_native_diagnostics`; the analytical `se`/`t_stat`/`p_value`/`conf_int`/`is_significant` stay NaN throughout. Core in the new `diff_diff/conformal.py` (reuses the Frank-Wolfe simplex solver). *Deferred:* one-sided variants (§7), covariates folded into the proxy, and the AR/innovation-permutation path (Lemmas 5–7).
+
 ## [3.5.1] - 2026-06-02
 
 ### Added

README.md

@@ -108,7 +108,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html) - Gardner (2022) two-stage estimator with GMM sandwich variance
 - [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under `survey_design=` for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC — `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`); `SurveyDesign.subpopulation()` preserves full-design `n_psu` / `df_survey` via zero-padded scores (Wave E.3, R `svyrecvar(subset())` form)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - Synthetic DiD combining standard DiD and synthetic control for few treated units
-- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/cv/inverse-variance/custom V; in-space placebo permutation inference via `in_space_placebo()`, plus ADH-2015 `leave_one_out()` + `in_time_placebo()` robustness)
+- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/cv/inverse-variance/custom V; in-space placebo permutation inference via `in_space_placebo()`, plus ADH-2015 `leave_one_out()` + `in_time_placebo()` robustness, Firpo-Possebom (2018) test-inversion confidence sets, and Chernozhukov-Wüthrich-Zhu (2021) conformal inference)
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html) - triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html) - Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves
 - [HeterogeneousAdoptionDiD](https://diff-diff.readthedocs.io/en/stable/api/had.html) - de Chaisemartin, Ciccia, D'Haultfœuille & Knau (2026) for designs where **no unit remains untreated**; local-linear estimator at the dose support boundary returning Weighted Average Slope (WAS) on Design 1' (`d̲ = 0` / QUG) or `WAS_{d̲}` on Design 1 (`d̲ > 0`, continuous-near-d̲ or mass-point), with a multi-period event-study extension (last-treatment cohort, pointwise CIs). **Panel-only** in this release - repeated cross-sections rejected by the validator. Alias `HAD`.

TODO.md

@@ -86,6 +86,7 @@ Deferred items from PR reviews that were not addressed before merge.
 | Multi-absorb weighted demeaning needs iterative alternating projections for N > 1 absorbed FE with survey weights; unweighted multi-absorb also uses single-pass (pre-existing, exact only for balanced panels) | `estimators.py` | #218 | Medium |
 | Survey design resolution/collapse patterns are inconsistent across panel estimators — ContinuousDiD rebuilds unit-level design in SE code, EfficientDiD builds once in fit(), StackedDiD re-resolves on stacked data; extract shared helpers for panel-to-unit collapse, post-filter re-resolution, and metadata recomputation | `continuous_did.py`, `efficient_did.py`, `stacked_did.py` | #226 | Low |
 | SyntheticControl: the remaining ADH-2015 §4 items — the regression-weight `W^reg = X_0'(X_0 X_0')^{-1} X_1` extrapolation diagnostic (flag implied OLS weights outside `[0,1]`) and sparse-SC subset search (`l < J`, holding `V` fixed). Leave-one-out (`leave_one_out()`), the in-time placebo (`in_time_placebo()`), out-of-sample CV `V`-selection (`v_method="cv"`), and inverse-variance `V` (`v_method="inverse_variance"`) have landed; these two are the deferred tail. | `synthetic_control.py`, `synthetic_control_results.py` | ADH-2015 follow-up | Low |
+| SyntheticControl conformal inference (CWZ 2021) deferred extensions: (a) one-sided / signed-`t` variants (§7); (b) covariates folded into the conformal proxy (`X_jt`, eqs 4/6 allow it — current proxy is outcomes-only); (c) the AR/innovation-permutation path (Lemmas 5–7) for time-series proxies where residual-permutation ≠ data-permutation. The joint test, pointwise CIs, and average-effect CI (the constrained-LS SC proxy) have landed. | `diff_diff/conformal.py`, `synthetic_control_results.py` | CWZ-2021 follow-up | Low |
 | ContinuousDiD deferred CGBS 2024 extensions: (a) `covariates=` kwarg not implemented (matches R `contdid` v0.1.0); (b) discrete-treatment saturated regression deferred (integer-valued dose currently warned, not routed to per-level coefficients); (c) lowest-dose-as-control per CGBS 2024 Remark 3.1 (when `P(D=0) = 0`) not implemented — estimator requires never-treated controls. REGISTRY `## ContinuousDiD` → Implementation Checklist marks these as deferred `[ ]` items. | `diff_diff/continuous_did.py` | — | Low |
 | Survey-weighted Silverman bandwidth in EfficientDiD conditional Omega* — `_silverman_bandwidth()` uses unweighted mean/std for bandwidth selection; survey-weighted statistics would better reflect the population distribution but is a second-order refinement | `efficient_did_covariates.py` | — | Low |
 | ImputationDiD: auxiliary `tau_tilde_g` (Theorem 3 variance) uses a simplified **observation-level** v_it-weighted mean `sum(v*tau_hat)/sum(v)` instead of the paper's **unit-clustered** Eq. 8 `sum_i[(sum_t v)(sum_t v*tau_hat)]/sum_i(sum_t v)^2` (BJS 2024 p. 3272). Coincides for uniform within-group weights (the **unweighted** overall ATT / single-horizon ES under default `cohort_horizon`); diverges for non-uniform weights (survey-weighted, balanced/heterogeneity; any partition) or multiple-obs-per-group under coarser `cohort` (under `horizon` each unit has <=1 obs/group, so the v_it channel only). Stays conservative (Theorem 3) but is not the excess-variance-minimizing form (Supp. App. A.8). Fix `_compute_auxiliary_residuals_treated` + its docstring + the REGISTRY label to the exact unit-clustered Eq. 8, with a diverging-case methodology test. Surfaced by the ImputationDiD PR-A AI review. | `imputation.py`, `docs/methodology/REGISTRY.md` | imputation-validation (PR-B) | Medium |