API#

pywhy_graphs:

This is the application programming interface (API) reference for classes (CamelCase names) and functions (underscore_case names) of pywhy-graphs, grouped thematically by analysis stage.

pywhy_graphs.classes: Causal graph classes#

These are the causal classes for Structural Causal Models (SCMs), or various causal graphs encountered in the literature.

ADMG([incoming_directed_edges, ...])

Acyclic directed mixed graph (ADMG).

CPDAG([incoming_directed_edges, ...])

Completed partially directed acyclic graphs (CPDAG).

PAG([incoming_directed_edges, ...])

Partial ancestral graph (PAG).

AugmentedGraph([incoming_directed_edges, ...])

An augmented causal diagram.

AugmentedPAG([incoming_directed_edges, ...])

An augmented PAG.

pywhy_graphs.algorithms: Algorithms for Mixed-Edge Graphs#

Traditional graph algorithms operate over graphs with only one type of edge. Equivalence class graphs in causality generally consist of more than one type of edge. These algorithms are common algorithms used in a variety of different causal graph operations.

dag_to_mag(G[, L, S])

Converts a DAG to a valid MAG.

valid_mag(G[, L, S])

Checks if the provided graph is a valid maximal ancestral graph (MAG).

has_adc(G)

Check if a graph has an almost directed cycle (adc).

inducing_path(G, node_x, node_y[, L, S])

Checks if an inducing path exists between two nodes.

is_valid_mec_graph(G[, on_error])

Check G is a valid PAG.

possible_ancestors(G, source)

Possible ancestors of a source node.

possible_descendants(G, source)

Possible descendants of a source node.

discriminating_path(graph, u, a, c[, ...])

Find the discriminating path for <..., a, u, c>.

pds(graph, node_x[, node_y, max_path_length])

Find all PDS sets between node_x and node_y.

pds_path(graph, node_x, node_y[, ...])

Compute the possibly-d-separating set path.

pds_t(graph, node_x, node_y[, max_path_length])

Compute the possibly-d-separating set over time.

pds_t_path(graph, node_x, node_y[, ...])

Compute the possibly-d-separating path set over time.

uncovered_pd_path(graph, u, c[, ...])

Compute uncovered potentially directed (pd) paths from u to c.

acyclification(G[, directed_edge_type, ...])

Acyclify a cyclic graph.

is_definite_noncollider(G, node1, node2, node3)

Check if <node1, node2, node3> path forms a definite non-collider.

find_connected_pairs(tuples, max_number)

Find connected pairs of domain tuples.

add_all_snode_combinations(G, n_domains[, ...])

Add all possible S-nodes to the graph given number of domains.

compute_invariant_domains_per_node(G, node)

Compute the invariant domains for a specific node.

is_semi_directed_path(G, nodes)

Returns True if and only if nodes form a semi-directed path in G.

all_semi_directed_paths(G, source, target[, ...])

Generate all semi-directed paths from source to target in G.

pywhy_graphs.algorithms: Algorithms for dealing with CPDAGs#

With Markov equivalence classes of DAGs in a Markovian SCM setting, we obtain a potentially directed acyclic graph (PDAG), which may be completed (CPDAG). We may want to generate a consistent DAG extension (i.e. Markov equivalent) of a CPDAG then we may use some of the algorithms described here. Or perhaps one may want to convert a DAG to its corresponding CPDAG.

pdag_to_dag(G)

Compute consistent extension of given PDAG resulting in a DAG.

dag_to_cpdag(G)

Convert a DAG to a CPDAG.

pdag_to_cpdag(G)

Convert a PDAG to a CPDAG.

order_edges(G)

Find total ordering of the edges of DAG G.

label_edges(G)

Label compelled and reversible edges of a DAG G.

Conversions between other package’s causal graphs#

Other packages, such as causal-learn, implement various causal inference procedures, but encode a causal graph object differently. This submodule converts between those causal graph data structures and corresponding causal graphs in pywhy-graphs.

graph_to_clearn(G)

clearn_to_graph(arr, arr_idx, graph_type)

Convert causal-learn array to a graph object.

graph_to_numpy(causal_graph)

Convert causal graph to a numpy adjacency array.

numpy_to_graph(arr, arr_idx, graph_type)

Convert an enumerated numpy array into causal graph.

graph_to_tetrad(G, filename)

Convert a pywhy causal graph to a tetrad text file.

tetrad_to_graph(filename, graph_type)

Convert a tetrad stored graph from a text file to causal graph in pywhy.

graph_to_pcalg(causal_graph)

Convert causal graph to a pcalg type adjacency array.

pcalg_to_graph(arr, arr_idx, amat_type)

Convert an array from R's pcalg into causal graph.

NetworkX Experimental Functionality#

Currently, NetworkX does not support mixed-edge graphs, which are crucial for representing causality with latent confounders and selection bias. The following represent functionality that we intend to PR eventually into networkx. They are included in pywhy-graphs as a temporary bridge. We welcome feedback.

MixedEdgeGraph([graphs, edge_types])

Base class for mixed-edge graphs.

bidirected_to_unobserved_confounder(G[, ...])

Convert all bidirected edges to unobserved confounders.

m_separated(G, x, y, z[, ...])

Check m-separation among 'x' and 'y' given 'z' in mixed-edge causal graph G, which may contain directed, bidirected, and undirected edges.

is_minimal_m_separator(G, x, y, z[, i, r, ...])

Check if a set 'z' is a i-minimal m-separator between 'x' and 'y'.

minimal_m_separator(G, x, y[, i, r, ...])

Find a i-minimal m-separating set 'z' between 'x' and 'y' in mixed-edge causal graph G.

pywhy_graphs.classes.timeseries: Timeseries#

The following are useful functions that operate specifically on time-series graphs.

complete_ts_graph(variables, max_lag[, ...])

Create a complete time-series graph.

empty_ts_graph(variables, max_lag[, ...])

get_summary_graph(G[, include_self_loops])

Compute the summary graph from a time-series graph.

has_homologous_edges(G, u_of_edge, v_of_edge)

Check whether the graph contains all homologous edges for (u, v).

nodes_in_time_order(G)

Return nodes from G in time order starting from max-lag to t=0.

We also have classes for representing causal time-series graphs.

Pywhy-graphs implements a networkx-like graph class for representing time-series. Stationary causal timeseries graphs may be useful in various applications.

TimeSeriesGraph([incoming_graph_data, max_lag])

A class to imbue undirected graph with time-series structure.

TimeSeriesDiGraph([incoming_graph_data, max_lag])

A class to imbue directed graph with time-series structure.

TimeSeriesMixedEdgeGraph([graphs, ...])

A class to imbue mixed-edge graph with time-series structure.

For stationary time-series, we explicitly represent them with different classes.

StationaryTimeSeriesCPDAG([...])

Completed partially directed acyclic graphs (CPDAG).

StationaryTimeSeriesDiGraph([...])

Stationary time-series directed graph.

StationaryTimeSeriesGraph([...])

Stationary time-series graph without directionality on edges.

StationaryTimeSeriesMixedEdgeGraph([graphs, ...])

A mixed-edge causal graph for stationary time-series.

StationaryTimeSeriesPAG([...])

pywhy_graphs.simulate: Causal graphical model simulations#

Pywhy-graphs implements a various functions for assisting in simulating a SCM and their data starting from the causal graph.

simulate.simulate_linear_var_process([...])

Simulate a linear VAR process of a "stationary" causal graph.

simulate.simulate_data_from_var(var_arr[, ...])

Simulate data from an already set VAR process.

simulate.simulate_var_process_from_summary_graph(G)

Simulate a VAR(max_lag) process starting from a summary graph.

Converting graphs to functional models#

An experimental submodule for converting graphs to functional models, such as linear structural equation Gaussian models (SEMs).

make_graph_linear_gaussian(G[, ...])

Convert an existing DAG to a linear Gaussian graphical model.

apply_linear_soft_intervention(G, targets[, ...])

Applies a soft intervention to a linear Gaussian graph.

set_node_attributes_with_G(G1, G2, node)

Set node attributes in G1 using G2.

make_graph_multidomain(G[, n_domains, ...])

Convert an existing linear Gaussian DAG to a multi-domain selection diagram model.

Visualization of causal graphs#

Visualization of causal graphs is different compared to networkx because causal graphs can consist of mixed-edges. We implement an API that wraps graphviz and pygraphviz to perform modular visualization of nodes and edges.

draw(G[, direction, pos, name, shape])

Visualize the graph.

timeseries_layout(G[, variable_order, ...])

Position nodes in a time-series layout from left to right with lags as columns.

Utilities for debugging#

sys_info([fid, show_paths, dependencies])

Print the system information for debugging.

Simulation#