Merge pull request #119 from neo4j/simplify-neo4j-viz

 Add convenience for Neo4j results

Author: FlorentinD

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,7 @@ Thank you for your contribution to the Graph Data Science Client project.
 If relevant, link to the corresponding issue.
 Please also include relevant motivation and context. List any dependencies that are required for this change. -->
 
-Before submitting this PR, please read [Contributing to the Neo4j Ecosystem](https://github.com/neo4j/nvl-python-wrapper/blob/main/CONTRIBUTING.md).
+Before submitting this PR, please read [Contributing to the Neo4j Ecosystem](https://github.com/neo4j/python-graph-visualization/blob/main/CONTRIBUTING.md).
 
 Make sure:
 - [ ] You signed the [Neo4j CLA](https://neo4j.com/developer/cla/#sign-cla) (Contributor License Agreement) so that we are allowed to ship your code in our library

.github/workflows/unit-tests.yml

@@ -23,7 +23,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     defaults:
       run:
@@ -40,27 +40,8 @@ jobs:
           cache-dependency-path: pyproject.toml
       - run: pip install ".[dev]"
       - run: pip install ".[pandas]"
+      - run: pip install ".[neo4j]"
       - run: pip install ".[gds]"
 
       - name: Run tests
         run: pytest tests/
-
-  tests-313:
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: python-wrapper
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.13
-          cache: 'pip'
-          cache-dependency-path: pyproject.toml
-      - run: pip install ".[dev]"
-      - run: pip install ".[pandas]"
-      # skip gds for now as it is not available for python 3.13
-
-      - name: Run tests
-        run: pytest tests/

CONTRIBUTING.md

@@ -94,16 +94,26 @@ pytest python-wrapper/tests
 
 Additionally, there are integration tests that require an external data source.
 These require additional setup and configuration, such as environment variables specifying connection details.
-To run tests requiring a Neo4j DB instance with GDS installed, execute:
 
+
+For a local Neo4j instance with GDS installed, execute:
+```sh
+cd test-envs/neo4j-gds
+docker compose up -d
+```
+
+To run tests requiring a Neo4j DB instance with GDS installed, execute:
 ```sh
-pytest python-wrapper/tests --include-neo4j-and-gds
+export NEO4J_URI=localhost:7687 # or credentials for Aura API
+cd python-wrapper/
+pytest tests --include-neo4j-and-gds
 ```
 
 To run tests requiring a Snowflake connection, execute:
 
 ```sh
-pytest python-wrapper/tests --include-snowflake
+cd python-wrapper/
+pytest tests/ --include-snowflake
 ```
 
 

README.md

@@ -27,6 +27,7 @@ Proper documentation is forthcoming.
 
 * Easy to import graphs represented as:
   * projections in the Neo4j Graph Data Science (GDS) library
+  * graphs from Neo4j query results
   * pandas DataFrames
 * Node features:
   * Sizing

docs/source/adjusting.rst

@@ -51,7 +51,7 @@ In this case, all nodes with the same caption will get the same color.
 
 If there are fewer colors that unique values for the node ``property`` provided, the colors will be reused in a cycle.
 To avoid that, you could use another palette or extend one with additional colors. Please refer to the
-:doc:`Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial <./tutorials/gds-nvl-example>` for an example on how
+:doc:`Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial <./tutorials/gds-example>` for an example on how
 to do the latter.
 
 If some nodes already have a ``color`` set, you can choose whether or not to override it with the ``override``
@@ -142,4 +142,4 @@ Each node and relationship has attributes that can be accessed and modified dire
     VG.nodes[0].size = 10
     VG.relationships[4].caption = "BUYS"
 
-Any changes made to the nodes and relationships will be reflected in the next rendering of the graph.
+Any changes made to the nodes and relationships will be reflected in the next rendering of the graph.

docs/source/api-reference/from_neo4j.rst

@@ -0,0 +1,5 @@
+Import from Neo4j
+------------------------------------------------
+
+.. automodule:: neo4j_viz.neo4j
+    :members:

docs/source/installation.rst

@@ -24,6 +24,15 @@ To install the additional dependencies required for the :doc:`from_dfs importer
 
     pip install neo4j-viz[pandas]
 
+Neo4j ``from_neo4j`` importer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To install the additional dependencies required for the :doc:`from_neo4j importer <./api-reference/from_neo4j>` you can run:
+
+.. code-block:: bash
+
+    pip install neo4j-viz[neo4j]
+
 
 Neo4j Graph Data Science ``from_gds`` importer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/integration.rst

@@ -67,7 +67,7 @@ and :doc:`Relationships <./api-reference/relationship>`.
     VG = from_dfs(nodes, relationships)
 
 For another example of the ``from_dfs`` importer in action, see the
-:doc:`Visualizing Snowflake Tables tutorial <./tutorials/snowpark-nvl-example>`.
+:doc:`Visualizing Snowflake Tables tutorial <./tutorials/snowpark-example>`.
 
 
 Neo4j Graph Data Science (GDS) library
@@ -139,5 +139,67 @@ We use the "pagerank" property to determine the size of the nodes, and the "comp
     VG.color_nodes("componentId")
 
 
-Please see the :doc:`Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial <./tutorials/gds-nvl-example>` for a
+Please see the :doc:`Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial <./tutorials/gds-example>` for a
+more extensive example.
+
+
+Neo4j Database
+---------------
+
+The ``neo4j-viz`` library provides a convenience method for importing data from Neo4j.
+It requires and additional dependency to be installed, which you can do by running:
+
+.. code-block:: bash
+
+    pip install neo4j-viz[neo4j]
+
+Once you have installed the additional dependency, you can use the :doc:`from_neo4j <./api-reference/from_neo4j>` method
+to import query results from Neo4j.
+
+The ``from_neo4j`` method takes one mandatory positional parameters:
+
+* A ``result`` representing the query result either in form of `neo4j.graph.Graph` or `neo4j.Result`.
+
+The ``node_caption`` parameter is also optional, and indicates the value to use for the caption of each node in the visualization.
+
+We can also provide an optional ``size_property`` parameter, which should refer to a node property of the projection,
+and will be used to determine the size of the nodes in the visualization.
+
+The last optional property, ``node_radius_min_max``, can be used (and is used by default) to scale the node sizes for
+the visualization.
+It is a tuple of two numbers, representing the radii (sizes) in pixels of the smallest and largest nodes respectively in
+the visualization.
+The node sizes will be scaled such that the smallest node will have the size of the first value, and the largest node
+will have the size of the second value.
+The other nodes will be scaled linearly between these two values according to their relative size.
+This can be useful if node sizes vary a lot, or are all very small or very big.
+
+
+Example
+~~~~~~~
+
+In this small example, we import a graph from a Neo4j query result.
+
+.. code-block:: python
+
+    from neo4j import GraphDataScience
+    from neo4j_viz.gds import from_gds
+
+    # Modify this to match your Neo4j instance's URI and credentials
+    URI = "neo4j://localhost:7687"
+    auth = ("neo4j", "password")
+
+    with GraphDatabase.driver(URI, auth=auth) as driver:
+        driver.verify_connectivity()
+
+        result = driver.execute_query(
+            "MATCH (n)-[r]->(m) RETURN n,r,m",
+            database_="neo4j",
+            result_transformer_=Result.graph,
+        )
+
+    VG = from_neo4j(result)
+
+
+Please see the :doc:`Visualizing Neo4j Graphs tutorial <./tutorials/neo4j-example>` for a
 more extensive example.

…/source/tutorials/gds-nvl-example.nblink docs/source/tutorials/gds-example.nblinkdocs/source/tutorials/gds-nvl-example.nblink renamed to docs/source/tutorials/gds-example.nblink docs/source/tutorials/gds-nvl-example.nblink renamed to docs/source/tutorials/gds-example.nblink

@@ -1,5 +1,5 @@
 {
-  "path": "../../../examples/gds-nvl-example.ipynb",
+  "path": "../../../examples/gds-example.ipynb",
   "extra-media": [
     "../../../examples/example_cora_graph.png"
   ]

docs/source/tutorials/neo4j-example.nblink

@@ -0,0 +1,3 @@
+{
+  "path": "../../../examples/neo4j-example.ipynb"
+}