From 6e3eaca481de71e0fcd2f34c03be41cb60ee42b4 Mon Sep 17 00:00:00 2001 From: Adam Schill Collberg Date: Wed, 5 Feb 2025 15:43:27 +0100 Subject: [PATCH] Extend Getting started in READMEs with small example --- README.md | 58 +++++++++++++++++++++++++++- python-wrapper/README.md | 81 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 132 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6d73f8ca..d1cfefea 100644 --- a/README.md +++ b/README.md @@ -51,10 +51,66 @@ Please note that this list is by no means exhaustive. ## Getting started -``` + +### Installation + +Simply install with pip: + +```sh pip install neo4j-viz ``` + +### Basic usage + +We will use a small toy graph representing the purchase history of a few people and products. + +We start by instantiating the [Nodes](https://neo4j.com/docs/nvl-python/preview/api-reference/node.html) and +[Relationships](https://neo4j.com/docs/nvl-python/preview/api-reference/relationship.html) we want in our graph. +The only mandatory fields for a node are the "id", and "source" and "target" for a relationship. +But the other fields can optionally be used to customize the appearance of the nodes and relationships in the +visualization. + +Lastly we create a +[VisualizationGraph](https://neo4j.com/docs/nvl-python/preview/api-reference/visualization-graph.html) object with the +nodes and relationships we created, and call its `render` method to display the graph. + +```python +from neo4j_viz import Node, Relationship, VisualizationGraph + +nodes = [ + Node(id=0, size=10, caption="Person"), + Node(id=1, size=10, caption="Product"), + Node(id=2, size=20, caption="Product"), + Node(id=3, size=10, caption="Person"), + Node(id=4, size=10, caption="Product"), +] +relationships = [ + Relationship( + source=0, + target=1, + caption="BUYS", + ), + Relationship( + source=0, + target=2, + caption="BUYS", + ), + Relationship( + source=3, + target=2, + caption="BUYS", + ), +] + +VG = VisualizationGraph(nodes=nodes, relationships=relationships) + +VG.render() +``` + +This will return a `IPython.display.HTML` object that can be rendered in a Jupyter Notebook or streamlit application. + + ### Examples For some Jupyter Notebook and streamlit examples, checkout the [/examples](/examples) directory. diff --git a/python-wrapper/README.md b/python-wrapper/README.md index 5c00c418..dadd7edd 100644 --- a/python-wrapper/README.md +++ b/python-wrapper/README.md @@ -3,14 +3,22 @@ [![Latest version](https://img.shields.io/pypi/v/neo4j-viz)](https://pypi.org/project/neo4j-viz/) [![PyPI downloads month](https://img.shields.io/pypi/dm/neo4j-viz)](https://pypi.org/project/neo4j-viz/) ![Python versions](https://img.shields.io/pypi/pyversions/neo4j-viz) +[![Documentation](https://img.shields.io/badge/Documentation-latest-blue)](https://neo4j.com/docs/nvl-python/preview/) +[![Discord](https://img.shields.io/discord/787399249741479977?label=Chat&logo=discord)](https://discord.gg/neo4j) +[![Community forum](https://img.shields.io/website?down_color=lightgrey&down_message=offline&label=Forums&logo=discourse&up_color=green&up_message=online&url=https%3A%2F%2Fcommunity.neo4j.com%2F)](https://community.neo4j.com) +[![License](https://img.shields.io/pypi/l/neo4j-viz)](https://pypi.org/project/neo4j-viz/) + +`neo4j-viz` is a Python package for creating interactive graph visualizations based on data from Neo4j products. + +The output is of type `IPython.display.HTML` and can be viewed directly in a Jupyter Notebook, Streamlit. +Alternatively, you can export the output to a file and view it in a web browser. -`neo4j-viz` is a Python package for creating interactive graph visualizations. The package wraps the [Neo4j Visualization JavaScript library (NVL)](https://neo4j.com/docs/nvl/current/). Proper documentation is forthcoming. -**WARNING:** -This package is still in development and the API is subject to change. +> [!WARNING] +> This package is still in development and the API is subject to change. ## Some notable features @@ -39,8 +47,69 @@ This package is still in development and the API is subject to change. Please note that this list is by no means exhaustive. -## Installation +## Getting started -``` + +### Installation + +Simply install with pip: + +```sh pip install neo4j-viz -``` \ No newline at end of file +``` + + +### Basic usage + +We will use a small toy graph representing the purchase history of a few people and products. + +We start by instantiating the [Nodes](https://neo4j.com/docs/nvl-python/preview/api-reference/node.html) and +[Relationships](https://neo4j.com/docs/nvl-python/preview/api-reference/relationship.html) we want in our graph. +The only mandatory fields for a node are the "id", and "source" and "target" for a relationship. +But the other fields can optionally be used to customize the appearance of the nodes and relationships in the +visualization. + +Lastly we create a +[VisualizationGraph](https://neo4j.com/docs/nvl-python/preview/api-reference/visualization-graph.html) object with the +nodes and relationships we created, and call its `render` method to display the graph. + +```python +from neo4j_viz import Node, Relationship, VisualizationGraph + +nodes = [ + Node(id=0, size=10, caption="Person"), + Node(id=1, size=10, caption="Product"), + Node(id=2, size=20, caption="Product"), + Node(id=3, size=10, caption="Person"), + Node(id=4, size=10, caption="Product"), +] +relationships = [ + Relationship( + source=0, + target=1, + caption="BUYS", + ), + Relationship( + source=0, + target=2, + caption="BUYS", + ), + Relationship( + source=3, + target=2, + caption="BUYS", + ), +] + +VG = VisualizationGraph(nodes=nodes, relationships=relationships) + +VG.render() +``` + +This will return a `IPython.display.HTML` object that can be rendered in a Jupyter Notebook or streamlit application. + + +### Examples + +For more extensive examples, including how to import graphs from Neo4j GDS projections and Pandas DataFrames, +checkout the [tutorials chapter](https://neo4j.com/docs/nvl-python/preview/tutorials/index.html) in the documentation. \ No newline at end of file