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）

输入输出契约

| 项目 | 内容 | |------|------| | 任务输入 | 基因列表文件（每行一个基因符号） | | 默认衔接输入 | ./np-output/intersection/intersection_genes.txt（Skill 3 产物） | | 独立输入 | 用户通过 --gene-list 提供任意基因列表 | | 默认输出目录 | ./np-output/ppi/ | | 最终产物 | 4 个文件：ppi_network.tsv、ppi_network.png、hub_genes.txt、hub_genes_ranked.csv | | 下游衔接 | hub_genes.txt 可用于 Skill 5 富集分析 |

契约要求

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

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

跨平台命令适配

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

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

注意： 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

命令模板：

| 场景 | 命令 | |------|------| | 默认（自动发现 Skill 3 输出） | 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 --output-dir ./my_output | | 调整置信度阈值 | python3 $SKILL_DIR/scripts/run_ppi.py --confidence-score 0.5 | | 选择 Hub 计算方法 | python3 $SKILL_DIR/scripts/run_ppi.py --hub-method pagerank --top-n 15 |

CLI 参数完整列表：

| 标志 | 类型 | 默认值 | 说明 | |------|------|--------|------| | --gene-list | str | ./np-output/intersection/intersection_genes.txt | 输入基因列表 | | -o/--output-dir | str | ./np-output/ppi/ | 输出目录 | | --confidence-score | float | 0.9 | STRING 置信度阈值（0-1，0.4=中等） | | --top-n | int | 10 | Hub 基因数量 | | --hub-method | str | CytoNCA | Hub 计算方法：CytoNCA/degree/betweenness/closeness/eigenvector/pagerank |

脚本行为：

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}/）：

| 文件 | 说明 | |------|------| | {prefix}_ppi_network.tsv | STRING TSV 格式网络数据，包含 stringId_A/B、preferredName_A/B、score、8 种子评分（nscore/fscore/pscore/ascore/escore/dscore/tscore）。Cytoscape 可直接导入 | | {prefix}_ppi_network.png | STRING 官方高清网络图片（confidence 风格），节点和边已布局优化 | | {prefix}_hub_genes.txt | Top N Hub 基因列表（纯文本，一行一个），下游 Skill 5 可直接使用 | | {prefix}_hub_genes_ranked.csv | Hub 基因详细排名表，包含 rank、gene、degree、degree_centrality、betweenness_centrality、closeness_centrality、eigenvector_centrality、subgraph_centrality、lac、pagerank、cytonca_score |

校验要点：

• 确认 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

---

错误处理与恢复指南

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | 基因列表缺失 | ❌ 错误 | ❌ 基因列表文件不存在 | 先运行 Skill 3（target-intersection） | | 基因列表为空 | ❌ 错误 | ❌ 基因列表为空 | 检查上游输出，确保交集不为空 | | NetworkX 未安装 | ❌ 错误 | ❌ NetworkX 未安装 | pip install networkx | | STRING API 不可用 | ❌ 错误 | ❌ 网络请求失败 | 检查网络连接；稍后重试 | | STRING TSV 返回过短 | ❌ 错误 | ❌ STRING API 返回数据过短 | 降低 --confidence-score；检查基因名是否标准 | | STRING 图片下载失败 | ⚠️ 警告 | ⚠️ 获取 STRING 图片失败 | 非致命，TSV 和 Hub 计算继续进行 | | 网络为空 | ❌ 错误 | ❌ 网络为空，无法计算 Hub | 降低置信度阈值；检查基因是否有 PPI 数据 | | 特征向量不收敛 | ⚠️ 警告 | ⚠️ 特征向量中心性计算未收敛 | 自动用 PageRank 替代，继续执行 | | Hub 基因数不足 | ⚠️ 警告 | Top N 大于节点总数 | 自动截断到实际节点数 |

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

---

执行检查清单

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+）