diff --git a/docs/extra/getting-started.ipynb b/docs/extra/getting-started.ipynb new file mode 100644 index 00000000..91cfa25a --- /dev/null +++ b/docs/extra/getting-started.ipynb @@ -0,0 +1,194 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0d3ffc27", + "metadata": {}, + "source": "# Getting Started" + }, + { + "cell_type": "markdown", + "id": "6b83277d", + "metadata": {}, + "source": [ + "In this section, we will cover the very basics of creating a visualization graph using the `neo4j-viz` library.\n", + "We will use a small toy graph representing the purchase history of a few people and products.\n", + "\n", + "To follow along with the example below, please make sure you have [installed the library](installation.rst) first.\n", + "\n", + "We start by instantiating the [Nodes](./api-reference/node.rst) and [Relationships](./api-reference/relationship.rst) we want in our graph.\n", + "The only mandatory fields for a node are the \"id\", and \"source\" and \"target\" for a relationship.\n", + "But the other fields can optionally be used to customize the appearance of the nodes and relationships in the visualization.\n", + "\n", + "Lastly we create a [VisualizationGraph](./api-reference/visualization-graph.rst) object with the nodes and relationships we created, and call its `render` method to display the graph.\n" + ] + }, + { + "cell_type": "code", + "id": "801d0bed", + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-23T14:36:35.101222Z", + "start_time": "2025-01-23T14:36:35.022822Z" + } + }, + "source": [ + "from neo4j_viz import Node, Relationship, VisualizationGraph\n", + "\n", + "nodes = [\n", + " Node(id=0, size=10, caption=\"Person\"),\n", + " Node(id=1, size=10, caption=\"Product\"),\n", + " Node(id=2, size=20, caption=\"Product\"),\n", + " Node(id=3, size=10, caption=\"Person\"),\n", + " Node(id=4, size=10, caption=\"Product\"),\n", + "]\n", + "relationships = [\n", + " Relationship(\n", + " source=0,\n", + " target=1,\n", + " caption=\"BUYS\",\n", + " ),\n", + " Relationship(\n", + " source=0,\n", + " target=2,\n", + " caption=\"BUYS\",\n", + " ),\n", + " Relationship(\n", + " source=3,\n", + " target=2,\n", + " caption=\"BUYS\",\n", + " ),\n", + "]\n", + "\n", + "VG = VisualizationGraph(nodes=nodes, relationships=relationships)\n", + "\n", + "VG.render()" + ], + "outputs": [ + { + "data": { + "text/plain": [ + "" + ], + "text/html": [ + "\n", + "
\n", + " \n", + " " + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "execution_count": 1 + }, + { + "cell_type": "markdown", + "id": "365a1c31", + "metadata": {}, + "source": [ + "As we can see in the graph above, the radius of one of the nodes is larger than the others.\n", + "This is because we set the \"size\" field of the node to 20, while the others are set to 10.\n", + "\n", + "At this time all nodes have the same color.\n", + "If we want to distinguish between the different types of nodes, we can color them differently with the `color_nodes` method.\n", + "We can pass the field we want to use to color the nodes as an argument.\n", + "In this case, we will use the \"caption\" field.\n", + "Nodes with the same \"caption\" will have the same color.\n", + "We will use the default colorscheme, which is the Neo4j colorscheme.\n" + ] + }, + { + "cell_type": "code", + "id": "d935b3d4", + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-23T14:36:44.792490Z", + "start_time": "2025-01-23T14:36:44.778867Z" + } + }, + "source": [ + "VG.color_nodes(\"caption\")\n", + "\n", + "VG.render()" + ], + "outputs": [ + { + "data": { + "text/plain": [ + "" + ], + "text/html": [ + "\n", + "
\n", + " \n", + " " + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "execution_count": 2 + }, + { + "cell_type": "markdown", + "id": "a28bd5aa", + "metadata": {}, + "source": "We are now easily able to distinguish between the different types of nodes in the graph." + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "## Next steps\n", + "\n", + "Now that we have covered the basics of creating and rendering a visualization graph, we can move on to more advanced topics.\n", + "\n", + "Here are some suggestions for what to do next:\n", + "\n", + "* Import a graph from pandas dataframes: [API reference](./api-reference/from_pandas.rst) and [notebook example](./tutorials/snowpark-nvl-example.nblink)\n", + "* Import a graph from Neo4j Graph Data Science: [API reference](./api-reference/from_gds.rst) and [notebook example](./tutorials/gds-nvl-example.nblink)\n", + "* Customize the appearance of the nodes and relationships: [Node API reference](./api-reference/node.rst) and [Relationship API reference](./api-reference/relationship.rst)\n", + "* Check out the rendering options and convenience methods of `VisualizationGraph`: [VisualizationGraph API reference](./api-reference/visualization-graph.rst)\n", + "* Browse the [tutorials](./tutorials/index.rst) for more examples and use cases\n" + ], + "id": "b3bb58465761e57a" + } + ], + "metadata": { + "language_info": { + "name": "python" + }, + "kernelspec": { + "name": "python3", + "language": "python", + "display_name": "Python 3 (ipykernel)" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/api-reference/graph.rst b/docs/source/api-reference/graph.rst deleted file mode 100644 index 094cc3df..00000000 --- a/docs/source/api-reference/graph.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. autoclass:: neo4j_viz.VisualizationGraph - :members: - - -.. autoclass:: neo4j_viz.Node - :members: - -.. autoclass:: neo4j_viz.Relationship - :members: diff --git a/docs/source/api-reference/node.rst b/docs/source/api-reference/node.rst new file mode 100644 index 00000000..11ba39e0 --- /dev/null +++ b/docs/source/api-reference/node.rst @@ -0,0 +1,2 @@ +.. autoclass:: neo4j_viz.Node + :members: diff --git a/docs/source/api-reference/relationship.rst b/docs/source/api-reference/relationship.rst new file mode 100644 index 00000000..29647130 --- /dev/null +++ b/docs/source/api-reference/relationship.rst @@ -0,0 +1,2 @@ +.. autoclass:: neo4j_viz.Relationship + :members: diff --git a/docs/source/api-reference/visualization-graph.rst b/docs/source/api-reference/visualization-graph.rst new file mode 100644 index 00000000..8b4da608 --- /dev/null +++ b/docs/source/api-reference/visualization-graph.rst @@ -0,0 +1,2 @@ +.. autoclass:: neo4j_viz.VisualizationGraph + :members: diff --git a/docs/source/getting-started.nblink b/docs/source/getting-started.nblink new file mode 100644 index 00000000..b79d8720 --- /dev/null +++ b/docs/source/getting-started.nblink @@ -0,0 +1,3 @@ +{ + "path": "../extra/getting-started.ipynb" +} \ No newline at end of file diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst deleted file mode 100644 index 55886fc2..00000000 --- a/docs/source/getting-started.rst +++ /dev/null @@ -1,2 +0,0 @@ -Getting Started ---------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 34528bcc..8a0e5b87 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,15 +6,14 @@ Graph Visualization for Python by Neo4j documentation ===================================================== -This is the documentation for the `neo4j_viz` Python library by Neo4j for creating interactive graph visualizations. +This is the documentation for the `neo4j-viz` Python library by Neo4j for creating interactive graph visualizations. .. toctree:: :glob: :maxdepth: 1 - :caption: Contents: installation.rst - getting-started.rst + getting-started.nblink api-reference/index.rst tutorials/index.rst diff --git a/docs/source/themes/sphinx_neo4j/static/css/neo4j.css b/docs/source/themes/sphinx_neo4j/static/css/neo4j.css index 31e91e4e..f580e7fb 100644 --- a/docs/source/themes/sphinx_neo4j/static/css/neo4j.css +++ b/docs/source/themes/sphinx_neo4j/static/css/neo4j.css @@ -195,6 +195,12 @@ div.code-block-caption:hover > a.headerlink { padding: 0.25rem 0; } +/* links */ +.doc span { + margin: 0; + padding: 0; +} + /* lists */ body.sphinx .doc ul li{ diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst index 692647fa..3999307a 100644 --- a/docs/source/tutorials/index.rst +++ b/docs/source/tutorials/index.rst @@ -6,7 +6,7 @@ Tutorials ===================================================== -This chapter contains Jupyter notebook tutorials for the `neo4j_viz` package. +This chapter contains Jupyter notebook tutorials for the `neo4j-viz` package. .. toctree:: diff --git a/python-wrapper/src/neo4j_viz/visualization_graph.py b/python-wrapper/src/neo4j_viz/visualization_graph.py index 3233086b..14546176 100644 --- a/python-wrapper/src/neo4j_viz/visualization_graph.py +++ b/python-wrapper/src/neo4j_viz/visualization_graph.py @@ -37,6 +37,33 @@ def render( allow_dynamic_min_zoom: bool = True, max_allowed_nodes: int = 10_000, ) -> HTML: + """ + Render the graph. + + Parameters + ---------- + layout: + The `Layout` to use. + renderer: + The `Renderer` to use. + width: + The width of the rendered graph. + height: + The height of the rendered graph. + pan_position: + The initial pan position. + initial_zoom: + The initial zoom level. + min_zoom: + The minimum zoom level. + max_zoom: + The maximum zoom level. + allow_dynamic_min_zoom: + Whether to allow dynamic minimum zoom level. + max_allowed_nodes: + The maximum allowed number of nodes to render. + """ + num_nodes = len(self.nodes) if num_nodes > max_allowed_nodes: raise ValueError(