`查看文档 <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 <https://discord.gg/cSBGb3vsZb>_ 社区 (|discord|_)
直接进入一些案例研究：
- 效应估计：酒店预订取消 <https://towardsdatascience.com/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://towardsdatascience.com/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-calculus 来建模假设和识别非参数因果效应。对于估计，它主要切换到基于潜在结果的方法。

对于超出效应估计的因果问题，它利用图形因果模型的力量，通过在每个节点显式建模因果机制来模拟数据生成过程，这例如解锁了将观察到的效应归因于特定变量或估计点反事实的能力。

想要快速了解因果推断，请查看 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 时遇到"Solving environment"问题，请尝试 :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 '<依赖项名称>==<版本>'

如果您希望以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的图形因果模型框架，通过*因果机制*明确模拟每个变量的因果数据生成过程，以支持广泛的因果算法。更多详情，请参阅
`因果推断要素 <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))

    # 第3步：进行因果分析。
    # 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: 因果推断的端到端库},
    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: DoWhy在图形因果模型中的因果推断扩展},
  journal = {机器学习研究期刊},
  year    = {2024},
  volume  = {25},
  number  = {147},
  pages   = {1--7},
  url     = {http://jmlr.org/papers/v25/22-1258.html}
  }

问题
~~~~~~
如果您遇到问题或对DoWhy有特定要求，请`提出问题 <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>`_。