Causal Graph
This is a class for representing DAGs of causal structures.
Generally, for a set of variables \(V\), a variable \(V_i\) is said to be a cause of a variable \(V_j\) if \(V_j\) can change in response to changes in \(V_i\). In a DAG for causal structures, every parent is a direct causes of all its children. And we refer to these DAGs for causal structures as causal graphs. For the terminologies of graph, one can see, for example, Chapter 1.2 in [Pearl].
There are five basic structures composed of two or three nodes for building causal graphs. Besides the structures, there are flows of association and causation in causal graphs in the probability language. Any two nodes \(X\) and \(Y\) connected by the flow of association implies that they are statistically dependent, i.e., \(P(X, Y) \neq P(X)P(Y)\). Let \(X, Y\) and \(W\) be three distinct nodes, then the five basics structures include:
chains:
\(X\) and \(Y\) are statistically dependent;
forks:
\(X\) and \(Y\) are statistically dependent;
colliders:
\(X\) and \(Y\) are statistically independent;
two unconnected nodes:
\(X\) and \(Y\) are statistically independent;
two connected nodes:
\(X\) and \(Y\) are statistically dependent.
In YLearn, one can use the CausalGraph
to represent causal structures by first giving a python dict where
each key in this dict is a child of all elements in the corresponding dict value, which usually should be a list
of str.
Examples
We can represent this causal structure with YLearn as follows:
from ylearn.causal_model.graph import CausalGraph
causation = {
'X': ['Z2'],
'Z1': ['X', 'Z2'],
'Y': ['Z1', 'Z3'],
'Z3': ['Z2'],
'Z2': [],
}
arcs = [('X', 'Z2'), ('X', 'Z3'), ('X', 'Y'), ('Z2', 'Y')]
cg = CausalGraph(causation=causation, latent_confounding_arcs=arcs)
list(cg.c_components)
>>> [{'X', 'Y', 'Z2', 'Z3'}, {'Z1'}]
Class Structures
- class ylearn.causal_model.graph.CausalGraph(causation, dag=None, latent_confounding_arcs=None)
- Parameters
causation (dict) – Descriptions of the causal structures where values are parents of the corresponding keys.
dag (networkx.MultiGraph, optional, default=None) – A known graph structure. If provided, dag must represent the causal structures stored in causation.
latent_confounding_arcs (set or list of tuple of two str, optional, default=None,) – Two elements in the tuple are names of nodes in the graph where there exists an latent confounding arcs between them. Semi-Markovian graphs with unobserved confounders can be converted to a graph without unobserved variables, where one can add bi-directed latent confounding arcs to represent these relations. For example, the causal graph X <- U -> Y, where U is an unobserved confounder of X and Y, can be converted equivalently to X <–>Y where <–> is a latent confounding arc.
- ancestors(x)
Return the ancestors of all nodes in x.
- Parameters
x (set of str) – A set of nodes in the graph.
- Returns
Ancestors of nodes in x in the graph.
- Return type
set of str
- descendents(x)
Return the descendents of all nodes in x.
- Parameters
x (set of str) – A set of nodes in the graph.
- Returns
Descendents of nodes in x in the graph.
- Return type
set of str
- parents(x, only_observed=True)
Return the direct parents of the node x in the graph.
- Parameters
x (str) – Name of the node x.
only_observed (bool, default=True) – If True, then only find the observed parents in the causal graph, otherwise also include the unobserved variables, by default True
- Returns
Parents of the node x in the graph
- Return type
list
- add_nodes(nodes, new=False)
If not new, add all nodes in the nodes to the current CausalGraph, else create a new graph and add nodes.
- Parameters
x (set or list) – Nodes waited to be added to the current causal graph.
new (bool, default=False) – If new create and return a new graph. Defaults to False.
- Returns
Modified causal graph
- Return type
instance of CausalGraph
- add_edges_from(edge_list, new=False, observed=True)
Add edges to the causal graph.
- Parameters
edge_list (list) – Every element of the list contains two elements, the first for the parent
new (bool, default=False) – If new create and return a new graph. Defaults to False.
observed (bool, default=True) – Add unobserved bidirected confounding arcs if not observed.
- Returns
Modified causal graph
- Return type
instance of CausalGraph
- add_edge(edge_list, s, t, observed=True)
Add edges to the causal graph.
- Parameters
s (str) – Source of the edge.
t (str) – Target of the edge.
observed (bool, default=True) – Add unobserved bidirected confounding arcs if not observed.
- remove_nodes(nodes, new=True)
Remove all nodes of nodes in the graph.
- Parameters
nodes (set or list) – Nodes waited to be removed.
new (bool, default=True) – If True, create a new graph, remove nodes in that graph and return it. Defaults to False.
- Returns
Modified causal graph
- Return type
instance of CausalGraph
- remove_edge(edge, observed=True)
Remove the edge in the CausalGraph. If not observed, remove the unobserved latent confounding arcs.
- Parameters
edge (tuple) – 2 elements denote the start and end of the edge, respectively.
observed (bool, default=True) – If not observed, remove the unobserved latent confounding arcs.
- remove_edges_from(edge_list, new=False, observed=True)
Remove all edges in the edge_list in the graph.
- Parameters
edge_list (list) – list of edges to be removed.
new (bool, default=False) – If new, create a new CausalGraph and remove edges.
observed (bool, default=True) – Remove unobserved latent confounding arcs if not observed.
- Returns
Modified causal graph
- Return type
instance of CausalGraph
- build_sub_graph(subset)
Return a new CausalGraph as the subgraph of the graph with nodes in the subset.
- Parameters
subset (set) – The set of the subgraph.
- Returns
Modified causal graph
- Return type
instance of CausalGraph
- remove_incoming_edges(x, new=False)
Remove incoming edges of all nodes of x. If new, do this in the new CausalGraph.
- Parameters
x (set or list) –
new (bool, default=False,) – Return a new graph if set as Ture.
- Returns
Modified causal graph
- Return type
instance of CausalGraph
- remove_outgoing_edges(x, new=False)
Remove outgoing edges of all nodes of x. If new, do this in the new CausalGraph.
- Parameters
x (set or list) –
new (bool, default=False,) – Return a new graph if set as Ture.
- Returns
Modified causal graph
- Return type
instance of CausalGraph
- property c_components
The C-components set of the graph.
- Returns
The C-components set of the graph.
- Return type
set of str
- property observed_dag
Return the observed part of the graph, including observed nodes and edges between them.
- Returns
The observed part of the graph
- Return type
networkx.MultiGraph
- property explicit_unob_var_dag
Build a new dag where all unobserved confounding arcs are replaced by explicit unobserved variables.
- Returns
Dag with explicit unobserved nodes
- Return type
networkx.MultiGraph
- property topo_order
Return the topological order of the nodes in the observed graph.
- Returns
Nodes in the topological order
- Return type
generator