tfcausalimpact

The algorithm fits a Bayesian structural time series model on past observed data to predict what future data would look like (the counter-factual). It then compares this prediction against the actual observed data to extract statistical conclusions about an intervention.

To run the model, you need:

• y: The observed data.
• X: Covariates used for linear regression.
• pre-period: An interval selecting data before the intervention.
• post-period: An interval selecting data after the intervention.

Install the package using pip:

pip install tfcausalimpact

Ensure your environment meets the following requirements:

• Python: 3.7, 3.8, 3.9, 3.10, or 3.11
• matplotlib
• jinja2
• tensorflow >= 2.10.0
• tensorflow_probability >= 0.18.0
• pandas >= 1.3.5

To perform a causal impact analysis, import CausalImpact from causalimpact. Pass your data (as a pandas DataFrame), the pre_period indices/dates, and the post_period indices/dates to the constructor.

You can then generate a summary of the results or a detailed report, and visualize the impact using .plot().

import pandas as pd
from causalimpact import CausalImpact

# Load data containing 'y' and covariates 'X'
data = pd.read_csv('your_data.csv')[['y', 'X']]

# Define periods (can be integer indices or date strings)
pre_period = [0, 69]
post_period = [70, 99]

# Initialize and run the model
ci = CausalImpact(data, pre_period, post_period)

# View results
print(ci.summary())           # Standard summary
print(ci.summary(output='report')) # Detailed report
ci.plot()                     # Visual plot

By default, tfcausalimpact uses Variational Inference, which is faster and suitable for most use cases.

If high precision is required, you can switch to the Hamiltonian Monte Carlo (HMC) algorithm by passing model_args={'fit_method': 'hmc'} to the CausalImpact constructor. Note that HMC is significantly slower and may take an hour or more for complex time series with many data points.

ci = CausalImpact(data, pre_period, post_period, model_args={'fit_method': 'hmc'})

The plot() method generates graphics representing the Causal Impact results.

Arguments:

• panels (List[str]): Which graphics to include. Options are:
  • 'original': Original data, forecast means, and credible intervals.
  • 'pointwise': Point-wise differences between observed data and predictions.
  • 'cumulative': Cumulative summation of the differences.
• figsize (Tuple[int]): Width and height of the figure.
• show (bool): If True, calls plt.show(). If False, allows you to manipulate the figure/axis manually (e.g., plt.gca() or plt.gcf()).

ci.plot(panels=['original', 'cumulative'], figsize=(12, 8), show=False)
# You can then use matplotlib to save or modify
import matplotlib.pyplot as plt
plt.savefig('impact_plot.png')

The summary() method produces a text report of the causal impact analysis.

Arguments:

• output (str):
  • 'summary': A simple output showing general metrics like expected absolute or relative effect.
  • 'report': A more detailed report.
• digits (int): Number of decimal places to round to (default is 2).

Returns a string containing the results.

print(ci.summary(output='report', digits=3))