PPI 蛋白互作网络分析

本 skill 封装 PPI 网络分析：从 STRING 数据库获取基因的蛋白互作网络，使用 NetworkX 计算多种中心性指标（类似 Cytoscape CytoNCA 插件），识别核心 Hub 基因，产出 Cytoscape 兼容文件、高清网络图和详细排名表。

定位

Use when
- 需要分析基因列表的蛋白互作网络
- 需要识别网络中的核心 Hub 基因
- 需要生成 Cytoscape 导入文件（TSV 格式）
- 需要计算网络拓扑指标（度、介数中心性、紧密中心性、特征向量中心性、PageRank）
- 用户提到 PPI 网络、蛋白互作、STRING、Hub 基因、核心基因、网络拓扑分析、CytoNCA

Do not use when
- 需要获取中药成分靶点 → 使用 Skill 1（tcmsp-ingredient-screening）
- 需要收集疾病靶点基因 → 使用 Skill 2（disease-target-collection）
- 需要做靶点交集分析 → 使用 Skill 3（target-intersection）
- 需要做 GO/KEGG 富集分析 → 使用 Skill 5（enrichment-analysis）
- 需要构建多层网络 → 使用 Skill 6（network-construction）

输入输出契约

契约要求
- hub_genes.txt 是下游契约文件，格式与 Skill 1-3 一致。
- ppi_network.tsv 可直接被 Cytoscape 导入。
- 所有产物直接位于输出目录，文件名固定。

运行模式

默认衔接模式

自动读取 Skill 3 产出的 intersection_genes.txt。

python3 $SKILL_DIR/scripts/run_ppi.py

独立运行模式

手动指定基因列表和输出参数。

python3 $SKILL_DIR/scripts/run_ppi.py --gene-list ./my_genes.txt
python3 $SKILL_DIR/scripts/run_ppi.py --gene-list ./my_genes.txt --hub-method pagerank --top-n 15 --confidence-score 0.5

⚠️ 常见参数错误

❌ 错误：使用位置参数

# 这样会报错！脚本不接受位置参数
python3 $SKILL_DIR/scripts/run_ppi.py np-output/intersection/intersection_genes.txt

✅ 正确：使用命名参数

# 必须使用 --gene-list 参数名
python3 $SKILL_DIR/scripts/run_ppi.py --gene-list np-output/intersection/intersection_genes.txt

✅ 或使用默认模式

# 不带参数时，自动读取默认路径
python3 $SKILL_DIR/scripts/run_ppi.py

工作流

用户输入（基因列表）
    ↓
┌─────────────────────────────────────┐
│ run_ppi.py (唯一脚本)                │
│ - 参数解析与验证                     │
│ - 读取基因列表                       │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ STRING API 调用                      │
│ - /api/tsv/network → TSV 数据       │
│ - /api/image/network → PNG 图片     │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ NetworkX 拓扑分析（CytoNCA 算法）     │
│ - 构建图对象                         │
│ - 计算 7 种中心性指标                │
│ - 序贯中位数过滤（DC→BC→CC→EC）       │
│ - Subgraph Centrality 排序            │
└─────────────────────────────────────┘
    ↓
产出：4 个文件（TSV + PNG + TXT + CSV）

运行约定

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

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

跨平台命令适配

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

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

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

# macOS/Linux 示例
python3 string-ppi-network/scripts/run_ppi.py

# Windows CMD 示例
python string-ppi-network\scripts\run_ppi.py

执行前检查

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

> 这是调用者/Agent 的操作规范，不是脚本内置交互保护；脚本本身可能直接覆盖同名输出文件。

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

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

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

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

Python 依赖检查

本 Skill 需要 NetworkX 包：

pip install networkx

脚本会自动检测 NetworkX 是否已安装，缺失时会提示安装命令并退出。

分步详解

唯一步骤：PPI 网络分析 (scripts/run_ppi.py)

用途： 一站式完成 STRING API 调用、NetworkX 拓扑分析、Hub 基因识别和数据导出。

前置条件：
- 基因列表文件（推荐 Skill 3 产出的 intersection_genes.txt）
- 网络可访问 https://string-db.org
- 已安装 NetworkX：pip install networkx

命令模板：

CLI 参数完整列表：

脚本行为：
1. 检查 NetworkX 是否已安装
2. 读取基因列表文件
3. 推导输出前缀（多级回退：用户指定 > 文件名推导 > "ppi_analysis"）
4. 创建输出子目录 {output_dir}/{prefix}/
5. 调用 STRING API /api/tsv/network 下载 TSV 数据
6. 调用 STRING API /api/image/network 下载高清 PNG 图片
7. 使用 NetworkX 解析 TSV，构建图对象
8. 计算 7 种中心性指标：Degree、Betweenness、Closeness、Eigenvector、PageRank、LAC、Subgraph Centrality
9. CytoNCA 多轮序贯过滤：每轮按指标中位数筛除下位 50%，依次经过 DC→BC→CC→EC（必要时继续用 LAC、Subgraph）
10. 按 Subgraph Centrality 排序，提取 Top N Hub 基因
11. 保存 Hub 基因列表（纯文本）和详细排名表（CSV）
12. 输出汇总和下一步建议

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

校验要点：
- 确认 TSV 文件已生成且行数 > 1（至少有表头 + 数据）
- 确认 PNG 文件大小 > 1 KB（有效图片）
- 确认 hub_genes.txt 包含 Top N 个基因
- 确认 hub_genes_ranked.csv 包含表头和 Top N 行数据

Hub 基因计算方法说明

本 Skill 使用 NetworkX 计算多种中心性指标，类似 Cytoscape CytoNCA 插件：

1. Degree（度中心性）

定义：节点的连接数（邻居数量）

适用场景：快速识别连接最多的基因

优点：计算简单，直观易懂

缺点：仅考虑直接连接，忽略网络全局结构

2. Betweenness（介数中心性）

定义：节点在多少条最短路径上（充当"桥梁"的能力）

适用场景：识别信息传递的关键节点

优点：捕捉全局拓扑重要性

缺点：计算复杂度高（O(n³)）

3. Closeness（紧密中心性）

定义：节点到其他所有节点的平均距离的倒数

适用场景：识别"中心位置"的基因

优点：反映节点在网络中的可达性

缺点：对断开的子图敏感

4. Eigenvector（特征向量中心性）

定义：节点的重要性取决于其邻居的重要性（递归定义）

适用场景：识别连接到其他重要节点的基因

优点：考虑邻居的质量而非数量

缺点：对有向图更适用，可能不收敛

5. PageRank

定义：Google 排名算法，模拟随机游走

适用场景：综合度数和邻居质量

优点：稳定收敛，适合大型网络

缺点：阻尼因子需调参

6. CytoNCA 迭代式子网络筛选（默认，推荐）

定义：完全模拟 Cytoscape CytoNCA 插件的迭代式子网络筛选流程

算法流程：

初始：全网络（N 个节点）
  │
  ▼ 第 1 轮迭代
  ├─ 计算当前网络的所有拓扑指标（DC, BC, CC, EC, LAC）
  ├─ 同时计算所有指标的中位值
  ├─ 并行筛选：保留同时满足所有指标 >= 中位值的基因
  ├─ 构建子网络（只保留通过筛选的基因及其连接）
  │
  ▼ 第 2 轮迭代（基于子网络）
  ├─ 重新计算子网络的拓扑指标（网络结构变化，指标值会变）
  ├─ 同时计算所有指标的中位值
  ├─ 并行筛选：保留同时满足所有指标 > 中位值的基因
  ├─ 构建更小的子网络
  │
  ▼ 第 N 轮迭代...
  └─ 直到剩余基因 <= 10 个或无法继续缩减

最终按 Subgraph Centrality 降序输出 Top N

停止条件：剩余基因数 ≤ 10 或本轮无缩减

关键特性：
1. 同时计算：每轮所有指标的 median 基于同一网络状态计算
2. 并行筛选：要求基因在所有指标上同时优秀（AND 逻辑）
3. 子网络重建：每轮用筛选后的基因重新构建子网络
4. 指标重新计算：Betweenness、Closeness 等依赖网络结构的指标会随子网络变化而更新

适用场景：网络药理学研究的核心靶点识别，与 Cytoscape CytoNCA 插件结果完全一致

优点：
- 确保胜出者在所有维度同时优秀（不会漏掉"某项极强但另一项中等"的基因）
- 子网络迭代捕捉相对重要性（在缩小的网络中重新评估）
- 与 Cytoscape 生态兼容，结果可复现
- Subgraph Centrality 作为最终排序指标，强调节点在全网络子闭途径中的参与度

缺点：
- 计算密集（每轮需重新计算所有拓扑指标）
- 需网络库支持 Subgraph Centrality 计算

完整运行示例

# 默认衔接模式（读取 Skill 3 产物）
python3 string-ppi-network/scripts/run_ppi.py

# 独立运行模式
python3 string-ppi-network/scripts/run_ppi.py \
    --gene-list ./my_genes.txt \
    --prefix alzheimer \
    --confidence-score 0.5 \
    --top-n 15 \
    --hub-method pagerank

# 仅查看 Top 20 Hub 基因（不保存）
python3 string-ppi-network/scripts/run_ppi.py --top-n 20

# 使用不同的 Hub 计算方法对比
python3 string-ppi-network/scripts/run_ppi.py --hub-method degree --prefix hub_degree
python3 string-ppi-network/scripts/run_ppi.py --hub-method betweenness --prefix hub_betweenness
python3 string-ppi-network/scripts/run_ppi.py --hub-method pagerank --prefix hub_pagerank

错误处理与恢复指南

> 严重级别说明：⚠️ 警告 = 非致命，继续执行；❌ 错误 = 当前步骤失败，修复后可重试。

执行检查清单

1. [ ] 检查残留文件 — 若输出子目录存在且有旧文件，提示用户确认
2. [ ] 确认输入数据 — 基因列表文件就绪（推荐 Skill 3 产物 intersection_genes.txt）
3. [ ] 确认环境 — pip install networkx
4. [ ] 运行 PPI 分析 — python3 $SKILL_DIR/scripts/run_ppi.py
5. [ ] 验证输出 — 4 个文件已生成（TSV + PNG + TXT + CSV）
6. [ ] 人工审核 — 检查 Top Hub 基因是否与疾病/药物机制相关
7. [ ] Cytoscape 导入测试 — 打开 Cytoscape，File → Import → Network from File → 选择 TSV
8. [ ] 下游衔接 — 使用 hub_genes.txt 运行 Skill 5 富集分析

资源组织

• scripts/ — 确定性脚本：
• run_ppi.py（唯一脚本，一站式完成所有功能）
• references/ — 暂无（参数表、API 细节保留在本 SKILL.md 中）
• assets/ — 暂无（本 Skill 无静态资源）

注意事项

• 仅支持人类（hsa/9606）：上游 Skill 1-2 均查询人类基因，保持一致性
• 基因符号格式：应为标准 HGNC 官方符号（如 TP53, IL6, TNF），STRING 会自动映射
• 置信度阈值选择：
• 0.15 (低) — 包含更多边，网络密集
• 0.4 (中，默认) — 平衡覆盖率和精度
• 0.7 (高) — 仅高可信边，网络稀疏
• 0.9 (极高) — 仅保留最高置信度互作关系（实验验证为主）
• Hub 方法选择建议：
• CytoNCA（默认）— 多轮序贯过滤，与 Cytoscape CytoNCA 插件一致，适合论文发表
• degree — 快速预览，解释直观
• pagerank — 适合大型网络（>100 节点）
• betweenness — 识别"桥梁"基因，适合模块化网络
• 网络要求：需要访问 https://string-db.org（STRING 官网），国内网络可能需要代理
• 幂等性：可重复运行，每次覆盖输出
• 下游分析衔接：hub_genes.txt 可直接作为 Skill 5（富集分析）的输入
• 与 Cytoscape 配合：导入 TSV 后，可在 Cytoscape 中进一步调整布局、样式、导出高质量图表

STRING API 参考

• 网络数据端点：https://string-db.org/api/tsv/network
• 图片端点：https://string-db.org/api/highres_image/network
• 官方文档：https://string-db.org/cgi/help?subpage=api
• 物种 ID：9606 (人类), 10090 (小鼠), 10116 (大鼠)
• 置信度评分说明：
• score: 综合评分（0-1）
• nscore: 邻域证据
• fscore: 基因融合证据
• pscore: 系统发生证据
• ascore: 共表达证据
• escore: 实验证据
• dscore: 数据库证据
• tscore: 文本挖掘证据

NetworkX 参考

• 官方文档：https://networkx.org/
• 中心性算法：https://networkx.org/documentation/stable/reference/algorithms/centrality.html
• 安装：pip install networkx
• 版本要求：≥ 2.5（Python 3.9+）