mgibio/vep_helper-cwl

VEP及空VCF处理辅助脚本镜像文档

1. 镜像概述和主要用途

本镜像集成了Variant Effect Predictor（VEP）工具及专用辅助脚本，主要用于基因组变异的功能注释及空VCF（Variant Call Format）文件的自动化处理。VEP是Ensembl开发的核心变异注释工具，可对DNA变异（如SNV、Indel等）进行基因、转录本、蛋白质水平的功能效应预测；辅助脚本则针对流程中可能出现的空VCF文件（如无变异样本产生的空文件）提供错误规避、标准化输出及日志记录功能，确保下游分析流程的连续性。

2. 核心功能和特性

2.1 VEP核心功能

• 变异注释：支持对SNV、Indel、CNV等多种变异类型进行注释，包括基因关联、转录本影响（如错义突变、无义突变）、蛋白质功能预测（如SIFT、PolyPhen分数）等。
• 数据库集成：可调用Ensembl、RefSeq等公共数据库，支持自定义数据库（如ClinVar、COSMIC）的集成。
• 多物种支持：覆盖人、小鼠、大鼠等常见模式生物及农业物种的参考基因组。

2.2 辅助脚本功能

• 空VCF检测：自动识别输入VCF文件是否为空（无变异记录仅含表头）。
• 标准化处理：对空VCF文件生成符合下游分析要求的标准化输出（如添加默认元信息、空结果标记），避免因空文件导致的流程中断。
• 日志与报告：记录空VCF处理过程，生成包含样本ID、空文件原因（如无变异检出、样本质量问题）的结构化报告。

2.3 Docker镜像特性

• 环境隔离：内置VEP运行所需的依赖库（Perl模块、数据库驱动等），无需本地配置环境。
• 版本一致性：固定VEP及辅助脚本版本，确保不同环境下分析结果的可重复性。
• 轻量化部署：基于Alpine或Ubuntu Slim基础镜像，降低存储空间占用。

3. 使用场景和适用范围

3.1 典型使用场景

• 基因组变异分析流程：作为变异检测后的注释环节，对VCF文件进行功能注释，并处理无变异样本产生的空VCF。
• 自动化生信管道：集成至WDL、Nextflow等工作流管理系统，解决空VCF导致的管道中断问题（如GATK、bcftools等工具对空VCF的兼容性问题）。
• 临床样本分析：对肿瘤/正常样本配对分析中“无变异检出”的样本生成标准化空VCF报告，辅助临床解读。

3.2 适用范围

• 用户群体：生物信息学研究员、基因组学实验室技术人员、生信流程开发工程师。
• 数据场景：全基因组测序（WGS）、全外显子测序（WES）、靶向测序等变异检测产出的VCF文件（含空文件）。

4. 使用方法和配置说明

4.1 前提条件

• 已安装Docker Engine（20.10+）或Docker Desktop。
• 本地需准备：
  • 输入VCF文件（含可能的空文件）；
  • VEP缓存数据（需提前通过vep_install下载，或使用镜像内置基础缓存，物种及版本需与分析匹配）。

4.2 基本使用流程

4.2.1 镜像拉取

bash
docker pull [镜像仓库地址]/vep-empty-vcf-helper:latest  # 需替换为实际镜像地址

4.2.2 单样本注释与空VCF处理（docker run）

命令格式：

bash
docker run -it --rm \
  -v [本地数据目录]:/data \          # 挂载本地数据目录（含输入VCF及缓存）
  -v [本地缓存目录]:/vep_cache \      # 挂载VEP缓存目录（如人类GRCh38缓存）
  -e VEP_SPECIES=homo_sapiens \        # 配置物种（默认人类）
  -e VEP_ASSEMBLY=GRCh38 \             # 配置参考基因组版本
  [镜像名称] \
  /bin/bash -c "vep -i /data/input.vcf -o /data/output.vep.vcf --cache --dir /vep_cache && \
                /scripts/empty_vcf_helper.sh -i /data/input.vcf -o /data/empty_vcf_report.txt"

参数说明：

• -v [本地数据目录]:/data：本地数据目录需包含输入VCF文件，输出文件（如注释结果、报告）将写入此目录。
• -v [本地缓存目录]:/vep_cache：VEP缓存目录需包含物种对应的参考数据（如homo_sapiens/105_GRCh38）。
• vep命令参数：-i指定输入VCF，-o指定注释输出文件，--cache启用缓存模式，--dir指定缓存路径（容器内路径/vep_cache）。
• empty_vcf_helper.sh（辅助脚本）参数：-i输入VCF路径，-o空VCF处理报告输出路径。

4.3 环境变量配置

4.4 辅助脚本配置参数

辅助脚本empty_vcf_helper.sh支持以下参数：

5. Docker Compose部署示例

适用于多样本批量处理场景，通过docker-compose.yml定义数据挂载、环境变量及命令：

yaml
version: '3'
services:
  vep_analysis:
    image: [镜像仓库地址]/vep-empty-vcf-helper:latest
    volumes:
      - ./local_data:/data           # 本地数据目录（输入VCF、输出结果）
      - ./vep_cache:/vep_cache       # VEP缓存目录
    environment:
      - VEP_SPECIES=homo_sapiens
      - VEP_ASSEMBLY=GRCh38
      - VEP_CACHE_VERSION=105
    command: >
      /bin/bash -c "for vcf in /data/*.vcf; do
                      sample_name=\$(basename \$vcf .vcf);
                      vep -i \$vcf -o /data/\${sample_name}_vep.vcf --cache --dir /vep_cache;
                      /scripts/empty_vcf_helper.sh -i \$vcf -o /data/\${sample_name}_empty_report.txt;
                    done"

说明：上述配置会批量处理./local_data目录下的所有.vcf文件，分别生成注释结果（*_vep.vcf）和空VCF报告（*_empty_report.txt）。

6. 注意事项

• 缓存数据：VEP缓存需与物种、参考基因组版本匹配（如人类GRCh38需对应homo_sapiens/105_GRCh38目录），可通过vep_install工具提前下载（https://www.ensembl.org/info/docs/tools/vep/script/vep_download.html%EF%BC%89%E3%80%82

• 空VCF定义：辅助脚本默认将“非表头行数=0”的文件判定为空VCF，可通过--min-rows参数调整阈值（如设为10，非表头行数<10视为“近空”文件）。

• 权限问题：本地挂载目录需确保Docker用户有读写权限（可通过chmod 775 local_data调整）。

注：辅助脚本的具体功能及参数可能因镜像版本略有差异，建议通过docker run --rm [镜像名称] /scripts/empty_vcf_helper.sh -h查看内置帮助文档。