Merge pull request #397 from brs96/promote-gds-alpha-graph-construct

brs96 · web-flow · commit 5ec9f8383af9 · 2023-06-14T10:10:29.000+01:00
Promote gds.alpha.graph.construct and improve deprecation warnings and tests
diff --git a/changelog.md b/changelog.md
@@ -13,6 +13,7 @@
 	* `gds.graph.ogbl.load` for link property prediction datasets.
 * Added possibility to load NetworkX graphs via the new method `gds.graph.networkx.load`.
 * Added new sphinx API reference documentation for all procedures.
+* Promoted `gds.alpha.graph.construct` to `gds.graph.construct`.
 
 ## Bug fixes
 
diff --git a/doc/modules/ROOT/pages/common-datasets.adoc b/doc/modules/ROOT/pages/common-datasets.adoc
@@ -285,3 +285,5 @@ assert G.relationship_count() == 5_088_434
 assert len(G.relationship_types()) == 51 * 3
 assert G.relationship_properties()["drug-drug_polycystic_ovary_syndrome_TRAIN"] == ["classLabel"]
 ----
+
+include::ROOT:partial$/graph-construct-limitation.adoc[]
diff --git a/doc/modules/ROOT/pages/graph-object.adoc b/doc/modules/ROOT/pages/graph-object.adoc
@@ -72,18 +72,15 @@ In addition to those aforementioned there are five more methods that create grap
 * `gds.graph.project.cypher`
 * `gds.beta.graph.subgraph`
 * `gds.beta.graph.generate`
-* `gds.alpha.graph.sample.rwr`
+* `gds.graph.sample.rwr`
 * `gds.graph.sample.cnarw`
 
 Their Cypher signatures map to Python in much the same way as `gds.graph.project` above.
 
 
-[.alpha]
 [[construct]]
 == Constructing a graph from DataFrames
 
-include::ROOT:partial$/alpha-note.adoc[]
-
 Instead of projecting a graph from the Neo4j database it is also possible to construct new graphs using pandas `DataFrames` from the client.
 
 === Syntax
@@ -122,7 +119,7 @@ relationships = pandas.DataFrame(
     }
 )
 
-G = gds.alpha.graph.construct(
+G = gds.graph.construct(
     "my-graph",      # Graph name
     nodes,           # One or more dataframes containing node data
     relationships    # One or more dataframes containing relationship data
@@ -162,6 +159,7 @@ This in particular means that:
 If multiple node dataframes are used, they need to contain distinct node ids across all node data frames.
 * Prior to the `construct` call, a call to `GraphDataScience.set_database` must have been made to explicitly specify which Neo4j database should be targeted.
 
+include::ROOT:partial$/graph-construct-limitation.adoc[]
 
 [[networkx]]
 == Loading a NetworkX graph
@@ -280,6 +278,8 @@ The direction (`DIRECTED` or `UNDIRECTED`) of the relationships in the projected
 If the given NetworkX graph is directed, so a (sub)class of either `networkx.DiGraph` or `networkx.MultiDiGraph`, the relationships will be `DIRECTED` in the projection.
 Otherwise, they will be `UNDIRECTED`.
 
+include::ROOT:partial$/graph-construct-limitation.adoc[]
+
 
 == Inspecting a graph object
 
diff --git a/doc/modules/ROOT/pages/tutorials/heterogeneous-node-classification-with-hashgnn.adoc b/doc/modules/ROOT/pages/tutorials/heterogeneous-node-classification-with-hashgnn.adoc
@@ -71,7 +71,7 @@ graph with `Movie`, `Actor` and `Director` nodes, connected by
 
 Note that a ``real world scenario'', we would probably project our own
 data from a Neo4j database into GDS instead, or using
-`gds.alpha.graph.construct` to create a graph from our own client side
+`gds.graph.construct` to create a graph from our own client side
 data.
 
 [source, python, role=no-test]
diff --git a/doc/modules/ROOT/pages/tutorials/import-sample-export-gnn.adoc b/doc/modules/ROOT/pages/tutorials/import-sample-export-gnn.adoc
@@ -115,7 +115,7 @@ It’s looks correct! Now let’s go ahead and sample the graph.
 [source, python, role=no-test]
 ----
 # We use the random walk with restarts sampling algorithm with default values
-G_sample, _ = gds.alpha.graph.sample.rwr("cora_sample", G, randomSeed=42, concurrency=1)
+G_sample, _ = gds.graph.sample.rwr("cora_sample", G, randomSeed=42, concurrency=1)
 ----
 
 [source, python, role=no-test]
diff --git a/doc/modules/ROOT/pages/tutorials/load-data-via-graph-construction.adoc b/doc/modules/ROOT/pages/tutorials/load-data-via-graph-construction.adoc
@@ -11,7 +11,7 @@ This Jupyter notebook is hosted
 https://github.com/neo4j/graph-data-science-client/blob/main/examples/load-data-via-graph-construction.ipynb[here]
 in the Neo4j Graph Data Science Client Github repository.
 
-The notebook shows the usage of the `gds.alpha.graph.construct` method
+The notebook shows the usage of the `gds.graph.construct` method
 (available only in GDS 2.1+) to build a graph directly in memory.
 
 NOTE: If you are using AuraDS, it is currently not possible to write the
@@ -155,7 +155,7 @@ Finally, we can create the in-memory graph.
 
 [source, python, role=no-test]
 ----
-G = gds.alpha.graph.construct("cora-graph", nodes, relationships)
+G = gds.graph.construct("cora-graph", nodes, relationships)
 ----
 
 == Use the graph
@@ -186,7 +186,7 @@ the graph, printing only the first 10.
 
 [source, python, role=no-test]
 ----
-gds.graph.streamNodeProperties(G, ["subject"]).head(10)
+gds.graph.nodeProperties.stream(G, ["subject"]).head(10)
 ----
 
 == Cleanup
diff --git a/doc/modules/ROOT/pages/tutorials/ml-pipelines-node-classification.adoc b/doc/modules/ROOT/pages/tutorials/ml-pipelines-node-classification.adoc
@@ -465,7 +465,7 @@ model_fastrp.predict_mutate(
     targetNodeLabels=["UnclassifiedPaper"],
 )
 
-predicted_fastrp = gds.graph.streamNodeProperty(G, "predictedClass", ["UnclassifiedPaper"])
+predicted_fastrp = gds.graph.nodeProperty.stream(G, "predictedClass", ["UnclassifiedPaper"])
 ----
 
 [source, python, role=no-test]
diff --git a/doc/modules/ROOT/pages/tutorials/node-regression-with-subgraph-and-graph-sample.adoc b/doc/modules/ROOT/pages/tutorials/node-regression-with-subgraph-and-graph-sample.adoc
@@ -451,7 +451,7 @@ print("MEAN_ABSOLUTE_ERROR     test score: " + str(train_result["modelInfo"]["me
 [source, python, role=no-test]
 ----
 # Let's sample the graph to see if we can get a similarly good model
-G_chameleon_sample, _ = gds.alpha.graph.sample.rwr(
+G_chameleon_sample, _ = gds.graph.sample.rwr(
     "cham_sample",
     G_chameleon,
     samplingRatio=0.30,  # We'll use 30% of the graph
diff --git a/doc/modules/ROOT/partials/graph-construct-limitation.adoc b/doc/modules/ROOT/partials/graph-construct-limitation.adoc
@@ -0,0 +1,7 @@
+=== Limitations on community edition
+
+For users of GDS community edition, performance can be impacted for large graphs.
+It is possible that socket connection with the database times out.
+If this happens, a possible workaround is to modify the server configuration https://neo4j.com/docs/operations-manual/current/configuration/configuration-settings/#config_server.bolt.connection_keep_alive[`server.bolt.connection_keep_alive`]
+or https://neo4j.com/docs/operations-manual/current/configuration/configuration-settings/#config_server.bolt.connection_keep_alive_probes[`server.bolt.connection_keep_alive_probes`].
+However, be aware of the side effects such as a genuine connection issue now taking longer to be detected.
diff --git a/doc/sphinx/source/graph.rst b/doc/sphinx/source/graph.rst
@@ -5,7 +5,7 @@ This includes all the methods for projecting, deleting, and listing graphs, as w
 These all assume that an object of :class:`.GraphDataScience` is available as `gds`.
 
 
-.. py:function:: gds.alpha.graph.construct(graph_name: str, nodes: Union[DataFrame, List[DataFrame]], relationships: Union[DataFrame, List[DataFrame]], concurrency: int = 4, undirected_relationship_types: Optional[List[str]] = None) -> Graph
+.. py:function:: gds.graph.construct(graph_name: str, nodes: Union[DataFrame, List[DataFrame]], relationships: Union[DataFrame, List[DataFrame]], concurrency: int = 4, undirected_relationship_types: Optional[List[str]] = None) -> Graph
 
     Constructs a new graph in the graph catalog, using the provided node and relationship data frames.
 
diff --git a/examples/heterogeneous-node-classification-with-hashgnn.ipynb b/examples/heterogeneous-node-classification-with-hashgnn.ipynb
@@ -110,7 +110,7 @@
     "Next we use the `graphdatascience` [built-in IMDB loader](https://neo4j.com/docs/graph-data-science-client/current/common-datasets/#_imdb) to get data into our GDS server.\n",
     "This should give us a graph with `Movie`, `Actor` and `Director` nodes, connected by `ACTED_IN` and `DIRECTED_IN` relationships.\n",
     "\n",
-    "Note that a \"real world scenario\", we would probably project our own data from a Neo4j database into GDS instead, or using `gds.alpha.graph.construct` to create a graph from our own client side data."
+    "Note that a \"real world scenario\", we would probably project our own data from a Neo4j database into GDS instead, or using `gds.graph.construct` to create a graph from our own client side data."
    ]
   },
   {
diff --git a/examples/load-data-via-graph-construction.ipynb b/examples/load-data-via-graph-construction.ipynb
@@ -25,7 +25,7 @@
    "source": [
     "This Jupyter notebook is hosted [here](https://github.com/neo4j/graph-data-science-client/blob/main/examples/load-data-via-graph-construction.ipynb) in the Neo4j Graph Data Science Client Github repository.\n",
     "\n",
-    "The notebook shows the usage of the `gds.alpha.graph.construct` method (available only in GDS 2.1+) to build a graph directly in memory.\n",
+    "The notebook shows the usage of the `gds.graph.construct` method (available only in GDS 2.1+) to build a graph directly in memory.\n",
     "\n",
     "NOTE: If you are using AuraDS, it is currently not possible to write the projected graph back to Neo4j."
    ]
@@ -279,7 +279,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "G = gds.alpha.graph.construct(\"cora-graph\", nodes, relationships)"
+    "G = gds.graph.construct(\"cora-graph\", nodes, relationships)"
    ]
   },
   {
@@ -351,7 +351,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "gds.graph.streamNodeProperties(G, [\"subject\"]).head(10)"
+    "gds.graph.nodeProperties.stream(G, [\"subject\"]).head(10)"
    ]
   },
   {
diff --git a/examples/ml-pipelines-node-classification.ipynb b/examples/ml-pipelines-node-classification.ipynb
@@ -634,7 +634,7 @@
     "    targetNodeLabels=[\"UnclassifiedPaper\"],\n",
     ")\n",
     "\n",
-    "predicted_fastrp = gds.graph.streamNodeProperty(G, \"predictedClass\", [\"UnclassifiedPaper\"])"
+    "predicted_fastrp = gds.graph.nodeProperty.stream(G, \"predictedClass\", [\"UnclassifiedPaper\"])"
    ]
   },
   {
diff --git a/graphdatascience/error/deprecation_warning.py b/graphdatascience/error/deprecation_warning.py
@@ -1,3 +1,4 @@
+import warnings
 from functools import wraps
 from logging import warning
 from typing import Any, Callable, Optional, TypeVar, cast
@@ -20,8 +21,9 @@ def decorator(func: F) -> F:
 
         @wraps(func)
         def wrapper(self: WithServerVersion, *args: Any, **kwargs: Any) -> Any:
-            if deprecation_start_version and self._server_version > deprecation_start_version:
+            if deprecation_start_version and self._server_version >= deprecation_start_version:
                 warning(f"Deprecated in favor of {new_procedure}")
+                warnings.warn(f"Deprecated in favor of {new_procedure}", DeprecationWarning)
             return func(self, *args, **kwargs)
 
         return cast(F, wrapper)
diff --git a/graphdatascience/graph/graph_alpha_proc_runner.py b/graphdatascience/graph/graph_alpha_proc_runner.py
@@ -4,6 +4,7 @@
 from pandas import DataFrame
 
 from ..error.client_only_endpoint import client_only_endpoint
+from ..error.deprecation_warning import deprecation_warning
 from ..error.illegal_attr_checker import IllegalAttrChecker
 from ..error.uncallable_namespace import UncallableNamespace
 from ..server_version.compatible_with import compatible_with
@@ -36,6 +37,7 @@ def project(self) -> GraphAlphaProjectRunner:
         return GraphAlphaProjectRunner(self._query_runner, self._namespace, self._server_version)
 
     @client_only_endpoint("gds.alpha.graph")
+    @deprecation_warning("gds.graph.construct", ServerVersion(2, 1, 0))
     @compatible_with("construct", min_inclusive=ServerVersion(2, 1, 0))
     def construct(
         self,
diff --git a/graphdatascience/graph/graph_proc_runner.py b/graphdatascience/graph/graph_proc_runner.py
@@ -1,3 +1,4 @@
+import os
 import pathlib
 import sys
 from logging import warning
@@ -13,7 +14,6 @@
 from ..error.uncallable_namespace import UncallableNamespace
 from ..server_version.compatible_with import compatible_with
 from ..server_version.server_version import ServerVersion
-from .graph_alpha_proc_runner import GraphAlphaProcRunner
 from .graph_entity_ops_runner import (
     GraphElementPropertyRunner,
     GraphNodePropertiesRunner,
@@ -44,6 +44,53 @@ def _path(package: str, resource: str) -> ContextManager[pathlib.Path]:
 
             return path(package, resource)
 
+    @client_only_endpoint("gds.graph")
+    @compatible_with("construct", min_inclusive=ServerVersion(2, 1, 0))
+    def construct(
+        self,
+        graph_name: str,
+        nodes: Union[DataFrame, List[DataFrame]],
+        relationships: Union[DataFrame, List[DataFrame]],
+        concurrency: int = 4,
+        undirected_relationship_types: Optional[List[str]] = None,
+    ) -> Graph:
+        nodes = nodes if isinstance(nodes, List) else [nodes]
+        relationships = relationships if isinstance(relationships, List) else [relationships]
+
+        errors = []
+
+        exists = self._query_runner.run_query(
+            f"CALL gds.graph.exists('{graph_name}') YIELD exists", custom_error=False
+        ).squeeze()
+
+        # compare against True as (1) unit tests return None here and (2) numpys True does not work with `is True`.
+        if exists == True:  # noqa: E712
+            errors.append(
+                f"Graph '{graph_name}' already exists. Please drop the existing graph or use a different name."
+            )
+
+        for idx, node_df in enumerate(nodes):
+            if "nodeId" not in node_df.columns.values:
+                errors.append(f"Node dataframe at index {idx} needs to contain a 'nodeId' column.")
+
+        for idx, rel_df in enumerate(relationships):
+            for expected_col in ["sourceNodeId", "targetNodeId"]:
+                if expected_col not in rel_df.columns.values:
+                    errors.append(f"Relationship dataframe at index {idx} needs to contain a '{expected_col}' column.")
+
+        if self._server_version < ServerVersion(2, 3, 0) and undirected_relationship_types:
+            errors.append("The parameter 'undirected_relationship_types' is only supported since GDS 2.3.0.")
+
+        if len(errors) > 0:
+            raise ValueError(os.linesep.join(errors))
+
+        constructor = self._query_runner.create_graph_constructor(
+            graph_name, concurrency, undirected_relationship_types
+        )
+        constructor.run(nodes, relationships)
+
+        return Graph(graph_name, self._query_runner, self._server_version)
+
     @client_only_endpoint("gds.graph")
     def load_cora(self, graph_name: str = "cora", undirected: bool = False) -> Graph:
         with self._path("graphdatascience.resources.cora", "cora_nodes_gzip.pkl") as nodes_resource:
@@ -52,14 +99,9 @@ def load_cora(self, graph_name: str = "cora", undirected: bool = False) -> Graph
         with self._path("graphdatascience.resources.cora", "cora_rels_gzip.pkl") as rels_resource:
             rels = read_pickle(rels_resource, compression="gzip")
 
-        self._namespace = "gds.alpha.graph"
-        alpha_proc_runner = GraphAlphaProcRunner(self._query_runner, self._namespace, self._server_version)
-
         undirected_relationship_types = ["*"] if undirected else []
 
-        return alpha_proc_runner.construct(
-            graph_name, nodes, rels, undirected_relationship_types=undirected_relationship_types
-        )
+        return self.construct(graph_name, nodes, rels, undirected_relationship_types=undirected_relationship_types)
 
     @client_only_endpoint("gds.graph")
     def load_karate_club(self, graph_name: str = "karate_club", undirected: bool = False) -> Graph:
@@ -69,14 +111,9 @@ def load_karate_club(self, graph_name: str = "karate_club", undirected: bool = F
         with self._path("graphdatascience.resources.karate", "karate_club_gzip.pkl") as rels_resource:
             rels = read_pickle(rels_resource, compression="gzip")
 
-        self._namespace = "gds.alpha.graph"
-        alpha_proc_runner = GraphAlphaProcRunner(self._query_runner, self._namespace, self._server_version)
-
         undirected_relationship_types = ["*"] if undirected else []
 
-        return alpha_proc_runner.construct(
-            graph_name, nodes, rels, undirected_relationship_types=undirected_relationship_types
-        )
+        return self.construct(graph_name, nodes, rels, undirected_relationship_types=undirected_relationship_types)
 
     @client_only_endpoint("gds.graph")
     def load_imdb(self, graph_name: str = "imdb", undirected: bool = True) -> Graph:
@@ -97,18 +134,13 @@ def load_imdb(self, graph_name: str = "imdb", undirected: bool = True) -> Graph:
         with self._path("graphdatascience.resources.imdb", "imdb_directed_in_rels_gzip.pkl") as rels_resource:
             directed_in_rels = read_pickle(rels_resource, compression="gzip")
 
-        self._namespace = "gds.alpha.graph"
-        alpha_proc_runner = GraphAlphaProcRunner(self._query_runner, self._namespace, self._server_version)
-
         nodes = [movies_with_genre, movies_without_genre, actors, directors]
         rels = [acted_in_rels, directed_in_rels]
 
         # Default undirected which matches raw data
         undirected_relationship_types = ["*"] if undirected else []
 
-        return alpha_proc_runner.construct(
-            graph_name, nodes, rels, undirected_relationship_types=undirected_relationship_types
-        )
+        return self.construct(graph_name, nodes, rels, undirected_relationship_types=undirected_relationship_types)
 
     @property
     def sample(self) -> GraphSampleRunner:
diff --git a/graphdatascience/tests/integration/test_graph_construct.py b/graphdatascience/tests/integration/test_graph_construct.py
diff --git a/graphdatascience/tests/integration/test_graph_ops.py b/graphdatascience/tests/integration/test_graph_ops.py
diff --git a/graphdatascience/tests/unit/test_graph_construct.py b/graphdatascience/tests/unit/test_graph_construct.py
diff --git a/graphdatascience/tests/unit/test_graph_ops.py b/graphdatascience/tests/unit/test_graph_ops.py

Original file line number	Diff line number	Diff line change
`@@ -465,7 +465,7 @@ model_fastrp.predict_mutate(`
`465`	`465`	`targetNodeLabels=["UnclassifiedPaper"],`
`466`	`466`	`)`
`467`	`467`
`468`		`-predicted_fastrp = gds.graph.streamNodeProperty(G, "predictedClass", ["UnclassifiedPaper"])`
	`468`	`+predicted_fastrp = gds.graph.nodeProperty.stream(G, "predictedClass", ["UnclassifiedPaper"])`
`469`	`469`	`----`
`470`	`470`
`471`	`471`	`[source, python, role=no-test]`