离线跑 VEP 必备：Reference FASTA 文件下载与预处理

这里，我们将详细介绍如何为 Ensembl Variant Effect Predictor (VEP) 离线模式准备本地参考基因组 FASTA，以及为什么要 先解压、再 bgzip 压缩。看完就能举一反三，为任何物种配置 VEP 参考序列。

1. 为什么一定要用 Ensembl 官方 FASTA？

	原因
坐标一致	VEP 只能 100% 保证与同版本 Ensembl 发布的注释（GTF/GFF、缓存）完全匹配。用其他来源 → 坐标或 HGVS 解析可能错位
目录统一	Ensembl FTP 采用统一的 …/release-114/fasta//dna/ 结构，自动化脚本好写
长期维护	每个 release 都保留完整历史，且提供 MD5 校验，便于版本溯源

简言之：想省心，就用 Ensembl FASTA ，且版本号要与当前 VEP 保持一致。

2. 选哪个文件最合适？

进入 …/dna/ 目录后，你会看到一堆后缀类似的压缩包：

文件名片段	含义	是否推荐做 VEP 参考？
dna.primary_assembly.fa.gz	仅含正式染色体 (24 条常染 + XY + M) 及少量 decoy	✅ 推荐
dna.toplevel.fa.gz	primary_assembly + alt contigs + patch	体积大，注释慢
_sm. / _rm.	soft-mask / repeat-mask	⛔ 不要（大小写或 N 会影响插件）

拿 unmasked + primary_assembly 即可。以人类 GRCh38 为例：Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz。

3. 下载 ➜ 解压 ➜ bgzip 三步走

#| eval: false
# 下载记得确认 release 号
curl -O https://ftp.ensembl.org/pub/release-114/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
# 先完全解压；bgzip 不能直接二次压缩 .gz
gzip -d Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
# 用 bgzip 重新块压缩，生成可随机索引的 .fa.gz
bgzip -@ 8 Homo_sapiens.GRCh38.dna.primary_assembly.fa   # -@ 8 = 8 线程
# （可选）提前生成索引，VEP 第一次跑时也会自动创建
samtools faidx Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz

为什么要这么折腾？

	特点	适用场景
纯文本 .fa	读取最快；占用磁盘大	本地磁盘富余
普通 gzip .fa.gz	空间省，但无法随机访问 ➜ VEP 巨慢	❌ 不要
bgzip .fa.gz	空间省，又可随机定位 (Bio::DB::HTS::Faidx)	✅ 推荐

bgzip 和 samtools 均来自 htslib，conda 安装：conda install -c bioconda htslib samtools。

其他物种同理，路径里换成对应英文学名即可。

4. 常见报错与解决方案

报错	原因	解决
`Can't locate Bio/DB/HTS/Faidx.pm`	perl-htslib 缺失	`conda install -c bioconda perl-htslib`
`Could not find index file`	`.fai` / `.gzi` 损坏或丢失	手动 `samtools faidx *.fa.gz` 重新索引
运行速度奇慢 + 单核	用了普通 gzip 文件	按上文改用 bgzip
内存占用飙升	开太多 `--fork` 线程	减少 `--fork` 或增加 `--buffer_size`

Take Home Message

下载 unmasked primary_assembly → 解压 → bgzip，然后把 .fa.gz 路径传给 –fasta，VEP 离线跑得又快又稳，磁盘占用还能少一半以上。

--- title: "离线跑 VEP 必备：Reference FASTA 文件下载与预处理" date: 2025-06-24 description: "Run VEP offline with local reference FASTA" image: "https://cdn.jsdelivr.net/gh/Leslie-Lu/WeChatOfficialAccount/img_2025/20250624022739.png" categories: - VEP - reference genome - bioinformatics - variant annotation - genomics format: html: shift-heading-level-by: 1 include-in-header: - text: | <style type="text/css"> hr.dinkus { width: 50px; margin: 2em auto 2em; border-top: 5px dotted #454545; } div.column-margin+hr.dinkus { margin: 1em auto 2em; } </style> --- 这里，我们将详细介绍如何为 Ensembl Variant Effect Predictor (VEP) 离线模式准备本地参考基因组 FASTA，以及为什么要 `先解压、再 bgzip 压缩`。看完就能举一反三，为任何物种配置 VEP 参考序列。 ## 1. 为什么一定要用 Ensembl 官方 FASTA？ | | 原因 | |------------|-------------------------------------------------------------------------------------------| | 坐标一致 | VEP 只能 100% 保证与同版本 Ensembl 发布的注释（GTF/GFF、缓存）完全匹配。用其他来源 → 坐标或 HGVS 解析可能错位 | | 目录统一 | Ensembl FTP 采用统一的 …/release-114/fasta/<species>/dna/ 结构，自动化脚本好写 | | 长期维护 | 每个 release 都保留完整历史，且提供 MD5 校验，便于版本溯源 | 简言之：想省心，就用 [Ensembl FASTA](https://www.ensembl.org/index.html "Ensembl") ，且版本号要与当前 VEP 保持一致。 ## 2. 选哪个文件最合适？进入 …/dna/ 目录后，你会看到一堆后缀类似的压缩包： | 文件名片段 | 含义 | 是否推荐做 VEP 参考？ | |--------------------------------|-----------------------------------------------------------|---------------------| | dna.primary_assembly.fa.gz | 仅含正式染色体 (24 条常染 + XY + M) 及少量 decoy | ✅ 推荐 | | dna.toplevel.fa.gz | primary_assembly + alt contigs + patch | 体积大，注释慢 | | _sm. / _rm. | soft-mask / repeat-mask | ⛔ 不要（大小写或 N 会影响插件） | 拿 `unmasked + primary_assembly` 即可。以人类 GRCh38 为例：Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz。 ## 3. 下载 ➜ 解压 ➜ bgzip 三步走 ```{bash} #| eval: false # 下载记得确认 release 号 curl -O https://ftp.ensembl.org/pub/release-114/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz # 先完全解压；bgzip 不能直接二次压缩 .gz gzip -d Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz # 用 bgzip 重新块压缩，生成可随机索引的 .fa.gz bgzip -@ 8 Homo_sapiens.GRCh38.dna.primary_assembly.fa # -@ 8 = 8 线程 # （可选）提前生成索引，VEP 第一次跑时也会自动创建 samtools faidx Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz ``` ### 为什么要这么折腾？ | | 特点 | 适用场景 | |--------------------|-----------------------------------------------------------|---------------------| | 纯文本 .fa | 读取最快；占用磁盘大 | 本地磁盘富余 | | 普通 gzip .fa.gz | 空间省，但无法随机访问 ➜ VEP 巨慢 | ❌ 不要 | | bgzip .fa.gz | 空间省，又可随机定位 (Bio::DB::HTS::Faidx) | ✅ 推荐 | bgzip 和 samtools 均来自 htslib，conda 安装：`conda install -c bioconda htslib samtools`。其他物种同理，路径里换成对应英文学名即可。 ## 4. 常见报错与解决方案 | 报错 | 原因 | 解决 | | ---------------------------------- | --------------------- | --------------------------------------- | | `Can't locate Bio/DB/HTS/Faidx.pm` | perl-htslib 缺失 | `conda install -c bioconda perl-htslib` | | `Could not find index file` | `.fai` / `.gzi` 损坏或丢失 | 手动 `samtools faidx *.fa.gz` 重新索引 | | 运行速度奇慢 + 单核 | 用了普通 gzip 文件 | 按上文改用 bgzip | | 内存占用飙升 | 开太多 `--fork` 线程 | 减少 `--fork` 或增加 `--buffer_size` | ## Take Home Message 下载 unmasked primary_assembly → 解压 → bgzip，然后把 .fa.gz 路径传给 --fasta，VEP 离线跑得又快又稳，磁盘占用还能少一半以上。