📚 课程目录第3章 ANNOVAR安装与配置

3、ANNOVAR安装与配置：下载、数据库设置、配置文件

说实话，ANNOVAR 的安装谈不上多复杂，但里面坑真不少。我入这行的时候，头一回装 ANNOVAR 就差点被它那个 Perl 环境和数据库路径搞疯掉。今天咱们就把这东西掰开了揉碎了讲清楚，你照着做，最多半小时就能跑起来。

3.1 下载与解压

ANNOVAR 官方维护得还不错，但需要你手动去官网申请一下。我个人习惯是直接去 http://annovar.openbioinformatics.org 搞个下载链接，然后用 wget 拉下来。来，先把压缩包弄到服务器上：

wget http://www.openbioinformatics.org/annovar/download/annovar.latest.tar.gz
tar -xzf annovar.latest.tar.gz
cd annovar

解压完你就得到一个 annovar/ 目录，里面主要就几个 Perl 脚本。嗯，这里要注意：ANNOVAR 本身是用 Perl 写的，所以你得确保系统里有 Perl。基本上每台 Linux 机器都自带 Perl，但如果你在 macOS 或 Windows 上跑，我建议用 WSL2 或 conda 环境。

我的经验： 千万别试图用 root 用户跑 ANNOVAR，权限问题会很麻烦。我就吃过这亏——装完发现数据库写不到系统目录下，折腾了半天。老老实实用普通用户，把 annovar 丢到 /home/yourname/tools/ 下面就行了。

解压后目录长这样：

annovar/
├── annotate_variation.pl       # 主程序：注释变异
├── coding_change.pl            # 推断氨基酸变化
├── convert2annovar.pl          # 转换多种输入格式
├── retrieve_seq_from_fasta.pl  # 从 fasta 提取序列
├── table_annovar.pl            # 一键多数据库注释
├── variants_reduction.pl       # 过滤变异
└── example/                    # 示例文件

我个人习惯把这些脚本的路径加到 $PATH 里，省得每次敲绝对路径。你在 ~/.bashrc 里加一行：

export PATH=$PATH:/path/to/annovar

然后 source ~/.bashrc 就生效了。为什么不建议用软链接？因为 ANNOVAR 脚本还会调用自身目录下的其他文件（比如库），软链接有时候会出幺蛾子。

3.2 数据库下载——这步最容易掉坑

ANNOVAR 的强大之处就在于它预配置了好多公共数据库。但下载数据库的方式，说起来就有点「古早味」了。它用的是 annotate_variation.pl -buildver 加上 -downdb 参数。

先看看有哪些数据库可选：

perl annotate_variation.pl -downdb -webfrom annovar -buildver hg38 avdblist

这条命令会列出所有可下载的数据库名称。如果你想下载人类基因组 hg38 的 refGene 数据库：

perl annotate_variation.pl -downdb -webfrom annovar -buildver hg38 refGene humandb/

注意最后的 humandb/ 是你存放数据库的目录路径。我个人习惯在 annovar 目录下建一个 humandb/ 子目录，以后所有基因组数据都丢进去。你以为这就完了？还早着呢。ANNOVAR 的数据库下载速度很慢，而且经常断连。我曾经在下载 1000g2015aug 的时候，一个 2GB 的文件下了三遍才成功。碰上了怎么办？可以分卷下载，或者干脆用我下面给的手动下载方式。

重要提醒： 别指望一次性把所有数据库都下下来，根本没必要。根据你的项目需求来——比如只做 SNV 注释，就下 refGene、dbSNP、ClinVar；做罕见病分析再加个 gnomAD 和 ExAC。全下的结果是你硬盘炸了，而且大部分用不上。

手动下载的方式（以 hg38 的 refGene 为例）：

# 先去官网找到对应版本
# 一般 url 格式：http://annovar.openbioinformatics.org/download/...
# 用 wget 直接拉
wget http://annovar.openbioinformatics.org/download/hg38_refGene.txt.gz
wget http://annovar.openbioinformatics.org/download/hg38_refGeneMrna.fa.gz
gunzip *.gz
mv hg38_* humandb/

我对比过，手动下载比用 -downdb 稳定得多，尤其在大陆网络环境下。你如果有代理，那用自动化命令也行。

3.3 数据库目录与配置文件

ANNOVAR 会按照 humandb/ 目录下的文件命名规范来自动识别数据库。比如 hg38_refGene.txt 对应注释文件，hg38_refGeneMrna.fa 对应转录本序列。我们来看看典型数据库列表：

数据库名称	文件名前缀	用途
refGene	hg38_refGene	基因结构注释（exon/intron/UTR 等）
dbSNP	hg38_avsnp150	已知 SNP 位点 ID 映射
ClinVar	hg38_clinvar_20190305	临床意义注释
1000 Genomes	hg38_1000g2015aug	人群频率
gnomAD	hg38_gnomad211_genome	人群频率（更全）
CADD	hg38_cadd13	功能预测评分

看到没？每种数据库有特定的版本命名。你下载的时候要注意版本一致性。比如你分析的是 hg38 的数据，就别混进去 hg19 的数据库，不然程序会报错。

关于配置文件，ANNOVAR 本身没有传统的 YAML/JSON 配置文件，而是依赖命令行参数。但我自己写了一个小的 shell 脚本，把常用的数据库路径和参数固化下来，避免每次敲一堆东西。比如 annovar_config.sh：

#!/bin/bash
# 自定义 ANNOVAR 配置文件
ANNOVAR_DIR="/home/user/tools/annovar"
HUMMANDB_DIR="$ANNOVAR_DIR/humandb"
BUILDVER="hg38"
PROTOCOLS="refGene,clinvar_20190305,avsnp150,gnomad211_genome"
# 其他常用参数
THREADS=4
OUTPUT_DIR="./annovar_results"

然后在跑命令的时候 source 这个脚本，用变量代替硬编码。这个方法我推荐给所有团队——特别是要重复跑几百个样本的时候，统一配置能减少低级错误。

3.4 验证安装是否成功

装完配置完，总得测一下。我习惯用 ANNOVAR 自带的示例文件跑一遍：

cd /path/to/annovar
perl table_annovar.pl example/example.vcf humandb/ -buildver hg38 -out test_output -remove -protocol refGene -operation g

如果顺利，你会看到屏幕上输出一堆日志，并且目录下生成 test_output.hg38_multianno.txt。打开看看，里面应该有基因名称、功能分区、等位基因频率等信息。

不成功怎么办？常见错误大致三种：

找不到 Perl 模块： 一般是因为系统缺少某些 Perl 库，用 cpan install Bundle::DBI 补上。
数据库无法下载： 见上面手动下载方案。
内存不够： 注释大 VCF 时容易挂，可以用 -slow 参数降速，或者分染色体跑。

避坑指南·真实翻车经历： 我曾经在服务器上装 ANNOVAR，下载完所有数据库后跑注释，结果报错说找不到某条染色体的文件。排查了老半天才发现，原来是数据库文件被 wget 下载成 .gz 格式但没解压——ANNOVAR 不认压缩文件。从那以后，每次下完我都先 ls -lh humandb/ 看一眼，确保没残留 .gz。

3.5 核心知识体系一览

你可能会觉得上面这些步骤零零碎碎的。我画了一张结构图，把整个安装配置流程串起来，你看一眼就能记住关键节点。

3.6 我的一些小建议

到这里为止，ANNOVAR 的安装配置算是搞定了。但别急，咱们再聊几个实用的点。

关于数据库版本： 同一个基因组版本（比如 hg38）的数据库，不同小组的更新频率不一样。ClinVar 几乎每月都会更新，dbSNP 每年大版本。你如果想做可重复的研究，最好固定住数据库的版本号，并且记录在项目笔记里。我在实际项目中就碰到过——三个月前跑的结果，三个月后用新数据库重跑，注释出来的位点数差了好几百。复现性全没了。

关于性能调优： 如果你要注释的 VCF 文件很大（比如全基因组、几千个样本），建议分染色体并行跑。先按染色体切分 VCF，然后用 GNU parallel 并发提交多个 table_annovar.pl 任务，最后合并。我写过一个小脚本，大概长这样：

#!/bin/bash
# 按染色体并行注释示例
CHR_LIST=$(seq 1 22) X Y
for chr in $CHR_LIST; do
  vcf_subset.sh input.vcf ${chr} > chr${chr}.vcf
  table_annovar.pl chr${chr}.vcf humandb/ \
    -buildver hg38 \
    -out chr${chr}_anno \
    -remove -protocol refGene,clinvar_20190305 \
    -operation g,f &
done
wait
cat chr*_anno.hg38_multianno.txt > all_anno.txt

注意：这个脚本只是示例，你用的时候得根据自己的路径和工具改改。别直接粘贴就运行。

关于存储空间： 全 hg38 的所有数据库加起来能有好几十个 GB。我建议数据库目录单独放一个分区或挂载一块大的磁盘，别跟根目录挤在一起。定期清理旧版本数据库也是好习惯。

好了，安装配置这块咱们就聊到这儿。你把以上步骤走一遍，就能在本地正常跑起来 ANNOVAR 了。接下来要做的事情就是准备输入数据，开始真正的注释之旅。