SCSPILLResults

utils.scspill_helpers.structures.SCSPILLResults()

Standardized results of a SCSPILL fit, for any model.

Subclasses :class:scspill.config_models.BaseEstimatorResults, so the flat effect surface (att, att_ci, counterfactual, gap, donor_weights, pre_rmse, .plot()) resolves through the shared contract for every model. The rest is typed:

• :attr:method – the model that produced the fit; it mirrors SCSPILLConfig.method and the suffix of method_details.method_name ("SCSPILL/<method>");
• :attr:inputs – the prepared panel (with the spatial weights for sar, the exposure matrix for cd);
• :attr:effects_detail – the cross-model effect contract: the counterfactual path and band, and the time-by-control spillover panel with its band;
• :attr:sar / :attr:cd – the model’s own fit. Exactly the slot named by :attr:method is set; the other is None.

Model-specific accessors read the matching slot – alpha_hat, rho_hat, diagnostics() for sar; effects_panel, effect_ci, test_hypothesis() for cd – and raise :class:AttributeError on a result of the other model.

Attributes

Name	Description
acc_rho	Post-burn acceptance rate of the rho Metropolis step.
alpha_draws	Step-1 alpha draws, shape (M, N).
alpha_hat	Posterior mean of the synthetic weights alpha.
alpha_posterior	Step-1 posterior block of the synthetic weights (sar only).
att_by_unit	Average post-treatment effect on every treated unit.
att_scm	ATT of the no-spillover synthetic-control comparator.
effect_ci	Pointwise interval of every unit’s effect, by ci_method (cd only).
effect_matrix	The exposure matrix A used by the fit (cd only).
effects_panel	Estimated effect on every unit by post period (cd only).
intercepts	Intercepts of every unit’s SCM equation (cd only).
kappa_test	The kappa_A structure test by post period (cd only).
mcmc_summary_table	Precomputed posterior summary table (sar only).
placebo_effects	Pre-treatment placebo effects, the P-test references (cd only).
pointwise_ci	Pointwise intervals by P-test inversion (cd only).
pointwise_p_values	P value of every unit’s effect by post period (cd only).
pre_residuals	Pre-treatment SCM residuals of every unit (cd only).
published_ci	Pointwise intervals by the authors’ signed-quantile rule (cd only).
rho_ci	Equal-tailed credible interval for rho at the fit’s ci level.
rho_draws	Step-2 rho draws, shape (M,).
rho_ess	Effective sample size of the rho chain.
rho_hat	Posterior mean of the spillover intensity rho.
sar_posterior	Step-2 posterior block of the SAR process (sar only).
scm_matrix	All-unit SCM weight matrix B (cd only).
spillover_lower	Pointwise lower credible band of the spillover effects.
spillover_panel	Posterior-mean spillover effects, (T, N) time-by-donor.
spillover_upper	Pointwise upper credible band of the spillover effects.
treated_labels	Every treated unit; the first is the headline of the effect surface.
unit_labels	Every unit: the treated units first, then the controls.

Methods

Name	Description
diagnostics	Posterior summary and convergence diagnostics table.
plot	Plot the fitted result.
select_structure_by_kappa	Choose among exposure structures by kappa_A (cd only).
test_hypothesis	Test C @ alpha_t = d by the pre-treatment P distribution (cd only).

diagnostics

utils.scspill_helpers.structures.SCSPILLResults.diagnostics(
    which_alpha=None,
    top_n_alpha=6,
    which_beta=None,
    top_n_beta=6,
)

Posterior summary and convergence diagnostics table.

Builds one row per monitored chain (rho, sigma2, selected alpha components, and covariate coefficients when present) with posterior mean, sd, quantiles, effective sample size, split-chain R-hat, Monte Carlo standard error, and a Geweke z-score – mirroring the R package’s diagnostics() summary.

Parameters

Name	Type	Description	Default
which_alpha	list	Donor labels whose alpha chains to include. Defaults to the top_n_alpha donors by absolute posterior-mean weight.	None
top_n_alpha	int	Number of top-|alpha| donors monitored when which_alpha is None.	6
which_beta	list	Covariate names whose beta chains to include. Defaults to the first top_n_beta covariates.	None
top_n_beta	int	Number of covariates monitored when which_beta is None.	6

Returns

Name	Type	Description
	pd.DataFrame	One row per parameter with columns mean, sd, q025, q50, q975, ess, rhat_split, mcse, geweke_z.

plot

utils.scspill_helpers.structures.SCSPILLResults.plot(
    kind='auto',
    *,
    ax=None,
    **overrides,
)

Plot the fitted result.

Parameters

Name	Type	Description	Default
kind	str	"auto" / "counterfactual" / "gap" use the shared effect-plot contract; "panel", "full", "effect", "spill_top", "weights" (both models), "rho", "trace" (sar), "spillover" and "kappa" (cd) route to :func:scspill.utils.scspill_helpers.plotter.plot_scspill.	"auto"
ax	matplotlib Axes	Draw into an existing axis (single-panel kinds only).	None
**overrides	Any	Cosmetic overrides forwarded to the plotting layer.	{}

Returns

Name	Type	Description
	matplotlib.axes.Axes or np.ndarray of Axes

select_structure_by_kappa

utils.scspill_helpers.structures.SCSPILLResults.select_structure_by_kappa(
    candidates,
    *,
    statistic='v3',
)

Choose among exposure structures by kappa_A (cd only).

See :func:scspill.utils.scspill_helpers.cd.inference.select_structure_by_kappa.

test_hypothesis

utils.scspill_helpers.structures.SCSPILLResults.test_hypothesis(
    C,
    *,
    d=None,
    period=None,
    weight=None,
    quantile_method=None,
)

Test C @ alpha_t = d by the pre-treatment P distribution (cd only).

See :meth:scspill.utils.scspill_helpers.cd.structures.CDFit.test_hypothesis.