Add the cd model: Cao & Dowd synthetic control with spillovers

.gitattributes

@@ -0,0 +1,2 @@
+# Preserve the authors' BOM and CRLF in the frozen state-list input.
+scspill/data/files/cao_dowd/state_list.csv whitespace=cr-at-eol

CHANGELOG.md

@@ -2,7 +2,29 @@
 
 ## Unreleased
 
-Authorship and citation metadata only; no functional change.
+### New model: `cd` (Cao & Dowd)
+
+- **`method="cd"` implements Cao and Dowd (arXiv:1902.07343v4)**: an
+  intercept-adjusted simplex SCM for every unit, a fixed exposure structure
+  given by `affected_units` or a labeled `effect_matrix`, period-specific
+  direct and spillover effects, Andrews-type P tests for `C α_t = d`, and the
+  `κ_A` specification test. `load_california_cd(51)` and
+  `load_california_cd(41)` bundle the authors' 50-state-plus-DC panel.
+- **The defaults follow the authors' Proposition 99 replication code**, so a
+  default fit reproduces the paper's Section 6 tables and Figure 4:
+  interpolated critical values (`quantile_method="linear"`) and intervals
+  that add the signed pre-treatment error quantiles to the estimate
+  (`ci_method="published"`, returned by `effect_ci`). The paper's Section 4
+  definitions are available as `quantile_method="empirical"`,
+  `ci_method="inversion"` and `reference_mode="leave_one_period_out"`; the
+  differences are listed under Caveats in `docs/models/cd.qmd`.
+- `scspill/tests/test_cd.py` checks the 51- and 41-unit fits against the
+  authors' frozen output (`jcao0/synthetic-control-spillover`, commit
+  `86004020`), stored in `benchmarks/reference/cao_dowd/`.
+
+### Authorship and citation
+
+No functional change.
 
 - **The software has three authors and one citation.** Shosei Sakaguchi and
   Hayato Tagawa have joined the project as co-authors, so `CITATION.cff`, the

README.md

@@ -24,18 +24,19 @@ express at all.
 | Model | `method` | Reference | Class | Docs |
 |---|---|---|---|---|
 | Bayesian spatial-autoregressive spillover SCM | `"sar"` | [Sakaguchi & Tagawa (2026)](https://doi.org/10.1093/ectj/utag006), *The Econometrics Journal* | `SCSPILL` | [`sar`](https://quarcs-lab.github.io/scspill/models/sar.html) |
+| SCM with spillover effects | `"cd"` | [Cao & Dowd, v4](https://arxiv.org/html/1902.07343v4) | `SCSPILL` | [`cd`](https://quarcs-lab.github.io/scspill/models/cd.html) |
 
-One model ships today. `sar` routes spillovers through spatial weights you
+`sar` routes spillovers through spatial weights you
 supply, scaled by a single intensity ρ that is estimated rather than assumed,
 fits unconstrained horseshoe-shrunk synthetic weights, and returns full
 Bayesian uncertainty for both estimands. At ρ = 0 it collapses exactly to the
 Bayesian horseshoe synthetic control.
 
-Three further spillover-aware models — Cao & Dowd, the inclusive SCM of
-Di Stefano & Mellace, and the partial-interference SCG of Grossi et al. — are
-on the [roadmap](https://quarcs-lab.github.io/scspill/models/#planned). They
-are **not implemented**, and `SCSPILLConfig` rejects their names rather than
-falling back silently.
+`cd` uses intercept-adjusted SCM equations for every unit and a specified
+exposure structure to recover direct and spillover effects. It includes
+Andrews P tests and a structure test. The inclusive SCM of Di Stefano &
+Mellace and partial-interference SCG of Grossi et al. remain on the
+[roadmap](https://quarcs-lab.github.io/scspill/models/#planned).
 
 The estimator architecture follows
 [mlsynth](https://github.com/jgreathouse9/mlsynth) (a pydantic config in, a
@@ -76,10 +77,10 @@ result.plot(kind="panel")          # counterfactual | effect | top spillovers
 
 | Subpackage | What it does | Docs |
 |---|---|---|
-| `scspill` | The model layer. `SCSPILL(config).fit()` — today the `sar` model's two-step Bayesian sampler (horseshoe synthetic weights, SAR spillover block, adaptive Metropolis for the spillover intensity) and its identification formulas | [Get started](https://quarcs-lab.github.io/scspill/get-started.html) |
+| `scspill` | The model layer. `SCSPILL(config).fit()` dispatches the Bayesian `sar` and Cao–Dowd `cd` estimators | [Models](https://quarcs-lab.github.io/scspill/models/) |
 | `scspill.validation` | `sar`'s sampler validation: the Geweke (2004) joint distribution test, prior-sensitivity grids, prior predictive checks | [Validation](https://quarcs-lab.github.io/scspill/articles/validation.html) |
 | `scspill.simulate` | `sar`'s Monte Carlo engine: rook-lattice SAR DGP, SCM/BSCM/SCSPILL comparison, the Tables 1–2 grid | [Simulation study](https://quarcs-lab.github.io/scspill/articles/simulation-study.html) |
-| `scspill.data` | The bundled California Prop 99 and Sudan secession spillover panels — model-agnostic, usable by any model added later | [Datasets](https://quarcs-lab.github.io/scspill/articles/datasets.html) |
+| `scspill.data` | California and Sudan panels, plus the authors' 51/41-unit Cao–Dowd Proposition 99 data | [Datasets](https://quarcs-lab.github.io/scspill/articles/datasets.html) |
 
 ## `sar` is validated, not just implemented
 

benchmarks/reference/cao_dowd/README.md

@@ -0,0 +1,41 @@
+# Cao–Dowd reference inputs
+
+Source: [jcao0/synthetic-control-spillover](https://github.com/jcao0/synthetic-control-spillover),
+commit `86004020a248c7ee18f3c8a68b1e41db6abc0dda`, for
+[Cao and Dowd, arXiv:1902.07343v4](https://arxiv.org/html/1902.07343v4).
+
+- `scspill/data/files/cao_dowd/cigs_consumption.csv` and `state_list.csv` are
+  copied from `replication files/application/prop99 spillover 51 units/data/`.
+  These are the CDC-based public-domain input data: 50 states plus DC,
+  1970–2000, with treatment beginning in 1989. They are distinct from the
+  package's older 39-state, 1988-onward California panel.
+- `results_51.json` and `results_41.json` are the authors' frozen application
+  outputs in the respective `prop99 spillover * units/output/` directories.
+- `inference_replication_1.npz` contains the six first-replication outcome
+  panels generated by the authors' inference DGP and the corresponding
+  SP-A direct-effect estimates at effect 5 from
+  `inference/provenance/published_estimates.npz`. The settings are stationary
+  and integrated factors, each at pure-donor distance $r=0,0.5,1$.
+- `loo_reference_stationary_r05_rep1.npy` holds all 50 squared SP-A
+  leave-one-pre-period-out reference statistics for the stationary, $r=0.5$
+  first inference replication. They were independently generated by the
+  authors' `inference/src/procedures.py::andrews_loo_references` at the same
+  pinned commit. The slow estimator test compares all 50 statistics.
+- `kappa_rep1.json` records the author's range and homogeneous-structure
+  $\kappa_A$ statistics and all 50 full-sample reference values on the
+  stationary, $r=0.5$ first inference panel. The statistic was generated with
+  `kappa_a/src/structures.py` and the fitted SCM equations with
+  `inference/src/scm.py` at the pinned commit.
+
+The bundled application CSV SHA-256 checksums are
+`2b96994df9f28f7a28948fe765a20efa65270cb36662f44422899bbf98119ddc`
+and `8e35c51b30e233bb8059be282d22b7f72637dc2950d7275158f1be26bd4bece8`,
+respectively. The frozen output checksums are
+`06357ece7e87a6b981e23bbe6338219849259b09303f917544d0f718a5eb55aa`
+for 51 units, `0cf41c805905c6c989a66262a721800d674632ec958acc7f835be76f78aaa1f3`
+for 41 units. The derived simulation fixture has SHA-256
+`7634351bfb1ea95242b74a89dfe8d10d865f48f72572ddbde50a4944cdec88de`.
+The leave-one-out reference vector has SHA-256
+`b07e8cf0ed30fbdbc8d654ac8e2e11819239547cb8ff2c664f7ec4345a1d7e1a`.
+The $\kappa_A$ reference JSON has SHA-256
+`267c7b9fd9e09e0c458ffcad78044468e99c36d5c8bec86d21af358ae15f9a45`.

benchmarks/reference/cao_dowd/kappa_rep1.json

@@ -0,0 +1,112 @@
+{
+  "range": {
+    "statistic": 5.866044590640894,
+    "reference": [
+      6.73742584461722,
+      5.32690209764272,
+      5.598498441459483,
+      5.623980426657359,
+      5.192919548247222,
+      4.682020135408817,
+      5.364715300901857,
+      6.183503725580241,
+      5.826501334400295,
+      5.881860095929147,
+      5.439145864861086,
+      5.969207242167086,
+      5.18314959713628,
+      5.600658356411405,
+      4.500061965114871,
+      5.6278601296189175,
+      4.530813003116822,
+      4.915967585201005,
+      5.281668471926136,
+      4.868597638775217,
+      5.069550240358595,
+      5.37807597568166,
+      5.582020615270328,
+      5.106798781334146,
+      6.1078932913427995,
+      5.579041201566973,
+      5.061085601965185,
+      5.754565605202067,
+      5.185274584811025,
+      5.7658920860929355,
+      4.982686537801549,
+      5.13090731067515,
+      4.660774167963435,
+      5.9948776299576965,
+      5.599733263206939,
+      5.425845828009287,
+      7.505218418787916,
+      5.233609737801514,
+      5.427125269986897,
+      5.379546413464169,
+      5.005961183906842,
+      5.893387001024662,
+      4.951031661362545,
+      5.567837253081451,
+      4.997314126976024,
+      5.983917896087184,
+      5.5179743853345,
+      4.410461998685994,
+      5.111617104499174,
+      5.293821498779172
+    ]
+  },
+  "homogeneous": {
+    "statistic": 6.450032327736446,
+    "reference": [
+      7.325305140324069,
+      6.092936846234802,
+      5.97787511650872,
+      6.319762474386711,
+      5.59939581465682,
+      5.947490124653801,
+      5.938469879304639,
+      6.989714138313834,
+      6.599462236925682,
+      6.253629247435942,
+      6.268952003306721,
+      6.71238972278363,
+      5.998773989074392,
+      6.642238583748685,
+      5.060370994545393,
+      5.943647054228487,
+      5.6774922105981735,
+      6.087482382227443,
+      6.457883341478321,
+      6.5537880825688735,
+      6.081276862424513,
+      6.016756696360435,
+      6.214165698736111,
+      5.804321372017244,
+      6.502287593492488,
+      6.3767956537928265,
+      5.907801616258618,
+      6.431346743910252,
+      6.053265550006875,
+      6.416817655386247,
+      6.524426051519425,
+      6.282811751213115,
+      5.46229311304185,
+      6.665560005113521,
+      6.445135203011679,
+      6.073972320808133,
+      8.065765837744179,
+      6.248489395531836,
+      6.616909732035294,
+      6.491114065730435,
+      5.916013841867676,
+      7.006978715841566,
+      6.2500968200449725,
+      6.2878245525865655,
+      5.924322617261755,
+      7.092850667523054,
+      6.828398469832565,
+      6.314887883517232,
+      5.8329156361119665,
+      5.960573920968978
+    ]
+  }
+}