多层网络构建与 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）

输入输出契约

| 项目 | 内容 | |------|------| | 任务输入 | 疾病名称（可选，默认自动推导）；--mode auto 时会根据 Skill 3 输出自动切换单/多疾病 | | 默认衔接输入 | Skill 1-5 的所有产物 | | 独立输入 | 通过参数指定各文件路径 | | 默认输出目录 | ./np-output/network/{disease}/ | | 最终产物 | {disease}_network.sif + {disease}_nodes.csv + {disease}_edges.csv + {disease}_full_network.json + {disease}_network_statistics.txt | | 可选产物 | {disease}_network_preview.png（高分辨率预览图） | | 下游衔接 | Cytoscape 导入（File → Import → Network from File） |

契约要求

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 路径：

| 安装方式 | Skill 位置 | 脚本前缀 | |----------|-----------|----------| | 项目内置 | {项目根}/network-construction/ | network-construction/scripts/ | | 项目级 Skill | {项目根}/.claude/skills/network-construction/ | .claude/skills/network-construction/scripts/ | | 全局 Skill | ~/.claude/skills/network-construction/ | ~/.claude/skills/network-construction/scripts/ |

网络结构定义

五层层级

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

节点类型

| 节点类型 | ID 格式 | 标签示例 | 核心属性 | |----------|---------|---------|---------| | herb | 拼音（如 Danggui） | 当归 | name_cn, pinyin | | ingredient | MOL_ID（如 MOL000098） | Quercetin | molecule_name, OB, DL | | target | Gene Symbol（如 TP53） | TP53 | degree, betweenness, hub_rank | | disease | slug（如 coronary_heart_disease） | Coronary Heart Disease | name, source | | pathway | KEGG ID（如 hsa04151） | PI3K-Akt signaling pathway | description, pvalue, FoldEnrichment |

边类型

| 边类型 | 方向 | 权重 | 核心属性 | |--------|------|------|---------| | contains | Herb → Ingredient | 1.0 | — | | targets | Ingredient → Target | 1.0 | — | | relates_to | Target → Disease | 1.0 | source_type (drug_target/disease_target) | | enriched_in | Target → Pathway | p-value | pvalue, FoldEnrichment |

运行约定

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

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

跨平台命令适配

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

| 平台 | Python 命令 | Skill 目录变量 | 示例 | |------|-------------|---------------|------| | macOS / Linux | python3 | $SKILL_DIR (bash/zsh) | python3 $SKILL_DIR/scripts/run_network.py | | Windows CMD | python | %SKILL_DIR% | python %SKILL_DIR%\scripts\run_network.py | | Windows PowerShell | python | $env:SKILL_DIR | python $env:SKILL_DIR/scripts/run_network.py |

注意： 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（可选）

命令模板：

| 场景 | 命令 | |------|------| | 默认（自动推导） | 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 --mode multi-disease --intersection-dir ./np-output/intersection/ | | 自动模式（默认） | python3 $SKILL_DIR/scripts/run_network.py --mode auto | | 自定义输出目录 | python3 $SKILL_DIR/scripts/run_network.py --output-dir ./my_network | | 包含 PPI 边 | python3 $SKILL_DIR/scripts/run_network.py --include-ppi | | 限制通路数量 | python3 $SKILL_DIR/scripts/run_network.py --top-pathways 15 | | 通路 p 值阈值 | python3 $SKILL_DIR/scripts/run_network.py --pvalue-cutoff 0.01 |

CLI 参数完整列表：

| 标志 | 类型 | 默认值 | 说明 | |------|------|--------|------| | --disease | str | 自动推导 | 疾病名称（用于文件命名和节点标签） | | --mode | str | auto | auto / single / multi-disease | | -o/--output-dir | str | ./np-output/network/ | 输出基础目录 | | --drug-targets | str | ./np-output/tcmsp/Drug_Targets.json | Skill 1 产物路径 | | --disease-targets-dir | str | ./np-output/disease/ | Skill 2 产物目录 | | --intersection-genes | str | ./np-output/intersection/intersection_genes.txt | Skill 3 产物路径 | | --intersection-dir | str | ./np-output/intersection/ | Skill 3 多疾病输出目录 | | --ppi-dir | str | ./np-output/ppi/ | Skill 4 产物目录 | | --enrichment-dir | str | ./np-output/enrichment/ | Skill 5 产物目录 | | --include-ppi | flag | off | 是否在网络中添加 PPI 边（默认不添加，避免过密） | | --top-pathways | int | 10 | 包含的 top KEGG 通路数量 | | --pvalue-cutoff | float | 0.05 | 通路的 p-value 阈值 | | --no-preview | flag | off | 跳过 PNG 预览图生成（需要 matplotlib） |

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

| 文件 | 说明 | |------|------| | {disease}_network.sif | Cytoscape SIF 文件（标准格式） | | {disease}_nodes.csv | 节点属性表（含所有节点的详细信息） | | {disease}_edges.csv | 边属性表（含所有边的权重和属性） | | {disease}_full_network.json | 完整网络 JSON 数据（供程序化使用） | | {disease}_network_statistics.txt | 统计报告（节点/边数量、拓扑统计、top hub 基因、核心通路） | | {disease}_network_preview.png | 高分辨率预览图（≥300 DPI，可选） | | cytoscape_import_guide.txt | Cytoscape 导入指南（用户说明） |

工作流程：

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

常见错误：

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | 缺少 Drug_Targets.json | ❌ 错误 | ❌ 未找到药物靶点文件 | 先运行 Skill 1 | | 缺少疾病靶点文件 | ❌ 错误 | ❌ 未找到疾病靶点文件 | 先运行 Skill 2 | | 缺少交集基因列表 | ❌ 错误 | ❌ 未找到交集基因列表 | 先运行 Skill 3 | | 交集基因列表为空 | ❌ 错误 | ❌ 交集基因列表为空 | 检查上游输出，确保交集不为空 | | 无法推导疾病名称 | ❌ 错误 | ❌ 无法自动推导疾病名称 | 使用 --disease 参数手动指定 | | Hub 基因文件缺失 | ⚠️ 警告 | ⚠️ 未找到 Hub 基因文件 | 非致命，靶点节点无拓扑属性 | | 富集结果缺失 | ⚠️ 警告 | ⚠️ 未找到富集结果 | 非致命，网络无通路层 | | matplotlib 未安装 | ⚠️ 警告 | ⚠️ matplotlib 未安装，跳过预览图 | pip install matplotlib 或使用 --no-preview |

校验要点：

确认 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": {}
    }
  ]
}

错误处理与恢复指南

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | Drug_Targets.json 不存在 | ❌ 错误 | ❌ 未找到药物靶点文件 | 先运行 Skill 1 完整管线 | | 疾病靶点文件不存在 | ❌ 错误 | ❌ 未找到疾病靶点文件 | 先运行 Skill 2 完整管线 | | intersection_genes.txt 不存在 | ❌ 错误 | ❌ 未找到交集基因列表 | 先运行 Skill 3 | | intersection_genes.txt 为空 | ❌ 错误 | ❌ 交集基因列表为空 | 检查上游输出，确保交集不为空 | | 无法推导疾病名称 | ❌ 错误 | ❌ 无法自动推导疾病名称 | 使用 --disease 参数手动指定 | | Hub 基因文件缺失 | ⚠️ 警告 | ⚠️ 未找到 Hub 基因文件 | 非致命，靶点节点无拓扑属性；可先运行 Skill 4 | | 富集结果缺失 | ⚠️ 警告 | ⚠️ 未找到富集结果 | 非致命，网络无通路层；可先运行 Skill 5 | | matplotlib 未安装 | ⚠️ 警告 | ⚠️ matplotlib 未安装 | pip install matplotlib 或使用 --no-preview | | networkx 未安装 | 💀 致命 | ImportError: No module named 'networkx' | pip install networkx | | pandas 未安装 | 💀 致命 | ImportError: No module named 'pandas' | pip install pandas |

执行检查清单

[ ] 检查残留文件 — 若输出目录存在且有旧文件，提示用户确认
[ ] 确认上游产物就绪 — 验证 Skill 1-5 的必需文件存在
[ ] 确认疾病名称 — 自动推导或手动指定
[ ] 确认参数 — 是否包含 PPI 边？top pathways 数量？p-value 阈值？
[ ] 运行网络构建 — python3 $SKILL_DIR/scripts/run_network.py
[ ] 验证输出 — 确认 SIF、CSV、JSON、统计报告均已生成
[ ] 人工审核 — 查看统计报告，确认节点/边数量合理
[ ] 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}/ 解析到项目根目录下

network-construction

多层网络构建与 Cytoscape 导出

定位

输入输出契约

运行模式

默认衔接模式

独立运行模式

工作流

运行约定

网络结构定义

五层层级

节点类型

边类型

运行约定

跨平台命令适配

执行前检查

分步详解

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

完整运行示例

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

场景 B：手动指定疾病

场景 C：多疾病模式

场景 D：自动模式

场景 E：自定义参数

场景 F：自定义输入路径

Cytoscape 导入指南

输出格式详细说明

SIF 文件格式

节点属性表（nodes.csv）

边属性表（edges.csv）

JSON 格式

错误处理与恢复指南

执行检查清单

资源组织

注意事项

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