API Reference

Estimator

Configure once, fit once. SCSPILL(config).fit() runs the spillover model named by method — "sar" (default), the Bayesian spatial sampler, or "cd", Cao & Dowd’s all-unit synthetic controls under a known exposure structure with P-test inference — and returns a SCSPILLResults holding the shared effect surface and the model’s own fit. The model catalogue says which models exist.

SCSPILL Spillover-aware synthetic control estimator (models sar and cd).

Configuration

One pydantic input contract for every model: method, the long panel and its column names, and the fields each model reads, marked (method='sar') or (method='cd'). For sar: the spatial weights spatial_w / spatial_W, covariates, the MCMC budget, priors, and the paper-correct switches (beta_prior, propagate_alpha, adapt_rho). For cd: the exposure structure (affected_units, spillover_structure, unit_distances, effect_matrix), weighting, and the inference switches (quantile_method, ci_method, reference_mode). Setting a field of the model you did not select is an error.

SCSPILLConfig Configuration for a spillover synthetic-control fit, any model.

Results

One result type for every model. The shared surface — att, att_ci, counterfactual, gap, donor_weights, the time-by-control spillover panel with its bands, and plot() — works for both; the model’s own fit sits in a typed slot (result.sar, result.cd). sar adds the posterior blocks and diagnostics(); cd adds effects_panel, effect_ci, pointwise_p_values, kappa_test, test_hypothesis() and select_structure_by_kappa(). Accessors of the other model raise AttributeError.

SCSPILLResults Standardized results of a SCSPILL fit, for any model.

Result containers

The frozen dataclasses behind a result — the model-agnostic prepared panel and effect contract, the sar model’s inputs and posterior blocks, and the cd model’s inputs, fit, P tests, efficient estimator, sensitivity weights and structure selection.

containers.PanelInputs A prepared long panel, split into treated and control outcomes.
containers.SCSPILLEffects Treatment and spillover effects: the contract every model fills.
sar.structures.SARInputs Prepared estimation inputs for the sar model.
sar.structures.AlphaPosterior Step-1 posterior: horseshoe draws of the synthetic weights alpha.
sar.structures.SARPosterior Step-2 posterior: the SAR block conditional on alpha_hat.
cd.structures.CDInputs Prepared estimation inputs for the cd model.
cd.structures.CDFit Everything the cd pipeline produced.
cd.structures.CDTestResult A P test with its pre-treatment reference distribution.
cd.structures.CDEfficientFit The lower-variance (efficient) estimator of Cao & Dowd v3 Section S.1.1.
cd.structures.PureDonorSensitivity Misspecification-bias weights of the two estimators of the direct effect.
cd.structures.KappaSelection Choice among candidate exposure structures by the kappa_A statistic.

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

Three bundled panels, each returned as a SpillPanel whose config_kwargs() feeds SCSPILLConfig directly: the sar article’s 39-state California and 34-country Sudan panels with their spatial weights, and Cao & Dowd’s 51- (or 41-) unit Proposition 99 panel, treated from 1989, with the paper’s exposed states.

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.
load_california_cd Load Cao and Dowd’s Proposition 99 panel: 1970–2000, treated from 1989.