PlantAI-dev/skills/annotation/SKILL.md

Annotation Skill - 功能注释分析技能

当前正式阶段入口使用本地 InterProScan 对蛋白序列进行 GO 注释，并在 KOfam 数据库完整时使用 KofamScan 进行 KEGG/KO 注释，生成可复用 gene2go.txt 和 gene2ko.txt 背景文件。

功能特性

• 调用本地 InterProScan 进行 GO 注释
• 调用 KofamScan 进行 KEGG KO 注释（依赖完整 data/kegg_new/profiles/ 和 ko_list）
• 支持 --annotation-scope go/kegg/both，RNA-seq GO 与 KEGG 自动背景注释可分别记录状态
• 自动生成 {prefix}.gene2go.txt
• 自动生成 {prefix}.gene2ko.txt（KofamScan 可用且有 KO 命中时）
• 保留 {prefix}.interproscan.tsv/xml/gff3 原始注释文件
• 保留 {prefix}.kofamscan.detail.tsv 原始注释文件
• 生成 {prefix}.gene_id_map.tsv，统一 transcript ID 与 gene ID
• 完整的可复现性支持（commands.sh, environment.yml, checksums.sha256）
• 详细的统计报告和 manifest

使用方法

基本用法

python apps/cli/run_annotation.py -i protein.fa -o workspace/job_id -p Ft.SPL -j job_id

指定参数

python apps/cli/run_annotation.py \
    -i protein.fa \
    -o workspace/job_id \
    -p Ft.SPL \
    -j job_id \
    -t 16 \
    --applications Pfam,PANTHER,SMART,ProSiteProfiles,ProSitePatterns

RNA-seq 自动背景按需拆分

# GO 背景：只运行 InterProScan/gene2go，写 annotation_go manifest/progress
python apps/cli/run_annotation.py -i protein.fa -o workspace/job_id -p Ft.SPL -j job_id \
  --annotation-scope go --skip-kegg

# KEGG 背景：只运行 KofamScan/gene2ko，写 annotation_kegg manifest/progress
python apps/cli/run_annotation.py -i protein.fa -o workspace/job_id -p Ft.SPL -j job_id \
  --annotation-scope kegg --skip-go --require-kegg

Demo模式

python run.py --demo --output ./annotation_demo

输出文件

文件	描述
final/{prefix}.gene2go.txt	归一化 gene ID 的 GO 背景文件
final/{prefix}.gene2ko.txt	归一化 gene ID 的 KO 背景文件
annotation/analysis/{prefix}.raw_id.gene2go.txt	原始 protein/transcript ID 的 GO 背景文件
annotation/analysis/{prefix}.raw_id.gene2ko.txt	原始 protein/transcript ID 的 KO 背景文件
annotation/analysis/{prefix}.interproscan.tsv	InterProScan TSV 原始结果
annotation/analysis/{prefix}.kofamscan.detail.tsv	KofamScan detail-tsv 原始结果
annotation/analysis/{prefix}.interproscan.xml	InterProScan XML 原始结果
annotation/analysis/{prefix}.interproscan.gff3	InterProScan GFF3 原始结果
annotation/analysis/{prefix}.gene_id_map.tsv	raw ID 到 canonical gene ID 映射
final/{prefix}.annotation_report.md	legacy both 分析报告
final/{prefix}.annotation_go_report.md	GO scope 分析报告
final/{prefix}.annotation_kegg_report.md	KEGG scope 分析报告
final/{prefix}.annotation.manifest.json	legacy both Manifest
final/{prefix}.annotation_go.manifest.json	GO scope Manifest
final/{prefix}.annotation_kegg.manifest.json	KEGG scope Manifest
annotation/analysis/commands.sh	legacy both 可复现命令脚本
annotation/analysis/commands.go.sh	GO scope 可复现命令脚本
annotation/analysis/commands.kegg.sh	KEGG scope 可复现命令脚本
annotation/analysis/environment*.yml	Conda环境配置
annotation/analysis/checksums*.sha256	文件校验值

当前本地依赖

• InterProScan: /home/xia-lab/wutx/02tool/interproscan5.77/interproscan-5.77-108.0/interproscan.sh
• Python: /home/xia-lab/miniconda3/envs/test4py311/bin/python

KEGG 来源

KEGG/KO 背景使用 KofamScan：

• exec_annotation 已安装在 test4py311
• KOfam 数据目录规划为 data/kegg_new/
• 解析高置信 * 命中生成 gene2ko.txt
• 若 profiles/ 数量明显少于 ko_list，阶段会跳过 KEGG 并在 manifest 中记录原因

测试

python -m pytest tests/test_annotation.py -v

注意事项

1. InterProScan 负责 GO 背景；KofamScan 负责 KEGG KO 背景。
2. final/gene2go.txt 仅在不存在或为空时写入兼容副本，避免覆盖已有全基因组背景。
3. 大蛋白组运行 InterProScan 可能较慢，应作为后台长任务执行。
4. RNA-seq GO 与 KEGG 自动注释分别使用 .annotation.go.lock 和 .annotation.kegg.lock，同类任务互斥，不同类任务可并行。