|构建状态|_ |PyPI版本|_ |Python支持|_ |下载量|_ |Discord|_ |Gurubase|_

.. |PyPiVersion| image:: https://img.shields.io/pypi/v/dowhy.svg .. _PyPiVersion: https://pypi.org/project/dowhy/

.. |PythonSupport| image:: https://img.shields.io/pypi/pyversions/dowhy.svg .. _PythonSupport: https://pypi.org/project/dowhy/

.. |BuildStatus| image:: https://github.com/py-why/dowhy/actions/workflows/ci.yml/badge.svg .. _BuildStatus: https://github.com/py-why/dowhy/actions

.. |Downloads| image:: https://pepy.tech/badge/dowhy .. _Downloads: https://pepy.tech/project/dowhy

.. |discord| image:: https://img.shields.io/discord/818456847551168542 .. _discord: https://discord.gg/cSBGb3vsZb

.. |gurubase| image:: https://img.shields.io/badge/Gurubase-Ask%20DoWhy%20Guru-006BFF .. _gurubase: https://gurubase.io/g/dowhy

.. image:: dowhy-logo-large.png :width: 50% :align: center

查看文档 <https://py-why.github.io/dowhy/>_

• 文档、用户指南、示例笔记本及其他信息可在 https://py-why.github.io/dowhy <https://py-why.github.io/dowhy/>_ 找到。
• DoWhy 是 PyWhy 生态系统 <https://www.pywhy.org/>_ 的一部分。如需更多与因果推断相关的工具和库，请访问 PyWhy GitHub 组织 <https://github.com/py-why/>_！
• 如有任何问题、意见或关于特定用例的讨论，请加入我们的 Discord 社区（|discord|_）。
• 立即阅读一些案例研究：
  • 效应估计：酒店预订取消 <https://medium.com/data-science/beyond-predictive-models-the-causal-story-behind-hotel-booking-cancellations-d29e8558cbaf>_ | 客户忠诚度计划的效果 <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy_example_effect_of_memberrewards_program.html>_ | 优化文章标题 <https://medium.com/@akelleh/introducing-the-do-sampler-for-causal-inference-a3296ea9e78d>_ | 家访对婴儿健康的影响（IHDP）<https://medium.com/data-science/implementing-causal-inference-a-key-step-towards-agi-de2cde8ea599>_ | 客户流失的原因 <https://medium.com/geekculture/a-quickstart-for-causal-analysis-decision-making-with-dowhy-2ce2d4d1efa9>_
  • 根因分析与解释：在线商店的因果归因与根因分析 <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_online_shop.html>_ | 微服务架构中延迟升高的根因查找 <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_rca_microservice_architecture.html>_ | 供应链变化的根因查找 <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_supply_chain_dist_change.html>_

更多示例笔记本请见 这里！ <https://www.pywhy.org/dowhy/main/example_notebooks/nb_index.html>_

简介与核心特性

决策制定涉及理解不同变量之间的相互影响，并预测当其中某些变量被调整为新值时的结果。例如，给定一个结果变量，人们可能希望确定某种行动对其产生的影响、了解其当前值的成因，或者模拟改变某些变量后会发生什么。回答这类问题需要进行因果推理。DoWhy 是一个 Python 库，它引导您完成因果推理的各个步骤，并提供统一的接口来解答因果问题。

DoWhy 提供了多种用于效应估计、预测、量化因果影响、诊断因果结构、根因分析、干预及反事实分析的算法。DoWhy 的一项关键特性是其反驳与证伪 API，可用于检验任何估计方法背后的因果假设，从而使推断更加稳健，并让非专业人士也能轻松使用。

图形化因果模型与潜在结果：兼得两者之优

DoWhy 基于因果推断领域中两个最强大的框架：图形化因果模型和潜在结果框架。在效应估计方面，它利用基于图的准则和 do-演算来建模假设并识别非参数化的因果效应。而在具体估计过程中，则切换到主要基于潜在结果的方法。

对于超出效应估计范围的其他因果问题，DoWhy 充分发挥图形化因果模型的优势，通过在每个节点上明确地建模数据生成机制来描述数据的产生过程，从而能够将观察到的效应归因于特定变量，或估算逐点的反事实。

如需快速了解因果推断，可参考 amit-sharma/causal-inference-tutorial <https://github.com/amit-sharma/causal-inference-tutorial/>。我们还在 ACM 知识发现与数据挖掘（KDD 2018 <http://www.kdd.org/kdd2018/>）会议上提供了更为全面的教程：causalinference.gitlab.io/kdd-tutorial <http://causalinference.gitlab.io/kdd-tutorial/>。若想了解因果推断的四个步骤及其对机器学习的影响，可观看微软研究院的视频教程 DoWhy 网络研讨会 <https://www.microsoft.com/en-us/research/video/foundations-of-causal-inference-and-its-impacts-on-machine-learning/>；而有关图形化因果模型 API 的介绍，则可参阅 PyCon 上关于使用 DoWhy 进行根因分析的演讲 <https://www.youtube.com/watch?v=icpHrbDlGaw>_。

核心特性

.. image:: https://raw.githubusercontent.com/py-why/dowhy/main/docs/images/dowhy-features.png

DoWhy 支持以下因果任务：

- 效应估计（识别、平均因果效应、条件平均因果效应、工具变量等）
- 量化因果影响（中介效应分析、直接路径强度、内在因果影响力）
- 假设分析（从干预分布中生成样本，估计反事实）
- 根因分析与解释（将异常归因于其原因，找出分布变化的原因，评估特征相关性等）

更多详细信息及实际使用方法，请查阅 `https://py-why.github.io/dowhy <https://py-why.github.io/dowhy/>`_ 处的文档。

快速入门
===========
DoWhy 支持 Python 3.8 及以上版本。您可以通过 pip、poetry 或 conda 来安装。

**最新版本**

使用 pip 安装最新的 `发布版本 <https://pypi.org/project/dowhy/>`__。

.. code:: shell

   pip install dowhy

使用 poetry 安装最新的 `发布版本 <https://pypi.org/project/dowhy/>`__。

.. code:: shell

   poetry add dowhy

使用 conda 安装最新的 `发布版本 <https://anaconda.org/conda-forge/dowhy>`__。

.. code:: shell

   conda install -c conda-forge dowhy

如果您在使用 conda 时遇到“解决环境”问题，请尝试运行 :code:`conda update --all`，然后安装 dowhy。如果仍然无效，请使用 :code:`conda config --set channel_priority false` 并再次尝试安装。若问题依旧存在，请在此处 `提交您的问题 <https://github.com/microsoft/dowhy/issues/197>`_。

**开发版本**

如果您希望使用最新的开发版本，您的依赖管理工具需要指向我们的 GitHub 仓库。

.. code:: shell

    pip install git+https://github.com/py-why/dowhy@main


**要求**

DoWhy 需要一些依赖项。具体版本信息可在 `pyproject.toml <./pyproject.toml>`_ 的 `tool.poetry.dependencies` 部分找到。

如果您遇到任何问题，可以尝试手动安装这些依赖项。

.. code:: shell

    pip install '<dependency-name>==<version>'

此外，如果您希望以 dot 格式输入图结构，可以安装 pydot（或 pygraphviz）。

为了获得更美观的图形，您还可以选择安装 pygraphviz。为此，首先需要安装 graphviz，然后再安装 pygraphviz（适用于 Ubuntu 和 Ubuntu WSL）。

.. note::
    在某些平台上安装 pygraphviz 可能会遇到问题。对于大多数 Linux 发行版而言，一个可行的方法是先安装 graphviz，再安装 pygraphviz，如下所示。否则，请参考 `pygraphviz 的官方文档 <https://pygraphviz.github.io/documentation/stable/install.html>`_。

.. code:: shell

    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

示例：效应识别与估计

在 DoWhy 中，大多数因果推断任务只需几行代码即可完成。以下我们以估计治疗对结果变量的因果效应为例：

.. code:: python

from dowhy import CausalModel
import dowhy.datasets

# 加载一些示例数据
data = dowhy.datasets.linear_dataset(
    beta=10,
    num_common_causes=5,
    num_instruments=2,
    num_samples=10000,
    treatment_is_binary=True)

因果图可以用多种方式定义，但最常见的方式是通过 NetworkX <https://networkx.org/>_。加载数据后，我们使用 DoWhy 中用于效应估计的四个主要步骤：建模、识别、估计 和 反驳：

.. code:: python

# I. 根据数据和给定的图构建因果模型。
model = CausalModel(
    data=data["df"],
    treatment=data["treatment_name"],
    outcome=data["outcome_name"],
    graph=data["gml_graph"])  # 或者也可以用 nx.DiGraph 表示

# II. 识别因果效应并返回目标估计量
identified_estimand = model.identify_effect()

# III. 使用统计方法估计目标估计量。
estimate = model.estimate_effect(identified_estimand,
                                 method_name="backdoor.propensity_score_matching")

# IV. 通过多种稳健性检验来反驳所得估计。
refute_results = model.refute_estimate(identified_estimand, estimate,
                                       method_name="random_common_cause")

DoWhy 强调其输出的可解释性。在分析的任何阶段，您可以检查未验证的假设、已识别的估计量（如有）以及估计值（如有）。以下是线性回归估计器的一个示例输出：

.. image:: https://raw.githubusercontent.com/py-why/dowhy/main/docs/images/regression_output.png :width: 80%

有关完整的代码示例，请参阅 开始使用 DoWhy <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy_simple_example.html>_ 笔记本。

您还可以使用来自 EconML <https://github.com/py-why/econml>_ 的条件平均处理效应 (CATE) 估计方法，如 条件处理效应 <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy-conditional-treatment-effects.html>_ 笔记本中所示。以下是一个代码片段。

.. code:: python

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":{}})

示例：基于图因果模型 (GCM) 的推断

DoWhy 的图因果模型框架提供了强大的工具，可用于解决效应估计之外的因果问题。它基于 Pearl 的图因果模型框架，通过 *因果机制* 显式建模每个变量的因果数据生成过程，从而支持广泛的因果算法。更多详细信息请参阅书籍《因果推断要素》（`Elements of Causal Inference <https://mitpress.mit.edu/9780262037310/elements-of-causal-inference/>`_）。

诸如将观测到的异常归因于系统中的某个节点等复杂因果查询，仅需几行代码即可完成：

.. code:: python

    import networkx as nx, numpy as np, pandas as pd
    from dowhy import gcm

    # 假设我们从实际问题领域获得了一些“正常”数据：
    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. 将因果关系建模为结构化因果模型
    #    （因果图 + 功能性因果模型）：
    causal_model = gcm.StructuralCausalModel(nx.DiGraph([('X', 'Y'), ('Y', 'Z')]))  # X -> Y -> Z
    gcm.auto.assign_causal_mechanisms(causal_model, data)

    # 2. 将 SCM 拟合到数据上：
    gcm.fit(causal_model, data)

    # 可选：评估因果模型
    print(gcm.evaluate_causal_model(causal_model, data))

    # 第三步：进行因果分析。
    # results = gcm.<causal_query>(causal_model, ...)
    # 例如，根本原因分析：
    anomalous_sample = pd.DataFrame(dict(X=[0.1], Y=[6.2], Z=[19]))  # 这里，Y 是根本原因。

    # “Z 中的异常是由哪个节点引起的？”:
    anomaly_attribution = gcm.attribute_anomalies(causal_model, "Z", anomalous_sample)

# 或者从干预分布中采样。这里，在干预 do(Y := 2) 下。
    samples = gcm.interventional_samples(causal_model, interventions={'Y': lambda y: 2}, num_samples_to_draw=100)

GCM 框架除了这些示例之外，还提供了许多其他功能。如需完整的代码示例，请查看“在线商店示例笔记本 <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_online_shop.html>`_。

如需了解更多功能、DoWhy 的应用示例以及输出的详细信息，请参阅《用户指南 <https://www.pywhy.org/dowhy/main/user_guide/intro.html>`_》或浏览 `Jupyter 笔记本 <https://www.pywhy.org/dowhy/main/example_notebooks/nb_index.html>`_。

更多信息与资源
============================
`微软研究博客 <https://www.microsoft.com/en-us/research/blog/dowhy-a-library-for-causal-inference/>`_ | `效应估计视频教程 <https://www.youtube.com/watch?v=LALfQStONEc&t=114s>`_ | `根本原因分析视频教程 <https://www.youtube.com/watch?v=icpHrbDlGaw>`_ | `ArXiv 论文 <https://arxiv.org/abs/2011.04216>`_ | `ArXiv 论文（图形因果模型扩展）<https://arxiv.org/abs/2206.06821>`_ | `幻灯片 <https://www2.slideshare.net/AmitSharma315/dowhy-an-endtoend-library-for-causal-inference>`_


引用本软件包
~~~~~~~~~~~~~~~~~~~
如果您发现 DoWhy 对您的工作有所帮助，请同时引用以下两篇文献：

- Amit Sharma, Emre Kiciman. DoWhy：用于因果推断的端到端库。2020年。https://arxiv.org/abs/2011.04216
- Patrick Blöbaum, Peter Götz, Kailash Budhathoki, Atalanti A. Mastakouri, Dominik Janzing. DoWhy-GCM：针对图形因果模型中因果推断的 DoWhy 扩展。2024年。MLOSS 25(147):1−7。https://jmlr.org/papers/v25/22-1258.html

BibTeX 格式::

  @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},
  url     = {http://jmlr.org/papers/v25/22-1258.html}
  }

问题
~~~~~~
如果您在使用 DoWhy 时遇到问题或有特定需求，请在 `GitHub 上提交问题 <https://github.com/py-why/dowhy/issues>`_。

贡献
~~~~~~~~~~~~

本项目欢迎各种形式的贡献和建议。有关贡献指南及所有贡献者的列表，请参阅 `CONTRIBUTING.md <https://github.com/py-why/dowhy/blob/main/CONTRIBUTING.md>`_ 和我们的 `代码贡献文档 <https://github.com/py-why/dowhy/blob/main/docs/source/contributing/contributing-code.rst>`_。我们的 `贡献者行为准则在此处提供 <https://github.com/py-why/governance/blob/main/CODE-OF-CONDUCT.md>`_。

DoWhy 快速上手指南

DoWhy 是一个强大的 Python 因果推断库，旨在通过统一的接口引导用户完成因果建模、识别、估计和反驳的全过程。它结合了图形因果模型和潜在结果框架的优势，帮助开发者稳健地评估变量间的因果关系。

环境准备

• 操作系统：支持 Linux, macOS, Windows (WSL 推荐用于绘图功能)。
• Python 版本：Python 3.8 或更高版本。
• 前置依赖：
  • 核心功能仅需标准 Python 环境。
  • 可选依赖（绘图）：若需输入 DOT 格式图谱或生成高质量因果图，需安装 graphviz 系统包及 pygraphviz。
    • Ubuntu/Debian: sudo apt install graphviz libgraphviz-dev
    • macOS (Homebrew): brew install graphviz

安装步骤

推荐使用国内镜像源加速安装。

方法一：使用 pip 安装（推荐）

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

方法二：使用 Conda 安装

conda install -c conda-forge dowhy

注：若遇到 "Solving environment" 问题，可尝试先运行 conda update --all 或配置 conda config --set channel_priority false。

方法三：安装开发版

pip install git+https://github.com/py-why/dowhy@main

可选：安装绘图支持

若需使用高级绘图功能，请在安装系统级 graphviz 后执行：

pip install pygraphviz --global-option=build_ext --global-option="-I/usr/local/include/graphviz/" --global-option="-L/usr/local/lib/graphviz"

基本使用

DoWhy 的核心工作流包含四个步骤：建模 (Model) -> 识别 (Identify) -> 估计 (Estimate) -> 反驳 (Refute)。

以下是一个完整的极简示例，演示如何估计处理变量对结果变量的因果效应：

from dowhy import CausalModel
import dowhy.datasets

# 1. 加载示例数据
data = dowhy.datasets.linear_dataset(
    beta=10,
    num_common_causes=5,
    num_instruments=2,
    num_samples=10000,
    treatment_is_binary=True)

# 2. 构建因果模型
# 可以通过 GML 字符串或 NetworkX 图对象定义因果图
model = CausalModel(
    data=data["df"],
    treatment=data["treatment_name"],
    outcome=data["outcome_name"],
    graph=data["gml_graph"]
)

# 3. 识别因果效应
# 基于因果图判断效应是否可识别，并返回目标估计量
identified_estimand = model.identify_effect()

# 4. 估计因果效应
# 使用统计方法（如倾向得分匹配）进行估算
estimate = model.estimate_effect(
    identified_estimand,
    method_name="backdoor.propensity_score_matching"
)

print(f"估计的因果效应: {estimate.value}")

# 5. 反驳验证 (鲁棒性检查)
# 通过添加随机共同原因等方法验证估计结果的稳健性
refute_results = model.refute_estimate(
    identified_estimand, 
    estimate,
    method_name="random_common_cause"
)

进阶提示：

• DoWhy 支持与 EconML 集成，用于条件平均处理效应 (CATE) 估计。
• 对于根因分析 (RCA) 和反事实推断，可探索 DoWhy 的 GCM (Graphical Causal Model) 模块。