scspill 0.1.0

Bayesian spatial-spillover synthetic control (Sakaguchi & Tagawa) for causal inference on panel data.

scspill

Synthetic control when the treatment leaks. scspill is a Python implementation of the Bayesian spatial-spillover synthetic control of Sakaguchi & Tagawa (Identification and Bayesian Inference for Synthetic Control Methods with Spillover Effects, The Econometrics Journal): it relaxes SUTVA by letting the treatment spill over to the donor pool through a spatial-autoregressive channel with user-supplied weights, and estimates both the treatment effect on the treated unit and the spillover effect received by every donor — with full Bayesian uncertainty.

The estimator follows the mlsynth architecture (a pydantic config in, a standardized results object out) 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

What's inside

Subpackage	What it does	Docs
scspill	SCSPILL(config).fit() — the two-step Bayesian sampler (horseshoe synthetic weights, SAR spillover block, adaptive Metropolis for the spillover intensity) and the identification formulas	Get started
scspill.validation	The Geweke (2004) joint distribution test of the sampler, prior-sensitivity grids, prior predictive checks	Validation
scspill.simulate	The paper'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 case studies	Datasets

Validated against the R replication package

The Python port 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 method article.

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 the methodological article and the software (see CITATION.cff):

Sakaguchi, S., & Tagawa, H. Identification and Bayesian Inference for Synthetic Control Methods with Spillover Effects. The Econometrics Journal.

Acknowledgments

The method and reference implementation are by Shosei Sakaguchi and Hayato Tagawa. The estimator architecture follows Jared Greathouse's mlsynth; the documentation stack follows the QuaRCS-lab geometrics package.

License

MIT