scspill for AI agents and LLMs

The machine-readable entry points and the minimal working contract

This page is the stable entry point for AI assistants working with scspill.

Machine-readable indexes

• https://quarcs-lab.github.io/scspill/llms.txt — curated overview: what the package does, the input contract, and links to every docs page (llmstxt.org convention).
• https://quarcs-lab.github.io/scspill/llms-full.txt — the full docs corpus: every page’s source plus the signature and docstring of every public function.

Both are also advertised via <link rel="alternate"> tags on every page and in robots.txt.

The contract in one block

from scspill import SCSPILL
from scspill.data import load_california

panel = load_california()          # or build your own inputs (below)
result = SCSPILL(
    {
        "df": panel.df,            # long panel: one row per (unit, period)
        "outcome": "cigsale",      # column names, not data
        "treat": "treated",        # 0/1; 1 = treated unit in post periods
        "unitid": "state",
        "time": "year",
        "spatial_w": panel.spatial_w,   # Series/dict by donor label, or array
        "spatial_W": panel.spatial_W,   # labelled (N, N) DataFrame, or array
        "covariates": ["retprice"],     # optional columns of df
        "m_iter": 20_000,
        "burn": 10_000,
        "seed": 42,
        "display_graphs": False,
    }
).fit()

result.att              # float: average treatment effect on the treated
result.att_ci           # (lo, hi): 95% credible interval
result.rho_hat          # float: spillover intensity posterior mean
result.rho_ci           # (lo, hi)
result.counterfactual   # (T,) array: the treated unit's no-treatment path
result.spillover_panel  # (T, N) DataFrame: effect received by each donor
result.diagnostics()    # DataFrame: mean/sd/quantiles/ESS/R-hat per chain
result.plot(kind="panel")   # counterfactual | effect | top spillovers

The cd model (Cao & Dowd) uses the same estimator and result type:

from scspill.data import load_california_cd

result = SCSPILL(
    {
        "method": "cd",
        "df": df, "outcome": "cigs", "treat": "treated",
        "unitid": "state", "time": "year",
        "affected_units": ["AZ", "NV", "OR"],   # controls that may be exposed
        # or spillover_structure="homogeneous" | "distance_decay"
        #    (with unit_distances={...}) | "custom" (with effect_matrix=A)
        "display_graphs": False,
    }
).fit()                    # or: SCSPILL(load_california_cd(51).config_kwargs()).fit()

result.att                 # average direct effect on the (first) treated unit
result.effects_panel       # (T1, units) DataFrame: direct effects and spillovers
result.effect_ci["NV"]     # pointwise interval of one unit's effect, by period
result.pointwise_p_values  # P value of every unit's effect, by period
result.test_hypothesis(C, d=0, period=1990)   # any C @ alpha_t = d
result.kappa_test          # structure test by period
result.cd.sensitivity      # bias bounds under missed spillovers

See the cd model page.

Rules of thumb for agents

• The treated unit and the treatment date are inferred from the treat column — there is no treated_unit argument.
• One config for every model: method selects it ("sar" by default), and setting a field of the other model (e.g. seed with method="cd") raises ScspillConfigError. Fields are marked (method='sar') / (method='cd').
• cd‘s defaults are the paper’s (v3 Section 4) inference; quantile_method="linear" and ci_method="published" reproduce the authors’ application code.
• Spatial weights align by label; pass pandas objects whenever you have labels. Raw/unnormalized weights are fine (normalization is internal).
• sar: rho is the weakly identified parameter: for real analyses use tens of thousands of iterations and check result.rho_ess and result.diagnostics().
• Errors are typed: ScspillConfigError (bad configuration), ScspillDataError (bad panel/weights), ScspillEstimationError, ScspillPlottingError — all subclass ScspillError.
• Sampler validation lives in scspill.validation (geweke_test, prior_sensitivity, prior_predictive); Monte Carlo tooling in scspill.simulate; bundled panels in scspill.data.
• The estimator’s architecture mirrors mlsynth (pydantic config in, standardized results object out), so mlsynth patterns transfer.

Install

pip install scspill              # or: pip install "scspill[numba]"