CausalNex Documentation

CausalNex is a toolkit for causal reasoning and "what-if" analysis using Bayesian Networks. It is designed to simplify the end-to-end process of identifying causal relationships and assessing the impact of interventions.

Core Capabilities:

• Structure Learning: Uses state-of-the-art methods to understand conditional dependencies between variables.
• Domain Knowledge Integration: Allows users to augment or encode domain expertise into the graph model.
• Predictive Modeling: Builds models based on structural relationships.
• Probability Fitting: Fits probability distributions to Bayesian Networks.
• Model Evaluation: Uses standard statistical checks to evaluate model quality.
• Visualization: Simplifies understanding of causality through graph visualization.
• Intervention Analysis: Uses Do-calculus to analyze the impact of interventions.

CausalNex is a Python library designed for causal reasoning using Bayesian Networks. It allows users to combine machine learning with domain expertise to:

• Uncover structural relationships (conditional dependencies) in data.
• Learn complex probability distributions.
• Observe the effects of potential interventions using Do-calculus.
• Build predictive models based on structural relationships.

The causalnex package is organized into several specialized modules that cover the causal discovery and inference pipeline. The core modules include:

• causalnex.structure: Tools for structure learning and defining causal graphs.
• causalnex.plots: Visualization utilities for causal networks and relationships.
• causalnex.discretiser: Tools for discretizing continuous data for causal analysis.
• causalnex.estimator: Modules for estimating causal effects.
• causalnex.network: Core network representations and graph handling.
• causalnex.evaluation: Metrics and methods for evaluating causal models.
• causalnex.inference: Tools for performing causal inference tasks.

The NOTEARS algorithm is used for structure learning and works by detecting if a small increase in a node's value results in an increase in another node.

• Recommended Data Type: Use continuous datasets for optimal performance.
• Categorical Variables: NOTEARS cannot directly process categorical variables (e.g., blood type). For these features, you should manually add the relationships to the structure based on domain expertise after the initial structure learning phase.

A Bayesian Network (BN) is a probabilistic graphical model used to represent the dependency structure of a set of variables. In CausalNex, BNs are treated as causal models where edges represent a cause $\rightarrow$ effect relationship.

A Bayesian Network consists of:

1. A Directed Acyclic Graph (DAG): A graph where edges have direction (parent $\rightarrow$ child) and there are no cycles.
2. Conditional Probability Distributions (CPDs): For each variable, a distribution representing $P(\text{variable} | \text{parents})$. If a variable has no parents, it represents $P(\text{variable})$.

While structure learning algorithms primarily identify dependencies, CausalNex users typically treat these dependencies as causal relationships by incorporating domain expertise or validating learned structures.

In CausalNex, these two components serve different stages of the modeling pipeline:

• StructureModel: Used during the discovery phase. It allows for the addition, removal, and flipping of edges. Because these modifications can temporarily introduce cycles, a StructureModel can be cyclic.
• BayesianNetwork: A specialized Directed Acyclic Graph (DAG). Once the StructureModel has been finalized and is acyclic, it can be used to create a BayesianNetwork for probability fitting and inference.

CausalNex provides several core capabilities for causal analysis:

• Structure Learning: Uses the DAG with NO TEARS method to identify conditional dependencies.
• Domain Knowledge Integration: Allows users to augment model relationships with expert knowledge.
• Predictive Modeling: Builds models grounded in structural relationships.
• Probabilistic Understanding: Provides insights into model probability.
• Quality Evaluation: Uses standard statistical checks to evaluate model quality.
• Visualization: Simplifies the understanding of causal structures.
• Intervention Analysis: Uses Do-calculus to analyze the impact of interventions.

A Do-intervention, symbolically represented as p(y|do(x)), asks: "What is the probability distribution of $Y$ if we were to arbitrarily set the value of $X$ to $x$?"

This is a core component of counterfactual analysis, allowing users to simulate outcomes that would have occurred if a different action or intervention had been taken.

The BayesianNetwork class is the central object for causal inference. It requires a StructureModel to define its causal graph (a Directed Acyclic Graph or DAG).

StructureModel is an extension of networkx.DiGraph that represents cause $\rightarrow$ effect relationships. While StructureModel objects can contain cycles, a BayesianNetwork requires an acyclic connected StructureModel. Isolated nodes are not permitted in the construction of a BayesianNetwork.

Bayesian Networks in CausalNex are used for:

• Inference & Counterfactuals: Updating variable probabilities as new observations are added to the model to understand what changes lead to specific effects.
• Predictive Analytics: Using the learned structure and CPDs to predict outcomes.
• Relationship Strength: Using metrics to identify the sensitivity of nodes to changes in other events and identifying the 'active trail' of a target node to see which variables influence it.

To verify that CausalNex is installed correctly, run a one-line Python command to attempt to import the module. If the installation is successful, the command will produce no output. If it fails, you will see a ModuleNotFoundError: No module named 'causalnex'.

python -c "import causalnex"

If your contribution requires dependencies that are not included in the core requirements.txt, you must define them in setup.py using the extras_require dictionary. Use the name of your project as the key.

Example configuration in setup.py:

...
extras_require={
        'my_project': ['requirement1==1.0.1', 'requirement2==2.0.1'],
    },