scspill 0.2.0

Synthetic control models with spillover effects: causal inference on panel data when the treatment reaches the donor pool.

scspill

Synthetic control when the treatment leaks. scspill is a Python package of synthetic control models that drop SUTVA on the donor pool: the treatment is allowed to reach the controls, and every model reports two estimands — the effect on the treated unit, purged of the contamination, and the spillover effect received by each donor, which classical synthetic control cannot express at all.

Models

Model	method	Reference	Class	Docs
Bayesian spatial-autoregressive spillover SCM	"sar"	Sakaguchi & Tagawa (2026), The Econometrics Journal	SCSPILL	sar

One model ships today. 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. They are not implemented, and SCSPILLConfig rejects their names rather than falling back silently.

The estimator architecture follows mlsynth (a pydantic config in, a standardized results object out), and the method names match its SPILLSYNTH dispatcher, so the two libraries compose naturally; the documentation site follows geometrics.

Installation

pip install scspill              # NumPy/SciPy sampler backend
pip install "scspill[numba]"     # + JIT-compiled samplers (~10x faster)
pip install "scspill @ git+https://github.com/quarcs-lab/scspill.git"   # latest

Python 3.10+.

At a glance

from scspill import SCSPILL
from scspill.data import load_california

panel = load_california()        # Prop 99 panel + rook-contiguity weights
result = SCSPILL(
    {**panel.config_kwargs(), "m_iter": 20_000, "burn": 10_000, "seed": 42}
).fit()

result.att, result.att_ci          # treatment effect on California + 95% CrI
result.rho_hat, result.rho_ci      # spillover intensity posterior
result.spillover_panel["Nevada"]   # the effect received by Nevada, per year
result.diagnostics()               # ESS / R-hat / MCSE per chain
result.plot(kind="panel")          # counterfactual | effect | top spillovers

Package layout

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
scspill.validation	sar's sampler validation: the Geweke (2004) joint distribution test, prior-sensitivity grids, prior predictive checks	Validation
scspill.simulate	sar's Monte Carlo engine: rook-lattice SAR DGP, SCM/BSCM/SCSPILL comparison, the Tables 1–2 grid	Simulation study
scspill.data	The bundled California Prop 99 and Sudan secession spillover panels — model-agnostic, usable by any model added later	Datasets

sar is validated, not just implemented

The sar model is cross-validated against the authors' R replication package (python benchmarks/run_benchmarks.py --all --report): California and Sudan posteriors against the frozen R credible intervals, the Monte Carlo grid against the paper's frozen Tables 1–2, prior predictive statistics to three decimals, and the samplers against the Geweke joint distribution test. The defaults are paper-correct: several documented bugs of the reference implementation (a covariate memory-layout mismatch, a missing horseshoe prior, alpha-frozen credible intervals, two incoherent factor-block conditionals) are fixed here, each with an escape hatch or a benchmark quantifying the difference — see the sar model page.

Documentation

Full documentation, executed tutorials, and the API reference live at https://quarcs-lab.github.io/scspill/. Machine-readable entry points for AI agents: llms.txt and llms-full.txt.

Development

git clone https://github.com/quarcs-lab/scspill && cd scspill
uv sync --all-extras --group dev --group docs
make test      # pytest (fast tier; `make test-slow` for the long tier)
make lint      # ruff check + format
make typecheck # mypy
make docs      # quartodoc build -> quarto render -> llms.txt

Citing

If you use scspill, please cite both the software and the methodological article (machine-readable metadata lives in CITATION.cff):

Mendez, C., Sakaguchi, S., & Tagawa, H. (2026). Synthetic Control Models with Spillovers in Python (version 0.2.0). https://github.com/quarcs-lab/scspill

Sakaguchi, S., & Tagawa, H. (2026). Identification and Bayesian Inference for Synthetic Control Methods with Spillover Effects. The Econometrics Journal. https://doi.org/10.1093/ectj/utag006

Acknowledgments

The method and the original R/C++ implementation are the work of Shosei Sakaguchi and Hayato Tagawa, who are credited as co-authors of this library on that basis; the Python implementation is by Carlos Mendez and any bug in it is his. Their replication package is MIT-licensed, and every release of scspill is cross-validated against its frozen results. The estimator architecture follows Jared Greathouse's mlsynth; the documentation stack follows the QuaRCS-lab geometrics package.

License

MIT