`causal_testing.specification.causal_dag`

This module contains the CausalDAG class, as well as the functions list_all_min_sep and close_seperator

Module Contents

Classes

CausalDAG

A causal DAG is a directed acyclic graph in which nodes represent random variables and edges represent causality

Functions

`close_separator`(→ set[Node])	Compute the close separator for a set of treatments in an undirected graph.
`list_all_min_sep`(→ Generator[Set, None, None])	A backtracking algorithm for listing all minimal treatment-outcome separators in an undirected graph.

Attributes

`Node`
`logger`

causal_testing.specification.causal_dag.Node

causal_testing.specification.causal_dag.logger

causal_testing.specification.causal_dag.close_separator(graph: networkx.Graph, treatment_node: Node, outcome_node: Node, treatment_node_set: set[Node]) → set[Node]

Compute the close separator for a set of treatments in an undirected graph.

A close separator (relative to a set of variables X) is a separator whose vertices are adjacent to those in X. An X-Y separator is a set of variables which, once deleted from a graph, create a subgraph in which X and Y are in different components.

Reference: (Space-optimal, backtracking algorithms to list the minimal vertex separators of a graph, Ken Takata, 2013, p.4, CloseSeparator procedure).

Parameters:

graph – An undirected graph.
treatment_node – A label for the treatment node (parent of treatments in undirected graph).
outcome_node – A label for the outcome node (parent of outcomes in undirected graph).
treatment_node_set – The set of variables containing the treatment node ({treatment_node}).

Returns:

A treatment_node-outcome_node separator whose vertices are adjacent to those in treatments.

causal_testing.specification.causal_dag.list_all_min_sep(graph: networkx.Graph, treatment_node: str, outcome_node: str, treatment_node_set: Set, outcome_node_set: Set) → Generator[Set, None, None]

A backtracking algorithm for listing all minimal treatment-outcome separators in an undirected graph.

Reference: (Space-optimal, backtracking algorithms to list the minimal vertex separators of a graph, Ken Takata, 2013, p.5, ListMinSep procedure).

Parameters:

graph – An undirected graph.
treatment_node – The node corresponding to the treatment variable we wish to separate from the output.
outcome_node – The node corresponding to the outcome variable we wish to separate from the input.
treatment_node_set – Set of treatment nodes.
outcome_node_set – Set of outcome nodes.

Returns:

A generator of minimal-sized sets of variables which separate treatment and outcome in the undirected graph.

class causal_testing.specification.causal_dag.CausalDAG(file_path: str = None, ignore_cycles: bool = False, **attr)

Bases: networkx.DiGraph

A causal DAG is a directed acyclic graph in which nodes represent random variables and edges represent causality between a pair of random variables. We implement a CausalDAG as a networkx DiGraph with an additional check that ensures it is acyclic. A CausalDAG must be specified as a dot file.

check_iv_assumptions(treatment, outcome, instrument) → bool

Checks the three instrumental variable assumptions, raising a ValueError if any are violated.

Returns:: Boolean True if the three IV assumptions hold.

add_edge(u_of_edge: Node, v_of_edge: Node, **attr)

Add an edge to the causal DAG.

Overrides the default networkx method to prevent users from adding a cycle.

Parameters:

u_of_edge – From node
v_of_edge – To node
attr – Attributes

cycle_nodes() → list

Get the nodes involved in any cycles.

Returns:: A list containing all nodes involved in a cycle.

is_acyclic() → bool

Checks if the graph is acyclic.

Returns:: True if acyclic, False otherwise.

get_proper_backdoor_graph(treatments: list[str], outcomes: list[str]) → CausalDAG

Convert the causal DAG to a proper back-door graph.

A proper back-door graph of a causal DAG is obtained by removing the first edge of every proper causal path from treatments to outcomes. A proper causal path from X to Y is a path of directed edges that starts from X and ends in Y.

Reference: (Separators and adjustment sets in causal graphs: Complete criteria and an algorithmic framework, Zander et al., 2019, Definition 3, p.15)

Parameters:

treatments – A list of treatment variables.
outcomes – A list of outcomes.

Returns:

A CausalDAG corresponding to the proper back-door graph.

get_ancestor_graph(treatments: list[str], outcomes: list[str]) → CausalDAG

Given a list of treament variables and a list of outcome variables, transform a CausalDAG into an ancestor graph.

An ancestor graph G[An(W)] for a CausalDAG G is a subgraph of G consisting of only the vertices who are ancestors of the set of variables W and all edges between them. Note that a node is an ancestor of itself.

Reference: (Adjustment Criteria in Causal Diagrams: An Algorithmic Perspective, Textor and Lískiewicz, 2012, p. 3 [Descendants and Ancestors]).

Parameters:

treatments – A list of treatment variables to include in the ancestral graph (and their ancestors).
outcomes – A list of outcome variables to include in the ancestral graph (and their ancestors).

Returns:

An ancestral graph relative to the set of variables X union Y.

get_indirect_graph(treatments: list[str], outcomes: list[str]) → CausalDAG

This is the counterpart of the back-door graph for direct effects. We remove only edges pointing from X to Y. It is a Python implementation of the indirectGraph function from Dagitty.

Parameters:

treatments – List of treatment names.
outcomes – List of outcome names.

Returns:

The indirect graph with edges pointing from X to Y removed.

direct_effect_adjustment_sets(treatments: list[str], outcomes: list[str], nodes_to_ignore: list[str] = None) → list[set[str]]

Get the smallest possible set of variables that blocks all back-door paths between all pairs of treatments and outcomes for DIRECT causal effect.

This is an Python implementation of the listMsasTotalEffect function from Dagitty using Algorithms presented in Adjustment Criteria in Causal Diagrams: An Algorithmic Perspective, Textor and Lískiewicz, 2012 and extended in Separators and adjustment sets in causal graphs: Complete criteria and an algorithmic framework, Zander et al., 2019. These works use the algorithm presented by Takata et al. in their work entitled: Space-optimal, backtracking algorithms to list the minimal vertex separators of a graph, 2013.

Parameters:

treatments – List of treatment names.
outcomes – List of outcome names.
nodes_to_ignore – List of nodes to exclude from tests if they appear as treatments, outcomes, or in the adjustment set.

Returns:

A list of possible adjustment sets.

enumerate_minimal_adjustment_sets(treatments: list[str], outcomes: list[str]) → Generator[set[str]]

Get the smallest possible set of variables that blocks all back-door paths between all pairs of treatments and outcomes.

This is an implementation of the Algorithm presented in Adjustment Criteria in Causal Diagrams: An Algorithmic Perspective, Textor and Lískiewicz, 2012 and extended in Separators and adjustment sets in causal graphs: Complete criteria and an algorithmic framework, Zander et al., 2019. These works use the algorithm presented by Takata et al. in their work entitled: Space-optimal, backtracking algorithms to list the minimal vertex separators of a graph, 2013.

At a high-level, this algorithm proceeds as follows for a causal DAG G, set of treatments X, and set of outcomes Y):

Transform G to a proper back-door graph G_pbd (remove the first edge from X on all proper causal paths).
Transform G_pbd to the ancestor moral graph (G_pbd[An(X union Y)])^m.
Apply Takata’s algorithm to output all minimal X-Y separators in the graph.

Parameters:

treatments – A list of strings representing treatments.
outcomes – A list of strings representing outcomes.

Returns:

A list of strings representing the minimal adjustment set.

adjustment_set_is_minimal(treatments: list[str], outcomes: list[str], adjustment_set: set[str]) → bool

Given a list of treatments X, a list of outcomes Y, and an adjustment set Z, determine whether Z is the smallest possible adjustment set.

Z is the minimal adjustment set if no element of Z can be removed without breaking the constructive back-door criterion.

Reference: Separators and adjustment sets in causal graphs: Complete criteria and an algorithmic framework, Zander et al., 2019, Corollary 5, p.19)

Parameters:

treatments – List of treatment variables.
outcomes – List of outcome variables.
adjustment_set – Set of adjustment variables.

Returns:

True or False depending on whether the adjustment set is minimal.

constructive_backdoor_criterion(proper_backdoor_graph: CausalDAG, treatments: list[str], outcomes: list[str], covariates: list[str]) → bool

A variation of Pearl’s back-door criterion applied to a proper backdoor graph which enables more efficient computation of minimal adjustment sets for the effect of a set of treatments on a set of outcomes.

The constructive back-door criterion is satisfied for a causal DAG G, a set of treatments X, a set of outcomes Y, and a set of covariates Z, if:

Z is not a descendent of any variable on a proper causal path between X and Y.
Z d-separates X and Y in the proper back-door graph relative to X and Y.

Reference: (Separators and adjustment sets in causal graphs: Complete criteria and an algorithmic framework, Zander et al., 2019, Definition 4, p.16)

Parameters:

proper_backdoor_graph – A proper back-door graph relative to the specified treatments and outcomes.
treatments – A list of treatment variables that appear in the proper back-door graph.
outcomes – A list of outcome variables that appear in the proper back-door graph.
covariates – A list of variables that appear in the proper back-door graph that we will check against the constructive back-door criterion.

Returns:

True or False, depending on whether the set of covariates satisfies the constructive back-door criterion.

proper_causal_pathway(treatments: list[str], outcomes: list[str]) → list[str]

Given a list of treatments and outcomes, compute the proper causal pathways between them.

PCP(X, Y) = {DeX^(X) - X} intersect AnX_(Y)}, where:

DeX^(X) refers to the descendents of X in the graph obtained by deleting all edges into X.
AnX_(Y) refers to the ancestors of Y in the graph obtained by deleting all edges leaving X.

Parameters:

treatments – A list of treatment variables in the causal DAG.
outcomes – A list of outcomes in the causal DAG.

Returns:

Return a list of the variables on the proper causal pathway between treatments and outcomes.

get_backdoor_graph(treatments: list[str]) → CausalDAG

A back-door graph is a graph for the list of treatments is a Causal DAG in which all edges leaving the treatment nodes are deleted.

Parameters:: treatments – The set of treatments whose outgoing edges will be deleted.
Returns:: A back-door graph corresponding to the given causal DAG and set of treatments.

identification(base_test_case: causal_testing.testing.base_test_case.BaseTestCase, avoid_variables: set[causal_testing.specification.variable.Variable] = None)

Identify and return the minimum adjustment set

Parameters:

base_test_case – A base test case instance containing the outcome_variable and the treatment_variable required for identification.
avoid_variables – Variables not to be adjusted for (e.g. hidden variables).

Returns:

The smallest set of variables which can be adjusted for to obtain a causal estimate as opposed to a purely associational estimate.

to_dot_string() → str

Return a string of the DOT representation of the causal DAG.

Returns:: DOT string of the DAG.

__str__()

Returns a short summary of the graph.

Returns

infostring: Graph information including the graph name (if any), graph type, and the number of nodes and edges.

Examples

>>> G = nx.Graph(name="foo")
>>> str(G)
"Graph named 'foo' with 0 nodes and 0 edges"

>>> G = nx.path_graph(3)
>>> str(G)
'Graph with 3 nodes and 2 edges'

causal_testing.specification.causal_dag

Module Contents

Classes

Functions

Attributes

Returns

Examples

`causal_testing.specification.causal_dag`