StaPH-B bcftools Docker镜像文档

1. 镜像概述和主要用途

1.1 项目背景

StaPH-B（State Public Health Lab Bioinformatics，州公共卫生实验室生物信息学）联盟维护的docker-builds仓库，旨在为联盟成员及生物信息学社区提供集中管理、易于访问且文档清晰的Docker镜像，涵盖各类常用生物信息学工具。

1.2 镜像简介

staphb/bcftools镜像基于samtools/bcftools项目构建，专注于Variant Call Format (VCF)及其二进制格式BCF（Binary Call Format）文件的处理。该镜像封装了bcftools的稳定版本，提供标准化运行环境，确保跨平台一致性。

1.3 支持版本

当前镜像支持以下bcftools版本：

• 1.10.2
• 1.11
• 1.12

2. 核心功能和特性

2.1 核心功能

bcftools是处理VCF/BCF文件的核心工具，主要功能包括：

• 文件查看与转换：支持VCF与BCF格式互转，提取指定区域或样本数据（bcftools view）。
• 索引与排序：为BCF/VCF文件创建索引（bcftools index），按坐标排序文件（bcftools sort）。
• 变异过滤：基于质量值、覆盖度等指标筛选变异（bcftools filter）。
• 统计分析：生成变异质量、等位基因频率等统计报告（bcftools stats）。
• 格式标准化：统一VCF文件格式，处理缺失数据（bcftools norm）。
• 变异合并：合并多个样本或区域的变异文件（bcftools merge）。

2.2 镜像特性

• 版本可控：明确标注支持的bcftools版本，便于复现分析流程。
• 环境一致性：预配置所有依赖（如htslib），避免“环境依赖”问题。
• 跨平台兼容：支持Docker及Singularity（大多数Docker容器可直接转换为Singularity格式）。
• 轻量高效：基于精简基础镜像，减少资源占用。

3. 使用场景和适用范围

3.1 适用场景

• 病原体基因组变异分析：处理细菌、病毒等病原体测序数据的变异结果（如SNP、Indel）。
• 公共卫生实验室检测：标准化变异文件处理流程，支持疫情监测中的基因组数据分析。
• 大规模样本筛选：对批量VCF/BCF文件进行质量控制、变异提取与统计。
• 变异数据格式转换：在不同分析工具间（如GATK、Plink）转换数据格式。

3.2 适用用户

• 生物信息学分析师
• 公共卫生实验室研究人员
• 基因组学及微生物学研究团队

4. 使用方法和配置说明

4.1 前提条件

• 已安装Docker引擎（参考Docker官方文档）。
• （可选）Singularity环境（如需转换镜像，参考StaPH-B用户指南）。

4.2 获取镜像

从Docker Hub拉取指定版本镜像（未指定版本默认使用最新版）：

# 拉取特定版本（如1.12）
docker pull staphb/bcftools:1.12

# 拉取最新版本
docker pull staphb/bcftools:latest

4.3 基本使用方法

通过docker run命令启动容器，挂载本地数据目录（如/path/to/data）至容器内路径（如/data），执行bcftools命令。

通用命令格式：

docker run --rm -v /path/to/local/data:/data staphb/bcftools:<version> bcftools <subcommand> [options] /data/input_file [output_options]

• --rm：容器退出后自动删除，释放资源。
• -v /path/to/local/data:/data：挂载本地数据目录到容器内/data，实现文件共享。
• <version>：指定bcftools版本（如1.12），省略则使用latest。

4.4 常用操作示例

示例1：查看VCF文件内容

# 查看本地/data/input.vcf的前10行
docker run --rm -v /path/to/data:/data staphb/bcftools:1.12 bcftools view -h /data/input.vcf | head -n 10

示例2：将VCF转换为BCF并索引

# 转换格式（输出为/data/output.bcf）并索引
docker run --rm -v /path/to/data:/data staphb/bcftools:1.12 \
  sh -c "bcftools view -Ob /data/input.vcf -o /data/output.bcf && bcftools index /data/output.bcf"

示例3：过滤低质量变异

# 保留QUAL>30且DP>10的变异，输出至/data/filtered.vcf
docker run --rm -v /path/to/data:/data staphb/bcftools:1.12 \
  bcftools filter -i 'QUAL>30 && DP>10' /data/input.vcf -o /data/filtered.vcf

示例4：生成变异统计报告

# 对BCF文件进行统计，结果输出至/data/stats.txt
docker run --rm -v /path/to/data:/data staphb/bcftools:1.12 \
  bcftools stats /data/input.bcf > /data/stats.txt

5. Docker部署方案示例

5.1 单命令部署（常用场景）

直接通过docker run执行单次任务，如批量处理VCF文件：

# 批量将目录下所有VCF转换为BCF
for vcf in /path/to/data/*.vcf; do
  docker run --rm -v /path/to/data:/data staphb/bcftools:1.12 \
    bcftools view -Ob "$vcf" -o "${vcf%.vcf}.bcf"
done

5.2 Docker Compose配置（多步骤流程）

如需整合到复杂流程（如与其他工具联动），可使用docker-compose.yml定义服务：

version: '3'
services:
  bcftools_process:
    image: staphb/bcftools:1.12
    volumes:
      - /local/data:/data  # 挂载本地数据
    command: >
      sh -c "bcftools view -Ob /data/input.vcf -o /data/output.bcf &&
             bcftools index /data/output.bcf &&
             bcftools stats /data/output.bcf > /data/report.txt"

运行命令：

docker-compose up

6. 配置参数与环境变量

6.1 工具原生参数

bcftools的所有功能通过命令行参数控制，常用参数示例：

• -o <file>：指定输出文件路径。
• --threads <n>：指定线程数（加速处理，如--threads 4）。
• -f <ref.fasta>：指定参考基因组序列（用于部分功能，如bcftools norm）。
• -i <expr>：过滤条件表达式（如-i 'QUAL>50'）。

完整参数列表参考bcftools官方文档。

6.2 环境变量

本镜像无特殊环境变量，所有配置通过bcftools命令行参数传递。容器内工作目录默认为/，建议通过-v挂载数据目录并指定绝对路径操作文件。

7. 注意事项

• 数据权限：确保本地数据目录对Docker进程有读写权限，避免因权限不足导致文件无法访问。
• 版本选择：不同版本功能可能存在差异，建议根据分析需求指定版本（如1.12支持最新过滤语法）。
• Singularity兼容性：如需在HPC环境使用，可通过singularity pull docker://staphb/bcftools:1.12转换为Singularity镜像。
• 问题反馈：使用中若遇到镜像相关问题，可提交Issue至StaPH-B/docker-builds。

8. 参考链接

• bcftools官方仓库
• StaPH-B Docker镜像仓库
• StaPH-B用户指南
• Docker-Singularity转换指南