Metadata-Version: 2.4
Name: neo4j-viz
Version: 0.5.0
Summary: A simple graph visualization tool
Author-email: Neo4j <team-gds@neo4j.org>
Project-URL: Homepage, https://neo4j.com/
Project-URL: Repository, https://github.com/neo4j/python-graph-visualization
Project-URL: Issues, https://github.com/neo4j/python-graph-visualization/issues
Project-URL: Documentation, https://neo4j.com/docs/nvl-python/preview
Keywords: graph,visualization,neo4j
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: ipython<10,>=7
Requires-Dist: pydantic<3,>=2
Requires-Dist: pydantic-extra-types<3,>=2
Requires-Dist: enum-tools==0.12.0
Provides-Extra: dev
Requires-Dist: ruff==0.11.8; extra == "dev"
Requires-Dist: mypy==1.17.1; extra == "dev"
Requires-Dist: pytest==8.3.4; extra == "dev"
Requires-Dist: selenium==4.32.0; extra == "dev"
Requires-Dist: ipykernel==6.29.5; extra == "dev"
Requires-Dist: palettable==3.3.3; extra == "dev"
Requires-Dist: pytest-mock==3.14.0; extra == "dev"
Requires-Dist: nbconvert==7.16.6; extra == "dev"
Requires-Dist: streamlit==1.45.0; extra == "dev"
Requires-Dist: matplotlib>=3.9.4; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx==8.1.3; extra == "docs"
Requires-Dist: enum-tools[sphinx]; extra == "docs"
Requires-Dist: nbsphinx==0.9.6; extra == "docs"
Requires-Dist: nbsphinx-link==1.3.1; extra == "docs"
Provides-Extra: pandas
Requires-Dist: pandas<3,>=2; extra == "pandas"
Requires-Dist: pandas-stubs<3,>=2; extra == "pandas"
Provides-Extra: gds
Requires-Dist: graphdatascience<2,>=1; extra == "gds"
Provides-Extra: neo4j
Requires-Dist: neo4j; extra == "neo4j"
Provides-Extra: snowflake
Requires-Dist: snowflake-snowpark-python<2,>=1; extra == "snowflake"
Provides-Extra: notebook
Requires-Dist: ipykernel>=6.29.5; extra == "notebook"
Requires-Dist: pykernel>=0.1.6; extra == "notebook"
Requires-Dist: neo4j>=5.26.0; extra == "notebook"
Requires-Dist: ipywidgets>=8.0.0; extra == "notebook"
Requires-Dist: palettable>=3.3.3; extra == "notebook"
Requires-Dist: matplotlib>=3.9.4; extra == "notebook"
Requires-Dist: snowflake-snowpark-python==1.37.0; extra == "notebook"

# Graph Visualization for Python by Neo4j

[![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.

The output is of type `IPython.display.HTML` and can be viewed directly in a Jupyter Notebook or Streamlit application.
Alternatively, you can export the output to a file and view it in a web browser.

The package wraps the [Neo4j Visualization JavaScript library (NVL)](https://neo4j.com/docs/nvl/current/).

> [!WARNING]
> This package is still in development and the API is subject to change.


![Example Graph](https://github.com/neo4j/python-graph-visualization/blob/main/examples/example_cora_graph.png)


## Some notable features

* 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
  * Colors
  * Captions
  * Pinning
  * On hover tooltip
* Relationship features:
  * Colors
  * Captions
  * On hover tooltip
* Graph features:
  * Zooming
  * Panning
  * Moving nodes
  * Using different layouts
* Additional convenience functionality for:
  * Resizing nodes, optionally including scale normalization
  * Coloring nodes based on a property
  * Toggle whether nodes should be pinned or not

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.

Please refer to the [documentation](https://neo4j.com/docs/nvl-python/preview/) for more details on the API and usage.


### 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.
