DOCSEARCHbyAlgolia
Submit Docs

DoWhy

repository·main·Indexed 27 days ago

https://github.com/py-why/dowhy

A Python library for causal inference that supports explicit modeling and testing of causal assumptions. It guides users through four steps of causal reasoning: modeling, identification, estimation, and refutation. DoWhy provides a unified interface for effect estimation, root cause analysis, what-if analysis, and counterfactual fairness. It features deep integration with EconML and CausalML, supports Graphical Causal Models (GCM), and includes a suite of refuters in the dowhy.causal_refuters package for robustness checks.

Tokens
61.1K
Snippets
154
Records
302
Agent score
93%

What's inside DoWhy

  1. Overview of DoWhy causal inference capabilities

    main

    DoWhy is a Python library designed for causal thinking and analysis. It provides a suite of algorithms for several key causal inference tasks:

    • Effect Estimation: Estimating the causal impact of variables.
    • Causal Structure Learning: Discovering causal relationships from data.
    • Diagnosis of Causal Structures: Evaluating the validity of causal models.
    • Root Cause Analysis: Identifying the underlying causes of observed effects.
    • Interventions and Counterfactuals: Modeling what happens when variables are changed or exploring hypothetical scenarios.

  2. Overview of DoWhy causal tasks

    main

    DoWhy is organized around several distinct causal tasks. Depending on your goal, you can use the library for:

    • Estimating causal effects: Calculating average causal effects (using backdoor, frontdoor, or instrumental variable methods) or conditional average causal effects (CATE) via EconML integration.
    • Quantifying causal influence: Measuring how much one variable influences another.
    • Root causing and explaining: Identifying the source of an effect (e.g., identifying which service caused a slowdown in a distributed system).
    • What-if analysis: Simulating interventions (e.g., "If I change the color of my button to red, how much will this change users' purchase decisions?").
    • Causal prediction: Using causal knowledge for predictive tasks.

  3. Explore DoWhy subpackages and modules

    main

    The dowhy package is organized into several specialized subpackages and modules for different stages of the causal inference pipeline. Key functional areas include:

    • Causal Modeling: dowhy.causal_model for creating causal models, dowhy.causal_graph for graph representations, and dowhy.graph_learners for learning graphs from data.
    • Identification & Estimation: dowhy.causal_identifier for identifying causal effects and dowhy.causal_estimators for statistical estimation.
    • Refutation: dowhy.causal_refuters for performing robustness checks on estimates.
    • Data & Sampling: dowhy.data_transformers for data preprocessing, dowhy.datasets for sample data, and dowhy.do_samplers for do-calculus sampling.
    • Interpretation & Visualization: dowhy.interpreters for understanding model behavior and dowhy.plotter for visual representations.

  4. Use the dowhy.causal_refuters package for robustness checks

    main
    The dowhy.causal_refuters package provides a suite of refuters designed to test the robustness of causal estimates. These refuters attempt to invalidate the estimated causal effect by introducing potential biases, unobserved confounders, or data perturbations. If the estimate remains stable under these tests, it increases confidence in the causal conclusion.

  5. Explore the dowhy.gcm package structure

    main

    The dowhy.gcm package provides tools for working with Graphical Causal Models (GCM). It is organized into several subpackages and modules covering different aspects of causal modeling, including independence testing, machine learning integration, and utility functions.

    Subpackages

    • dowhy.gcm.independence_test: Tools for testing independence between variables.
    • dowhy.gcm.ml: Integration with machine learning workflows.
    • dowhy.gcm.util: General utility functions for GCM.

    Key Functional Modules

    • Modeling: causal_mechanisms, causal_models, stochastic_models, and equation_parser.
    • Evaluation & Robustness: model_evaluation, falsify, validation, anomaly, and distribution_change.
    • Inference & Uncertainty: confidence_intervals, uncertainty, stats, and influence.
    • Analysis: feature_relevance, shapley, whatif, and divergence.

  6. Explore the dowhy.utils package submodules

    main

    The dowhy.utils package provides a collection of utility modules for causal inference tasks, including graph operations, plotting, data generation, and statistical helpers. Key submodules available for use include:

    • dowhy.utils.api: API-related utilities.
    • dowhy.utils.cit: Conditional Independence Test utilities.
    • dowhy.utils.dgp: Data Generating Process utilities.
    • dowhy.utils.graph_operations: Tools for manipulating causal graphs.
    • dowhy.utils.graphviz_plotting & dowhy.utils.networkx_plotting: Specialized plotting modules for different graph backends.
    • dowhy.utils.propensity_score: Utilities for calculating propensity scores.
    • dowhy.utils.regression: Regression-related helper functions.
    • dowhy.utils.timeseries: Utilities for time-series data handling.

  8. Perform effect identification and estimation

    main

    The standard workflow for causal effect estimation in DoWhy follows four main steps:

    1. Model: Create a CausalModel using your data, treatment variable, outcome variable, and a causal graph (e.g., a NetworkX DiGraph).
    2. Identify: Call model.identify_effect() to find the target estimands based on the causal graph.
    3. Estimate: Call model.estimate_effect() using a statistical method (e.g., backdoor.propensity_score_matching) to calculate the effect.
    4. Refute: Call model.refute_estimate() to perform robustness checks (e.g., random_common_cause) to validate the estimate.
    from dowhy import CausalModel
import dowhy.datasets

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

# I. Create a causal model
model = CausalModel(
    data=data["df"],
    treatment=data["treatment_name"],
    outcome=data["outcome_name"],
    graph=data["gml_graph"])

# II. Identify causal effect
identified_estimand = model.identify_effect()

# III. Estimate the target estimand
estimate = model.estimate_effect(identified_estimand, 
                                 method_name="backdoor.propensity_score_matching")

# IV. Refute the estimate
refute_results = model.refute_estimate(identified_estimand, estimate, 
                                        method_name="random_common_cause")

  9. Generate samples from a random SCM for benchmarking

    main

    The dowhy.gcm.data_generator module allows you to create synthetic datasets from randomly generated Structural Causal Models (SCMs). This is ideal for testing and benchmarking algorithms with realistic properties like mixed linear/nonlinear mechanisms and varying noise types.

    Use generate_samples_from_random_scm for a quick way to get a DataFrame of samples, or generate_random_scm to obtain the actual SCM object for inspection or intervention experiments.

    from dowhy.gcm.data_generator import generate_samples_from_random_scm

# Quick way to get samples
samples = generate_samples_from_random_scm(num_roots=3, num_children=5, num_samples=1000)

  10. Initialize a Structural Causal Model (SCM)

    main

    To work with Graphical Causal Models (GCMs), you first define a causal graph using a directed acyclic graph (DAG) and then wrap it in a StructuralCausalModel. The graph can be constructed using networkx.

    from dowhy import gcm
import networkx as nx

# Define the causal graph
causal_model = gcm.StructuralCausalModel(nx.DiGraph([("X", "Y"), ("Y", "Z")]))

  11. Automate causal graph refutation for large graphs

    main

    For complex graphs with many conditional independence constraints, DoWhy can automatically enumerate and execute all necessary tests to check the validity of the entire structure.

    To perform this task, refer to the refute_causal_structure and independence_tests documentation or follow the pattern demonstrated in the Falsification of User-Given Directed Acyclic Graphs example notebook.

  12. Manage do-sampler statefulness

    main

    The do-sampler behavior regarding state depends on the API used:

    High-level pandas API

    By default, the sampler is stateless. Repeated calls to pandas.DataFrame.causal.do will generate different samples.

    To improve efficiency—especially when step 1 requires fitting an expensive model (like the MCMC, kernel density, or weighting samplers)—you can make the sampler stateful. This allows you to fit the model once and then generate many samples from that fitted state.

    • Enable statefulness: Pass stateful=True when calling pandas.DataFrame.causal.do.
    • Reset state: Call pandas.DataFrame.causal.reset to delete the internal model and the internal dataframe.

    Low-level API

    The sampler is stateful by default in the low-level API. State is carried by the internal dataframe self._df (a copy of the input), while the original data is preserved in self._data for use during resets.