多层网络构建与 Cytoscape 导出

本 skill 封装网络药理学的最终整合步骤：读取 Skill 1-5 的所有产物，构建五层网络（中药→成分→靶点→疾病→通路），导出 Cytoscape 可直接导入的标准格式文件、JSON 全数据、统计报告和高分辨率预览图。

定位

Use when
- 需要整合所有上游分析结果，构建完整的网络药理学网络图
- 需要导出 Cytoscape 可编辑的网络文件
- 需要生成论文级的网络可视化图表
- 用户提到网络构建、多层网络、Cytoscape、网络可视化、中药-成分-靶点-疾病-通路网络

Do not use when
- 需要获取中药成分靶点 → 使用 Skill 1（tcmsp-ingredient-screening）
- 需要收集疾病靶点基因 → 使用 Skill 2（disease-target-collection）
- 需要做靶点交集韦恩图 → 使用 Skill 3（target-intersection）
- 需要做 PPI 网络分析 → 使用 Skill 4（string-ppi-network）
- 需要做 GO/KEGG 富集分析 → 使用 Skill 5（enrichment-analysis）

输入输出契约

契约要求
- SIF + CSV 文件必须符合 Cytoscape 标准格式
- 节点/边属性表必须包含完整的元数据（用于样式映射）
- 支持单疾病模式（当前实现）和多疾病模式（--mode multi-disease）；默认 --mode auto 会根据输入自动切换

运行模式

默认衔接模式

自动读取 Skill 1-5 产物，推导疾病名称。

python3 $SKILL_DIR/scripts/run_network.py

独立运行模式

手动指定疾病名称和输入路径。

python3 $SKILL_DIR/scripts/run_network.py --disease coronary_heart_disease
python3 $SKILL_DIR/scripts/run_network.py --disease diabetes_mellitus --output-dir ./my_network

工作流

[输入验证]
  ↓ 验证 Skill 1-5 产物存在性
  ↓ 推导疾病名称（从文件名或用户参数）
[网络构建] (network_builder.py)
  ↓ 读取 Drug_Targets.json → 添加 Herb/Ingredient/Target 三层
  ↓ 读取 {Disease}_Merged_Targets.json → 添加 Disease 层
  ↓ 读取 intersection_genes.txt → 筛选核心靶点
  ↓ 读取 hub_genes_ranked.csv → 添加拓扑属性
  ↓ 读取 kegg_enrichment.csv → 添加 Pathway 层
  ↓ 构建 networkx.DiGraph
[导出] (network_export.py)
  ↓ 导出 SIF 文件
  ↓ 导出节点/边属性表（CSV）
  ↓ 导出 JSON 全数据
[统计] (network_statistics.py)
  ↓ 生成统计报告
[可视化] (network_visualize.py, 可选)
  ↓ 生成 PNG 预览图

运行约定

始终从项目根目录运行脚本。 默认输出目录 ./np-output/network/ 解析到项目根目录下。

Skill 可能通过不同方式安装，命令模板统一使用 $SKILL_DIR 表示实际 Skill 路径：

网络结构定义

五层层级

[中药层 Herb]
  ↓ contains (中药-成分)
[成分层 Ingredient] [OB≥30, DL≥0.18]
  ↓ targets (成分-靶点)
[靶点层 Target] [药物靶点 ∩ 疾病靶点]
  ↓ relates_to (靶点-疾病)
[疾病层 Disease]
  ↓ enriched_in (靶点-通路)
[通路层 Pathway] [显著富集的 KEGG 通路, p<0.05]

节点类型

边类型

运行约定

始终从项目根目录运行脚本。 默认输出目录 ./np-output/network/ 解析到项目根目录下。

Skill 可能通过不同方式安装，命令模板统一使用 $SKILL_DIR 表示实际 Skill 路径：

跨平台命令适配

命令模板中的 python3 和 $SKILL_DIR 需要根据平台调整：

> 注意： Windows 通常只有 python 命令（没有 python3）。如果你的 Windows 环境安装了 python3 别名，也可以用 python3。

或者直接用绝对/相对路径替换 $SKILL_DIR：

# macOS/Linux 示例
python3 network-construction/scripts/run_network.py

# Windows CMD 示例
python network-construction\scripts\run_network.py

执行前检查

在运行脚本之前，必须先检查输出目录是否已存在且有内容。

首先确定本次使用的输出目录（用户指定了 --output-dir 就用自定义目录，否则用默认的 ./np-output/network/{disease}/）。

如果输出目录存在且包含上次执行的结果文件，说明上次执行有残留输出。此时应提示用户：

> ⚠️ 检测到 {输出目录}/ 中已有上次执行的结果文件：
> - {列出文件}
>
> 是否删除这些文件重新开始？
>
> - 删除并重新开始（推荐）
> - 保留现有文件

• 若用户选择删除：删除该输出目录中的所有文件
• 若用户选择保留：跳过执行
• 若目录不存在或目录为空：直接开始执行

分步详解

唯一步骤：网络构建 (scripts/run_network.py)

用途： Python 主入口，验证输入、推导疾病名称、编排子模块

前置条件：
- Skill 1 产物：./np-output/tcmsp/Drug_Targets.json
- Skill 2 产物：./np-output/disease/{Disease}_Merged_Targets.json
- Skill 3 产物：./np-output/intersection/intersection_genes.txt
- Skill 4 产物：./np-output/ppi/{prefix}_hub_genes_ranked.csv（可选）
- Skill 5 产物：./np-output/enrichment/{prefix}_kegg_enrichment.csv（可选）

命令模板：

CLI 参数完整列表：

输出文件（位于 {output_dir}/{disease}/）：

工作流程：
1. 验证所有必需输入文件存在
2. 推导疾病名称（从 disease_targets_dir 中的文件名或用户参数）
3. 调用 network_builder.py 构建 networkx.DiGraph
4. 调用 network_export.py 导出 SIF + CSV + JSON
5. 调用 network_statistics.py 生成统计报告
6. 调用 network_visualize.py 生成 PNG 预览图（可选）
7. 生成 Cytoscape 导入指南

常见错误：

校验要点：
- 确认 SIF 文件已生成且格式正确（三列：source [tab] interaction [tab] target）
- 确认 nodes.csv 和 edges.csv 已生成且含完整属性
- 确认 JSON 文件已生成且结构完整
- 检查统计报告中的节点/边数量是否合理

完整运行示例

场景 A：默认模式（推荐）

# 前提：已完成 Skill 1-5
python3 network-construction/scripts/run_network.py
# 自动推导疾病名称，输出到 ./np-output/network/{disease}/

场景 B：手动指定疾病

python3 network-construction/scripts/run_network.py --disease coronary_heart_disease

场景 C：多疾病模式

python3 network-construction/scripts/run_network.py \
    --mode multi-disease \
    --intersection-dir ./np-output/intersection/

场景 D：自动模式

python3 network-construction/scripts/run_network.py --mode auto

场景 E：自定义参数

python3 network-construction/scripts/run_network.py \
    --disease diabetes_mellitus \
    --top-pathways 15 \
    --pvalue-cutoff 0.01 \
    --include-ppi

场景 F：自定义输入路径

python3 network-construction/scripts/run_network.py \
    --drug-targets ./my_data/Drug_Targets.json \
    --disease-targets-dir ./my_data/disease/ \
    --intersection-genes ./my_data/intersection_genes.txt \
    --output-dir ./my_network/

Cytoscape 导入指南

生成的 cytoscape_import_guide.txt 文件内容：

=== Cytoscape 导入指南 ===

1. 打开 Cytoscape（推荐版本 ≥ 3.9.0）

2. 导入网络：
   File → Import → Network from File
   选择: {disease}_network.sif
   格式: SIF (Simple Interaction Format)

3. 导入节点属性表：
   File → Import → Table from File
   选择: {disease}_nodes.csv
   Import Data as: Node Table Columns
   Key Column: id

4. 导入边属性表：
   File → Import → Table from File
   选择: {disease}_edges.csv
   Import Data as: Edge Table Columns
   Key Column: 选择第一列（source-target pair）

5. 应用布局：
   Layout → Hierarchical Layout（推荐）
   或 Layout → Prefuse Force Directed Layout

6. 样式映射建议：
   - 节点颜色：按 node_type 映射
     Herb: 绿色 (#4CAF50)
     Ingredient: 蓝色 (#2196F3)
     Target: 红色 (#F44336)
     Disease: 紫色 (#9C27B0)
     Pathway: 橙色 (#FF9800)

   - 节点大小：按 degree 映射（仅 Target 节点）

   - 边颜色：按 interaction 映射
     contains: 绿色
     targets: 蓝色
     relates_to: 紫色
     enriched_in: 橙色

   - 边宽度：按 weight 映射

7. 导出高分辨率图片：
   File → Export → Network as Image
   格式: PNG/PDF
   分辨率: ≥300 DPI

输出格式详细说明

SIF 文件格式

SourceNode [tab] InteractionType [tab] TargetNode

示例：

Danggui contains    MOL000098
MOL000098   targets TP53
TP53    relates_to  coronary_heart_disease
TP53    enriched_in hsa04151

节点属性表（nodes.csv）

基础列（所有节点）：

id,node_type,label,description

扩展列（按节点类型）：
- Herb: name_cn, pinyin
- Ingredient: MOL_ID, molecule_name, OB, DL
- Target: degree, betweenness, closeness, hub_rank
- Disease: name, source
- Pathway: pathway_id, description, pvalue, p.adjust, FoldEnrichment, GeneRatio, Count

边属性表（edges.csv）

基础列（所有边）：

source,target,interaction,weight

扩展列（按边类型）：
- relates_to: source_type (drug_target/disease_target)
- enriched_in: pvalue, FoldEnrichment
- interacts_with（仅当 --include-ppi 时）: combined_score

JSON 格式

{
  "metadata": {
    "disease": "Coronary Heart Disease",
    "disease_slug": "coronary_heart_disease",
    "herbs": ["Danggui", "Chuanxiong"],
    "num_herbs": 2,
    "num_ingredients": 45,
    "num_targets": 128,
    "num_diseases": 1,
    "num_pathways": 10,
    "generated_at": "2026-06-26T10:30:00"
  },
  "nodes": [
    {
      "id": "TP53",
      "type": "target",
      "label": "TP53",
      "properties": {
        "degree": 95,
        "betweenness": 0.123,
        "hub_rank": 1
      }
    }
  ],
  "edges": [
    {
      "source": "MOL000098",
      "target": "TP53",
      "type": "targets",
      "weight": 1.0,
      "properties": {}
    }
  ]
}

错误处理与恢复指南

执行检查清单

1. [ ] 检查残留文件 — 若输出目录存在且有旧文件，提示用户确认
2. [ ] 确认上游产物就绪 — 验证 Skill 1-5 的必需文件存在
3. [ ] 确认疾病名称 — 自动推导或手动指定
4. [ ] 确认参数 — 是否包含 PPI 边？top pathways 数量？p-value 阈值？
5. [ ] 运行网络构建 — python3 $SKILL_DIR/scripts/run_network.py
6. [ ] 验证输出 — 确认 SIF、CSV、JSON、统计报告均已生成
7. [ ] 人工审核 — 查看统计报告，确认节点/边数量合理
8. [ ] Cytoscape 导入测试 — 按导入指南在 Cytoscape 中加载网络

资源组织

• scripts/ — 确定性脚本和模块化组件：
• run_network.py（主入口，参数解析、输入验证、编排）
• network_builder.py（网络构建逻辑，读取 Skill 1-5 产物，构建 networkx 图）
• network_export.py（导出模块，SIF、CSV、JSON）
• network_statistics.py（统计模块，生成统计报告）
• network_visualize.py（可视化模块，生成 PNG 预览图）
• references/ — 暂无（参数表、格式规范保留在本 SKILL.md 中）
• assets/ — 暂无（本 Skill 无静态资源）

注意事项

• 依赖最小化：仅依赖 networkx、pandas（标准数据科学包），matplotlib 可选（仅用于预览图）
• Cytoscape 兼容性：SIF + CSV 格式经过 Cytoscape 3.9.0 测试，完全兼容
• 多疾病支持：当前实现单疾病模式，预留多疾病接口（未来通过 --mode multi-disease 启用）
• PPI 边可选：默认不添加 PPI 边（避免网络过密），通过 --include-ppi 启用
• 通路层可选：如果 Skill 5 未运行或无显著富集结果，网络自动退化为四层（无通路层）
• Hub 基因属性可选：如果 Skill 4 未运行，靶点节点无拓扑属性（degree、betweenness 等）
• 自动降级：缺少可选输入时，脚本不报错，自动跳过对应功能并打印警告
• 幂等性：可重复运行，每次覆盖输出
• 输出目录位置：始终从项目根目录运行，默认输出 ./np-output/network/{disease}/ 解析到项目根目录下