Metadata-Version: 2.4
Name: scspill
Version: 0.1.0
Summary: Bayesian spatial-spillover synthetic control (Sakaguchi & Tagawa) for causal inference on panel data.
Author-email: Carlos Mendez <carlosmendez777@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/quarcs-lab/scspill
Project-URL: Documentation, https://quarcs-lab.github.io/scspill/
Project-URL: Repository, https://github.com/quarcs-lab/scspill
Project-URL: Issues, https://github.com/quarcs-lab/scspill/issues
Keywords: synthetic control,spillover effects,spatial econometrics,bayesian inference,causal inference,panel data,MCMC
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: matplotlib>=3.8
Requires-Dist: pydantic>=2.0
Requires-Dist: threadpoolctl>=3.6.0
Provides-Extra: numba
Requires-Dist: numba>=0.60; extra == "numba"
Provides-Extra: all
Requires-Dist: scspill[numba]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/quarcs-lab/scspill/main/docs/images/hero-v2.png" alt="scspill — Bayesian synthetic control with spillovers" width="85%">
</p>

# scspill

[![CI](https://github.com/quarcs-lab/scspill/actions/workflows/ci.yml/badge.svg)](https://github.com/quarcs-lab/scspill/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-quarcs--lab.github.io%2Fscspill-blue)](https://quarcs-lab.github.io/scspill/)
[![PyPI](https://img.shields.io/pypi/v/scspill.svg)](https://pypi.org/project/scspill/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/scspill/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/quarcs-lab/scspill/blob/main/notebooks/california.ipynb)

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](https://github.com/jgreathouse9/mlsynth) architecture (a pydantic
config in, a standardized results object out) so the two libraries compose
naturally; the documentation site follows
[geometrics](https://github.com/quarcs-lab/geometrics).

## Installation

```bash
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

```python
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](https://quarcs-lab.github.io/scspill/get-started.html) |
| `scspill.validation` | The Geweke (2004) joint distribution test of the sampler, prior-sensitivity grids, prior predictive checks | [Validation](https://quarcs-lab.github.io/scspill/articles/validation.html) |
| `scspill.simulate` | The paper'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 case studies | [Datasets](https://quarcs-lab.github.io/scspill/articles/datasets.html) |

## 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](https://quarcs-lab.github.io/scspill/articles/method.html).

## 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`](https://quarcs-lab.github.io/scspill/llms.txt)
and [`llms-full.txt`](https://quarcs-lab.github.io/scspill/llms-full.txt).

## Development

```bash
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
