Skip to content

Commit c490dc4

Browse files
ParticularlyPythonicBSParticularlyPythonicBS
committed
updated readme
1 parent a31a390 commit c490dc4

File tree

3 files changed

+144
-10
lines changed

3 files changed

+144
-10
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: CI & Deploy
1+
name: CI
22

33
on:
44
push:

‎README.md‎

Lines changed: 142 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,148 @@
1+
# NX-VIS Visualizer
12

23
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
3-
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/ParticularlyPythonicBS/nx-vis-visualizer/master.svg)](https://results.pre-commit.ci/latest/github/ParticularlyPythonicBS/nx-vis-visualizer/master)
4+
[![pre-commit.ci](https://results.pre-commit.ci/badge/github/ParticularlyPythonicBS/nx-vis-visualizer/master.svg)](https://results.pre-commit.ci/latest/github/ParticularlyPythonicBS/nx-vis-visualizer/master)
5+
[![CI & Deploy](https://github.com/ParticularlyPythonicBS/nx-vis-visualizer/actions/workflows/ci.yml/badge.svg)](https://github.com/ParticularlyPythonicBS/nx-vis-visualizer/actions/workflows/ci.yml)
6+
[![Netlify Status](https://api.netlify.com/api/v1/badges/6c56b010-ff27-4087-af9a-07e69af5e1f4/deploy-status)](https://app.netlify.com/sites/nx-vis-visualizer/deploys)
7+
[![PyPI version](https://badge.fury.io/py/nx-vis-visualizer.svg)](https://badge.fury.io/py/nx-vis-visualizer)
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
49

5-
# NX-VIS Visualizer
10+
**NX-VIS Visualizer** is a Python library designed to bridge the gap between [NetworkX](https://networkx.org/), a powerful graph manipulation library, and [vis.js Network](https://visjs.github.io/vis-network/docs/network/), a dynamic, browser-based visualization library. It allows you to easily render your NetworkX graphs as interactive HTML files or embed them directly into Jupyter Notebooks.
11+
12+
**[View the Documentation & Live Examples](https://nx-vis-visualizer.netlify.app/)**
13+
14+
## Key Features
15+
16+
* **Seamless Conversion:** Effortlessly convert NetworkX `Graph` and `DiGraph` objects into a format compatible with vis.js.
17+
* **Rich Customization:** Leverage the extensive [vis.js Network options](https://visjs.github.io/vis-network/docs/network/options.html) to tailor the appearance and behavior of your graphs (nodes, edges, layout, physics, interaction, etc.).
18+
* **Node & Edge Styling:** Apply vis.js styling attributes directly to your NetworkX nodes and edges.
19+
* **Self-Contained HTML:** Generate standalone HTML files that can be easily shared or embedded.
20+
* **Jupyter Notebook Integration:** Display interactive graphs directly within your Jupyter Notebooks or IPython environments.
21+
* **Interactive Exploration:** Enables panning, zooming, node dragging (if physics allows), and information display on hover/click.
22+
* **Configurable UI:** Optionally include a vis.js configuration panel within the generated HTML to tweak graph settings live in the browser.
23+
24+
## Installation
25+
26+
You can install NX-VIS Visualizer using pip:
27+
28+
```bash
29+
pip install nx-vis-visualizer
30+
```
31+
32+
Alternatively, for development or to install from source:
33+
34+
```bash
35+
git clone https://github.com/ParticularlyPythonicBS/nx-vis-visualizer.git
36+
cd nx-vis-visualizer
37+
uv pip install -e .
38+
```
39+
40+
## Quick Start
41+
42+
Here's a basic example of how to visualize a simple NetworkX graph:
43+
44+
```python
45+
import networkx as nx
46+
from nx_vis_visualizer import nx_to_vis
47+
48+
# 1. Create a NetworkX graph
49+
G = nx.cycle_graph(5)
50+
51+
# Add some basic attributes for visualization
52+
for i, node_id in enumerate(G.nodes()):
53+
G.nodes[node_id]['label'] = f'Node {i+1}'
54+
G.nodes[node_id]['title'] = f'This is Node {i+1}' # Tooltip
55+
G.nodes[node_id]['group'] = i % 2
56+
57+
G.edges[0,1]['label'] = 'Link 0-1'
58+
G.edges[0,1]['color'] = 'red'
59+
60+
# 2. Define (optional) vis.js options
61+
custom_options = {
62+
"nodes": {"font": {"size": 16}},
63+
"edges": {"smooth": {"enabled": True}},
64+
"groups": {
65+
0: {"color": "skyblue", "shape": "dot"},
66+
1: {"color": "lightgreen", "shape": "square"}
67+
},
68+
"interaction": {"navigationButtons": True, "hover": True},
69+
"physics": {"enabled": True}
70+
}
71+
72+
# 3. Generate and show the interactive HTML graph
73+
# This will create 'cycle_graph.html' and open it in your browser.
74+
nx_to_vis(
75+
G,
76+
output_filename="cycle_graph.html",
77+
html_title="My Interactive Cycle Graph",
78+
vis_options=custom_options,
79+
show_browser=True
80+
)
81+
82+
# To get HTML for a Jupyter Notebook:
83+
# html_output = nx_to_vis(G, vis_options=custom_options, notebook=True, show_browser=False)
84+
# if html_output:
85+
# from IPython.display import HTML
86+
# display(HTML(html_output))
87+
```
88+
89+
For more detailed examples, including directed graphs and advanced customizations, please see the [**Documentation**](https://nx-vis-visualizer.netlify.app/examples/basic/).
90+
91+
## Documentation
92+
93+
Full documentation, including API references and more examples, is available at:
94+
**[https://nx-vis-visualizer.netlify.app/](https://nx-vis-visualizer.netlify.app/)**
95+
96+
The documentation covers:
97+
98+
* Installation
99+
* Basic Usage
100+
* Styling Nodes and Edges
101+
* Using vis.js Options
102+
* Directed Graphs
103+
* Advanced Customization
104+
* Jupyter Notebook Integration
105+
* API Reference
106+
107+
## Contributing
108+
109+
Contributions are welcome! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please feel free to open an issue or submit a pull request.
110+
111+
To set up for development:
112+
113+
1. Clone the repository:
114+
115+
```bash
116+
git clone https://github.com/ParticularlyPythonicBS/nx-vis-visualizer.git
117+
cd nx-vis-visualizer
118+
```
119+
120+
2. Install dependencies using [uv](https://github.com/astral-sh/uv):
121+
122+
```bash
123+
uv sync --all-extras --dev
124+
uv pip install -e . --no-deps
125+
```
126+
127+
3. Set up [pre-commit](https://pre-commit.com/) hooks for code formatting and linting:
128+
129+
```bash
130+
uv run pre-commit install
131+
```
132+
133+
4. Run tests:
134+
135+
```bash
136+
uv run pytest tests
137+
```
138+
139+
Please ensure your contributions pass all tests and adhere to the coding style (enforced by pre-commit hooks).
140+
141+
## License
6142

7-
A Python library to render NetworkX graphs interactively in HTML using vis.js.
143+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
8144

9-
## Features
145+
## Acknowledgements
10146

11-
- Convert NetworkX graphs (Graph and DiGraph) to vis.js format.
12-
- Customize vis.js options.
13-
- Generate self-contained HTML files.
14-
- Optionally open in browser or return HTML for Jupyter notebooks.
147+
* [NetworkX](https://networkx.org/) development team.
148+
* [vis.js Network](https://visjs.github.io/vis-network/docs/network/) library and its contributors.

‎requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# requirements.txt
1+
# requirements.txt for netlify
22
mkdocs>=1.5
33
mkdocs-material>=9.0
44
networkx>=3.0

0 commit comments

Comments
 (0)