Skip to content

Commit 4e9ff36

Browse files
yuxizheyuxizhe
committed
feat: add hypergraph visualization feature with interactive web interface
1 parent 3d0ce8c commit 4e9ff36

File tree

5 files changed

+915
-37
lines changed

5 files changed

+915
-37
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,3 +169,5 @@ cython_debug/
169169
# and can be added to the global gitignore or merged into this file. For a more nuclear
170170
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
171171
#.idea/
172+
173+
hyperdb/templates/data.js

‎README.md‎

Lines changed: 67 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<div align="center" id="top">
22
<img src="docs/_static/logo.svg" alt="Hyper DB" width="30%" height="50%" />
33

4-
&#xa0;
4+
&#xa0;
55

66
<!-- <a href="https://hyperdb.netlify.app">Demo</a> -->
77
</div>
@@ -30,9 +30,9 @@
3030

3131
<!-- Status -->
3232

33-
<!-- <h4 align="center">
33+
<!-- <h4 align="center">
3434
🚧 Hyper DB 🚀 Under construction... 🚧
35-
</h4>
35+
</h4>
3636
3737
<hr> -->
3838

@@ -48,7 +48,7 @@
4848

4949
<br>
5050

51-
## :dart: About
51+
## :dart: About
5252

5353
Hypergraph-DB is a lightweight, flexible, and Python-based database designed to model and manage **hypergraphs**—a generalized graph structure where edges (hyperedges) can connect any number of vertices. This makes Hypergraph-DB an ideal solution for representing complex relationships between entities in various domains, such as knowledge graphs, social networks, and scientific data modeling.
5454

@@ -73,15 +73,15 @@ This example demonstrates the efficiency of Hypergraph-DB, even when working wit
7373
The following table shows the results of stress tests performed on Hypergraph-DB with varying scales. The tests measure the time taken to add vertices, add hyperedges, and query vertices and hyperedges.
7474

7575
| **Number of Vertices** | **Number of Hyperedges** | **Add Vertices (s)** | **Add Edges (s)** | **Query Vertices (s/queries)** | **Query Edges (s/queries)** | **Total Time (s)** |
76-
|-------------------------|--------------------------|-----------------------|-------------------|-------------------------------|----------------------------|--------------------|
77-
| 5,000 | 1,000 | 0.01 | 0.01 | 0.00/2,000 | 0.01/2,000 | 0.02 |
78-
| 10,000 | 2,000 | 0.01 | 0.01 | 0.00/4,000 | 0.02/4,000 | 0.05 |
79-
| 25,000 | 5,000 | 0.03 | 0.04 | 0.01/10,000 | 0.05/10,000 | 0.13 |
80-
| 50,000 | 10,000 | 0.06 | 0.07 | 0.02/20,000 | 0.12/20,000 | 0.26 |
81-
| 100,000 | 20,000 | 0.12 | 0.17 | 0.04/40,000 | 0.24/40,000 | 0.58 |
82-
| 250,000 | 50,000 | 0.35 | 0.40 | 0.11/100,000 | 0.61/100,000 | 1.47 |
83-
| 500,000 | 100,000 | 0.85 | 1.07 | 0.22/200,000 | 1.20/200,000 | 3.34 |
84-
| 1,000,000 | 200,000 | 1.75 | 1.82 | 0.51/400,000 | 2.52/400,000 | 6.60 |
76+
| ---------------------- | ------------------------ | -------------------- | ----------------- | ------------------------------ | --------------------------- | ------------------ |
77+
| 5,000 | 1,000 | 0.01 | 0.01 | 0.00/2,000 | 0.01/2,000 | 0.02 |
78+
| 10,000 | 2,000 | 0.01 | 0.01 | 0.00/4,000 | 0.02/4,000 | 0.05 |
79+
| 25,000 | 5,000 | 0.03 | 0.04 | 0.01/10,000 | 0.05/10,000 | 0.13 |
80+
| 50,000 | 10,000 | 0.06 | 0.07 | 0.02/20,000 | 0.12/20,000 | 0.26 |
81+
| 100,000 | 20,000 | 0.12 | 0.17 | 0.04/40,000 | 0.24/40,000 | 0.58 |
82+
| 250,000 | 50,000 | 0.35 | 0.40 | 0.11/100,000 | 0.61/100,000 | 1.47 |
83+
| 500,000 | 100,000 | 0.85 | 1.07 | 0.22/200,000 | 1.20/200,000 | 3.34 |
84+
| 1,000,000 | 200,000 | 1.75 | 1.82 | 0.51/400,000 | 2.52/400,000 | 6.60 |
8585

8686
---
8787

@@ -92,6 +92,7 @@ The following table shows the results of stress tests performed on Hypergraph-DB
9292

9393
2. **Query Performance**:
9494
Querying vertices and hyperedges remains fast, even for large-scale hypergraphs. For instance:
95+
9596
- Querying **200,000 vertices** takes only **0.22 seconds**.
9697
- Querying **200,000 hyperedges** takes only **1.20 seconds**.
9798

@@ -102,30 +103,40 @@ This performance makes **Hypergraph-DB** a great choice for applications requiri
102103

103104
---
104105

105-
## :sparkles: Features
106+
## :sparkles: Features
106107

107-
:heavy_check_mark: **Flexible Hypergraph Representation**
108-
- Supports vertices (`v`) and hyperedges (`e`), where hyperedges can connect any number of vertices.
109-
- Hyperedges are represented as sorted tuples of vertex IDs, ensuring consistency and efficient operations.
108+
:heavy_check_mark: **Flexible Hypergraph Representation**
110109

111-
:heavy_check_mark: **Vertex and Hyperedge Management**
112-
- Add, update, delete, and query vertices and hyperedges with ease.
113-
- Built-in methods to retrieve neighbors, incident edges, and other relationships.
110+
- Supports vertices (`v`) and hyperedges (`e`), where hyperedges can connect any number of vertices.
111+
- Hyperedges are represented as sorted tuples of vertex IDs, ensuring consistency and efficient operations.
114112

115-
:heavy_check_mark: **Neighbor Queries**
116-
- Get neighboring vertices or hyperedges for a given vertex or hyperedge.
113+
:heavy_check_mark: **Vertex and Hyperedge Management**
117114

118-
:heavy_check_mark: **Persistence**
119-
- Save and load hypergraphs to/from disk using efficient serialization (`pickle`).
120-
- Ensures data integrity and supports large-scale data storage.
115+
- Add, update, delete, and query vertices and hyperedges with ease.
116+
- Built-in methods to retrieve neighbors, incident edges, and other relationships.
121117

122-
:heavy_check_mark: **Customizable and Extensible**
123-
- Built on Python’s `dataclasses`, making it easy to extend and customize for specific use cases.
118+
:heavy_check_mark: **Neighbor Queries**
124119

125-
---
120+
- Get neighboring vertices or hyperedges for a given vertex or hyperedge.
121+
122+
:heavy_check_mark: **Persistence**
123+
124+
- Save and load hypergraphs to/from disk using efficient serialization (`pickle`).
125+
- Ensures data integrity and supports large-scale data storage.
126+
127+
:heavy_check_mark: **Interactive Visualization**
126128

127-
## :rocket: Installation
129+
- Built-in web-based visualization tool with `draw()` method.
130+
- Interactive exploration of hypergraph structure, vertex properties, and relationships.
131+
- Real-time visualization that reflects the current state of your hypergraph.
128132

133+
:heavy_check_mark: **Customizable and Extensible**
134+
135+
- Built on Python's `dataclasses`, making it easy to extend and customize for specific use cases.
136+
137+
---
138+
139+
## :rocket: Installation
129140

130141
Hypergraph-DB is a Python library. You can install it directly from PyPI using `pip`.
131142

@@ -146,7 +157,7 @@ pip install -r requirements.txt
146157

147158
---
148159

149-
## :checkered_flag: Starting
160+
## :checkered_flag: Starting
150161

151162
This section provides a quick guide to get started with Hypergraph-DB, including iusage, and running basic operations. Below is an example of how to use Hypergraph-DB, based on the provided test cases.
152163

@@ -246,26 +257,45 @@ print(hg2.all_v) # Output: {1, 2, 4, 5, 6, 7, 8, 9, 10}
246257
print(hg2.all_e) # Output: {(4, 5, 7, 9), (9, 10), (1, 2, 7), (1, 2), (2, 6, 9), (1, 4, 6), (2, 5, 6)}
247258
```
248259

260+
#### **7. Visualization with draw()**
261+
262+
Hypergraph-DB includes a built-in visualization tool that allows you to interactively explore your hypergraph data through a web-based interface.
263+
264+
```python
265+
# Visualize the hypergraph in your browser
266+
hg.draw()
267+
```
268+
269+
The `draw()` function will:
249270

250-
---
271+
- Start a local web server (default port: 8080)
272+
- Automatically open your default web browser
273+
- Display an interactive visualization of your hypergraph
274+
- Show vertex degrees, relationships, and hyperedge information
275+
- Allow you to explore the graph structure visually
251276

277+
**Features of the visualization:**
252278

253-
## :memo: License
279+
- **Interactive HyperGraph View**: Navigate through vertices and hyperedges
280+
- **Vertex Information**: View vertex properties, degrees, and descriptions
281+
- **Hyperedge Details**: Explore hyperedge relationships and metadata
282+
- **Degree-based Sorting**: Vertices are sorted by degree for easy identification of important nodes
283+
- **Real-time Data**: The visualization reflects the current state of your hypergraph
254284

255-
Hypergraph-DB is open-source and licensed under the [Apache License 2.0](LICENSE). Feel free to use, modify, and distribute it as per the license terms.
285+
---
256286

287+
## :memo: License
288+
289+
Hypergraph-DB is open-source and licensed under the [Apache License 2.0](LICENSE). Feel free to use, modify, and distribute it as per the license terms.
257290

258291
---
259292

260-
## :email: Contact
293+
## :email: Contact
261294

262295
Hypergraph-DB is maintained by [iMoon-Lab](http://moon-lab.tech/), Tsinghua University. If you have any questions, please feel free to contact us via email: [Yifan Feng](mailto:[email protected]).
263296

264-
265297
Made with :heart: by <a href="https://github.com/yifanfeng97" target="_blank">Yifan Feng</a>
266298

267299
&#xa0;
268300

269301
<a href="#top">Back to top</a>
270-
271-

‎hyperdb/base.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,3 +283,20 @@ def stats(self) -> dict:
283283
Return basic statistics of the hypergraph.
284284
"""
285285
raise NotImplementedError
286+
287+
def draw(self, port: int = 8080, open_browser: bool = True):
288+
"""
289+
Draw the hypergraph data of the current HyperDB instance
290+
291+
Args:
292+
``port``: Server port number, defaults to 8080
293+
``open_browser``: Whether to automatically open the browser, defaults to True
294+
295+
"""
296+
from .draw import draw_hypergraph
297+
298+
return draw_hypergraph(
299+
hypergraph_db=self,
300+
port=port,
301+
open_browser=open_browser
302+
)

0 commit comments

Comments
 (0)