靶点交集分析

本 skill 封装靶点交集分析：加载 Skill 1（药物靶点）和 Skill 2（各疾病靶点）产出的基因列表，自动发现所有疾病基因文件，计算多集合全交集（药物 ∩ 疾病A ∩ 疾病B ∩ ...）。提供两种韦恩图方法：

• html（默认，无需 R）：交互式 HTML 页面，支持点击查看基因、搜索、统计、CSV 导出
• r（需 R）：ggVennDiagram + ggplot2，PDF 矢量格式，医学期刊风格

两种方法均输出 intersection_genes.txt + 韦恩图产物；html 方法输出交互式 HTML，r 方法输出 PDF 矢量格式。

定位

Use when
- 需要计算药物靶点与疾病靶点的交集（多集合全交集）
- 需要绘制韦恩图（Venn diagram）展示靶点重叠
- 用户提到靶点交集、基因交集、韦恩图、药物疾病共同靶点、交集分析、Venn diagram
- 已有 Skill 1 和 Skill 2 的产物，想进入下游分析

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

输入输出契约

契约要求
- 两种方法均须产出 intersection_genes.txt（全交集基因列表），用于下游 Skill 4/5 衔接。
- html 方法额外产出 html/intersection_venn.html；r 方法额外产出 intersection_venn.pdf。
- 两种方法上限均为 6 个集合。
- 默认 --output-mode auto：发现 1 个疾病时按 single 输出；发现 2 个及以上疾病时自动按 multi-disease 输出。
- multi-disease 输出包括 drug_{disease}.txt、{disease}_specific_genes.txt、shared_genes.txt 和 multi_disease_report.txt。

运行模式

默认衔接模式

自动发现 ./np-output/ 中的 Skill 1/2 产物，计算多集合全交集。

python3 $SKILL_DIR/scripts/run_intersection.py

当疾病目录中已有 osteoporosis_Gene_List.txt 和 depression_Gene_List.txt 这类多个疾病列表时，默认命令会自动启用多疾病输出；例如“强骨温阳汤（杜仲、茯苓、牛膝、山药、山茱萸、淫羊藿、泽泻）治疗骨质疏松症 + 抑郁症网络药理学”场景无需手动追加 --output-mode multi-disease。

独立运行模式

手动指定药物基因列表和疾病目录。

python3 $SKILL_DIR/scripts/run_intersection.py --drug-list ./my_drug.txt --disease-dir ./my_disease/
# 或切换方法/配色
python3 $SKILL_DIR/scripts/run_intersection.py --method r --palette viridis

工作流

html 路径: Python 读取基因 → 计算交集+HTML模板+数据 → intersection_genes.txt + html/intersection_venn.html
r 路径:   Python 包装器 → Rscript ggVennDiagram → intersection_genes.txt + intersection_venn.pdf

> 多疾病自动发现：Python 包装器自动扫描疾病输出目录中的 {Disease}_Gene_List.txt（不含 Disease_ 前缀的聚合产物），与药物基因列表一起传入。单疾病时退化为 2 集合韦恩图。

运行约定

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

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

跨平台命令适配

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

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

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

# macOS/Linux 示例
python3 target-intersection/scripts/run_intersection.py

# Windows CMD 示例
python target-intersection\scripts\run_intersection.py

可视化约定

本 Skill 的所有图片输出使用内置医学期刊主题模块（scripts/theme_journal.R，自包含，无需外部依赖），确保统一的期刊级样式。所有图片输出为 PDF 矢量格式（仅 r 方法）。

调色板

通过 --palette 参数切换配色方案（仅 r 方法有效；html 方法使用 jvenn 内置调色板）：

韦恩图固定尺寸：5 × 5 in，适合单栏。

执行前检查

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

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

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

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

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

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

分步详解

Step 1: 靶点交集分析 (scripts/run_intersection.py)

用途： Python 包装器，自动发现疾病基因列表、验证输入文件、创建输出目录、完成多集合交集计算和韦恩图绘制。

前置条件：
- Skill 1 产物：./np-output/tcmsp/Drug_Targets_Gene_List.txt
- Skill 2 产物：./np-output/disease/{Disease}_Gene_List.txt（至少一个疾病）
- html 方法：无额外依赖，生成 HTML 用浏览器打开即可（仅 jQuery 从 CDN 加载）
- r 方法：R 环境已安装，ggVennDiagram + ggplot2 包。Python 包装器会在执行前自动检查依赖，缺失时提示用户确认安装（交互式终端）或打印安装命令（非交互式）；非交互场景可通过 --install-missing-r-packages 显式授权自动安装，安装成功后继续执行

R 依赖检查（r 方法）

r 方法需要 R 环境和以下包：

R -e 'install.packages(c("ggVennDiagram", "ggplot2"))'

缺包时 Python 包装器自动检测并提示安装：
- 交互式终端：显示缺失包列表 → 展示安装命令 → 询问 是否现在安装? [Y/n] → 输入 Y 确认自动安装 → 继续执行
- 非交互式环境（Agent 调用）：默认打印安装命令 → 返回错误；Agent 需征得用户同意后追加 --install-missing-r-packages 重新执行，脚本将自动安装后继续

手动安装命令：

Rscript -e 'install.packages("ggVennDiagram", repos = "https://cloud.r-project.org")'   # 核心依赖
Rscript -e 'install.packages("ggplot2", repos = "https://cloud.r-project.org")'           # 通常已随 ggVennDiagram 自动安装

命令模板：

Python 包装器行为：
1. 验证 --drug-list 文件存在
2. 验证 --disease-dir 目录存在
3. 自动扫描 {Disease}_Gene_List.txt（排除 Disease_ 前缀的聚合产物）
4. 检查集合总数 ≤ 上限（6 个）
5. 创建输出目录
6. 解析 --output-mode auto：1 个疾病 → single；2 个及以上疾病 → multi-disease
7. html 方法：Python 读取基因列表 → 计算统计 → 模板+数据 → 生成 html/intersection_venn.html
8. r 方法：预检 Rscript + ggVennDiagram + ggplot2 依赖 → 缺失时提示确认安装（交互式）或打印安装命令（非交互式）→ 非交互且显式追加 --install-missing-r-packages 时自动安装 → 安装成功后调用 Rscript intersection_analysis.R --set Drug:<path> --set <disease>:<path> ... → 检查输出
9. multi-disease 输出：在默认产物之外，额外生成 drug_{disease}.txt、{disease}_specific_genes.txt、shared_genes.txt 和 multi_disease_report.txt

R 脚本接口（intersection_analysis.R）：
- --set name:path — 可重复参数，指定集合名称和基因列表文件路径（第一个集合用于确定输出基因的大小写）
- --output-dir <path> — 输出目录
- --palette <name> — 配色方案（npg/viridis/lancet）

输出文件（位于输出目录中）：
- 两种方法均产出：
- intersection_genes.txt — 全交集基因列表，一行一个基因符号
- html 方法额外产出（位于 html/ 子目录）：
- intersection_venn.html — 交互式韦恩图（jvenn、canvas2svg 和样式本地打包，仅 jQuery 从 CDN 加载）
- r 方法额外产出：
- intersection_venn.pdf — 多集合韦恩图（PDF 矢量格式，医学期刊风格）

校验要点：
- 确认 intersection_genes.txt 已生成（即使交集为 0 也应生成空文件）
- r 方法：确认 intersection_venn.pdf 文件有效且可打开
- html 方法：用浏览器打开 html/intersection_venn.html，确认韦恩图正常渲染且点击交互可用
- 检查交集基因数量是否在合理范围（通常 ≥ 10 才有下游分析意义，但零交集也是有效结果）

完整运行示例

# 从项目根目录运行，使用默认路径（自动发现所有疾病）
python3 target-intersection/scripts/run_intersection.py

# 自定义药物列表
python3 target-intersection/scripts/run_intersection.py \
    --drug-list ./np-output/tcmsp/Drug_Targets_Gene_List.txt

# 单疾病场景（自动退化为 2 集合韦恩图）
python3 target-intersection/scripts/run_intersection.py \
    --disease-dir ./np-output/disease/

# 使用 R 方法生成 PDF
python3 target-intersection/scripts/run_intersection.py --method r

# 自定义配色（仅 r 方法）
python3 target-intersection/scripts/run_intersection.py --method r --palette viridis

# 非交互环境自动安装缺失 R 包（需显式授权）
python3 target-intersection/scripts/run_intersection.py --method r --install-missing-r-packages

# 生成交互式 HTML 韦恩图（默认，无需 R）
python3 target-intersection/scripts/run_intersection.py --method html

错误处理与恢复指南

执行检查清单

1. [ ] 检查残留文件 — 若输出目录存在且有旧文件，提示用户确认
2. [ ] 确认输入数据 — Drug_Targets_Gene_List.txt 和至少一个 {Disease}_Gene_List.txt 是否就绪
3. [ ] 确认环境 — html 方法无额外依赖；r 方法 Python 包装器自动检查 ggVennDiagram + ggplot2 并提示安装
4. [ ] 运行交集分析 — python3 $SKILL_DIR/scripts/run_intersection.py [--method html|r]
5. [ ] 验证输出 — intersection_genes.txt + 韦恩图产物（html 方法：html/intersection_venn.html；r 方法：intersection_venn.pdf）
6. [ ] 人工审核 — 检查交集基因数量是否合理；html 用浏览器打开确认韦恩图正常渲染

注意事项

• 多疾病自动发现：Python 包装器自动扫描 --disease-dir 下的 {Disease}_Gene_List.txt 文件（排除 Disease_ 前缀的聚合产物），无需手动指定每个疾病文件
• 集合数量限制：两种方法均最多支持 6 个集合，即 Drug + 最多 5 个疾病；超过时 Python 包装器会出具明确错误
• html 方法：纯 Python 实现，无需 R 环境。生成交互式 HTML 文件，用浏览器打开即可使用。支持功能：点击韦恩图区域查看基因列表、搜索基因、Classic/Edwards 布局切换、统计信息、选中基因复制/CSV 导出。仅 jQuery 从 CDN 加载；jvenn、canvas2svg 和样式文件随仓库本地提供。同样输出 intersection_genes.txt 用于下游 Skill 衔接
• r 方法：使用 ggVennDiagram（ggplot2 生态，适配 theme_journal() 主题）。Python 包装器自动预检 Rscript 和依赖包，缺失时在交互式终端提示确认后自动安装；非交互式环境默认打印安装命令，显式追加 --install-missing-r-packages 时才会自动安装
• 方法切换：通过 --method html|r 选择，默认 html
• 输入格式：基因列表为纯文本文件，每行一个基因符号（与 Skill 1/2 的 _Gene_List.txt 输出格式一致）
• 大小写处理：不区分大小写比较，输出交集基因时保留第一个集合（药物侧）的原始大小写
• 幂等性：可重复运行，每次覆盖输出
• 下游分析衔接：intersection_genes.txt 可直接作为 Skill 4（PPI 网络）和 Skill 5（富集分析）的输入

资源组织

• scripts/ — 确定性脚本：run_intersection.py（主入口 + Python 包装器）、intersection_analysis.R（R 韦恩图分析）
• references/ — 暂无（参数表、API 细节保留在本 SKILL.md 中）
• assets/ — html 方法依赖：jvenn_template.html（模板）、app.js、styles.css、jvenn.min.js、canvas2svg.js