Graph Explorer (RS) 🚀

A Neo4J-like graph visualization tool built in Rust that allows you to discover relationships in CSV data through an interactive web interface. The tool uses a (localhost) browser to display graphs created from CSV data files, enabling users to explore connections, analyze paths, and visualize data relationships easily.

I created this project to perform some quick and easy graph visualizations of CSV data for research purposes.

I thought that the existing tools were either too complex, required heavy installations, or lacked the necessary interactivity that I thought was important for the project. Thus, I developed Graph Explorer to fill this gap, providing a lightweight and user-friendly solution for visualizing and analyzing graph data directly from CSV files.

There are still many features to be added, but the core functionality is present and usable. I hope this tool proves useful to others facing similar challenges when working with graphs and graph visualization.

Oliver Bonham-Carter, web

Email: obonhamcarter at allegheny.edu

Date: 29 November 2025

Features ✨

Core Functionality

📁 CSV Loading: Load CSV files via command line or web interface
🏗️ Graph Creation: Convert CSV data into interactive graphs with customizable relationships
🌐 Web Interface: Modern, responsive interface with D3.js visualizations
⚡ Physics Engine: Configurable node attraction/repulsion forces with real-time controls
🔍 Analysis Tools: Shortest path finding, graph statistics, and adjacency matrix export
💾 Data Persistence: Save graphs in multiple formats (JSON, GraphML, CSV)

Visualization Features

Interactive Controls: Zoom, pan, select, and manipulate nodes
Multiple Layouts: Force-directed, circular, and hierarchical layouts
Physics Controls: Real-time adjustment of link strength, repulsion, and distance
Path Highlighting: Visual shortest path display with persistent results panel
Collapsible UI: Organized sidebar panels for cleaner workspace

Graph Operations

CRUD Operations: Create, read, update, delete nodes and relationships
Real-time Updates: Dynamic graph updates based on user selections
Node Analysis: Degree analysis, clustering coefficients, centrality measures
Export Capabilities: Multiple export formats with metadata preservation

Installation & Setup 🛠️

Special Note: The following commands have been tested on a MacOS system with Rust 1.85.0 installed. Some testing has also been conducted on a Linux (Ubuntu 22.4) machine. The project has not been tested on a Windows machine. You will have to determine how to run the following commands if you are using Windows.

Adjust commands as necessary for your operating system.

Prerequisites

Rust (1.70 or later)
A modern web browser

Quick Start

Clone and build the project:

git clone <repository-url>
cd graph_explorer
cargo build --release

Run with a CSV file:

cargo run -- --csv-file data/sample.csv

Or start the server without pre-loading data:

cargo run

Or, use the main Launch command:

sh launch.sh

Open your browser:
- Navigate to http://localhost:3000
- Use the web interface to load and explore your CSV data

Command Line Options

Usage: graph_explorer [OPTIONS]

Options:
  -c, --csv-file <CSV_FILE>    CSV file path to load
  -p, --port <PORT>            Port to run the web server on [default: 3000]
  -s, --static-only            Generate static files only (no server)
  -h, --help                   Print help
  -V, --version                Print version

Usage Guide 📖

1. Loading CSV Data

Option A: Command Line

cargo run -- --csv-file your_data.csv

Option B: Web Interface

Click "📁 Load CSV" button
Select your CSV file
Review the data summary

2. Building Your Graph

Select ID Column: Choose the column that uniquely identifies each row
Select Label Column: Choose the column to display as node labels
Select Relationship Columns: Choose columns that define relationships between nodes
Click "🔄 Build Graph": Generate the interactive visualization

Example CSV Structure

id,name,department,location,role
1,Alice,Engineering,New York,Developer
2,Bob,Engineering,New York,Manager
3,Charlie,Marketing,Los Angeles,Analyst
4,Dave,Marketing,Los Angeles,Manager

This creates connections between people in the same department or location.

3. Exploring Your Graph

Physics Controls ⚡

The Graph Explorer features comprehensive physics controls that allow you to fine-tune the graph layout and behavior in real-time. Both the main application and exported HTML files include identical physics control functionality.

Physics Toggle Panel

Hide/Show Panel: Click the "Hide"/"Show" button in the physics panel header to smoothly collapse or expand the entire control panel
- Panel slides in/out with smooth CSS transitions
- Button text automatically updates between "Hide" and "Show"
- When hidden, only the panel header remains visible
Show Physics Panel Button: Main control bar includes a dedicated "⚙️ Show Physics Panel" button for easy access
Complete Physics Control: Prominent physics toggle button completely enables or disables the physics simulation
- ✅ Physics Enabled (Green): Full D3.js force simulation with automatic node positioning
- ❌ Physics Disabled (Red): Physics simulation completely stops - all forces removed, nodes draggable without attraction
- State Synchronization: Both main toggle and panel toggle update together
- Visual Feedback: Controls are greyed out when physics is disabled

Advanced Physics Parameters

Gravity Strength (0.0 - 1.0): Controls overall center attraction force
Link Distance (20 - 200): Sets the preferred distance between connected nodes
Link Strength (0.1 - 2.0): Adjusts the stiffness of connections between nodes
Node Size (3 - 30): Controls the visual radius of nodes and affects collision detection
Collision Radius (0 - 50): Sets boundaries for node collision detection
Center Force (0.0 - 1.0): Adjusts attraction strength toward the graph center

Quick Actions

📐 Fit to Screen: Auto-zoom to fit all nodes in the viewport
🎯 Center Graph: Reset view to center position with default zoom
🔄 Re-render: Restart the physics simulation with current parameters

Preset Configurations

Quickly apply optimized physics settings for different use cases:

Tight: Dense, compact layout with strong connections (ideal for small, highly connected graphs)
Loose: Spread out, relaxed layout with weak forces (ideal for large graphs with many nodes)
Circular: Radial arrangement with strong center force (ideal for hub-and-spoke patterns)
Linear: Elongated layout with minimal center force (ideal for sequential or timeline data)

Physics Behavior

Real-time Updates: All physics parameters update immediately as you adjust sliders
Visual Feedback: Slider values are displayed and update in real-time
Persistent Settings: Physics settings are maintained until manually changed
Manual Override: When physics is disabled, manual node positioning is preserved
Smooth Transitions: Layout changes animate smoothly for better user experience

Export Consistency

The exported HTML files include the same comprehensive physics controls as the main application:

Identical Interface: Exact same physics panel layout, styling, and functionality
Enhanced Hide/Show Toggle: Panel can be collapsed/expanded in exported visualizations with smooth animations
Complete Physics Control: Full on/off toggle functionality that completely removes all D3.js forces when disabled
All Parameters: Every physics control (gravity, link distance/strength, node size, collision, center force) available in exported files
Preset Support: All preset configurations (Tight, Loose, Circular, Linear) work identically in exported visualizations
Standalone Operation: Exported HTML files work completely offline without external dependencies
Main Control Integration: Both main "Physics ON/OFF" button and "Show Physics Panel" button included in exported controls
State Management: Physics enabled/disabled state properly synchronized across all controls in exports
Professional Quality: Print-ready visualizations suitable for presentations, reports, and sharing

Layout Options 🎨

Force Layout: Physics-based automatic positioning
Circular Layout: Nodes arranged in a circle
Hierarchical Layout: Nodes grouped by connectivity

Graph Controls 🎯

Zoom In/Out: Scale the visualization
Reset View: Return to default zoom and position
Toggle Labels: Show/hide node labels

4. Graph Analysis 🔍

Shortest Path Analysis

Select source and target nodes from dropdowns
Click "🔍 Find Shortest Path"
View highlighted path and results in the green panel

Graph Statistics

Click "📈 Graph Statistics" to see:
- Node and edge counts
- Connected components
- Average degree
- Graph density

Export Options

📊 Export Adjacency Matrix: Download as CSV
💾 Save Graph: Save in JSON, GraphML, or CSV format
📄 Export HTML (Vis.js): Export standalone HTML with Vis.js visualization
📄 Export HTML (D3.js): Export standalone HTML with D3.js visualization and full physics controls
🖼️ Export PNG: Save current graph view as PNG image

Enhanced HTML Export Features

The D3.js HTML export includes all the advanced features from the main application:

Complete Physics Panel: Full physics controls with enhanced hide/show toggle functionality
Identical Interface: Exact same layout, styling, and functionality as the main application
Standalone Operation: Works completely offline without external dependencies or internet connection
Embedded Data: Graph data is embedded directly in the HTML file for portability
Interactive Controls: All zoom, pan, selection, physics, and preset features included
Professional Quality: Print-ready visualizations suitable for presentations, reports, and sharing
Physics On/Off Toggle: Complete physics simulation control with visual state feedback
Main Control Buttons: All main control bar buttons including "Physics ON/OFF" and "Show Physics Panel"
Real-time Physics: All physics parameters work identically to the main application
Smooth Animations: Panel hide/show transitions and physics changes animate smoothly

5. Interactive Features

Node Operations

Click: Select/deselect nodes
Double-click: Focus and zoom to node
Drag: Move nodes manually
Delete key: Remove selected nodes

Results Panel

Analysis results appear in a persistent green panel
💾 Save Results: Export analysis to text file
✖️ Close: Hide results panel

Architecture 🏗️

The project follows a modular architecture. The main components are organized as follows:

src/
├── main.rs           # Entry point and CLI handling
├── csv_loader.rs     # CSV parsing and validation
├── graph.rs          # Graph data structures and operations
├── analysis.rs       # Graph algorithms and analysis
├── visualization.rs  # Static file generation
├── web_server.rs     # HTTP server and API endpoints
├── database.rs       # Data persistence and CRUD operations
└── errors.rs         # Error handling

Key Components

Graph Module: Uses petgraph for efficient graph operations
Web Server: Axum-based REST API with multipart file upload
Visualization: D3.js for interactive graph rendering
Analysis: Implements shortest path, statistics, and matrix operations
Persistence: Multiple export formats with proper metadata

API Endpoints 🌐

Core Operations

POST /api/upload-csv - Upload CSV file
POST /api/build-graph - Create graph from CSV data
GET /api/graph-stats - Get graph statistics
POST /api/shortest-path - Find shortest path between nodes
GET /api/adjacency-matrix - Export adjacency matrix
POST /api/save-graph - Save graph in specified format

Request Examples

Build Graph:

POST /api/build-graph
{
  "id_column": "id",
  "label_column": "name", 
  "relationship_columns": ["department", "location"]
}

Find Shortest Path:

POST /api/shortest-path
{
  "source_id": "1",
  "target_id": "4"
}

File Formats 📁

Supported Import Formats

CSV: Comma-separated values with headers

Supported Export Formats

JSON: Graph data with full metadata
GraphML: Standard graph markup language
CSV: Separate node and edge files
SVG: Vector graphics export (from UI)

Configuration ⚙️

Default Ports

Web Server: 3000
Static Files: Served from /static/
Exports: Saved to /exports/

Physics Defaults

Link Strength: 1.0
Node Repulsion: 300
Link Distance: 80

Troubleshooting 🔧

Common Issues

CSV Loading Fails

Ensure UTF-8 encoding
Check for proper headers
Verify comma separation

Graph Not Displaying

Check browser console for errors
Ensure CSV has been loaded
Verify column selections are valid

Performance Issues

Large graphs (>1000 nodes) may be slow
Disable physics for manual positioning
Use filtering to reduce visible nodes

Build Errors

Ensure Rust 1.70+
Run cargo clean && cargo build
Check dependency versions

Debug Mode

Run with detailed logging:

RUST_LOG=debug cargo run

Testing 🧪

Graph Explorer includes a comprehensive test suite to ensure code reliability and correctness. The project has 43 unit tests covering all major modules and functionality.

The following testing instructions are provided for completeness. A variety of tests are included to cover some of the different aspects of the project. You can run the tests using the below commands.

Running the Tests Using Runner Scripts

We provide a convenient test runner script for easy testing:

# Run all tests
./run_tests.sh

# Run tests in quiet mode
./run_tests.sh quick

# Run specific test modules
./run_tests.sh csv
./run_tests.sh graph
./run_tests.sh analysis
./run_tests.sh database
./run_tests.sh errors

# Generate coverage report
./run_tests.sh coverage

# Show help
./run_tests.sh help

Manual Test Commands

Run All Tests

cargo test

Run Tests with Output

cargo test -- --show-output

Run Specific Test Module

# Test CSV loading functionality
cargo test test_csv_loader

# Test graph operations
cargo test test_graph

# Test analysis algorithms
cargo test test_analysis

# Test database operations
cargo test test_database

# Test error handling
cargo test test_errors

Run Tests with Coverage Information

# Install cargo-tarpaulin for coverage reports
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --out Html

Test Modules

The test suite is organized into the following modules:

📊 CSV Loader Tests (`tests/test_csv_loader.rs`)

File loading and parsing
Column validation
Data integrity checks
Error handling for malformed files
7 tests covering data input/output operations

🕸️ Graph Tests (`tests/test_graph.rs`)

Graph construction and manipulation
Node and edge operations
Graph data conversion
CSV-to-graph conversion
9 tests covering core graph functionality

🔍 Analysis Tests (`tests/test_analysis.rs`)

Shortest path algorithms
Graph statistics calculation
Adjacency matrix generation
Node analysis and centrality
8 tests covering analytical algorithms

💾 Database Tests (`tests/test_database.rs`)

JSON/GraphML/CSV export/import
Graph serialization and deserialization
Data persistence operations
10 tests covering data storage operations

⚠️ Error Tests (`tests/test_errors.rs`)

Error type conversions
Error handling chains
Custom error messages
9 tests covering error handling

Test Data

Tests use temporary files and in-memory data structures to avoid external dependencies. Each test is isolated and creates its own test data as needed.

Writing New Tests

When adding new functionality, please include tests that cover:

Happy Path: Normal operation with valid inputs
Edge Cases: Boundary conditions and unusual inputs
Error Cases: Invalid inputs and error conditions
Integration: How the feature works with existing code

Example test structure:

#[test]
fn test_new_feature() {
    // Arrange - set up test data
    let test_data = create_test_data();
    
    // Act - call the function being tested
    let result = my_function(test_data);
    
    // Assert - verify the result
    assert!(result.is_ok());
    assert_eq!(result.unwrap().expected_field, expected_value);
}

Continuous Integration

The test suite runs automatically on:

Every commit to main branch
Pull request submissions
Release builds

All tests must pass before code can be merged.

Contributing 🤝

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

Development Guidelines

Follow Rust best practices
Add documentation for public APIs
Include error handling
Write unit tests for algorithms

Roadmap 🗺️

A Feature Wish List

Below is a list of implementation ideas and features planned for a future releases.

Directional Edges: Support for directed graphs
Advanced Layouts: More sophisticated positioning algorithms
Node Clustering: Collapse high-degree nodes
Real-time Collaboration: Multi-user graph editing
Plugin System: Custom analysis modules
Database Integration: Direct database connectivity
Advanced Filtering: Query-based node/edge filtering

Performance Improvements

WebAssembly Integration: Move heavy computations to WASM
Streaming Data: Handle large datasets efficiently
Caching: Persistent graph state between sessions

Acknowledgments 🙏

D3.js for powerful visualization capabilities
petgraph for efficient graph algorithms
Axum for the modern web framework
Neo4j for inspiration on graph interfaces

License

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

Contributing

Contributions are welcome! If you have ideas for improvements or want to add more features, feel free to open an issue or submit a pull request.

A Work In Progress

Check back often to see the evolution of the project! This project is a work-in-progress. Updates will come periodically.

If you would like to contribute to this project, please do! For instance, if you see some low-hanging fruit or tasks that could add value to the project, I would love to have your insight.

Otherwise, please create an issue for bugs or errors. Since I am a teaching faculty member at Allegheny College, I may not have all the time necessary to quickly fix bugs. I welcome the Open Source Community to further the development of this project. Much thanks in advance.

If you appreciate this project, please consider clicking the project's Star button. :-)

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github		.github
graphics		graphics
sample_data		sample_data
src		src
templates		templates
tests		tests
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md
launch.sh		launch.sh
run_tests.sh		run_tests.sh

Uh oh!

developmentAC/graph_explorer_rs

Folders and files

Latest commit

History

Repository files navigation