:py:mod:`causal_testing.specification.causal_dag` ================================================= .. py:module:: causal_testing.specification.causal_dag .. autoapi-nested-parse:: This module contains the CausalDAG class, as well as the functions list_all_min_sep and close_seperator Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: causal_testing.specification.causal_dag.CausalDAG Functions ~~~~~~~~~ .. autoapisummary:: causal_testing.specification.causal_dag.close_separator causal_testing.specification.causal_dag.list_all_min_sep Attributes ~~~~~~~~~~ .. autoapisummary:: causal_testing.specification.causal_dag.Node causal_testing.specification.causal_dag.logger .. py:data:: Node .. py:data:: logger .. py:function:: 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). :param graph: An undirected graph. :param treatment_node: A label for the treatment node (parent of treatments in undirected graph). :param outcome_node: A label for the outcome node (parent of outcomes in undirected graph). :param treatment_node_set: The set of variables containing the treatment node ({treatment_node}). :return: A treatment_node-outcome_node separator whose vertices are adjacent to those in treatments. .. py:function:: 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). :param graph: An undirected graph. :param treatment_node: The node corresponding to the treatment variable we wish to separate from the output. :param outcome_node: The node corresponding to the outcome variable we wish to separate from the input. :param treatment_node_set: Set of treatment nodes. :param outcome_node_set: Set of outcome nodes. :return: A generator of minimal-sized sets of variables which separate treatment and outcome in the undirected graph. .. py:class:: CausalDAG(file_path: str = None, ignore_cycles: bool = False, **attr) Bases: :py:obj:`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. .. py:method:: check_iv_assumptions(treatment, outcome, instrument) -> bool Checks the three instrumental variable assumptions, raising a ValueError if any are violated. :return: Boolean True if the three IV assumptions hold. .. py:method:: 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. :param u_of_edge: From node :param v_of_edge: To node :param attr: Attributes .. py:method:: cycle_nodes() -> list Get the nodes involved in any cycles. :return: A list containing all nodes involved in a cycle. .. py:method:: is_acyclic() -> bool Checks if the graph is acyclic. :return: True if acyclic, False otherwise. .. py:method:: 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) :param treatments: A list of treatment variables. :param outcomes: A list of outcomes. :return: A CausalDAG corresponding to the proper back-door graph. .. py:method:: 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]). :param treatments: A list of treatment variables to include in the ancestral graph (and their ancestors). :param outcomes: A list of outcome variables to include in the ancestral graph (and their ancestors). :return: An ancestral graph relative to the set of variables X union Y. .. py:method:: 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. :param treatments: List of treatment names. :param outcomes: List of outcome names. :return: The indirect graph with edges pointing from X to Y removed. .. py:method:: 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. :param treatments: List of treatment names. :param outcomes: List of outcome names. :param nodes_to_ignore: List of nodes to exclude from tests if they appear as treatments, outcomes, or in the adjustment set. :return: A list of possible adjustment sets. .. py:method:: 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): 1. Transform G to a proper back-door graph G_pbd (remove the first edge from X on all proper causal paths). 2. Transform G_pbd to the ancestor moral graph (G_pbd[An(X union Y)])^m. 3. Apply Takata's algorithm to output all minimal X-Y separators in the graph. :param treatments: A list of strings representing treatments. :param outcomes: A list of strings representing outcomes. :return: A list of strings representing the minimal adjustment set. .. py:method:: 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) :param treatments: List of treatment variables. :param outcomes: List of outcome variables. :param adjustment_set: Set of adjustment variables. :return: True or False depending on whether the adjustment set is minimal. .. py:method:: 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: (1) Z is not a descendent of any variable on a proper causal path between X and Y. (2) 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) :param proper_backdoor_graph: A proper back-door graph relative to the specified treatments and outcomes. :param treatments: A list of treatment variables that appear in the proper back-door graph. :param outcomes: A list of outcome variables that appear in the proper back-door graph. :param covariates: A list of variables that appear in the proper back-door graph that we will check against the constructive back-door criterion. :return: True or False, depending on whether the set of covariates satisfies the constructive back-door criterion. .. py:method:: 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. :param treatments: A list of treatment variables in the causal DAG. :param outcomes: A list of outcomes in the causal DAG. :return: Return a list of the variables on the proper causal pathway between treatments and outcomes. .. py:method:: 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. :param treatments: The set of treatments whose outgoing edges will be deleted. :return: A back-door graph corresponding to the given causal DAG and set of treatments. .. py:method:: 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 :param base_test_case: A base test case instance containing the outcome_variable and the treatment_variable required for identification. :param avoid_variables: Variables not to be adjusted for (e.g. hidden variables). :return: The smallest set of variables which can be adjusted for to obtain a causal estimate as opposed to a purely associational estimate. .. py:method:: to_dot_string() -> str Return a string of the DOT representation of the causal DAG. :return: DOT string of the DAG. .. py:method:: __str__() Returns a short summary of the graph. Returns ------- info : string 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'