pywhy-graphs#
pywhy-graphs is a Python package for representing causal graphs. For example, Acyclic
Directed Mixed Graphs (ADMG), also known as causal DAGs and Partial Ancestral Graphs (PAGs).
We build on top of networkx supporting graphs with mixed-edges using a composition
of networkx graph classes.
We encourage you to use the package for your causal inference research and also build on top with relevant Pull Requests. Also, see our contributing guide.
Please refer to our User Guide for details on all the tools that we
provide. You can also find an exhaustive list of the public API in the
API. You can also look at our numerous examples
that illustrate the use of pywhy_graphs in many different contexts.
API Stability#
Currently, we are in very early stages of development. Most likely certain aspects of the causal graphs API will change, but we will do our best to maintain some consistency. Our goal is to eventually converge to a stable API that maintains the common software engineering release cycle traits (e.g. deprecation cycles and API stability within major versions). Certain functionality will be marked as “alpha” indicating that their might be drastic changes over different releases. One should use alpha functionality with caution.
How do we compare with NetworkX?#
We fashioned pywhy-graphs API based on NetworkX because NetworkX’s API is stable, robust and has an existing community around it. Therefore, we expect all NetworkX users to have a relatively low learning curve when transitioning to pywhy-graphs. However, NetworkX does not currently support graphs with mixed-edges, so that is where the fundamental difference between the two APIs lie.
In all the “NetworkX-like” functions related to edges, such as add_edge, has_edge,
number_of_edges, etc. all have an additional keyword parameter, edge_type. We also
add a handful of new functions to the basic pywhy_graphs.networkx.MixedEdgeGraph class,
which is summarized in the table below. The edge
type is specified by this parameter and internally, all pywhy-graphs graph classes are a
composition of different networkx base graphs, networkx.DiGraph and networkx.Graph
that map to a user-specified edge type. For example,
import pywhy_graphs.networkx as pywhy_nx
import networkx as nx
# a mixed-edge graph is a composition of networkx graphs
# so we can create a representation of a graph with directed and
# bidirected edges using the MixedEdgeGraph class
G = pywhy_nx.MixedEdgeGraph()
G.add_edge_type(nx.DiGraph(), edge_type='directed')
G.add_edge_type(nx.Graph(), edge_type='bidirected')
assert 'directed' in G.edge_types
assert 'bidirected' in G.edge_types
# when we use networkx-like API, we usually will have to specify the edge type
G.add_edge(0, 1, edge_type='directed')
Because of this feature, not all NetworkX algorithms will work with pywhy-graphs because
they implicitly assume a single edge type. We implement common graph algorithms for
mixed-edge graphs that are focused on causal inference in the pywhy_graphs.algorithms
submodule. This is a similar design to NetworkX, where all graph classes have a relatively
lightweight API designed solely for interfacing with nodes and edges, while more complicated
algorithms are implemented as functions that take in a mixed edge graph.
New API |
Description |
|---|---|
add_edge_type |
Adds a new edge type to the graph |
get_graphs |
Get a dictionary of edge types and their networkx graphs |
Contents#
Getting started:
Team#
pywhy-graphs is developed and maintained by open-source contributors like yourself, and is always interested in getting contributions from YOU! Our Github Issues page contains many issues that need to be solved to improve the overall package. If you are interested in contributing, please do not hesitate to reach out to us on Github!
See our contributing document for details on our approach to Issues and Pull Requests.
To learn more about who specifically contributed to this codebase, see our contributors page.