# 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

## 使用方法

### 基本用法

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

### 指定参数

```bash
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 自动背景按需拆分

```bash
# 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模式

```bash
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 中记录原因

## 测试

```bash
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`，同类任务互斥，不同类任务可并行。