Annovar自动化脚本

ANNOVAR 自动化注释流程脚本

目录

• 简介
• 主要功能
• 环境要求
• 安装与准备
• 使用方法
  • 基本用法
  • 参数详解
  • 分步执行
• 工作流程详解
• 输出文件
• 注意事项

简介

本项目是一个功能强大的Python脚本，旨在自动化执行ANNOVAR对VCF文件的完整注释流程。它特别适用于非模式生物或使用自定义基因组注释（GFF3文件）的研究场景。

脚本将从原始的GFF3注释文件和基因组序列文件开始，自动生成ANNOVAR所需的数据库文件，处理输入的VCF文件，并执行最终的变异注释，极大地简化了繁琐的手动操作。

主要功能

• 自动化数据库构建:
  • 将GFF3文件自动转换为ANNOVAR所需的GenePred格式（refGene.txt）。
  • 从基因组Fasta文件自动提取转录本序列（refGeneMrna.fa）。
• 智能GFF3文件预处理:
  • 自动检查并修复GFF3文件，确保其包含##gff-version 3头部。
  • 自动修复CDS条目中缺失或无效的phase（相位）信息，解决gff3ToGenePred转换失败的常见问题。
• VCF文件处理:
  • （可选）使用bcftools对VCF文件进行质量过滤。默认跳过此步骤。
  • 将VCF文件转换为ANNOVAR的标准输入格式。
• 一键式注释:
  • 调用ANNOVAR核心脚本，使用生成的自定义数据库对变异进行注释。
• 详细日志与报告:
  • 记录每个步骤的详细命令和执行状态到日志文件 (annovar_annotation.log)，方便调试。
  • 流程结束后生成一份简洁的总结报告 (annotation_summary.txt)。

环境要求

在运行此脚本之前，请确保您的系统中已安装并配置好以下软件：

1. Python 3: 脚本本身需要Python 3环境。
2. ANNOVAR: 核心注释工具。脚本需要能调用其目录下的Perl脚本，如 annotate_variation.pl, convert2annovar.pl, retrieve_seq_from_fasta.pl。
3. UCSC Kent Utilities: 至少需要gff3ToGenePred工具，用于将GFF3转换为GenePred格式。请确保该工具在系统的PATH环境变量中。
4. bcftools (可选): 如果您需要启用VCF质量过滤功能（通过--enable-vcf-filter参数），则需要安装bcftools并确保其在PATH中。

安装与准备

1. 下载脚本: 将此项目的脚本文件（例如 annovar_pipeline.py）下载到您的工作目录。

2. 准备输入文件:

   • GFF3文件: 您的物种的基因注释文件 (.gff3)。
   • 基因组文件: 您的物种的基因组序列文件 (.fa 或 .fasta)。
   • VCF文件: 待注释的变异位点文件 (.vcf)。

3. 准备ANNOVAR数据库目录:
   脚本会生成物种特异性的数据库文件（如 build-ver_refGene.txt 和 build-ver_refGeneMrna.fa）。您需要为这些文件指定一个存放位置。ANNOVAR将从这个位置读取它们。

   • 推荐做法: 在输出目录（--output-dir）下创建一个子目录（如 database），并将--database-path指向它。

使用方法

基本用法

以下是一个完整的运行示例。假设您的ANNOVAR安装在 /path/to/annovar，并且您希望将所有输出文件和数据库文件都放在 ./annovar_results 目录下。

# 运行完整注释流程
python annovar_pipeline.py \
  --gff3 my_species.gff3 \
  --genome my_species.fasta \
  --vcf my_variants.vcf \
  --build-ver my_species_v1 \
  --annovar-path /opt/annovar \
  --output-dir ./annovar_results \
  --database-path ./annovar_results

命令解释:

• 使用 my_species.gff3 和 my_species.fasta 作为注释和参考序列。
• 对 my_variants.vcf 文件进行注释。
• 定义基因组构建版本为 my_species_v1，这将用作生成数据库文件的前缀。
• ANNOVAR的安装路径为 /opt/annovar。
• 所有输出（包括中间文件和最终结果）都将保存在 ./annovar_results 目录。
• 脚本将在 ./annovar_results 目录中生成数据库文件，并告知ANNOVAR也从该目录加载它们。

参数详解

参数	是否必需	描述	默认值
--gff3	是	输入的GFF3注释文件路径。	-
--genome	是	输入的基因组序列Fasta文件路径。	-
--vcf	是	输入的VCF变异文件路径。	-
--build-ver	是	基因组构建版本的唯一标识符（例如: my_species_v1, ASM123v2）。不应包含路径分隔符 (/ 或 \)。	-
--annovar-path	否	ANNOVAR软件的安装目录路径。	/share/org/YZWL/yzwl_lixg/software/annovar/annovar
--database-path	否	ANNOVAR数据库文件所在的目录。脚本将在此处生成_refGene.txt和_refGeneMrna.fa文件。	./database
--output-dir	否	所有输出文件（日志、报告、注释结果等）的存放目录。	./annovar_output
--qual-threshold	否	VCF质量过滤阈值（QUAL值）。仅在启用VCF过滤时生效。	20
--skip-gff-fix	否	一个标志，如果设置，将跳过对GFF3文件的自动修复（如添加头部、修复CDS phase）。	False
--skip-vcf-filter	否	一个标志，跳过VCF过滤步骤。此为默认行为。	True
--enable-vcf-filter	否	一个标志，强制启用bcftools进行VCF过滤。如果设置此项，--skip-vcf-filter将失效。	False
--step	否	只运行指定的单个步骤 (1:gff3转换, 2:提取序列, 3:VCF处理, 4:注释)。	-

分步执行

如果您只想执行流程中的特定步骤，可以使用 --step 参数。例如，只生成ANNOVAR数据库文件（步骤1和2）：

# 步骤1: GFF3转GenePred
python annovar_pipeline.py --step 1 --gff3 ... --build-ver ... --output-dir ...

# 步骤2: 提取转录本序列
python annovar_pipeline.py --step 2 --genome ... --build-ver ... --output-dir ... --annovar-path ...

注意: 运行后续步骤通常依赖于前面步骤的输出。

工作流程详解

脚本按以下顺序执行任务：

1. 步骤 1: GFF3转GenePred

   • 检查并修复GFF3文件（除非使用--skip-gff-fix）。
   • 使用 gff3ToGenePred 将 GFF3 文件转换为 [build-ver]_refGene.txt 文件，并存放在 --database-path 指定的目录中。

2. 步骤 2: 提取转录本序列

   • 使用 ANNOVAR 的 retrieve_seq_from_fasta.pl 脚本。
   • 根据上一步生成的 _refGene.txt 文件，从基因组Fasta文件中提取所有转录本的mRNA序列。
   • 生成 [build-ver]_refGeneMrna.fa 文件，并存放在 --database-path 指定的目录中。

3. 步骤 3: VCF处理与转换

   • 过滤 (默认跳过): 如果启用了 --enable-vcf-filter，使用 bcftools filter 根据 QUAL 值过滤VCF文件。
   • 转换: 使用 ANNOVAR 的 convert2annovar.pl 脚本将VCF文件（原始或过滤后的）转换为ANNOVAR的输入格式 (.annovar.vcf)。

4. 步骤 4: 变异注释

   • 使用 ANNOVAR 的 annotate_variation.pl 核心脚本。
   • 利用步骤1和2生成的自定义数据库对 .annovar.vcf 文件进行注释。
   • 生成最终的注释结果文件。

输出文件

在指定的 --output-dir 目录下，您会找到以下主要文件：

• 最终注释结果:

  • [vcf_basename].exonic_variant_function: 外显子区域变异的功能注释（如同义/非同义突变）。
  • [vcf_basename].variant_function: 所有变异的区域注释（如外显子、内含子、基因间区等）。

• 日志与报告:

  • annovar_annotation.log: 详细的运行日志，记录了每一步执行的命令、输出和错误信息。
  • annotation_summary.txt: 流程运行的总结报告，包含输入输出文件和关键配置信息。

• 中间文件:

  • [vcf_basename].annovar.vcf: 转换后的ANNOVAR格式输入文件。
  • [vcf_basename].filtered.gz (如果启用了过滤): 过滤后的VCF文件。
  • 数据库文件 (位于 --database-path 目录):
    • [build-ver]_refGene.txt
    • [build-ver]_refGeneMrna.fa

注意事项

• 路径问题: 请确保所有输入文件的路径以及 --annovar-path 都是正确的。脚本会进行存在性检查，但正确的路径是成功运行的前提。
• build-ver的重要性: --build-ver 参数是连接所有步骤的关键。它作为ANNOVAR数据库文件的前缀，必须保持一致。请使用一个简洁且唯一的标识符。
• GFF3文件质量: 虽然脚本包含自动修复功能，但过于混乱或格式不标准的GFF3文件仍可能导致gff3ToGenePred失败。如果遇到问题，请首先检查GFF3文件的格式。