DoWhy 因果推断库实践指南：从 Model–Identify–Estimate–Refute 四步工作流到 GCM 根因分析

• 机器学习
• 数据分析

DoWhy 是一个面向因果推断的 Python 库，它把"因果图模型"与"潜在结果（potential outcomes）"两大框架统一在一套 Model → Identify → Estimate → Refute 的工作流之下，并提供了可对任意估计方法做假设检验的 refutation/falsification API。读完本文，你将掌握 DoWhy 的完整安装与依赖配置方式，能独立跑通"效应识别与估计"的端到端示例，并能使用其 Graphical Causal Model（GCM）子模块完成异常归因、干预分布采样等超出平均因果效应的复杂因果查询。

一、DoWhy 是什么：统一两种因果框架

决策问题往往要求我们回答"改变某个变量会导致什么"——例如某个干预动作如何影响结果变量、当前取值是由什么造成的、或者如果某些变量被改变会发生什么。这类问题需要因果推理，而 DoWhy 正是为此设计的：它通过统一的接口引导用户完成因果推理的各个步骤。

从源码结构看，DoWhy 的公开入口非常精简。dowhy/init.py 只导出CausalModel、identify_effect、identify_effect_auto、identify_effect_id、EstimandType等符号，核心对象CausalModel定义在 dowhy/causal_model.py 中，负责编排完整的四步工作流。

DoWhy 建立在因果推断两大最有力的框架之上，并取二者之长：

• 图模型 + do-calculus 阶段：对效应估计问题，DoWhy 使用基于图的判据和 do-calculus 来建模假设、识别非参数因果效应；
• 潜在结果阶段：一旦效应被识别，估计阶段切换到以潜在结果为基础的各种统计方法（回归调整、倾向得分、工具变量等）；
• GCM 阶段：对效应估计之外的因果问题（异常归因、反事实估计等），DoWhy 在每个节点上显式建模数据生成过程（causal mechanisms），从而支撑更复杂的因果算法。

官方支持的四类因果任务（与 README 中 Key Features 一致）：

1. 效应估计：识别、平均因果效应（ATE）、条件平均因果效应（CATE）、工具变量等；
2. 量化因果影响：中介分析、直接箭头强度、内在因果影响（intrinsic causal influence）；
3. What-if 分析：从干预分布采样、估计反事实；
4. 根因分析与解释：将异常归因到原因节点、定位分布变化的来源、估计特征相关性等。

其中最具特色的是refutation（反证）/ falsification API：任何估计方法得到的结果都可以用同一套稳健性检查来检验其背后的因果假设，这使推断对非专家也更具鲁棒性和可访问性。

二、安装与环境要求

2.1 三种安装方式

当前仓库 pyproject.toml 声明的 Python 支持范围是>=3.9,<3.14（classifiers 覆盖 3.9–3.13，AGENTS.md 中同样注明 Python 3.9–3.13）。README 中写有 "Python 3.8+"，实际以仓库构建配置为准。

安装最新 release，可选 pip、poetry 或 conda 之一：

pip install dowhy

poetry add dowhy

conda install -c conda-forge dowhy

如果 conda 出现 "Solving environment" 问题，README 给出的处理顺序是：先执行conda update --all再安装 dowhy；若仍失败，可设置conda config --set channel_priority false后重试。

开发版需要把依赖工具指向项目仓库，例如：

pip install git+https://gitcode.com/gh_mirrors/do/dowhy@main

2.2 依赖清单与可选扩展

DoWhy 的核心依赖在 pyproject.toml 的[tool.poetry.dependencies]一节中声明，关键项包括：

可选扩展（[tool.poetry.extras]）：

• plotting：matplotlib，用于绘图；
• pygraphviz/pydot：图可视化，其中 pydot 支持以 dot 格式输入图；
• econml：econml >=0.16，用于 CATE 估计（见第 4 节）。

若安装遇到问题，README 建议按版本手动安装依赖：pip install '<dependency-name>==<version>'。

对图可视化，若希望在 Ubuntu / Ubuntu WSL 上使用 pygraphviz 获得更美观的图，需先安装 graphviz 及其开发头文件，再安装 pygraphviz：

sudo apt install graphviz libgraphviz-dev graphviz-dev pkg-config pip install --global-option=build_ext \ --global-option="-I/usr/local/include/graphviz/" \ --global-option="-L/usr/local/lib/graphviz" pygraphviz

README 特别提示：pygraphviz 在部分平台上可能安装失败，上述方式是多数 Linux 发行版下可用的做法；也可参考 pygraphviz 官方安装文档。

三、效应识别与估计：四步工作流实战

DoWhy 中大多数因果任务只需几行代码。下面完整继承 README 的 Quick Start 示例：估计一个处理变量对结果变量的因果效应。

3.1 生成带已知效应的合成数据

from dowhy import CausalModel import dowhy.datasets # Load some sample data data = dowhy.datasets.linear_dataset( beta=10, num_common_causes=5, num_instruments=2, num_samples=10000, treatment_is_binary=True)

linear_dataset定义在 dowhy/datasets.py，其参数语义与 README 示例中的取值可以对照理解：

• beta：结果变量生成方程中处理变量（v）的系数，即真值效应大小；
• num_common_causes：同时影响处理与结果的共同原因（confounder，w -> v; w -> y）数量，示例中为 5；
• num_instruments：工具变量（z -> v）数量，示例中为 2；
• num_samples：样本量，示例中为 10000；
• treatment_is_binary：处理是否二值，默认为True；
• 其他可选参数还包括num_effect_modifiers、num_treatments、num_frontdoor_variables（前门变量v -> FD -> y）、离散化选项（stochastic_discretization、num_discrete_*）与噪声尺度（stddev_treatment_noise默认 1、stddev_outcome_noise默认 0.01）。

函数返回一个字典，包含df（数据帧）、treatment_name、outcome_name、gml_graph（GML 格式的因果图）、ate（数据集的真实 ATE）等键；变量命名约定是首字母表示角色（v处理、y结果、W共同原因、Z工具变量、X效应修饰、FD前门变量）。因此示例中beta=10意味着真值 ATE 为 10，后续可用它对照估计精度。

3.2 Model → Identify → Estimate → Refute

# I. Create a causal model from the data and given graph. model = CausalModel( data=data["df"], treatment=data["treatment_name"], outcome=data["outcome_name"], graph=data["gml_graph"]) # Or alternatively, as nx.DiGraph # II. Identify causal effect and return target estimands identified_estimand = model.identify_effect() # III. Estimate the target estimand using a statistical method. estimate = model.estimate_effect(identified_estimand, method_name="backdoor.propensity_score_matching") # IV. Refute the obtained estimate using multiple robustness checks. refute_results = model.refute_estimate(identified_estimand, estimate, method_name="random_common_cause")

因果图可以用多种方式定义，最常用的是通过 NetworkX 的nx.DiGraph传入（示例中则直接传入数据集附带的 GML 字符串）。CausalModel构造函数（见 dowhy/causal_model.py）还支持不显式给图、而用common_causes/instruments/effect_modifiers参数让 DoWhy 自行构建图；另有两个值得注意的开关：

• estimand_type：默认"nonparametric-ate"；
• missing_nodes_as_confounders：数据中存在但图里没有的变量是否自动当作混杂节点；
• proceed_when_unidentifiable：在可能存在未观测混杂导致不可识别时是否继续处理。

从源码结构看，四个步骤分别落在CausalModel的方法identify_effect、estimate_effect、refute_estimate上（另提供do、view_model、interpret、summary、refute_graph等辅助方法）。method_name字符串（如"backdoor.propensity_score_matching"）会被解析为dowhy/causal_estimators/下对应的估计器类（15+ 种实现，涵盖回归、线性回归、广义线性模型、倾向得分回归/加权/匹配/分层、距离匹配、双重稳健、工具变量、两阶段回归、EconML、TabPFN 等）。

Refute 步骤同样通过字符串选择反证器：dowhy/causal_refuters/init.py 的get_class_object会按method_name动态导入并实例化对应模块中的类（random_common_cause→RandomCommonCause，placebo_treatment→PlaceboTreatmentRefuter等）。仓库内置的 refuter 包括：随机共同原因、安慰剂处理、哑结果、数据子采样、bootstrap、未观测共同原因（含 E-value 与敏感性模拟）、图反证、多种敏感性分析器（线性、部分线性、非参数/Reisz）等，对应文件均在 dowhy/causal_refuters/ 目录下。

3.3 可解释输出

DoWhy 强调输出的可解释性：分析过程中任何时点都可以检查未测试的假设、已识别的估计量（若有）和估计值（若有）。上图所示即为线性回归估计器的典型输出截图（源自 README 引用的regression_output.png）。完整的可运行示例见 docs/source/example_notebooks/dowhy_simple_example.ipynb（Getting Started with DoWhy）。

四、进阶：使用 EconML 估计条件平均处理效应（CATE）

如果关心"对谁效果更大"，可以接入 EconML 的 CATE 方法。注意econml是 pyproject 中的可选 extra，需要先安装（如poetry install -E "econml"或pip install dowhy[econml]）。README 给出的 DML 代码片段：

from sklearn.preprocessing import PolynomialFeatures from sklearn.linear_model import LassoCV from sklearn.ensemble import GradientBoostingRegressor dml_estimate = model.estimate_effect(identified_estimand, method_name="backdoor.econml.dml.DML", control_value = 0, treatment_value = 1, target_units = lambda df: df["X0"]>1, confidence_intervals=False, method_params={ "init_params":{'model_y':GradientBoostingRegressor(), 'model_t': GradientBoostingRegressor(), 'model_final':LassoCV(), 'featurizer':PolynomialFeatures(degree=1, include_bias=True)}, "fit_params":{}})

要点：method_name采用backdoor.econml.<estimator>的分层命名；target_units是一个对数据帧求值的 lambda，用于圈定目标子群体（此处为X0 > 1的个体）；init_params指定 DML 的三个 nuisance 模型（结果模型model_y、处理模型model_t）与最终模型model_final。更多用法可参考 docs/source/example_notebooks/dowhy-conditional-treatment-effects.ipynb。

五、GCM：超越效应估计的因果推断

DoWhy 的 Graphical Causal Model（GCM）框架基于 Pearl 的图因果模型，把每个变量的数据生成过程显式建模为因果机制（causal mechanisms），从而支撑异常归因、反事实估计、干预分布采样、分布变化归因等复杂查询。从源码看，GCM 模块的公共 API 集中在 dowhy/gcm/init.py：StructuralCausalModel/ProbabilisticCausalModel/InvertibleStructuralCausalModel三类模型，anomaly_scores、attribute_anomalies等异常归因函数，以及interventional_samples、counterfactual_samples、average_causal_effect等 what-if 函数。

README 给出的最小 GCM 示例（归因异常 + 干预采样）：

import networkx as nx, numpy as np, pandas as pd from dowhy import gcm # Let's generate some "normal" data we assume we're given from our problem domain: X = np.random.normal(loc=0, scale=1, size=1000) Y = 2 * X + np.random.normal(loc=0, scale=1, size=1000) Z = 3 * Y + np.random.normal(loc=0, scale=1, size=1000) data = pd.DataFrame(dict(X=X, Y=Y, Z=Z)) # 1. Modeling cause-effect relationships as a structural causal model # (causal graph + functional causal models): causal_model = gcm.StructuralCausalModel(nx.DiGraph([('X', 'Y'), ('Y', 'Z')])) # X -> Y -> Z gcm.auto.assign_causal_mechanisms(causal_model, data) # 2. Fitting the SCM to the data: gcm.fit(causal_model, data) # Optional: Evaluate causal model print(gcm.evaluate_causal_model(causal_model, data)) # Step 3: Perform a causal analysis. # results = gcm.<causal_query>(causal_model, ...) # For instance, root cause analysis: anomalous_sample = pd.DataFrame(dict(X=[0.1], Y=[6.2], Z=[19])) # Here, Y is the root cause. # "Which node is the root cause of the anomaly in Z?": anomaly_attribution = gcm.attribute_anomalies(causal_model, "Z", anomalous_sample) # Or sampling from an interventional distribution. Here, under the intervention do(Y := 2). samples = gcm.interventional_samples(causal_model, interventions={'Y': lambda y: 2}, num_samples_to_draw=100)

流程拆解：

1. 建模：StructuralCausalModel接收一个 NetworkX 有向图（X -> Y -> Z），gcm.auto.assign_causal_mechanisms根据数据为每个节点自动挑选函数因果机制（如线性回归、噪声模型等）；
2. 拟合：gcm.fit把模型拟合到"正常"数据上；随后可用gcm.evaluate_causal_model评估模型质量；
3. 因果查询：gcm.attribute_anomalies回答"Z 的异常是哪个节点引起的"（示例中Y=6.2明显偏离2*X的尺度，Y 即根因）；gcm.interventional_samples则在干预do(Y := 2)下从干预分布中采样 100 个样本。

GCM 的完整应用示例（在线商店因果归因与根因分析）见 docs/source/example_notebooks/gcm_online_shop.ipynb；仓库 tests/gcm/ 目录下还有针对异常检测（test_anomaly.py）、归因（test_anomaly_attribution.py）、what-if（test_whatif.py）、分布变化（test_distribution_change.py）等的测试用例，可作为各 API 行为的验证依据。

六、延伸资源、测试与引用

• 用户指南：更完整的文档位于 docs/source/user_guide/intro.rst，涵盖因果任务（效应估计、量化因果影响、What-if、根因分析）、因果图建模与 GCM 建模等章节；
• 示例 Notebooks：全部案例集中在 docs/source/example_notebooks/ 目录，包括酒店订单取消、IHDP、Lalonde、中介分析、多重处理、时间序列等主题；
• 测试与工程约定：仓库自带与dowhy/镜像结构的 tests/ 测试套件，以及面向开发者的 AGENTS.md（环境搭建、poetry run poe test等测试命令、lint 规则、依赖管理约定），可用于理解各模块的验证方式；
• 相关生态：DoWhy 属于 PyWhy 生态的一部分，文档站、Discord 社区入口见 README 顶部。

若 DoWhy 对你的工作有帮助，请同时引用以下两篇文献（BibTeX 同样收录在 README 中）：

@article{dowhy, title={DoWhy: An End-to-End Library for Causal Inference}, author={Sharma, Amit and Kiciman, Emre}, journal={arXiv preprint arXiv:2011.04216}, year={2020} } @article{JMLR:v25:22-1258, author = {Patrick Bl{\"o}baum and Peter G{\"o}tz and Kailash Budhathoki and Atalanti A. Mastakouri and Dominik Janzing}, title = {DoWhy-GCM: An Extension of DoWhy for Causal Inference in Graphical Causal Models}, journal = {Journal of Machine Learning Research}, year = {2024}, volume = {25}, number = {147}, pages = {1--7} }

适用前提与限制：本文基于当前仓库快照撰写——核心依赖以 pyproject.toml 中声明的版本约束为准（Python 3.9–3.13、numpy ≥ 2.0 等）；econml、pygraphviz 等均为可选扩展，未安装时相应功能不可用（源码中以 try/except 保护可选导入并给出提示性报错）；linear_dataset的ate等返回值可用于自校验，但真实场景下识别与估计的有效性始终取决于所给因果图是否符合领域假设，这正是第 3.2 节 Refute 步骤存在的意义。

• 机器学习
• 数据分析