Skip to content

api.md

Latest commit

 

History

History
159 lines (120 loc) · 7.15 KB

api.md

File metadata and controls

159 lines (120 loc) · 7.15 KB

API Reference

CausalImpact

from causal_impact import CausalImpact

ci = CausalImpact(data, pre_period, post_period, model_args=None, alpha=0.05)

Constructor Parameters

Parameter Type Description
data DataFrame or ndarray First column is the response variable, remaining columns are covariates
pre_period list[str | int] [start, end] of the pre-intervention period
post_period list[str | int] [start, end] of the post-intervention period
model_args dict or ModelOptions MCMC parameters (see below)
alpha float Significance level for credible intervals (default: 0.05)

Methods

Method Returns Description
summary(output="summary", digits=2) str Tabular summary of causal effects. Set output="report" for narrative form.
report() str Narrative interpretation of results (shortcut for summary(output="report"))
plot(metrics=None) Figure Matplotlib figure with original/pointwise/cumulative panels. Pass a list like ["original", "cumulative"] to select panels.
run_placebo_test(n_placebos=None, min_pre_length=3) PlaceboTestResults Validates the causal effect against a null distribution from pre-period splits.
run_conformal_analysis(alpha=None) ConformalResults Distribution-free prediction intervals via split conformal inference.

Properties

Property Type Description
inferences DataFrame Per-timestep actuals, predictions, prediction s.d., and effect intervals
summary_stats dict Aggregate statistics (effect mean, CI, p-value, etc.)
posterior_inclusion_probs ndarray | None Posterior inclusion probability per covariate (spike-and-slab only; returns None for horseshoe)
posterior_shrinkage ndarray | None Mean shrinkage factor kappa_j per covariate (horseshoe only; returns None for spike-and-slab). Values near 0 = weakly shrunk (included), near 1 = strongly shrunk.

ModelOptions

from causal_impact import ModelOptions

opts = ModelOptions(niter=5000, seed=123)
ci = CausalImpact(data, pre_period, post_period, model_args=opts)

Parameters

Parameter Type Default Description
niter int 1000 Total MCMC iterations
nwarmup int 500 Burn-in iterations to discard
nchains int 1 Number of MCMC chains
seed int 0 Random seed for reproducibility
prior_level_sd float 0.01 Prior standard deviation for the local level
standardize_data bool True Standardize data before fitting
expected_model_size int 2 Expected number of active covariates for spike-and-slab prior
dynamic_regression bool False Enable time-varying regression coefficients
prior_type str "spike_slab" "spike_slab" (discrete variable selection) or "horseshoe" (continuous shrinkage). Horseshoe is recommended for dense DGP settings.
state_model str "local_level" "local_level" or "local_linear_trend"
nseasons int | None None Seasonal cycle count. nseasons=1 is equivalent to no seasonal component.
season_duration int | None None Duration of each seasonal block; defaults to 1 when nseasons is set. Requires nseasons to be set.

CausalImpactResults

Returned by ci._results. A frozen dataclass containing all computed quantities.

Fields

Field Type Description
actual ndarray Observed y values in the post period
point_effects ndarray Mean effect per time point
point_effect_lower ndarray Lower pointwise credible interval per time point
point_effect_upper ndarray Upper pointwise credible interval per time point
point_effect_mean float Mean of point effects across time
ci_lower float Lower CI bound on average effect
ci_upper float Upper CI bound on average effect
cumulative_effect_total float Total cumulative effect
relative_effect_mean float Relative effect (effect / predicted)
p_value float Bayesian one-sided tail probability
predictions_mean ndarray Mean counterfactual prediction
predictions_sd ndarray Posterior standard deviation of the counterfactual prediction
predictions_lower ndarray Lower CI on counterfactual
predictions_upper ndarray Upper CI on counterfactual

Horseshoe Prior (alternative to spike-and-slab)

CausalImpact supports the horseshoe prior (Carvalho, Polson & Scott 2010) applied to BSTS regression, following the formulation of Kohns & Bhattacharjee (2022) (arXiv:2011.00938).

When to use horseshoe

Scenario Recommended prior
Few true covariates (sparse DGP) spike_slab (default)
Many true covariates (dense DGP) horseshoe

Usage

from causal_impact import CausalImpact, ModelOptions

ci = CausalImpact(
    data, pre_period, post_period,
    model_args=ModelOptions(prior_type='horseshoe'),
)
print(ci.posterior_shrinkage)   # mean(kappa_j), 0=included 1=shrunk
# ci.posterior_inclusion_probs is None for horseshoe (spike-slab only)

Shrinkage diagnostics

Property prior_type Meaning
posterior_inclusion_probs spike_slab E[gamma_j] — discrete inclusion probability
posterior_inclusion_probs horseshoe None (not applicable)
posterior_shrinkage horseshoe E[kappa_j] — continuous shrinkage factor kappa_j = 1/(1+lambda_j^2 * tau^2). Values close to 0 indicate the covariate is weakly shrunk (effectively included).
posterior_shrinkage spike_slab None (not applicable)

Incompatible combinations

  • prior_type='horseshoe' + dynamic_regression=True raises ValueError

References

  • Kohns, D. & Bhattacharjee, A. (2022). Horseshoe Prior for Sparse Bayesian Structural Time Series. arXiv:2011.00938.
  • Makalic, E. & Schmidt, D.F. (2015). A simple sampler for the horseshoe estimator. IEEE Signal Processing Letters, 23(1), 179-182.
  • Carvalho, C.M., Polson, N.G. & Scott, J.G. (2010). The horseshoe estimator for sparse signals. Biometrika, 97(2), 465-480.

Beyond R Extensions

PlaceboTestResults

Returned by ci.run_placebo_test(). Validates the effect against a null distribution.

Field Type Description
p_value float Fraction of placebo effects >= real effect
rank_ratio float Conservative p-value estimate
effect_distribution ndarray Absolute average effects from each placebo split
real_effect float Absolute average effect from the real intervention
n_placebos int Number of placebo splits evaluated

ConformalResults

Returned by ci.run_conformal_analysis(). Distribution-free prediction intervals.

Field Type Description
q_hat float Conformal quantile threshold
lower ndarray Lower conformal prediction interval for post-period
upper ndarray Upper conformal prediction interval for post-period
n_calibration int Number of calibration points used