Skip to content

feat: add HIF format support for hypergraph export and import #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yifanfeng97 merged 1 commit into from
Nov 5, 2025
Merged

feat: add HIF format support for hypergraph export and import #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,12 @@ hg.save("my_hypergraph.hgdb")
hg2 = HypergraphDB(storage_file="my_hypergraph.hgdb")
print(hg2.all_v) # Output: {1, 2, 4, 5, 6, 7, 8, 9, 10}
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)}

# Or save in HIF format
hg.save_as_hif("my_hypergraph.hif.json")

# Load the hypergraph from a HIF file
hg.load_from_hif("my_hypergraph.hif.json")
```

#### **7. 🎨 Interactive Visualization**
Expand Down
34 changes: 29 additions & 5 deletions docs/api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,15 @@ The foundational base class that defines the core hypergraph structure and basic

### Persistence Operations

| Method | Description |
|--------|-------------|
| `save(filepath)` | Save hypergraph to file |
| `load(filepath)` | Load hypergraph from file |
| `copy()` | Create a deep copy of the hypergraph |
| Method | Description |
| ------------------------- | -------------------------------------------------- |
| `save(filepath)` | Save hypergraph to file |
| `load(filepath)` | Load hypergraph from file |
| `to_hif()` | Export to HIF (Hypergraph Interchange Format) JSON |
| `save_as_hif(filepath)` | Save hypergraph as HIF format JSON file |
| `from_hif(hif_data)` | Load hypergraph from HIF format data |
| `load_from_hif(filepath)` | Load hypergraph from HIF format JSON file |
| `copy()` | Create a deep copy of the hypergraph |

### Visualization

Expand Down Expand Up @@ -136,6 +140,26 @@ hg.add_e(("person1", "person2", "person3"), {
})
```

### HIF Format Import/Export

Hypergraph-DB supports HIF (Hypergraph Interchange Format) for standardized hypergraph data exchange.

#### Export to HIF Format

```python
# Export and save to file
hg.to_hif("my_hypergraph.hif.json")

# Or use save_as_hif method
hg.save_as_hif("my_hypergraph.hif.json")
```

#### Import from HIF Format

```python
hg.load_from_hif("my_hypergraph.hif.json")
```

## Error Handling

The API includes comprehensive error handling:
Expand Down
98 changes: 61 additions & 37 deletions docs/api/index.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,47 +39,51 @@ class CustomHypergraphDB(BaseHypergraphDB):

### 基础操作

| 方法 | 描述 | 示例 |
|------|------|------|
| `add_v(id, data)` | 添加顶点 | `hg.add_v("A", {"name": "Alice"})` |
| `add_e(tuple, data)` | 添加超边 | `hg.add_e(("A", "B"), {"type": "friend"})` |
| `remove_v(id)` | 移除顶点 | `hg.remove_v("A")` |
| `remove_e(tuple)` | 移除超边 | `hg.remove_e(("A", "B"))` |
| `v(id)` | 获取顶点数据 | `data = hg.v("A")` |
| `e(tuple)` | 获取超边数据 | `data = hg.e(("A", "B"))` |
| 方法 | 描述 | 示例 |
| -------------------- | ------------ | ------------------------------------------ |
| `add_v(id, data)` | 添加顶点 | `hg.add_v("A", {"name": "Alice"})` |
| `add_e(tuple, data)` | 添加超边 | `hg.add_e(("A", "B"), {"type": "friend"})` |
| `remove_v(id)` | 移除顶点 | `hg.remove_v("A")` |
| `remove_e(tuple)` | 移除超边 | `hg.remove_e(("A", "B"))` |
| `v(id)` | 获取顶点数据 | `data = hg.v("A")` |
| `e(tuple)` | 获取超边数据 | `data = hg.e(("A", "B"))` |

### 查询操作

| 方法 | 描述 | 示例 |
|------|------|------|
| `has_v(id)` | 检查顶点是否存在 | `hg.has_v("A")` |
| `has_e(tuple)` | 检查超边是否存在 | `hg.has_e(("A", "B"))` |
| `degree_v(id)` | 顶点度数 | `deg = hg.degree_v("A")` |
| `degree_e(tuple)` | 超边大小 | `size = hg.degree_e(("A", "B"))` |
| `nbr_v(id)` | 顶点的邻居顶点 | `neighbors = hg.nbr_v("A")` |
| `nbr_e_of_v(id)` | 顶点的邻居超边 | `edges = hg.nbr_e_of_v("A")` |
| `nbr_v_of_e(tuple)` | 超边的邻居顶点 | `vertices = hg.nbr_v_of_e(("A", "B"))` |
| 方法 | 描述 | 示例 |
| ------------------- | ---------------- | -------------------------------------- |
| `has_v(id)` | 检查顶点是否存在 | `hg.has_v("A")` |
| `has_e(tuple)` | 检查超边是否存在 | `hg.has_e(("A", "B"))` |
| `degree_v(id)` | 顶点度数 | `deg = hg.degree_v("A")` |
| `degree_e(tuple)` | 超边大小 | `size = hg.degree_e(("A", "B"))` |
| `nbr_v(id)` | 顶点的邻居顶点 | `neighbors = hg.nbr_v("A")` |
| `nbr_e_of_v(id)` | 顶点的邻居超边 | `edges = hg.nbr_e_of_v("A")` |
| `nbr_v_of_e(tuple)` | 超边的邻居顶点 | `vertices = hg.nbr_v_of_e(("A", "B"))` |

### 全局属性

| 属性 | 描述 | 示例 |
|------|------|------|
| 属性 | 描述 | 示例 |
| ------- | -------- | --------------------- |
| `all_v` | 所有顶点 | `vertices = hg.all_v` |
| `all_e` | 所有超边 | `edges = hg.all_e` |
| `num_v` | 顶点数量 | `count = hg.num_v` |
| `num_e` | 超边数量 | `count = hg.num_e` |
| `all_e` | 所有超边 | `edges = hg.all_e` |
| `num_v` | 顶点数量 | `count = hg.num_v` |
| `num_e` | 超边数量 | `count = hg.num_e` |

### 持久化操作

| 方法 | 描述 | 示例 |
|------|------|------|
| `save(path)` | 保存到文件 | `hg.save("graph.hgdb")` |
| `load(path)` | 从文件加载 | `hg.load("graph.hgdb")` |
| 方法 | 描述 | 示例 |
| ------------------------- | ------------------- | --------------------------------------------------------- |
| `save(path)` | 保存到文件 | `hg.save("graph.hgdb")` |
| `load(path)` | 从文件加载 | `hg.load("graph.hgdb")` |
| `to_hif(filepath=None)` | 导出为 HIF 格式 | `hif_data = hg.to_hif()` 或 `hg.to_hif("graph.hif.json")` |
| `save_as_hif(filepath)` | 保存为 HIF 格式文件 | `hg.save_as_hif("graph.hif.json")` |
| `from_hif(hif_data)` | 从 HIF 格式数据加载 | `hg.from_hif(hif_data)` 或 `hg.from_hif(json_string)` |
| `load_from_hif(filepath)` | 从 HIF 格式文件加载 | `hg.load_from_hif("graph.hif.json")` |

### 可视化

| 方法 | 描述 | 示例 |
|------|------|------|
| 方法 | 描述 | 示例 |
| -------------------------- | ---------- | -------------------- |
| `draw(port, open_browser)` | 启动可视化 | `hg.draw(port=8080)` |

[查看完整可视化 API →](visualization.zh.md)
Expand Down Expand Up @@ -144,6 +148,26 @@ updated_user = hg.v("user1")
updated_edge = hg.e(("user1", "user2"))
```

### HIF 格式导入导出

Hypergraph-DB 支持 HIF (Hypergraph Interchange Format) 格式，用于标准化的超图数据交换。

#### 导出到 HIF 格式

```python
# 导出并保存到文件
hg.to_hif("my_hypergraph.hif.json")

# 或者使用 save_as_hif 方法
hg.save_as_hif("my_hypergraph.hif.json")
```

#### 从 HIF 格式导入

```python
hg.load_from_hif("my_hypergraph.hif.json")
```

## 错误处理

### 常见异常
Expand All @@ -152,16 +176,16 @@ updated_edge = hg.e(("user1", "user2"))
try:
# 尝试添加顶点
hg.add_v("user1", {"name": "张三"})

# 尝试添加超边（顶点必须已存在）
hg.add_e(("user1", "user999"), {"type": "朋友"})

except AssertionError as e:
print(f"断言错误: {e}")

except KeyError as e:
print(f"键错误: {e}")

except Exception as e:
print(f"其他错误: {e}")
```
Expand Down Expand Up @@ -199,24 +223,24 @@ from hyperdb import HypergraphDB

class AnalyticsHypergraphDB(HypergraphDB):
"""扩展了分析功能的超图数据库"""

def clustering_coefficient(self, vertex_id: str) -> float:
"""计算顶点的聚类系数"""
neighbors = self.nbr_v(vertex_id)
if len(neighbors) < 2:
return 0.0

# 计算邻居之间的连接
connections = 0
total_possible = len(neighbors) * (len(neighbors) - 1) // 2

for edge in self.all_e:
edge_vertices = self.nbr_v_of_e(edge)
if len(edge_vertices.intersection(neighbors)) >= 2:
connections += 1

return connections / total_possible if total_possible > 0 else 0.0

def k_core_decomposition(self, k: int) -> Set[str]:
"""k-核分解：找出度数至少为k的顶点"""
return {v for v in self.all_v if self.degree_v(v) >= k}
Expand Down
Loading
Loading