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

Both models are selected through one configuration, SCSPILLConfig(method=...), and return one result type.

• sar (the default) routes spillovers through spatial weights you supply, scaled by a single intensity ρ that is estimated rather than assumed. It 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.
• cd fits an intercept-adjusted simplex synthetic control for every unit. A known exposure structure then separates the direct effect from each spillover in every post-treatment period. The structure can be named units with free effects, one shared spillover, a spillover decaying with distance, or any exposure matrix. Andrews-type P tests give the inference for any linear hypothesis; the κ_A test checks the structure; a sensitivity analysis bounds the bias of missed spillovers. Its defaults are the paper's (v3) definitions.

The inclusive SCM of Di Stefano & Mellace and the partial-interference SCG of Grossi et al. remain on the roadmap.

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

import numpy as np
from scspill.data import load_california_cd

cd = SCSPILL(load_california_cd(51).config_kwargs()).fit()   # method="cd"

cd.att                             # average direct effect on California
cd.effects_panel[["CA", "NV"]]     # direct effect and Nevada's spillover, by year
cd.effect_ci["NV"]                 # pointwise 95% intervals (P-test inversion)
no_spill = np.eye(len(cd.unit_labels))[1:]          # every unit but California
cd.test_hypothesis(no_spill, period=1990)         # "no spillover anywhere" in 1990
cd.kappa_test                      # is the assumed structure right?
cd.plot(kind="spillover")          # every exposed state's effect with intervals

Package layout

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.

The cd model is checked against three independent sources:

• the paper (v3): its statements on the Proposition 99 application, including Figure 3's sensitivity break-even points;
• the authors' replication code: every P value of their Proposition 99 output, and the statistics of their simulation code;
• mlsynth's SPILLSYNTH(method="cd"): to solver tolerance, with identical P values.

See Replicating Cao & Dowd.

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 it as (machine-readable metadata lives in CITATION.cff):

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

Authors: Carlos Mendez · Shosei Sakaguchi · Hayato Tagawa

Acknowledgments

The library's design, syntax, and infrastructure are based on Jared Greathouse's mlsynth, a larger and more comprehensive package of synthetic control methods. The documentation stack follows geometrics, from the QuaRCS lab, where scspill is developed. The sar model is cross-validated, every release, against the MIT-licensed replication package for the article it implements; that package's copyright notice is retained in LICENSE. The cd model implements Jianfei Cao and Connor Dowd's method and is checked against their replication repository; its implementation was contributed by Hayato Tagawa.

License

MIT