API Reference
Estimator
Configure once, fit once. SCSPILL(config).fit() runs the spillover model named by method — today "sar", whose two-step sampler fits the horseshoe synthetic weights and then the SAR spillover block — and returns a SCSPILLResults with the treatment effect, its credible interval, and the spillover received by every donor. The model catalogue says which models exist.
| SCSPILL | Spillover-aware synthetic control estimator (model sar). |
Configuration
The pydantic input contract — method (the spillover model; "sar" is the only accepted value today), the long panel and its column names, the spatial weights spatial_w / spatial_W (label-aligned), covariates, the MCMC budget, priors, and the paper-correct switches (beta_prior, propagate_alpha, adapt_rho) with their R-compatible settings.
| SCSPILLConfig | Configuration for a spillover synthetic-control fit (today, model sar). |
Results
The standardized posterior report — flat accessors (att, att_ci, counterfactual, gap, donor_weights), the posterior blocks with their full draw arrays, the time-by-donor spillover panel with credible bands, a diagnostics() summary table, and plot() panels.
| SCSPILLResults | Standardized results of the SCSPILL estimator. |
| SCSPILLInputs | Prepared estimation inputs for the SCSPILL estimator. |
| AlphaPosterior | Step-1 posterior: horseshoe draws of the synthetic weights alpha. |
| SARPosterior | Step-2 posterior: the SAR block conditional on alpha_hat. |
| SCSPILLEffects | Posterior treatment and spillover effects (Theorems 3.1-3.2). |
Validation & prior checks
The sar article’s appendix machinery as user-facing functions — the Geweke (2004) joint distribution test of that model’s Step-2 sampler (simplified and production kernels), prior-sensitivity re-runs across hyperparameter grids, and prior predictive checks against nine summary statistics of the pre-treatment donor panel. These target sar; the Geweke harness already accepts a custom kernel, so a model added later plugs in here rather than replacing it.
| geweke_test | Run the Geweke joint distribution test of the Step-2 sampler. |
| prior_sensitivity | Re-run the Step-2 posterior across a grid of prior settings. |
| prior_predictive | Prior predictive check of the Step-2 model. |
| run_posterior_mcmc | Sample the Step-2 posterior on a fixed panel under explicit priors. |
| ppc_stats | Nine summary statistics of a pre-treatment donor panel. |
| plot_geweke | Dot plot of the Geweke z-scores with the critical band. |
| plot_prior_predictive | Histogram grid of the prior predictive statistics with observed markers. |
Simulation
The sar article’s Monte Carlo engine — simulate spillover panels from a known SAR data-generating process on a rook lattice, fit the classical SCM, the Bayesian horseshoe SCM, and sar on each replication, and score bias, RMSE, and coverage (its Tables 1–2 design). This is that model’s design, not a package-wide framework.
| scspill_sim_dgp | Simulate one spillover panel from the paper’s SAR DGP. |
| run_one_sim | Run one simulation replication: DGP, three estimators, metrics. |
| run_many_sim | Run many replications, optionally in parallel. |
| summarize_many | Aggregate replication metrics into per-method summary rows. |
| mc_grid | Run the paper’s Monte Carlo grid (Tables 1-2 design). |
| load_r_mc_reference | Load the frozen R Monte Carlo results for comparison. |
| rook_W | Binary rook adjacency on an nrow x ncol lattice (row-major ids). |
| make_w | Build the indicator exposure vector linking the treated unit to selected controls. |
Diagnostics
Model-agnostic convergence diagnostics for posterior chains — effective sample size, split-chain R-hat, Monte Carlo standard errors, Geweke z-scores, and the posterior summary table behind SCSPILLResults.diagnostics().
| ess_acf | Effective sample size of a chain via initial-positive-sequence ACF. |
| split_rhat | Split-chain R-hat of a single chain (halves as pseudo-chains). |
| mcse_from_ess | Monte Carlo standard error sd(x) / sqrt(ess). |
| geweke_z | Geweke convergence z-score comparing early and late chain segments. |
| mcmc_summary | Posterior summary table for a set of named chains. |
Datasets
Two bundled spillover case studies, shipped inside the wheel — the California Proposition 99 tobacco panel (39 states, 1970–2000, rook contiguity weights) and the 2011 Sudan secession panel (34 African countries, 2000–2015, bilateral-trade weights). Each loader returns a SpillPanel whose config_kwargs() feeds any spillover model’s configuration directly.
| load_california | Load the California Proposition 99 tobacco panel with rook-contiguity weights. |
| load_sudan | Load the 2011 Sudan secession panel with bilateral-trade weights. |
| SpillPanel | A bundled case study, ready to feed :class:scspill.SCSPILLConfig. |