scspill 0.1.0__tar.gz

scspill-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Mendez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scspill-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+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

scspill-0.1.0/README.md

@@ -0,0 +1,116 @@
+<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

scspill-0.1.0/pyproject.toml

@@ -0,0 +1,136 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scspill"
+version = "0.1.0"
+description = "Bayesian spatial-spillover synthetic control (Sakaguchi & Tagawa) for causal inference on panel data."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Carlos Mendez", email = "carlosmendez777@gmail.com" }]
+keywords = [
+    "synthetic control",
+    "spillover effects",
+    "spatial econometrics",
+    "bayesian inference",
+    "causal inference",
+    "panel data",
+    "MCMC",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "pandas>=2.0",
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "matplotlib>=3.8",
+    "pydantic>=2.0",
+    "threadpoolctl>=3.6.0",
+]
+
+[project.optional-dependencies]
+# JIT-accelerated Gibbs/SAR kernels. Optional because numba wheels can lag new
+# Python releases; the pure-NumPy path is always available.
+numba = ["numba>=0.60"]
+all = ["scspill[numba]"]
+
+[project.urls]
+Homepage = "https://github.com/quarcs-lab/scspill"
+Documentation = "https://quarcs-lab.github.io/scspill/"
+Repository = "https://github.com/quarcs-lab/scspill"
+Issues = "https://github.com/quarcs-lab/scspill/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pytest-xdist>=3",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "pandas-stubs",
+]
+docs = [
+    "quartodoc>=0.11",
+    "griffe<1",
+    "jupyter",
+    "nbformat>=5.9",
+]
+
+# ---------------------------------------------------------------------------
+# Packaging: flat layout, in-package tests excluded from the wheel (mlsynth
+# convention), bundled case-study CSVs shipped as package data.
+# ---------------------------------------------------------------------------
+[tool.setuptools.packages.find]
+include = ["scspill*"]
+exclude = ["scspill.tests*"]
+
+[tool.setuptools.package-data]
+scspill = ["py.typed"]
+"scspill.data" = ["files/*.csv"]
+
+# ---------------------------------------------------------------------------
+# Tooling
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["scspill"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "D", "RUF"]
+ignore = [
+    "D100", "D104", "D105", "D107",   # module/package/magic/__init__ docstrings
+    "D106",                            # pydantic `class Config` blocks need no docstring
+    "E501",                            # line length handled by the formatter
+]
+# Greek symbols appear in scientific prose and labels: alpha donor weights,
+# rho spillover intensity, tau treatment effect, sigma error scale.
+allowed-confusables = ["α", "ρ", "τ", "σ", "β", "γ", "η", "ξ", "ω", "φ", "ψ", "λ", "−"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"scspill/tests/*" = ["D"]
+"docs/*" = ["D"]
+"tools/*" = ["D"]
+"benchmarks/*" = ["D"]
+# json_encoders in the pydantic Config blocks (mlsynth-inherited surface).
+"scspill/config_models.py" = ["RUF012"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_unused_configs = true
+ignore_missing_imports = true
+files = ["scspill"]
+exclude = ["scspill/tests"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "--strict-markers --strict-config"
+testpaths = ["scspill/tests"]
+markers = [
+    "slow: long-running tests (full-length MCMC chains, large Monte-Carlo designs)",
+]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.coverage.run]
+source = ["scspill"]
+branch = true
+omit = ["scspill/tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = ["pragma: no cover", "raise NotImplementedError", "if TYPE_CHECKING:"]

scspill-0.1.0/scspill/__init__.py

@@ -0,0 +1,82 @@
+"""scspill: Bayesian spatial-spillover synthetic control.
+
+Implements:
+
+    Sakaguchi, S., & Tagawa, H. "Identification and Bayesian Inference for
+    Synthetic Control Methods with Spillover Effects." The Econometrics
+    Journal.
+
+A synthetic control method that relaxes SUTVA: spillovers from the treated
+unit to the donor pool are modeled through a spatial-autoregressive (SAR)
+structure with user-supplied spatial weights, and both the treatment effect on
+the treated and the spillover effect received by every control unit are
+identified from the synthetic-control weights ``alpha``, the spillover
+intensity ``rho``, and the weights ``(w, W)``. Estimation is a two-step
+Bayesian sampler: a horseshoe Gibbs sampler for ``alpha`` on the
+pre-treatment fit, then a SAR block (latent AR(1) factors, covariates, and a
+random-walk Metropolis step for ``rho``) conditional on the posterior mean of
+``alpha``.
+
+Public API::
+
+    from scspill import SCSPILL, SCSPILLConfig
+
+    result = SCSPILL(config).fit()   # -> SCSPILLResults
+
+plus the companion subpackages :mod:`scspill.validation` (Geweke joint
+distribution test, prior sensitivity, prior predictive checks),
+:mod:`scspill.simulate` (the paper's Monte Carlo engine), and
+:mod:`scspill.data` (the bundled California Proposition 99 and Sudan
+secession case studies).
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:  # pragma: no cover - fallback exercised only in odd install states
+    __version__ = version("scspill")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0.dev0"
+
+from scspill.exceptions import (
+    ScspillConfigError,
+    ScspillDataError,
+    ScspillError,
+    ScspillEstimationError,
+    ScspillPlottingError,
+)
+
+__all__ = [
+    "SCSPILL",
+    "SCSPILLConfig",
+    "SCSPILLResults",
+    "ScspillConfigError",
+    "ScspillDataError",
+    "ScspillError",
+    "ScspillEstimationError",
+    "ScspillPlottingError",
+    "__version__",
+]
+
+# Lazy exports (PEP 562): the estimator stack imports pandas/pydantic/scipy,
+# so defer those imports until first attribute access for fast cold starts.
+_LAZY_EXPORTS = {
+    "SCSPILL": ("scspill.estimators.scspill", "SCSPILL"),
+    "SCSPILLConfig": ("scspill.utils.scspill_helpers.config", "SCSPILLConfig"),
+    "SCSPILLResults": ("scspill.utils.scspill_helpers.structures", "SCSPILLResults"),
+}
+
+
+def __getattr__(name: str):
+    """Resolve lazily exported public names (PEP 562)."""
+    target = _LAZY_EXPORTS.get(name)
+    if target is not None:
+        import importlib
+
+        module_path, attr = target
+        return getattr(importlib.import_module(module_path), attr)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    """Include lazy exports in ``dir(scspill)``."""
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))