|BuildStatus|_ |PyPiVersion|_ |PythonSupport|_ |Downloads|_ |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
`Checkout the documentation <https://py-why.github.io/dowhy/>`_
===============================================================
- The documentation, user guide, sample notebooks and other information are available at
`https://py-why.github.io/dowhy <https://py-why.github.io/dowhy/>`_
- DoWhy is part of the `PyWhy Ecosystem <https://www.pywhy.org/>`_. For more tools and libraries related to causality, checkout the `PyWhy GitHub organization <https://github.com/py-why/>`_!
- For any questions, comments, or discussions about specific use cases, join our community on `Discord <https://discord.gg/cSBGb3vsZb>`_ (|discord|_)
- Jump right into some case studies:
- Effect estimation: `Hotel booking cancellations <https://towardsdatascience.com/beyond-predictive-models-the-causal-story-behind-hotel-booking-cancellations-d29e8558cbaf>`_ | `Effect of customer loyalty programs <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy_example_effect_of_memberrewards_program.html>`_ | `Optimizing article headlines <https://medium.com/@akelleh/introducing-the-do-sampler-for-causal-inference-a3296ea9e78d>`_ | `Effect of home visits on infant health (IHDP) <https://towardsdatascience.com/implementing-causal-inference-a-key-step-towards-agi-de2cde8ea599>`_ | `Causes of customer churn/attrition <https://medium.com/geekculture/a-quickstart-for-causal-analysis-decision-making-with-dowhy-2ce2d4d1efa9>`_
- Root cause analysis and explanations: `Causal attribution and root-cause analysis of an online shop <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_online_shop.html>`_ | `Finding the Root Cause of Elevated Latencies in a Microservice Architecture <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_rca_microservice_architecture.html>`_ | `Finding Root Causes of Changes in a Supply Chain <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_supply_chain_dist_change.html>`_
For more example notebooks, see `here! <https://www.pywhy.org/dowhy/main/example_notebooks/nb_index.html>`_
Introduction & Key Features
===========================
Decision-making involves understanding how different variables affect each other and predicting the outcome when some of them are changed to new values. For instance, given an outcome variable, one may be interested in determining how a potential action(s) may affect it, understanding what led to its current value, or simulate what would happen if some variables are changed. Answering such questions requires causal reasoning. DoWhy is a Python library that guides you through the various steps of causal reasoning and provides a unified interface for answering causal questions.
DoWhy provides a wide variety of algorithms for effect estimation, prediction, quantification
of causal influences, diagnosis of causal structures, root cause analysis, interventions and
counterfactuals. A key feature of DoWhy is its refutation and falsification API that can test causal assumptions for any estimation method,
thus making inference more robust and accessible to non-experts.
**Graphical Causal Models and Potential Outcomes: Best of both worlds**
DoWhy builds on two of the most powerful frameworks for causal inference:
graphical causal models and potential outcomes. For effect estimation, it uses graph-based criteria and do-calculus for
modeling assumptions and identifying a non-parametric causal effect. For estimation, it switches to methods based
primarily on potential outcomes.
For causal questions beyond effect estimation, it uses the power of graphical causal models by modeling the data
generation process via explicit causal mechanisms at each node, which, for instance, unlocks capabilities to attribute
observed effects to particular variables or estimate point-wise counterfactuals.
For a quick introduction to causal inference, check out `amit-sharma/causal-inference-tutorial <https://github.com/amit-sharma/causal-inference-tutorial/>`_
We also gave a more comprehensive tutorial at the ACM Knowledge Discovery and Data Mining (`KDD 2018 <http://www.kdd.org/kdd2018/>`_) conference: `causalinference.gitlab.io/kdd-tutorial <http://causalinference.gitlab.io/kdd-tutorial/>`_.
For an introduction to the four steps of causal inference and its implications for machine learning, you can access this video tutorial from Microsoft Research `DoWhy Webinar <https://www.microsoft.com/en-us/research/video/foundations-of-causal-inference-and-its-impacts-on-machine-learning/>`_ and for an introduction to the graphical causal model API, see the `PyCon presentation on Root Cause Analysis with DoWhy <https://www.youtube.com/watch?v=icpHrbDlGaw>`_.
Key Features
~~~~~~~~~~~~
.. image:: https://raw.githubusercontent.com/py-why/dowhy/main/docs/images/dowhy-features.png
DoWhy supports the following causal tasks:
- Effect estimation (identification, average causal effect, conditional average causal effect, instrumental variables and more)
- Quantify causal influences (mediation analysis, direct arrow strength, intrinsic causal influence)
- What-if analysis (generate samples from interventional distribution, estimate counterfactuals)
- Root cause analysis and explanations (attribute anomalies to their causes, find causes for changes in distributions, estimate feature relevance and more)
For more details and how to use these methods in practice, checkout the documentation at `https://py-why.github.io/dowhy <https://py-why.github.io/dowhy/>`_
Quick Start
===========
DoWhy support Python 3.8+. To install, you can use pip, poetry, or conda.
**Latest Release**
Install the latest `release <https://pypi.org/project/dowhy/>`__ using pip.
.. code:: shell
pip install dowhy
Install the latest `release <https://pypi.org/project/dowhy/>`__ using poetry.
.. code:: shell
poetry add dowhy
Install the latest `release <https://anaconda.org/conda-forge/dowhy>`__ using conda.
.. code:: shell
conda install -c conda-forge dowhy
If you face "Solving environment" problems with conda, then try :code:`conda update --all` and then install dowhy. If that does not work, then use :code:`conda config --set channel_priority false` and try to install again. If the problem persists, please `add your issue here <https://github.com/microsoft/dowhy/issues/197>`_.
**Development Version**
If you prefer to use the latest dev version, your dependency management tool will need to point at our GitHub repository.
.. code:: shell
pip install git+https://github.com/py-why/dowhy@main
**Requirements**
DoWhy requires a few dependencies.
Details on specific versions can be found in `pyproject.toml <./pyproject.toml>`_, under the `tool.poetry.dependencies` section.
If you face any problems, try installing dependencies manually.
.. code:: shell
pip install '<dependency-name>==<version>'
Optionally, if you wish to input graphs in the dot format, then install pydot (or pygraphviz).
For better-looking graphs, you can optionally install pygraphviz. To proceed,
first install graphviz and then pygraphviz (on Ubuntu and Ubuntu WSL).
.. note::
Installing pygraphviz can cause problems on some platforms.
One way that works for most Linux distributions is to
first install graphviz and then pygraphviz as shown below.
Otherwise, please consult the documentation of `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
Example: Effect identification and estimation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most causal tasks in DoWhy only require a few lines of code to write. Here, we exemplarily estimate the causal effect of
a treatment on an outcome variable:
.. code:: python
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)
A causal graph can be defined in different way, but the most common way is via `NetworkX <https://networkx.org/>`_.
After loading in the data, we use the four main operations for effect estimation in DoWhy: *model*, *identify*,
*estimate* and *refute*:
.. code:: python
# 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")
DoWhy stresses on the interpretability of its output. At any point in the analysis,
you can inspect the untested assumptions, identified estimands (if any), and the
estimate (if any). Here's a sample output of the linear regression estimator:
.. image:: https://raw.githubusercontent.com/py-why/dowhy/main/docs/images/regression_output.png
:width: 80%
For a full code example, check out the `Getting Started with DoWhy <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy_simple_example.html>`_ notebook.
You can also use Conditional Average Treatment Effect (CATE) estimation methods from `EconML <https://github.com/py-why/econml>`_, as shown in the `Conditional Treatment Effects <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy-conditional-treatment-effects.html>`_ notebook. Here's a code snippet.
.. 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":{}})
Example: Graphical causal model (GCM) based inference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DoWhy's graphical causal model framework offers powerful tools to address causal questions beyond effect estimation.
It is based on Pearl's graphical causal model framework and models the causal data generation process of each variable
explicitly via *causal mechanisms* to support a wide range of causal algorithms. For more details, see the book
`Elements of Causal Inference <https://mitpress.mit.edu/9780262037310/elements-of-causal-inference/>`_.
Complex causal queries, such as attributing observed anomalies to nodes in the system, can be performed with just a few
lines of code:
.. code:: python
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)
The GCM framework offers many more features beyond these examples. For a full code example, check out the `Online Shop example notebook <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_online_shop.html>`_.
For more functionalities, example applications of DoWhy and details about the outputs, see the `User Guide <https://www.pywhy.org/dowhy/main/user_guide/intro.html>`_ or
checkout `Jupyter notebooks <https://www.pywhy.org/dowhy/main/example_notebooks/nb_index.html>`_.
More Information & Resources
============================
`Microsoft Research Blog <https://www.microsoft.com/en-us/research/blog/dowhy-a-library-for-causal-inference/>`_ | `Video Tutorial for Effect Estimation <https://www.youtube.com/watch?v=LALfQStONEc&t=114s>`_ | `Video Tutorial for Root Cause Analysis <https://www.youtube.com/watch?v=icpHrbDlGaw>`_ | `Arxiv Paper <https://arxiv.org/abs/2011.04216>`_ | `Arxiv Paper (Graphical Causal Model extension) <https://arxiv.org/abs/2206.06821>`_ | `Slides <https://www2.slideshare.net/AmitSharma315/dowhy-an-endtoend-library-for-causal-inference>`_
Citing this package
~~~~~~~~~~~~~~~~~~~
If you find DoWhy useful for your work, please cite **both** of the following two references:
- Amit Sharma, Emre Kiciman. DoWhy: An End-to-End Library for Causal Inference. 2020. https://arxiv.org/abs/2011.04216
- Patrick Blöbaum, Peter Götz, Kailash Budhathoki, Atalanti A. Mastakouri, Dominik Janzing. DoWhy-GCM: An extension of DoWhy for causal inference in graphical causal models. 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}
}
Issues
~~~~~~
If you encounter an issue or have a specific request for DoWhy, please `raise an issue <https://github.com/py-why/dowhy/issues>`_.
Contributing
~~~~~~~~~~~~
This project welcomes contributions and suggestions. For a guide to contributing and a list of all contributors, check out `CONTRIBUTING.md <https://github.com/py-why/dowhy/blob/main/CONTRIBUTING.md>`_ and our `docs for contributing code <https://github.com/py-why/dowhy/blob/main/docs/source/contributing/contributing-code.rst>`_. Our `contributor code of conduct is available here <https://github.com/py-why/governance/blob/main/CODE-OF-CONDUCT.md>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/py-why/dowhy",
"name": "dowhy",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": null,
"keywords": "causality, machine-learning, causal-inference, statistics, graphical-model",
"author": "PyWhy Community",
"author_email": "amshar@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/aa/0f/793cbb59d0ac3f25ba8053724c446e2704974b4a192835e59953b7f74a1f/dowhy-0.12.tar.gz",
"platform": null,
"description": "|BuildStatus|_ |PyPiVersion|_ |PythonSupport|_ |Downloads|_ |discord|_ |gurubase|_\n\n.. |PyPiVersion| image:: https://img.shields.io/pypi/v/dowhy.svg\n.. _PyPiVersion: https://pypi.org/project/dowhy/\n\n.. |PythonSupport| image:: https://img.shields.io/pypi/pyversions/dowhy.svg\n.. _PythonSupport: https://pypi.org/project/dowhy/\n\n.. |BuildStatus| image:: https://github.com/py-why/dowhy/actions/workflows/ci.yml/badge.svg\n.. _BuildStatus: https://github.com/py-why/dowhy/actions\n\n.. |Downloads| image:: https://pepy.tech/badge/dowhy\n.. _Downloads: https://pepy.tech/project/dowhy\n\n.. |discord| image:: https://img.shields.io/discord/818456847551168542\n.. _discord: https://discord.gg/cSBGb3vsZb\n\n.. |gurubase| image:: https://img.shields.io/badge/Gurubase-Ask%20DoWhy%20Guru-006BFF\n.. _gurubase: https://gurubase.io/g/dowhy\n\n.. image:: dowhy-logo-large.png\n :width: 50%\n :align: center\n\n\n`Checkout the documentation <https://py-why.github.io/dowhy/>`_\n===============================================================\n\n- The documentation, user guide, sample notebooks and other information are available at\n `https://py-why.github.io/dowhy <https://py-why.github.io/dowhy/>`_\n- DoWhy is part of the `PyWhy Ecosystem <https://www.pywhy.org/>`_. For more tools and libraries related to causality, checkout the `PyWhy GitHub organization <https://github.com/py-why/>`_!\n- For any questions, comments, or discussions about specific use cases, join our community on `Discord <https://discord.gg/cSBGb3vsZb>`_ (|discord|_)\n- Jump right into some case studies:\n - Effect estimation: `Hotel booking cancellations <https://towardsdatascience.com/beyond-predictive-models-the-causal-story-behind-hotel-booking-cancellations-d29e8558cbaf>`_ | `Effect of customer loyalty programs <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy_example_effect_of_memberrewards_program.html>`_ | `Optimizing article headlines <https://medium.com/@akelleh/introducing-the-do-sampler-for-causal-inference-a3296ea9e78d>`_ | `Effect of home visits on infant health (IHDP) <https://towardsdatascience.com/implementing-causal-inference-a-key-step-towards-agi-de2cde8ea599>`_ | `Causes of customer churn/attrition <https://medium.com/geekculture/a-quickstart-for-causal-analysis-decision-making-with-dowhy-2ce2d4d1efa9>`_\n - Root cause analysis and explanations: `Causal attribution and root-cause analysis of an online shop <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_online_shop.html>`_ | `Finding the Root Cause of Elevated Latencies in a Microservice Architecture <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_rca_microservice_architecture.html>`_ | `Finding Root Causes of Changes in a Supply Chain <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_supply_chain_dist_change.html>`_\n\nFor more example notebooks, see `here! <https://www.pywhy.org/dowhy/main/example_notebooks/nb_index.html>`_\n\nIntroduction & Key Features\n===========================\nDecision-making involves understanding how different variables affect each other and predicting the outcome when some of them are changed to new values. For instance, given an outcome variable, one may be interested in determining how a potential action(s) may affect it, understanding what led to its current value, or simulate what would happen if some variables are changed. Answering such questions requires causal reasoning. DoWhy is a Python library that guides you through the various steps of causal reasoning and provides a unified interface for answering causal questions.\n\nDoWhy provides a wide variety of algorithms for effect estimation, prediction, quantification\nof causal influences, diagnosis of causal structures, root cause analysis, interventions and\ncounterfactuals. A key feature of DoWhy is its refutation and falsification API that can test causal assumptions for any estimation method,\nthus making inference more robust and accessible to non-experts.\n\n**Graphical Causal Models and Potential Outcomes: Best of both worlds**\n\nDoWhy builds on two of the most powerful frameworks for causal inference:\ngraphical causal models and potential outcomes. For effect estimation, it uses graph-based criteria and do-calculus for\nmodeling assumptions and identifying a non-parametric causal effect. For estimation, it switches to methods based\nprimarily on potential outcomes.\n\nFor causal questions beyond effect estimation, it uses the power of graphical causal models by modeling the data\ngeneration process via explicit causal mechanisms at each node, which, for instance, unlocks capabilities to attribute\nobserved effects to particular variables or estimate point-wise counterfactuals.\n\nFor a quick introduction to causal inference, check out `amit-sharma/causal-inference-tutorial <https://github.com/amit-sharma/causal-inference-tutorial/>`_\nWe also gave a more comprehensive tutorial at the ACM Knowledge Discovery and Data Mining (`KDD 2018 <http://www.kdd.org/kdd2018/>`_) conference: `causalinference.gitlab.io/kdd-tutorial <http://causalinference.gitlab.io/kdd-tutorial/>`_.\nFor an introduction to the four steps of causal inference and its implications for machine learning, you can access this video tutorial from Microsoft Research `DoWhy Webinar <https://www.microsoft.com/en-us/research/video/foundations-of-causal-inference-and-its-impacts-on-machine-learning/>`_ and for an introduction to the graphical causal model API, see the `PyCon presentation on Root Cause Analysis with DoWhy <https://www.youtube.com/watch?v=icpHrbDlGaw>`_.\n\nKey Features\n~~~~~~~~~~~~\n\n.. image:: https://raw.githubusercontent.com/py-why/dowhy/main/docs/images/dowhy-features.png\n\nDoWhy supports the following causal tasks:\n\n- Effect estimation (identification, average causal effect, conditional average causal effect, instrumental variables and more)\n- Quantify causal influences (mediation analysis, direct arrow strength, intrinsic causal influence)\n- What-if analysis (generate samples from interventional distribution, estimate counterfactuals)\n- Root cause analysis and explanations (attribute anomalies to their causes, find causes for changes in distributions, estimate feature relevance and more)\n\nFor more details and how to use these methods in practice, checkout the documentation at `https://py-why.github.io/dowhy <https://py-why.github.io/dowhy/>`_\n\nQuick Start\n===========\nDoWhy support Python 3.8+. To install, you can use pip, poetry, or conda.\n\n**Latest Release**\n\nInstall the latest `release <https://pypi.org/project/dowhy/>`__ using pip.\n\n.. code:: shell\n\n pip install dowhy\n\nInstall the latest `release <https://pypi.org/project/dowhy/>`__ using poetry.\n\n.. code:: shell\n\n poetry add dowhy\n\nInstall the latest `release <https://anaconda.org/conda-forge/dowhy>`__ using conda.\n\n.. code:: shell\n\n conda install -c conda-forge dowhy\n\nIf you face \"Solving environment\" problems with conda, then try :code:`conda update --all` and then install dowhy. If that does not work, then use :code:`conda config --set channel_priority false` and try to install again. If the problem persists, please `add your issue here <https://github.com/microsoft/dowhy/issues/197>`_.\n\n**Development Version**\n\nIf you prefer to use the latest dev version, your dependency management tool will need to point at our GitHub repository.\n\n.. code:: shell\n\n pip install git+https://github.com/py-why/dowhy@main\n\n\n**Requirements**\n\nDoWhy requires a few dependencies. \nDetails on specific versions can be found in `pyproject.toml <./pyproject.toml>`_, under the `tool.poetry.dependencies` section.\n\nIf you face any problems, try installing dependencies manually.\n\n.. code:: shell\n\n pip install '<dependency-name>==<version>'\n\nOptionally, if you wish to input graphs in the dot format, then install pydot (or pygraphviz).\n\nFor better-looking graphs, you can optionally install pygraphviz. To proceed,\nfirst install graphviz and then pygraphviz (on Ubuntu and Ubuntu WSL).\n\n.. note::\n Installing pygraphviz can cause problems on some platforms.\n One way that works for most Linux distributions is to\n first install graphviz and then pygraphviz as shown below.\n Otherwise, please consult the documentation of `pygraphviz <https://pygraphviz.github.io/documentation/stable/install.html>`_.\n\n.. code:: shell\n\n sudo apt install graphviz libgraphviz-dev graphviz-dev pkg-config\n pip install --global-option=build_ext \\\n --global-option=\"-I/usr/local/include/graphviz/\" \\\n --global-option=\"-L/usr/local/lib/graphviz\" pygraphviz\n\nExample: Effect identification and estimation\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nMost causal tasks in DoWhy only require a few lines of code to write. Here, we exemplarily estimate the causal effect of\na treatment on an outcome variable:\n\n.. code:: python\n\n from dowhy import CausalModel\n import dowhy.datasets\n\n # Load some sample data\n data = dowhy.datasets.linear_dataset(\n beta=10,\n num_common_causes=5,\n num_instruments=2,\n num_samples=10000,\n treatment_is_binary=True)\n\nA causal graph can be defined in different way, but the most common way is via `NetworkX <https://networkx.org/>`_.\nAfter loading in the data, we use the four main operations for effect estimation in DoWhy: *model*, *identify*,\n*estimate* and *refute*:\n\n.. code:: python\n\n # I. Create a causal model from the data and given graph.\n model = CausalModel(\n data=data[\"df\"],\n treatment=data[\"treatment_name\"],\n outcome=data[\"outcome_name\"],\n graph=data[\"gml_graph\"]) # Or alternatively, as nx.DiGraph\n\n # II. Identify causal effect and return target estimands\n identified_estimand = model.identify_effect()\n\n # III. Estimate the target estimand using a statistical method.\n estimate = model.estimate_effect(identified_estimand,\n method_name=\"backdoor.propensity_score_matching\")\n\n # IV. Refute the obtained estimate using multiple robustness checks.\n refute_results = model.refute_estimate(identified_estimand, estimate,\n method_name=\"random_common_cause\")\n\nDoWhy stresses on the interpretability of its output. At any point in the analysis,\nyou can inspect the untested assumptions, identified estimands (if any), and the\nestimate (if any). Here's a sample output of the linear regression estimator:\n\n.. image:: https://raw.githubusercontent.com/py-why/dowhy/main/docs/images/regression_output.png\n :width: 80%\n\nFor a full code example, check out the `Getting Started with DoWhy <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy_simple_example.html>`_ notebook.\n\nYou can also use Conditional Average Treatment Effect (CATE) estimation methods from `EconML <https://github.com/py-why/econml>`_, as shown in the `Conditional Treatment Effects <https://www.pywhy.org/dowhy/main/example_notebooks/dowhy-conditional-treatment-effects.html>`_ notebook. Here's a code snippet.\n\n.. code:: python\n\n\tfrom sklearn.preprocessing import PolynomialFeatures\n\tfrom sklearn.linear_model import LassoCV\n\tfrom sklearn.ensemble import GradientBoostingRegressor\n\tdml_estimate = model.estimate_effect(identified_estimand, method_name=\"backdoor.econml.dml.DML\",\n control_value = 0,\n treatment_value = 1,\n target_units = lambda df: df[\"X0\"]>1,\n confidence_intervals=False,\n method_params={\n \"init_params\":{'model_y':GradientBoostingRegressor(),\n 'model_t': GradientBoostingRegressor(),\n 'model_final':LassoCV(),\n 'featurizer':PolynomialFeatures(degree=1, include_bias=True)},\n \"fit_params\":{}})\n\n\nExample: Graphical causal model (GCM) based inference\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nDoWhy's graphical causal model framework offers powerful tools to address causal questions beyond effect estimation.\nIt is based on Pearl's graphical causal model framework and models the causal data generation process of each variable\nexplicitly via *causal mechanisms* to support a wide range of causal algorithms. For more details, see the book\n`Elements of Causal Inference <https://mitpress.mit.edu/9780262037310/elements-of-causal-inference/>`_.\n\nComplex causal queries, such as attributing observed anomalies to nodes in the system, can be performed with just a few\nlines of code:\n\n.. code:: python\n\n import networkx as nx, numpy as np, pandas as pd\n from dowhy import gcm\n\n # Let's generate some \"normal\" data we assume we're given from our problem domain:\n X = np.random.normal(loc=0, scale=1, size=1000)\n Y = 2 * X + np.random.normal(loc=0, scale=1, size=1000)\n Z = 3 * Y + np.random.normal(loc=0, scale=1, size=1000)\n data = pd.DataFrame(dict(X=X, Y=Y, Z=Z))\n\n # 1. Modeling cause-effect relationships as a structural causal model\n # (causal graph + functional causal models):\n causal_model = gcm.StructuralCausalModel(nx.DiGraph([('X', 'Y'), ('Y', 'Z')])) # X -> Y -> Z\n gcm.auto.assign_causal_mechanisms(causal_model, data)\n\n # 2. Fitting the SCM to the data:\n gcm.fit(causal_model, data)\n\n # Optional: Evaluate causal model\n print(gcm.evaluate_causal_model(causal_model, data))\n\n # Step 3: Perform a causal analysis.\n # results = gcm.<causal_query>(causal_model, ...)\n # For instance, root cause analysis:\n anomalous_sample = pd.DataFrame(dict(X=[0.1], Y=[6.2], Z=[19])) # Here, Y is the root cause.\n\n # \"Which node is the root cause of the anomaly in Z?\":\n anomaly_attribution = gcm.attribute_anomalies(causal_model, \"Z\", anomalous_sample)\n\n # Or sampling from an interventional distribution. Here, under the intervention do(Y := 2).\n samples = gcm.interventional_samples(causal_model, interventions={'Y': lambda y: 2}, num_samples_to_draw=100)\n\nThe GCM framework offers many more features beyond these examples. For a full code example, check out the `Online Shop example notebook <https://www.pywhy.org/dowhy/main/example_notebooks/gcm_online_shop.html>`_.\n\nFor more functionalities, example applications of DoWhy and details about the outputs, see the `User Guide <https://www.pywhy.org/dowhy/main/user_guide/intro.html>`_ or\ncheckout `Jupyter notebooks <https://www.pywhy.org/dowhy/main/example_notebooks/nb_index.html>`_.\n\nMore Information & Resources\n============================\n`Microsoft Research Blog <https://www.microsoft.com/en-us/research/blog/dowhy-a-library-for-causal-inference/>`_ | `Video Tutorial for Effect Estimation <https://www.youtube.com/watch?v=LALfQStONEc&t=114s>`_ | `Video Tutorial for Root Cause Analysis <https://www.youtube.com/watch?v=icpHrbDlGaw>`_ | `Arxiv Paper <https://arxiv.org/abs/2011.04216>`_ | `Arxiv Paper (Graphical Causal Model extension) <https://arxiv.org/abs/2206.06821>`_ | `Slides <https://www2.slideshare.net/AmitSharma315/dowhy-an-endtoend-library-for-causal-inference>`_\n\n\nCiting this package\n~~~~~~~~~~~~~~~~~~~\nIf you find DoWhy useful for your work, please cite **both** of the following two references:\n\n- Amit Sharma, Emre Kiciman. DoWhy: An End-to-End Library for Causal Inference. 2020. https://arxiv.org/abs/2011.04216\n- Patrick Bl\u00f6baum, Peter G\u00f6tz, Kailash Budhathoki, Atalanti A. Mastakouri, Dominik Janzing. DoWhy-GCM: An extension of DoWhy for causal inference in graphical causal models. 2024. MLOSS 25(147):1\u22127. https://jmlr.org/papers/v25/22-1258.html\n\nBibtex::\n\n @article{dowhy,\n title={DoWhy: An End-to-End Library for Causal Inference},\n author={Sharma, Amit and Kiciman, Emre},\n journal={arXiv preprint arXiv:2011.04216},\n year={2020}\n }\n\n @article{JMLR:v25:22-1258,\n author = {Patrick Bl{{\\\"o}}baum and Peter G{{\\\"o}}tz and Kailash Budhathoki and Atalanti A. Mastakouri and Dominik Janzing},\n title = {DoWhy-GCM: An Extension of DoWhy for Causal Inference in Graphical Causal Models},\n journal = {Journal of Machine Learning Research},\n year = {2024},\n volume = {25},\n number = {147},\n pages = {1--7},\n url = {http://jmlr.org/papers/v25/22-1258.html}\n }\n\nIssues\n~~~~~~\nIf you encounter an issue or have a specific request for DoWhy, please `raise an issue <https://github.com/py-why/dowhy/issues>`_.\n\nContributing\n~~~~~~~~~~~~\n\nThis project welcomes contributions and suggestions. For a guide to contributing and a list of all contributors, check out `CONTRIBUTING.md <https://github.com/py-why/dowhy/blob/main/CONTRIBUTING.md>`_ and our `docs for contributing code <https://github.com/py-why/dowhy/blob/main/docs/source/contributing/contributing-code.rst>`_. Our `contributor code of conduct is available here <https://github.com/py-why/governance/blob/main/CODE-OF-CONDUCT.md>`_.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "DoWhy is a Python library for causal inference that supports explicit modeling and testing of causal assumptions",
"version": "0.12",
"project_urls": {
"Documentation": "https://py-why.github.io/dowhy",
"Homepage": "https://github.com/py-why/dowhy",
"Repository": "https://github.com/py-why/dowhy"
},
"split_keywords": [
"causality",
" machine-learning",
" causal-inference",
" statistics",
" graphical-model"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "60056b7bfb09a81899b2cb047450f35515019b1cc5c3da9b5c0a3be4ed5cd3ab",
"md5": "49a3a8c08844c1b2c7f47c1d38aa879a",
"sha256": "545fbcf73861302ec919b3079005e808ea2c2f036b5b1ad5f8e94e9467ebbc00"
},
"downloads": -1,
"filename": "dowhy-0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "49a3a8c08844c1b2c7f47c1d38aa879a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 398366,
"upload_time": "2024-11-24T07:36:17",
"upload_time_iso_8601": "2024-11-24T07:36:17.461772Z",
"url": "https://files.pythonhosted.org/packages/60/05/6b7bfb09a81899b2cb047450f35515019b1cc5c3da9b5c0a3be4ed5cd3ab/dowhy-0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa0f793cbb59d0ac3f25ba8053724c446e2704974b4a192835e59953b7f74a1f",
"md5": "57a255149de6f856e6faf0cf3aac399c",
"sha256": "de67fbb3066d25cb065b32af669373065e2f18dfd1f95938da346bc6a315d163"
},
"downloads": -1,
"filename": "dowhy-0.12.tar.gz",
"has_sig": false,
"md5_digest": "57a255149de6f856e6faf0cf3aac399c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 13030585,
"upload_time": "2024-11-24T07:36:19",
"upload_time_iso_8601": "2024-11-24T07:36:19.825513Z",
"url": "https://files.pythonhosted.org/packages/aa/0f/793cbb59d0ac3f25ba8053724c446e2704974b4a192835e59953b7f74a1f/dowhy-0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 07:36:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "py-why",
"github_project": "dowhy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dowhy"
}
JSON
