Add initial working multigraph edge validator plus tests (#107)

* Add initial working model of multigraph edge validator plus tests * Add example test where multigraph ANY fails * Add temporary documentation while we improve support * Add basic multigraph tests * Working multigraph "ANY" support * Add failure check in unit tests * Update formatting in grandiso executor * Remove dotmotif.dotmotif deprecated API * Remove dotmotif.dotmotif from tests * Update documentation * Update multigraph documentation * fix dangling dotmotif.dotmotif reference
aplbrain · Sep 30, 2021 · 8e8ddb7 · 8e8ddb7
1 parent c60ba4e
commit 8e8ddb7
Show file tree

Hide file tree

Showing 26 changed files with 468 additions and 205 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+-   **0.10.0**
+    -   Features:
+        -   `GrandIsoExecutor` and `NetworkXExecutor`: Support for `networkx.MultiGraph` and `networkx.MultiDiGraph` search through the use of the `multigraph_edge_match` executor argument (#107).
+    -   Deprecations:
+        -   Removed `dotmotif.dotmotif` method-style API (#107).
 -   **0.9.2** (May 28 2021)
     -   Features:
         -   `GrandIsoExecutor`: Utilizes the node attribute matching flow available in grandiso≥2.0.0 to reduce complexity of attribute-heavy searches (#104)

diff --git a/docs/reference/dotmotif/dotmotif.md b/docs/reference/dotmotif/dotmotif.md
@@ -23,7 +23,7 @@ Create a new dotmotif object.
 > - **parser** (`dotmotif.parsers.Parser`: `DEFAULT_MOTIF_PARSER`): The parser
         to use to parse the document. Defaults to the v2 parser.
 > - **exclude_automorphisms** (`bool`: `False`): Whether to exclude automorphism
-        variants of the motif when rturning results.
+        variants of the motif when returning results.
 > - **validators** (`List[Validator]`: `None`): A list of dotmotif.Validators to use
         when verifying the motif for correctness and executability.
 

diff --git a/docs/reference/dotmotif/utils.py.md b/docs/reference/dotmotif/utils.py.md
@@ -4,7 +4,7 @@
 Draw a dotmotif motif object.
 
 ### Arguments
-> - **dm** (`None`: `None`): dotmotif.DotMotif
+> - **dm** (`None`: `None`): dotmotif.Motif
 > - **negative_edge_color** (`str`: `r`): Color used to represent negative edges
 > - **pos** (`dict`: `None`): The position to use. If unset, uses nx.spring_layout
 

diff --git a/docs/reference/executors/GrandIsoExecutor.py.md b/docs/reference/executors/GrandIsoExecutor.py.md
@@ -1,8 +1,23 @@
+## *Class* `GrandIsoExecutor(NetworkXExecutor)`
+
+
+A DotMotif executor that uses grandiso for subgraph monomorphism.
+
+This executor is dramatically fast than the NetworkX search, and is still a pure-Python implementation.
+
+[GrandIso](https://github.com/aplbrain/grandiso-networkx)
+
+
+
 ## *Function* `find(self, motif, limit: int = None)`
 
 
 Find a motif in a larger graph.
 
 ### Arguments
-    motif (dotmotif.dotmotif)
+    motif (dotmotif.Motif)
+> - **int** (`None`: `None`): None)
+
+### Returns
+    List[dict]
 
diff --git a/docs/reference/executors/Neo4jExecutor.py.md b/docs/reference/executors/Neo4jExecutor.py.md
@@ -72,21 +72,21 @@ You should usually ignore this, and use .find() instead.
 
 
 
-## *Function* `count(self, motif: "dotmotif", limit=None) -> int`
+## *Function* `count(self, motif: "dotmotif.Motif", limit=None) -> int`
 
 
 Count a motif in a larger graph.
 
 ### Arguments
-    motif (dotmotif.dotmotif)
+    motif (dotmotif.Motif)
 
 
 
-## *Function* `find(self, motif: "dotmotif", limit=None, cursor=True)`
+## *Function* `find(self, motif: "dotmotif.Motif", limit=None, cursor=True)`
 
 
 Find a motif in a larger graph.
 
 ### Arguments
-    motif (dotmotif.dotmotif)
+    motif (dotmotif.Motif)
 
diff --git a/docs/reference/executors/NetworkXExecutor.py.md b/docs/reference/executors/NetworkXExecutor.py.md
@@ -4,6 +4,12 @@
 Check if a single edge satisfies the constraints.
 
 
+## *Function* `_edge_satisfies_many_constraints_for_muligraph_any_edges(edge_attributes: dict, constraints: dict) -> List[Tuple[str, str, str]]`
+
+
+Returns a subset of constraints that this edge matches, in the form (key, op, val).
+
+
 ## *Function* `_node_satisfies_constraints(node_attributes: dict, constraints: dict) -> bool`
 
 
@@ -32,19 +38,19 @@ Create a new NetworkXExecutor.
 
 
 
-## *Function* `count(self, motif: "dotmotif", limit: int = None)`
+## *Function* `count(self, motif: "dotmotif.Motif", limit: int = None)`
 
 
 Count the occurrences of a motif in a graph.
 
 See NetworkXExecutor#find for more documentation.
 
 
-## *Function* `find(self, motif: "dotmotif", limit: int = None)`
+## *Function* `find(self, motif: "dotmotif.Motif", limit: int = None)`
 
 
 Find a motif in a larger graph.
 
 ### Arguments
-    motif (dotmotif.dotmotif)
+    motif (dotmotif.Motif)
 
diff --git a/docs/reference/executors/NeuPrintExecutor.py.md b/docs/reference/executors/NeuPrintExecutor.py.md
@@ -42,26 +42,26 @@ You should usually ignore this, and use .find() instead.
 
 
 
-## *Function* `count(self, motif: dotmotif, limit=None) -> int`
+## *Function* `count(self, motif: Motif, limit=None) -> int`
 
 
 Count a motif in a larger graph.
 
 ### Arguments
-> - **motif** (`dotmotif.dotmotif`: `None`): The motif to search for
+> - **motif** (`dotmotif.Motif`: `None`): The motif to search for
 
 ### Returns
 > - **int** (`None`: `None`): The count of this motif in the host graph
 
 
 
-## *Function* `find(self, motif: dotmotif, limit=None) -> pd.DataFrame`
+## *Function* `find(self, motif: Motif, limit=None) -> pd.DataFrame`
 
 
 Find a motif in a larger graph.
 
 ### Arguments
-> - **motif** (`dotmotif.dotmotif`: `None`): The motif to search for
+> - **motif** (`dotmotif.Motif`: `None`): The motif to search for
 
 ### Returns
 > - **pd.DataFrame** (`None`: `None`): The results of the search

diff --git a/docs/reference/ingest/ingest.md b/docs/reference/ingest/ingest.md
@@ -5,10 +5,10 @@ An abstract base class for import to the NetworkX format.
 
 
 
-## *Class* `CSVEdgelistConverter(NetworkXConverter)`
+## *Class* `EdgelistConverter(NetworkXConverter)`
 
 
-A converter that takes an arbitrary CSV file on disk and converts it to a graph.
+Convert an edgelist dataframe or CSV to a graph.
 
 
 

diff --git a/docs/reference/tests/tests.md b/docs/reference/tests/tests.md
diff --git a/dotmotif/__init__.py b/dotmotif/__init__.py
@@ -119,7 +119,7 @@ def from_motif(self, cmd: str):
 
         return self
 
-    def from_nx(self, graph: nx.DiGraph) -> "dotmotif":
+    def from_nx(self, graph: nx.DiGraph) -> "Motif":
         """
         Ingest directly from a graph.
 
@@ -197,7 +197,7 @@ def save(self, fname: Union[str, IO[bytes]]) -> Union[str, IO[bytes]]:
         return fname
 
     @staticmethod
-    def load(fname: Union[str, IO[bytes]]) -> "dotmotif":
+    def load(fname: Union[str, IO[bytes]]) -> "Motif":
         """
         Load the motif from a file on disk.
 
@@ -215,6 +215,3 @@ def load(fname: Union[str, IO[bytes]]) -> "dotmotif":
         result = pickle.load(f)
         f.close()
         return result
-
-
-dotmotif = Motif
diff --git a/dotmotif/executors/GrandIsoExecutor.py b/dotmotif/executors/GrandIsoExecutor.py
@@ -83,10 +83,19 @@ def _node_attr_match_fn(
             is_node_attr_match=_node_attr_match_fn,
         )
 
+        _edge_constraint_validator = (
+            self._validate_edge_constraints if not self._host_is_multigraph
+            else (
+                self._validate_multigraph_all_edge_constraints
+                if self._multigraph_edge_match == "all"
+                else self._validate_multigraph_any_edge_constraints
+            )
+        )
+
         results = []
         for r in graph_matches:
             if _doesnt_have_any_of_motifs_negative_edges(r) and (
-                self._validate_edge_constraints(
+                _edge_constraint_validator(
                     r, self.graph, motif.list_edge_constraints()
                 )
                 # and self._validate_node_constraints(

diff --git a/dotmotif/executors/Neo4jExecutor.py b/dotmotif/executors/Neo4jExecutor.py
@@ -1,5 +1,5 @@
 """
-Copyright 2020 The Johns Hopkins University Applied Physics Laboratory.
+Copyright 2021 The Johns Hopkins University Applied Physics Laboratory.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -280,12 +280,12 @@ def run(self, cypher: str, cursor=True):
             return self.G.run(cypher).to_table()
         return self.G.run(cypher)
 
-    def count(self, motif: "dotmotif", limit=None) -> int:
+    def count(self, motif: "dotmotif.Motif", limit=None) -> int:
         """
         Count a motif in a larger graph.
 
         Arguments:
-            motif (dotmotif.dotmotif)
+            motif (dotmotif.Motif)
 
         """
         qry = self.motif_to_cypher(
@@ -295,12 +295,12 @@ def count(self, motif: "dotmotif", limit=None) -> int:
             qry += f" LIMIT {limit}"
         return int(self.G.run(qry).to_ndarray())
 
-    def find(self, motif: "dotmotif", limit=None, cursor=True):
+    def find(self, motif: "dotmotif.Motif", limit=None, cursor=True):
         """
         Find a motif in a larger graph.
 
         Arguments:
-            motif (dotmotif.dotmotif)
+            motif (dotmotif.Motif)
 
         """
         qry = self.motif_to_cypher(motif, static_entity_labels=self._entity_labels)
@@ -312,7 +312,7 @@ def find(self, motif: "dotmotif", limit=None, cursor=True):
 
     @staticmethod
     def motif_to_cypher(
-        motif: "dotmotif", count_only: bool = False, static_entity_labels: dict = None,
+        motif: "dotmotif.Motif", count_only: bool = False, static_entity_labels: dict = None,
     ) -> str:
         """
         Output a query suitable for Cypher-compatible engines (e.g. Neo4j).