bsts-causalimpact

Bayesian structural time series for causal inference in Python. A faithful port of Google's CausalImpact R package. No TensorFlow required.

The Gibbs sampler is implemented in Rust (via PyO3), reproducing the same algorithm as R's bsts package while achieving 10-30x speedup.

When to Use (and When Not to)

This method is valid only when all of the following hold:

• Control series are not contaminated by the intervention
• The relationship between treated and control series is stable across the pre- and post-intervention periods
• The pre-intervention period is sufficiently long (rule of thumb: at least 3x the post-intervention period)

If any of these assumptions are violated, the causal estimate will be unreliable. Consider a difference-in-differences or synthetic control approach instead.

Installation

Requires Python 3.10+. Binary wheels are intended for supported platforms, so Rust is only required when building from source.

pip install bsts-causalimpact

For development (builds Rust extension locally):

git clone https://github.com/YuminosukeSato/bsts-causalimpact.git
cd bsts-causalimpact

# Install with uv (recommended)
uv sync --all-extras

# Or install with pip (builds Rust extension via maturin)
pip install -e ".[dev]"

Quick Start

import pandas as pd
from causal_impact import CausalImpact

# Prepare your data: first column = response, remaining columns = covariates
data = pd.read_csv("your_data.csv", index_col="date", parse_dates=True)

# Define pre- and post-intervention periods
pre_period = ["2020-01-01", "2020-03-14"]
post_period = ["2020-03-15", "2020-04-14"]

# Run the analysis
ci = CausalImpact(data, pre_period, post_period)

# Print a summary table
print(ci.summary())

# Print a narrative report
print(ci.report())

# Plot the results
fig = ci.plot()
fig.savefig("causal_impact.png")

Example Output

Posterior inference {CausalImpact}

                         Average        Cumulative
Actual                   136.32          3953.19
Prediction (s.d.)        125.42 (0.66)   3637.07 (19.08)
95% CI                   [124.18, 126.71]  [3601.33, 3674.59]

Absolute effect (s.d.)   10.90 (0.66)    316.13 (19.08)
95% CI                   [9.61, 12.13]   [278.60, 351.86]

Relative effect (s.d.)   8.69% (0.57%) 8.69% (0.57%)
95% CI                   [7.58%, 9.77%] [7.58%, 9.77%]

Posterior tail-area probability p: 0.001
Posterior prob. of a causal effect: 99.90%

Comparison with Alternatives

Why this library exists

Existing Python ports have fundamental limitations:

• pycausalimpact uses MLE (not MCMC), producing results that diverge substantially from R
• tfcausalimpact uses variational inference by default (not Gibbs sampling), and requires TensorFlow (3 GB+)
• tfp-causalimpact (Google's own Python port) does not publish numerical equivalence tests with R
• None of the above implement spike-and-slab variable selection matching R's bsts

This library reproduces the core Gibbs-sampler workflow from R's bsts package in Rust, with CI-enforced numerical equivalence tests on every commit.

Numerical Equivalence with R

Verified against R CausalImpact 1.4.1 (bsts 0.9.10, R 4.5) across 5 scenarios. Enforced on every commit via CI.

Test Matrix

Three-Layer Equivalence Verification

No other Python CausalImpact implementation has statistical equivalence tests. This library provides three layers of verification, exceeding even Google's own Python port.

Layer 1 runs on every commit (CI-blocking). Layers 2-3 run with --runslow flag.

# Layer 1: deterministic (runs in CI)
uv run pytest tests/test_numerical_equivalence.py -v

# Layers 2+3: TOST + ROPE (30 seeds x 4 scenarios, ~80s)
uv run pytest tests/test_equivalence_tost_rope.py -v --runslow

CI Enforcement

Two-layer CI enforcement:

1. Fixture-based (ci.yml): Compares Python output against committed R reference data. Blocking on every PR/push.
2. Live R comparison (numerical-equivalence.yml): Installs R, regenerates fixtures from scratch, and compares. Blocking when R is available. Weekly auto-regeneration.

How to Reproduce

1. Install R 4.5+ and packages: install.packages(c("CausalImpact", "jsonlite"))
2. Generate R reference: Rscript scripts/generate_r_reference.R
3. Run equivalence tests: .venv/bin/pytest tests/test_numerical_equivalence.py -v

Equivalence Verification: Comparison with Other Implementations

Evidence per implementation (all verified from source code, not documentation claims):

• tfp-causalimpact (Google official Python port): 47 tests across 7 files. No R reference fixtures. Self-consistency checks use rtol=0.2 (±20%) and atol=0.01. No R output comparison exists in the test suite. README states "designed to produce results close to the R package" but this is not verified by any automated test. (source)
• tfcausalimpact (WillianFuks): 64 tests across 7 files. tests/fixtures/comparison_data.csv exists but is only used in README demo, not in automated tests. The README demo itself shows ~8% difference in AbsEffect (R: -657 vs Python: -708.51). (source)
• pycausalimpact (dafiti): 62 tests across 5 files. Uses MLE (not MCMC), fundamentally different algorithm. No R comparison of any kind. Repository archived. (source)
• causalimpact (jamalsenouci): 54 tests across 4 files. No R comparison. Open issue #7 reports "significantly different results from R". (source)

What is matching R and what is not

Matching = CI-enforced numerical equivalence with R bsts (±1% or tighter). Supported = Feature implemented, no R parity fixture yet. Extended = Python-only feature with no R equivalent.

Beyond R: Python-Only Extensions

Features that go beyond R's CausalImpact. These have no R equivalent.

API

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

Model Arguments

Methods and Properties

Benchmark Results

Median of 3 runs. Reproduce: python benchmarks/benchmark.py

Architecture

python/causal_impact/
    __init__.py          # Public API: CausalImpact, ModelOptions, __version__
    data.py              # DataProcessor: validation, standardization, period parsing
    main.py              # CausalImpact facade class
    options.py           # ModelOptions: typed MCMC configuration
    analysis.py          # CausalAnalysis: effect computation, CI, p-values
    summary.py           # SummaryFormatter: tabular and narrative reports
    plot.py              # Plotter: matplotlib visualization
    decomposition.py     # DATE decomposition (spot/persistent/trend)
    retrospective.py     # Retrospective attribution mode

src/ (Rust)
    lib.rs               # PyO3 entry point: run_gibbs_sampler()
    sampler.rs           # Gibbs sampler (R bsts-compatible algorithm)
    kalman.rs            # Kalman filter and simulation smoother
    state_space.rs       # State space model representation
    distributions.rs     # Posterior sampling distributions

Development

git config core.hooksPath .githooks

Running Tests

# All tests
uv run pytest tests/ -v

# Numerical equivalence only
uv run pytest tests/test_numerical_equivalence.py -v

# Rust tests
cargo test

Contributing

See CONTRIBUTING.md for development setup, PR workflow, and test requirements.

License

MIT