tfcausalimpact

基于 TensorFlow Probability 实现的 Google Causal Impact 算法。

工作原理

该算法本质上是在过去观测数据上拟合一个 贝叶斯结构化 时间序列模型，以预测未来数据可能的样子。过去的数据包括干预发生之前的所有内容（通常是指某个变量的状态发生变化，例如在某一时间点开始执行的营销活动）。然后，它会将反事实（预测的）序列与实际观测到的数据进行比较，从而得出统计结论。

运行该模型非常简单，只需要提供观测数据 y、用于线性回归的协变量 X，以及两个时间段：pre-period 表示干预前的时间段，post-period 表示“影响”发生之后的时间段。

有关更多详细信息，请参阅这篇 Medium 文章：Implementing Causal Impact on Top of TensorFlow Probability。

安装

pip install tfcausalimpact

依赖项

• python{3.7, 3.8, 3.9, 3.10, 3.11}
• matplotlib
• jinja2
• tensorflow>=2.10.0
• tensorflow_probability>=0.18.0
• pandas >= 1.3.5

快速入门

我们推荐观看 Kay Brodersen（R 语言中 Causal Impact 的创建者之一）的这个 演示文稿。

此外，我们还创建了一个介绍性的 ipython 笔记本，其中包含如何使用此包的示例。

这篇 Medium 文章 Implementing Causal Impact on Top of TensorFlow Probability 也提供了关于该库的一些思路和概念。

示例

以下是一个简单的示例（也可以在 Google 原始的 R 实现中找到），在 Python 中运行：

import pandas as pd
from causalimpact import CausalImpact


data = pd.read_csv('https://raw.githubusercontent.com/WillianFuks/tfcausalimpact/master/tests/fixtures/arma_data.csv')[['y', 'X']]
data.iloc[70:, 0] += 5

pre_period = [0, 69]
post_period = [70, 99]

ci = CausalImpact(data, pre_period, post_period)
print(ci.summary())
print(ci.summary(output='report'))
ci.plot()

摘要应如下所示：

后验推断 {Causal Impact}
                          平均            累计
实际                    125.23             3756.86
预测（标准差）         120.34 (0.31)      3610.28 (9.28)
95% 置信区间            [119.76, 120.97]   [3592.67, 3629.06]

绝对效应（标准差）    4.89 (0.31)        146.58 (9.28)
95% 置信区间            [4.26, 5.47]       [127.8, 164.19]

相对效应（标准差）    4.06% (0.26%)      4.06% (0.26%)
95% 置信区间            [3.54%, 4.55%]     [3.54%, 4.55%]

后验尾部概率 p: 0.0
后验因果效应概率: 100.0%

有关更多详情，请运行命令：print(impact.summary('report'))

以下是图表：

Google R 包 vs TensorFlow Python

这两个包应该给出等效的结果。以下是一个使用 fixtures 文件夹中提供的 comparison_data.csv 数据集的示例。在原始 R 包中运行 CausalImpact 时，结果如下：

R

data = read.csv.zoo('comparison_data.csv', header=TRUE)
pre.period <- c(as.Date("2019-04-16"), as.Date("2019-07-14"))
post.period <- c(as.Date("2019-07-15"), as.Date("2019-08-01"))
ci = CausalImpact(data, pre.period, post.period)

摘要结果：

后验推断 {CausalImpact}

                         平均          累计
实际                   78574            1414340
预测（标准差）        79232 (736)      1426171 (13253)
95% 置信区间           [77743, 80651]   [1399368, 1451711]

绝对效应（标准差）   -657 (736)       -11831 (13253)
95% 置信区间           [-2076, 832]     [-37371, 14971]

相对效应（标准差）   -0.83% (0.93%)   -0.83% (0.93%)
95% 置信区间           [-2.6%, 1%]      [-2.6%, 1%]

后验尾部概率 p:   0.20061
后验因果效应概率:  80%

有关更多详情，请键入：summary(impact, "report")

对应的图表如下：

Python

import pandas as pd
from causalimpact import CausalImpact


data = pd.read_csv('https://raw.githubusercontent.com/WillianFuks/tfcausalimpact/master/tests/fixtures/comparison_data.csv', index_col=['DATE'])
pre_period = ['2019-04-16', '2019-07-14']
post_period = ['2019-7-15', '2019-08-01']
ci = CausalImpact(data, pre_period, post_period, model_args={'fit_method': 'hmc'})

摘要如下：

后验推断 {Causal Impact}
                          平均            累计
实际                    78574.42           1414339.5
预测（标准差）         79282.92 (727.48)  1427092.62 (13094.72)
95% 置信区间            [77849.5, 80701.18][1401290.94, 1452621.31]

绝对效应（标准差）    -708.51 (727.48)   -12753.12 (13094.72)
95% 置信区间            [-2126.77, 724.92] [-38281.81, 13048.56]

相对效应（标准差）    -0.89% (0.92%)     -0.89% (0.92%)
95% 置信区间            [-2.68%, 0.91%]    [-2.68%, 0.91%]

后验尾部概率 p: 0.16
后验因果效应概率: 84.12%

有关更多详情，请运行命令：print(impact.summary('report'))

对应的图表如下：

两种结果是等价的。

性能

该包默认使用 TensorFlow Probability 中的 变分推断 方法，这种方法速度较快，在大多数情况下都能正常工作。对于较为复杂的时间序列，收敛时间通常在 2 到 3 分钟之间。您也可以尝试在 GPU 上运行该包，以观察性能是否有所提升。

另一方面，如果在进行因果效应分析时对精度有极高要求，可以通过调整输入参数来切换算法，如下所示：

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

这将使用 哈密顿蒙特卡洛 算法，该算法是目前用于求解贝叶斯后验分布的最先进方法。不过，请注意，对于包含数千个数据点、且涉及多种季节性成分的复杂时间序列模型，这种优化可能需要 1 小时甚至更长时间才能完成（即使在 GPU 上）。此时会牺牲部分性能以换取更高的精度。

Bug 与问题

如果您在使用本库时发现任何 bug 或遇到问题，请考虑在 GitHub 仓库 上提交一个包含完整描述和可复现环境的 issue，以便我们更好地帮助您解决问题。

tfcausalimpact 快速上手指南

tfcausalimpact 是 Google Causal Impact 算法的 Python 实现，基于 TensorFlow Probability。它通过贝叶斯结构时间序列模型，评估干预措施（如营销活动、产品上线）对目标指标的实际因果影响。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.7, 3.8, 3.9, 3.10 或 3.11
• 核心依赖：
  • tensorflow >= 2.10.0
  • tensorflow_probability >= 0.18.0
  • pandas >= 1.3.5
  • matplotlib
  • jinja2

提示：国内用户建议在安装前配置 pip 镜像源（如清华源或阿里源）以加速下载。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

使用 pip 直接安装最新稳定版：

pip install tfcausalimpact

若需指定国内镜像源加速安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tfcausalimpact

基本使用

以下是一个最简示例，演示如何加载数据、定义干预前后时间段并生成因果分析报告。

1. 准备数据与参数

数据需要包含目标变量 y 和可选的协变量 X。你需要定义两个时间段：

• pre_period：干预发生前的时间段（用于训练模型）。
• post_period：干预发生后的时间段（用于评估影响）。

2. 运行分析

import pandas as pd
from causalimpact import CausalImpact

# 加载示例数据 (实际使用时请替换为自己的 DataFrame)
data = pd.read_csv('https://raw.githubusercontent.com/WillianFuks/tfcausalimpact/master/tests/fixtures/arma_data.csv')[['y', 'X']]

# 模拟干预效果：将后段数据的 y 值增加 5
data.iloc[70:, 0] += 5

# 定义干预前后区间 (索引范围)
pre_period = [0, 69]
post_period = [70, 99]

# 初始化并运行模型
ci = CausalImpact(data, pre_period, post_period)

# 打印统计摘要
print(ci.summary())

# 打印详细报告
print(ci.summary(output='report'))

# 绘制因果影响图
ci.plot()

3. 结果解读

运行上述代码后，你将获得类似以下的输出：

• Summary 输出：展示实际值、预测值（及标准差）、95% 置信区间，以及绝对效应和相对效应。
• 概率判断：Posterior prob. of a causal effect 表示存在因果效应的后验概率（例如 100.0% 表示极大概率存在影响）。
• 可视化：ci.plot() 会生成一张图表，直观对比“实际观测值”与“若无干预的预测值”，阴影部分通常代表置信区间。

进阶提示：精度与性能平衡

默认情况下，库使用 变分推断 (Variational Inference)，速度较快（通常几分钟内完成）。如果对精度有极高要求且愿意牺牲计算时间，可以通过 model_args 切换为 哈密顿蒙特卡洛 (HMC) 算法：

# 使用 HMC 算法以提高精度（耗时可能长达数小时）
ci = CausalImpact(data, pre_period, post_period, model_args={'fit_method': 'hmc'})