Package: dowhy
Checkout the documentationThe documentation, user guide, sample notebooks and other information are available athttps://py-why.github.io/dowhyDoWhy is part of thePyWhy Ecosystem. For more tools and libraries related to causality, checkout thePyWhy GitHub organization!For any questions, comments, or discussions about specific use cases, join our community onDiscord()Jump right into some case studies:Effect estimation:Hotel booking cancellations|Effect of customer loyalty programs|Optimizing article headlines|Effect of home visits on infant health (IHDP)|Causes of customer churn/attritionRoot cause analysis and explanations:Causal attribution and root-cause analysis of an online shop|Finding the Root Cause of Elevated Latencies in a Microservice Architecture|Finding Root Causes of Changes in a Supply ChainFor more example notebooks, seehere!Introduction & Key FeaturesDecision-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 worldsDoWhy 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 outamit-sharma/causal-inference-tutorialWe also gave a more comprehensive tutorial at the ACM Knowledge Discovery and Data Mining (KDD 2018) conference: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 ResearchDoWhy Webinarand for an introduction to the graphical causal model API, see thePyCon presentation on Root Cause Analysis with DoWhy.Key FeaturesDoWhy 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 athttps://py-why.github.io/dowhyQuick StartDoWhy support Python 3.8+. To install, you can use pip, poetry, or conda.Latest ReleaseInstall the latestreleaseusing pip.pipinstalldowhyInstall the latestreleaseusing poetry.poetryadddowhyInstall the latestreleaseusing conda.condainstall-cconda-forgedowhyIf you face “Solving environment” problems with conda, then tryconda update --alland then install dowhy. If that does not work, then useconda config --set channel_priority falseand try to install again. If the problem persists, pleaseadd your issue here.Development VersionIf you prefer to use the latest dev version, your dependency management tool will need to point at our GitHub repository.pipinstallgit+https://github.com/py-why/dowhy@mainRequirementsDoWhy requires a few dependencies.
Details on specific versions can be found inpyproject.toml, under thetool.poetry.dependenciessection.If you face any problems, try installing dependencies manually.pipinstall'<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).sudoaptinstallgraphvizlibgraphviz-devgraphviz-devpkg-config## from https://github.com/pygraphviz/pygraphviz/issues/71pipinstallpygraphviz--install-option="--include-path=/usr/include/graphviz"\--install-option="--library-path=/usr/lib/graphviz/"Example: Effect identification and estimationMost 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:fromdowhyimportCausalModelimportdowhy.datasets# Load some sample datadata=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 viaNetworkX.
After loading in the data, we use the four main operations for effect estimation in DoWhy:model,identify,estimateandrefute:# 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 estimandsidentified_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:For a full code example, check out theGetting Started with DoWhynotebook.You can also use Conditional Average Treatment Effect (CATE) estimation methods fromEconML, as shown in theConditional Treatment Effectsnotebook. Here’s a code snippet.fromsklearn.preprocessingimportPolynomialFeaturesfromsklearn.linear_modelimportLassoCVfromsklearn.ensembleimportGradientBoostingRegressordml_estimate=model.estimate_effect(identified_estimand,method_name="backdoor.econml.dml.DML",control_value=0,treatment_value=1,target_units=lambdadf: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 inferenceDoWhy’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 viacausal mechanismsto support a wide range of causal algorithms. For more details, see the bookElements 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:importnetworkxasnx,numpyasnp,pandasaspdfromdowhyimportgcm# 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 -> Zgcm.auto.assign_causal_mechanisms(causal_model,data)# 2. Fitting the SCM to the data:gcm.fit(causal_model,data)# Optional: Evaluate causal modelprint(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':lambday:2},num_samples_to_draw=100)The GCM framework offers many more features beyond these examples. For a full code example, check out theOnline Shop example notebook.For more functionalities, example applications of DoWhy and details about the outputs, see theUser Guideor
checkoutJupyter notebooks.More Information & ResourcesMicrosoft Research Blog|Video Tutorial for Effect Estimation|Video Tutorial for Root Cause Analysis|Arxiv Paper|Arxiv Paper (Graphical Causal Model extension)|SlidesCiting this packageIf you find DoWhy useful for your work, please citebothof the following two references:Amit Sharma, Emre Kiciman. DoWhy: An End-to-End Library for Causal Inference. 2020.https://arxiv.org/abs/2011.04216Patrick 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. 2022.https://arxiv.org/abs/2206.06821Bibtex:@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{dowhy_gcm,
    author = {Bl{\"o}baum, Patrick and G{\"o}tz, Peter and Budhathoki, Kailash and Mastakouri, Atalanti A. and Janzing, Dominik},
    title = {DoWhy-GCM: An extension of DoWhy for causal inference in graphical causal models},
    journal={arXiv preprint arXiv:2206.06821},
    year={2022}
}IssuesIf you encounter an issue or have a specific request for DoWhy, pleaseraise an issue.ContributingThis project welcomes contributions and suggestions. For a guide to contributing and a list of all contributors, check outCONTRIBUTING.mdand ourdocs for contributing code. Ourcontributor code of conduct is available here.