NX-VIS Visualizer

NX-VIS Visualizer is a Python library designed to bridge the gap between NetworkX, a powerful graph manipulation library, and vis.js 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.

View the Documentation & Live Examples

Key Features

• Seamless Conversion: Effortlessly convert NetworkX Graph and DiGraph objects into a format compatible with vis.js.
• Rich Customization: Leverage the extensive vis.js Network options to tailor the appearance and behavior of your graphs (nodes, edges, layout, physics, interaction, etc.).
• Node & Edge Styling: Apply vis.js styling attributes directly to your NetworkX nodes and edges.
• Self-Contained HTML: Generate standalone HTML files that can be easily shared or embedded.
• Jupyter Notebook Integration: Display interactive graphs directly within your Jupyter Notebooks or IPython environments.
• Interactive Exploration: Enables panning, zooming, node dragging (if physics allows), and information display on hover/click.
• Configurable UI: Optionally include a vis.js configuration panel within the generated HTML to tweak graph settings live in the browser.

Installation

You can install NX-VIS Visualizer using pip:

pip install nx-vis-visualizer

Alternatively, for development or to install from source:

git clone https://github.com/ParticularlyPythonicBS/nx-vis-visualizer.git
cd nx-vis-visualizer
uv pip install -e .

Quick Start

Here's a basic example of how to visualize a simple NetworkX graph:

import networkx as nx
from nx_vis_visualizer import nx_to_vis

# 1. Create a NetworkX graph
G = nx.cycle_graph(5)

# Add some basic attributes for visualization
for i, node_id in enumerate(G.nodes()):
    G.nodes[node_id]['label'] = f'Node {i+1}'
    G.nodes[node_id]['title'] = f'This is Node {i+1}' # Tooltip
    G.nodes[node_id]['group'] = i % 2

G.edges[0,1]['label'] = 'Link 0-1'
G.edges[0,1]['color'] = 'red'

# 2. Define (optional) vis.js options
custom_options = {
    "nodes": {"font": {"size": 16}},
    "edges": {"smooth": {"enabled": True}},
    "groups": {
        0: {"color": "skyblue", "shape": "dot"},
        1: {"color": "lightgreen", "shape": "square"}
    },
    "interaction": {"navigationButtons": True, "hover": True},
    "physics": {"enabled": True}
}

# 3. Generate and show the interactive HTML graph
# This will create 'cycle_graph.html' and open it in your browser.
nx_to_vis(
    G,
    output_filename="cycle_graph.html",
    html_title="My Interactive Cycle Graph",
    vis_options=custom_options,
    show_browser=True
)

# To get HTML for a Jupyter Notebook:
# html_output = nx_to_vis(G, vis_options=custom_options, notebook=True, show_browser=False)
# if html_output:
#     from IPython.display import HTML
#     display(HTML(html_output))

For more detailed examples, including directed graphs and advanced customizations, please see the Documentation.

Documentation

Full documentation, including API references and more examples, is available at: https://nx-vis-visualizer.netlify.app/

The documentation covers:

• Installation
• Basic Usage
• Styling Nodes and Edges
• Using vis.js Options
• Directed Graphs
• Advanced Customization
• Jupyter Notebook Integration
• API Reference

Contributing

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.

To set up for development:

1. Clone the repository:

   git clone https://github.com/ParticularlyPythonicBS/nx-vis-visualizer.git
   cd nx-vis-visualizer
   

2. Install dependencies using uv:

   uv sync --all-extras --dev
   uv pip install -e . --no-deps
   

3. Set up pre-commit hooks for code formatting and linting:

   uv run pre-commit install
   

4. Run tests:

   uv run pytest tests
   

Please ensure your contributions pass all tests and adhere to the coding style (enforced by pre-commit hooks).

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• NetworkX development team.
• vis.js Network library and its contributors.