hkubal/clair3

Clair3 Docker镜像文档

1. 镜像概述与主要用途

Clair3 是一款针对长读长测序数据设计的小型变异调用器（variant caller），旨在通过深度学习方法实现高效、准确的小变异（SNP和Indel）检测。相比前代工具 PEPPER (r0.4)，Clair3 (v0.1) 在 ≤30 倍覆盖度的 ONT（Oxford Nanopore Technologies）数据中，展现出更优的 SNP F1 分数和 Indel F1 分数，同时运行速度提升约 4 倍。其核心优势在于融合了 pileup 和 full-alignment 两种输入模式，为深度学习模型提供更全面的特征，从而平衡检测精度与计算效率。

Clair3 采用模块化设计，部署与集成简便，适用于各类长读长测序数据的变异分析场景。项目开源，代码托管于 https://github.com/HKU-BAL/Clair3%E3%80%82

2. 核心功能与特性

2.1 长读长小变异检测

• 专注于长读长测序数据（如 ONT、PacBio）的 SNP 和 Indel 检测，支持小型变异（通常 ≤50 bp）的精准识别。

2.2 融合双输入模式

• 创新性结合 pileup 和 full-alignment 作为深度学习模型的输入：
  • Pileup：提供局部碱基分布统计特征，计算效率高；
  • Full-alignment：保留完整的读长比对信息，提升变异边界识别精度。

2.3 性能优化

• 精度提升：在 ≤30 倍 ONT 数据中，SNP 和 Indel 的 F1 分数均优于 PEPPER (r0.4)（基于 precisionFDA Truth Challenge V2 验证）；
• 速度提升：运行效率较 PEPPER (r0.4) 提高约 4 倍，降低计算资源消耗。

2.4 模块化与可扩展性

• 采用简洁的模块化架构，支持与现有生物信息分析流程（如变异检测流水线）快速集成，适配不同测序平台和数据类型。

3. 使用场景与适用范围

3.1 适用数据类型

• 长读长测序数据：主要支持 ONT 和 PacBio 平台生成的长读长数据；
• 覆盖度要求：优化于低至 ≤30 倍覆盖度的数据，在中高覆盖度场景下仍保持稳定性能。

3.2 应用场景

• 基因组变异分析：科研或临床领域中，基于长读长数据的个体基因组、肿瘤基因组等小变异检测；
• 低覆盖度数据优化：适用于样本量较大或测序成本受限的项目，在有限覆盖度下实现高效变异检出；
• 流程集成：作为变异检测模块，嵌入长读长数据分析流水线（如结构变异联合检测、单倍型定相分析等）。

4. 使用方法与 Docker 部署

4.1 镜像获取

假设 Clair3 官方 Docker 镜像托管于 Docker Hub（实际使用时需以 GitHub 项目文档为准），可通过以下命令拉取：

bash
docker pull hku-bal/clair3:latest

若需构建本地镜像，可从 https://github.com/HKU-BAL/Clair3 克隆代码后，基于项目根目录的 Dockerfile 构建：

bash
git clone https://github.com/HKU-BAL/Clair3.git
cd Clair3
docker build -t clair3:local .

4.2 基础使用示例（docker run）

Clair3 的核心功能通过命令行工具实现，基本调用需指定输入 BAM 文件、参考基因组 FASTA 文件及输出目录。以下为典型运行示例：

bash
docker run -it --rm \
  -v /path/to/local/data:/data \  # 挂载本地数据目录至容器内/data
  hku-bal/clair3:latest \
  run \  # 主命令（具体子命令以官方文档为准）
  --bam /data/input.bam \  # 输入长读长比对文件（BAM格式，需索引）
  --ref /data/reference.fasta \  # 参考基因组FASTA文件（需索引）
  --output /data/output_vcf \  # 输出目录（存放VCF及中间文件）
  --threads 8 \  # 线程数（根据宿主机CPU核心数调整）
  --model ont \  # 测序平台模型（如ont/pacbio，默认ont）
  --coverage 30  # 数据覆盖度（用于模型参数优化，默认自动推断）

参数说明：

• -v /path/to/local/data:/data：将本地数据目录（含 BAM、参考基因组等）挂载至容器内 /data，确保容器可访问输入文件；
• --bam：输入 BAM 文件路径（容器内路径，需对应挂载目录），必须包含索引文件（.bai）；
• --ref：参考基因组 FASTA 文件路径（容器内路径），必须包含索引文件（.fai）；
• --output：输出目录路径（容器内路径），结果文件（如 VCF）将保存至该目录；
• --threads：并行计算线程数，建议根据宿主机 CPU 核心数设置（如 8-16）；
• --model：指定测序平台模型（ont 或 pacbio），用于加载预训练权重；
• --coverage：输入数据的预期覆盖度（如 20、30），辅助模型优化检测阈值。

4.3 Docker Compose 配置示例

对于需要长期运行或集成至流程的场景，可通过 docker-compose.yml 简化部署：

yaml
version: '3'
services:
  clair3:
    image: hku-bal/clair3:latest
    volumes:
      - /local/data:/data  # 本地数据目录挂载
      - /local/models:/models  # （可选）自定义模型权重目录挂载
    command: >
      run
      --bam /data/sample.bam
      --ref /data/hg38.fasta
      --output /data/clair3_results
      --threads 12
      --model ont
      --coverage 25
      --min_af 0.05  # （可选）最小等位基因频率阈值
    environment:
      - TMPDIR=/tmp  # 临时文件目录（默认/tmp，可自定义）
    restart: no  # 非长期运行任务，完成后退出

启动命令：

bash
docker-compose up

5. 配置说明

5.1 核心命令行参数

Clair3 的主要功能通过子命令 run 实现，关键参数如下（详细列表请参考 https://github.com/HKU-BAL/Clair3%EF%BC%89%EF%BC%9A

5.2 环境变量

容器运行时可通过环境变量调整基础配置：

• TMPDIR：临时文件目录（默认 /tmp），若需指定更大空间的临时目录，可设置为 /data/tmp（需提前在挂载目录中创建）；
• CUDA_VISIBLE_DEVICES：若容器支持 GPU 加速（需使用带 CUDA 的镜像变体），可通过该变量指定使用的 GPU 设备（如 0,1）。

5.3 输出文件说明

Clair3 输出目录（--output 指定）包含以下关键文件：

• calls.vcf.gz：压缩的变异检测结果 VCF 文件（包含 SNP 和 Indel 信息）；
• calls.vcf.gz.tbi：VCF 索引文件（用于快速检索）；
• log.txt：运行日志（包含参数、进度及异常信息）；
• intermediate/：中间文件目录（可删除以节省空间）。

6. 注意事项

• 输入文件需提前索引：BAM 文件需生成 .bai 索引，FASTA 文件需生成 .fai 索引（可通过 samtools index 和 samtools faidx 生成）；
• 资源需求：根据数据规模调整线程数和内存（推荐 ≥16 GB 内存，低覆盖度数据可适当降低）；
• 模型选择：需根据测序平台（ONT/PacBio）指定 --model 参数，否则可能影响检测精度；
• 版本兼容性：建议使用最新版镜像，以获取性能优化和 bug 修复，具体版本信息可通过 docker run hku-bal/clair3:latest --version 查看。

7. 参考链接

• 官方代码仓库：https://github.com/HKU-BAL/Clair3
• 详细使用文档：参见 GitHub 仓库 docs/ 目录
• 性能验证数据集：precisionFDA Truth Challenge V2