[DOC] Add some documentation describing Networkx vs PywhyGraphs (#66)

* Add additional statements on networkx
* Add reference guide for algorithms

---------
Signed-off-by: Adam Li <[email protected]>

Author: adam2392

docs/api.rst

@@ -32,8 +32,8 @@ graphs encountered in the literature.
    IPAG
    PsiPAG
 
-Algorithms for Markov Equivalence Classes
-=========================================
+:mod:`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

docs/conf.py

@@ -82,7 +82,7 @@ def setup(app):
     "inherited-members": False,
     "private-members": False,
 }
-autodoc_inherit_docstrings = False
+autodoc_inherit_docstrings = True
 # autodoc_typehints = "signature"
 
 # -- numpydoc
@@ -357,6 +357,8 @@ def setup(app):
 ]
 
 
+doctest_global_setup = "import networkx as nx"
+
 # -- Other extension configuration -------------------------------------------
 
 linkcheck_request_headers = dict(

docs/index.rst

@@ -3,8 +3,8 @@
 
 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's`` ``MixedEdgeGraph`` such that we maintain all the well-tested and efficient
-algorithms and data structures of ``networkx``. 
+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 <https://github.com/mne-tools/mne-icalabel/blob/main/CONTRIBUTING.md>`_.
@@ -23,6 +23,55 @@ eventually converge to a stable API that maintains the common software engineeri
 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 :class:`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, :class:`networkx.DiGraph` and :class:`networkx.Graph`
+that map to a user-specified edge type. For example,
+
+.. code-block:: Python
+
+   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 :mod:`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
 --------
 

docs/reference/algorithms/index.rst

@@ -0,0 +1,65 @@
+.. _algorithms:
+
+********************************
+Causal Graph Algorithms in PyWhy
+********************************
+
+.. automodule:: pywhy_graphs.algorithms
+    :no-members:
+    :no-inherited-members:
+
+
+Pywhy-graphs provides data structures and methods for storing causal graphs, which
+are documented in :ref:`classes`. We also provide a submodule for common graph
+algorithms in the form of functions that take a mixed-edge graph as input.
+
+Core Algorithms
+---------------
+.. currentmodule:: pywhy_graphs.algorithms
+    
+.. autosummary::
+   :toctree: ../../generated/
+
+   is_valid_mec_graph
+   possible_ancestors
+   possible_descendants
+   discriminating_path
+   is_definite_noncollider
+
+.. currentmodule:: pywhy_graphs.networkx
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   bidirected_to_unobserved_confounder
+   m_separated
+   is_minimal_m_separator
+   minimal_m_separator
+   
+
+Algorithms for Markov Equivalence Classes
+-----------------------------------------
+.. currentmodule:: pywhy_graphs.algorithms
+.. autosummary::
+   :toctree: ../../generated/
+
+   pds
+   pds_path
+   uncovered_pd_path
+
+Algorithms for Time-Series Graphs
+---------------------------------
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   pds_t
+   pds_t_path
+
+Algorithms for handling acyclicity
+----------------------------------
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   acyclification

docs/user_guide.rst

@@ -12,10 +12,10 @@ User Guide
 
 .. toctree::
    :numbered:
-   :maxdepth: 3
+   :maxdepth: 2
 
-   
    reference/classes/index
+   reference/algorithms/index
    reference/simulation/index
    reference/export/index
    glossary

examples/intro/intro_causal_graphs.py

@@ -172,7 +172,10 @@ def clone(self):
 # Say we add a bidirected edge between 'z' and 'x', then they are no longer
 # d-separated.
 admg.add_edge("z", "x", admg.bidirected_edge_name)
-print(f"'z' is d-separated from 'x': {pywhy_nx.m_separated(admg, {'z'}, {'x'}, set())}")
+print(
+    f"'z' is d-separated from 'x' after adding a bidirected edge z<->x: "
+    f"{pywhy_nx.m_separated(admg, {'z'}, {'x'}, set())}"
+)
 
 # Markov Equivalence Classes
 # --------------------------
@@ -228,7 +231,7 @@ def clone(self):
 #          an ancestral relationship.
 #
 # Typically, PAGs are learnt using some variant of the FCI algorithm :footcite:`Spirtes1993` and
-# :footcite`Zhang2008`.
+# :footcite:`Zhang2008`.
 pag = PAG()
 
 # let's assume all the undirected edges are formed from the earlier DAG

pywhy_graphs/__init__.py

@@ -15,6 +15,7 @@
 from .algorithms import *  # noqa: F403
 from .config import sys_info
 
+from . import algorithms
 from . import export
 from . import classes
 from . import networkx

pywhy_graphs/classes/admg.py

@@ -39,6 +39,7 @@ class ADMG(pywhy_nx.MixedEdgeGraph, AncestralMixin):
     --------
     networkx.DiGraph
     networkx.Graph
+    pywhy_graphs.networkx.MixedEdgeGraph
 
     Notes
     -----

pywhy_graphs/classes/cpdag.py

@@ -36,6 +36,7 @@ class CPDAG(pywhy_nx.MixedEdgeGraph, AncestralMixin, ConservativeMixin):
     networkx.DiGraph
     networkx.Graph
     pywhy_graphs.ADMG
+    pywhy_graphs.networkx.MixedEdgeGraph
 
     Notes
     -----

pywhy_graphs/classes/intervention.py

@@ -15,7 +15,7 @@ class InterventionMixin:
     nodes: NodeView
 
     @abstractmethod
-    def add_edge(self, u, v, edge_type: Optional[str]):
+    def add_edge(self, u_of_edge, v_of_edge, edge_type="all", **attr):
         pass
 
     @abstractmethod
@@ -82,6 +82,15 @@ def add_f_nodes_from(self, intervention_sets: List[Set[Node]]):
         for intervention_set in intervention_sets:
             self.add_f_node(intervention_set)
 
+    def set_f_node(self, f_node, targets: Optional[Set] = None):
+        if f_node not in self.nodes:
+            raise RuntimeError(f"{f_node} is not a node in the existing graph.")
+
+        if targets is not None and not all(target in self.nodes for target in targets):
+            raise RuntimeError(f"Not all targets {targets} are in the existing graph.")
+
+        self.graph["F-nodes"][f_node] = targets
+
     @property
     def f_nodes(self) -> Set[Node]:
         """Return set of F-nodes."""
@@ -139,6 +148,7 @@ class AugmentedGraph(ADMG, InterventionMixin):
     networkx.DiGraph
     networkx.Graph
     ADMG
+    pywhy_graphs.networkx.MixedEdgeGraph
 
     Notes
     -----
@@ -190,20 +200,6 @@ def remove_node(self, n):
             del self.graph["F-nodes"][n]
         return super().remove_node(n)
 
-    def add_edge(self, u_of_edge, v_of_edge, edge_type="all", **attr):
-        if u_of_edge in self.f_nodes or v_of_edge in self.f_nodes:
-            raise RuntimeError("Adding edges to F-nodes is not allowed.")
-        return super().add_edge(u_of_edge, v_of_edge, edge_type, **attr)
-
-    def remove_edge(self, u, v, edge_type="all"):
-        if u in self.f_nodes or v in self.f_nodes:
-            raise RuntimeError(
-                "Removing edges from F-nodes is not allowed. "
-                "Please just call `remove_node` to remove the F-node "
-                "and its corresponding edges"
-            )
-        return super().remove_edge(u, v, edge_type)
-
 
 class IPAG(PAG, InterventionMixin):
     """A I-PAG Markov equivalence class of causal graphs.
@@ -305,20 +301,6 @@ def remove_node(self, n):
             del self.graph["F-nodes"][n]
         return super().remove_node(n)
 
-    def add_edge(self, u_of_edge, v_of_edge, edge_type="all", **attr):
-        if u_of_edge in self.f_nodes or v_of_edge in self.f_nodes:
-            raise RuntimeError("Adding edges to F-nodes is not allowed.")
-        return super().add_edge(u_of_edge, v_of_edge, edge_type, **attr)
-
-    def remove_edge(self, u, v, edge_type="all"):
-        if u in self.f_nodes or v in self.f_nodes:
-            raise RuntimeError(
-                "Removing edges from F-nodes is not allowed. "
-                "Please just call `remove_node` to remove the F-node "
-                "and its corresponding edges"
-            )
-        return super().remove_edge(u, v, edge_type)
-
 
 class PsiPAG(PAG, InterventionMixin):
     """A Psi-PAG Markov equivalence class of causal graphs.
@@ -416,17 +398,3 @@ def remove_node(self, n):
         if n in self.f_nodes:
             del self.graph["F-nodes"][n]
         return super().remove_node(n)
-
-    def add_edge(self, u_of_edge, v_of_edge, edge_type="all", **attr):
-        if u_of_edge in self.f_nodes or v_of_edge in self.f_nodes:
-            raise RuntimeError("Adding edges to F-nodes is not allowed.")
-        return super().add_edge(u_of_edge, v_of_edge, edge_type, **attr)
-
-    def remove_edge(self, u, v, edge_type="all"):
-        if u in self.f_nodes or v in self.f_nodes:
-            raise RuntimeError(
-                "Removing edges from F-nodes is not allowed. "
-                "Please just call `remove_node` to remove the F-node "
-                "and its corresponding edges"
-            )
-        return super().remove_edge(u, v, edge_type)