SyntheticControl.power_analysis#

SyntheticControl.power_analysis(effect_sizes, n_simulations=50, criterion='hdi_excludes_zero', effect_type='relative', holdout_periods=None, sample_kwargs=None, random_seed=None, noise_method='iid_gaussian', block_length=None)[source]#

Simulation-based Bayesian power curve.

For each candidate effect size, runs validate_design() multiple times (with added residual noise) and records detection rates. The simulation perturbs only the treated unit’s pre-period outcomes; donor paths, the model class, the candidate effect size, and the design are fixed across simulations.

The default noise_method="iid_gaussian" preserves the original implementation: it adds iid Gaussian noise with standard deviation equal to the posterior-mean pre-period residual standard deviation. This is a heuristic sensitivity calculation. It assumes independent, homoscedastic Gaussian residual variation, and is not a canonical synthetic-control sampling-distribution power analysis. No clean synthetic-control reference is known for this exact treated-only resampling scheme.

"block_bootstrap" and "ar1" are opt-in sensitivity checks for short-range residual dependence. They are not universally better replacements for iid Gaussian noise. All methods rely on posterior-mean residuals and do not address donor-pool uncertainty, heteroscedasticity, seasonality, posterior-predictive design priors, or pseudo-post misfit bias. Users should compare noise methods and cross-check the resulting curve with placebo-in-space and placebo-in-time diagnostics. The block bootstrap samples overlapping moving blocks of centered residuals. The AR(1) method centers the residuals, estimates the lag-1 coefficient by least squares with no intercept, clips it to [-0.99, 0.99], and simulates innovations from the fitted residual innovation scale.

Parameters:

  • effect_sizes (list[float]) – Candidate effect sizes to evaluate.

  • n_simulations (int) – Number of simulations per effect size.

  • criterion (Literal['hdi_excludes_zero', 'prob_gt_zero', 'recovery_accuracy']) –

    Detection criterion: - "hdi_excludes_zero": 94 % HDI of cumulative impact

    excludes zero.

    • "prob_gt_zero": P(cumulative impact > 0) > 0.95.

    • "recovery_accuracy": posterior mean within 20 % of injected truth.

  • effect_type (Literal['relative', 'absolute']) – Passed through to validate_design.

  • holdout_periods (int | None) – Passed through to validate_design.

  • sample_kwargs (dict | None) – MCMC sampling arguments for refitted models.

  • random_seed (int | None) – RNG seed for reproducible noise injection. When provided and sample_kwargs does not contain "random_seed", deterministic per-refit PyMC seeds are drawn from the same RNG.

  • noise_method (Literal['iid_gaussian', 'block_bootstrap', 'ar1']) – Residual-noise simulation method. "iid_gaussian" keeps the original iid Gaussian behavior. "block_bootstrap" resamples contiguous centered residual blocks. "ar1" estimates and simulates a zero-mean AR(1) residual path.

  • block_length (int | None) – Block length for noise_method="block_bootstrap". If None, uses ceil(sqrt(n_pre)), bounded to the pre-period length. noise_method="ar1" requires at least 3 pre-period residuals; use "iid_gaussian" or "block_bootstrap" for very short pre-periods.

Return type:

PowerCurveResult