HKU-BAL/Clair3

Clair3 - Symphonizing pileup and full-alignment for deep learning-based long-read variant calling

什么是 Clair3？

Clair3 是一个开源的 体细胞小变异检测工具，专为 长读长测序数据（Oxford Nanopore、PacBio HiFi、Illumina）设计。它使用深度学习模型来判断基因组中的某个位点是否包含 SNP 或插入/缺失（indel）。其核心思想是 结合两个互补的神经网络模型：

模型	功能	权衡
Pileup	基于比对结果的紧凑摘要（A/C/G/T、插入、删除等计数）。非常快速，能捕捉大部分简单变异。	可能遗漏复杂或低置信度的位点。
Full‑alignment	查看每个候选位点的完整、单倍型解析比对结果。计算开销更大，但能解决难题。	更慢，但能提升困难区域的准确性。

通过先用 pileup 模型快速扫描，再用 full‑alignment 模型重新检查不确定的候选位点，Clair3 实现了 高精度与合理运行时间的平衡。

哪些人可能会使用它？

场景	推荐工具
长读长 DNA（ONT、PacBio）的体细胞变异检测	Clair3
长读长 RNA‑seq 的体细胞变异检测	Clair3‑RNA（独立仓库）
体细胞（肿瘤/正常）变异检测	ClairS
单肿瘤样本体细胞变异检测	ClairS‑TO

该仓库还附带一个插件 Clair‑skills，可让 AI 编程助手（Claude、Cursor、Codex 等）自动选择合适的 Clair 工具、构建命令行并解析结果。

主要特性（截至 v2.0.3，2026 年 9 月）

两阶段深度学习流程 – 快速 pileup + 精确 full‑alignment。
PyTorch 后端（v2.0.0 起从 TensorFlow 迁移）。所有 v2 模型均为 PyTorch .pt 文件；旧版 TensorFlow 模型不兼容。
GPU 加速 – 原生 CUDA 支持（Linux）可实现比 CPU 快约 5 倍；提供预构建的 GPU Docker 镜像。
信号感知检测 – 可通过 --enable_dwell_time 标志使用 Dorado 基因组测序器生成的 ONT “move‑table”（mv）标签。
性染色体处理 – --gender 选项可让检测器根据正确的倍性处理 X/Y 染色体。
鲁棒输出 – 即使未检测到变异，也始终生成有效的、已索引的 VCF/gVCF 文件。
跨平台安装 – 支持 Docker、Singularity、Bioconda，或逐步安装的 Conda 配方（含 Apple‑Silicon 支持）。
丰富的后处理功能 – 可选的相位分析（WhatsHap 或 LongPhase）、GVCF 压缩，以及用于扩增子数据、停留时间特征等的脚本。

快速入门（快速演示）

# 使用预构建的 CPU Docker 镜像示例
INPUT=/data   # 包含 input.bam 和 ref.fa 的文件夹
OUTPUT=/out
MODEL=r1041_e82_400bps_sup_v500

docker run -it \
  -v ${INPUT}:${INPUT} \
  -v ${OUTPUT}:${OUTPUT} \
  hkubal/clair3:v2.0.2 \
  /opt/bin/run_clair3.sh \
    --bam_fn=${INPUT}/input.bam \
    --ref_fn=${INPUT}/ref.fa \
    --threads=8 \
    --platform=ont \
    --model_path=/opt/models/${MODEL} \
    --output=${OUTPUT}

将 --platform 替换为 hifi 或 ilmn 以分别用于 PacBio HiFi 或 Illumina 数据。若需 GPU 加速，请使用 *_gpu Docker 镜像并添加 --use_gpu（或等效的 Singularity 标志）。

安装选项

方法	适用场景	亮点
Docker	已安装 Docker 且希望一键安装。	提供预构建的 CPU 和 GPU 镜像；隔离所有依赖项。
Singularity	Docker 不被允许的 HPC 集群。	与 Docker 使用相同镜像，支持 `--nv` 用于 GPU。
Bioconda	偏好 Conda 环境且仅需 CPU。	安装 PyTorch（仅 CPU）、samtools、whatshap、LongPhase 及捆绑模型。
逐步 Conda 安装	需要自定义 PyTorch 构建（如 Apple Silicon、特定 CUDA 版本）。	对每个包拥有完全控制权；支持 M 系列 Mac。

所有方法最终都调用相同的脚本（run_clair3.sh 或更新的 run_clair3.py）。

模型库

预训练模型随包提供，也可下载：

ONT 模型 – 支持多种化学版本（R10.4、R9.4 等）和碱基识别器版本（Guppy 5、Dorado v5.2）。部分为 信号感知 模型（需 --enable_dwell_time）。
PacBio HiFi 模型 – 包括 Revio 专用模型。
Illumina 模型 – 用于短读长数据（Clair3‑Illumina）。

模型存储在 ${PREFIX}/bin/models/（Conda）或 /opt/models/（Docker）。README 提供了将旧版 TensorFlow 模型转换的工具链接。

文档与社区

发布说明 – 从 2021 年首个版本到 v2.0.3 的详细变更日志。
高级主题 – 处理停留时间、扩增子数据、后处理脚本及训练数据指南。
引用 – 一篇发表于 bioRxiv（2026 年 2 月）的预印本，描述了 Clair3‑v2 的性能表现。
支持 – 三位主要开发者的联系邮箱；GitHub 上的议题追踪器用于报告错误和功能请求。

TL;DR

Clair3 是一个 基于深度学习的长读长测序变异检测工具，在速度（pileup 模型）与精度（full‑alignment 模型）之间取得平衡。它可在 CPU、GPU 或 Apple Silicon 上运行，支持通过 Docker、Singularity、Bioconda 或 Conda 环境安装，并提供 ONT、PacBio 和 Illumina 数据的预训练模型。如果你需要从长读长数据中获得高质量的体细胞 SNP/indel 检测结果，Clair3 是一个成熟且持续维护的选项。