Clair3: 基于深度学习的第三代长读长变异检测工具¶

概述¶

Clair3 是一款专为 长读长 测序数据设计的 胚系小变异（germline small variants）检测工具。它巧妙结合了两种互补的分析策略，在检测速度与准确性之间取得了良好平衡：

• Pileup 召回: 基于覆盖度堆积统计信息，利用轻量级模型快速处理绝大多数候选变异位点，效率极高。
• Full‑alignment 召回: 针对不确定或复杂的变异位点，采用完整的单倍型解析比对，调用计算复杂度更高的深度学习模型进行精细分析。

Clair3 是此工具系列的第三代产品，前两代分别为 Clair（第二代）与 Clairvoyante（第一代）。相比于前作，它在架构上引入了 PyTorch 作为深度学习后端，并增加了信号感知（signal‑aware）等前沿功能，进一步提升了在 PacBio HiFi 和 Oxford Nanopore (ONT) 数据上的表现。

若需应对特定应用场景，可参考同一家族的其它工具：

此外，Clair‑skills 是一个面向 AI 编码助手（如 Claude Code、Cursor 等）的插件集合，可辅助用户根据数据类型与需求选择合适的 Clair 家族工具及模型，自动生成可执行命令行，并解读分析结果。

核心知识点¶

1. 双策略协同的工作流¶

Clair3 的核心是将变异位点拆分为两类，分别路由至不同的深度学习模型：

1. Pileup 模型：输入为参考基因组上的覆盖度堆栈信息（pileup），输出每个位置的基因型概率。该模型具有极高的吞吐量，能够处理绝大多数低复杂度位点，是整体速度的保证。
2. Full‑alignment 模型：当 pileup 模型对某些候选变异位点给出不确定结果时（例如该位点的等位基因频率、链偏向、比对质量等特征异常），系统会从 BAM 文件中提取该位点附近所有读段的详细比对信息（包括插入删除、软剪切等），拼接成完整的单倍型比对矩阵。这一过程计算量较大，但可显著提升复杂区域或低频率变异的召回精度。

两种模型均基于深度神经网络，v2.0 版本之后统一迁移至 PyTorch 框架，不再兼容旧版 TensorFlow 模型。

2. 安装与环境配置¶

Clair3 提供多种安装途径，适应不同计算环境。推荐使用 Bioconda 或 Docker，以获得最佳依赖管理体验。若需要使用 GPU 加速（速度提升可达 5 倍），必须确保安装对应版本的 PyTorch 与 CUDA 环境。

方式 1：Docker（支持 CPU/GPU）¶

# 拉取 CPU 版本镜像
docker pull hkubal/clair3:latest

# 或拉取预构建的 GPU 镜像（含 CUDA 12.1 + PyTorch）
docker pull hkubal/clair3:v2.0.1_gpu

# 运行容器并挂载数据目录
docker run -it --rm \
  -v /your/data:/data \
  hkubal/clair3:latest \
  /opt/bin/run_clair3.sh --bam_fn /data/input.bam --ref_fn /data/ref.fa ...

方式 2：Singularity¶

singularity pull docker://hkubal/clair3:latest
./clair3_latest.sif run_clair3.sh --bam_fn sample.bam --ref_fn ref.fa ...

方式 3：Bioconda（推荐于本地或集群）¶

conda install -c bioconda clair3

方式 4：手动 Conda 分步安装¶

# 创建独立环境
conda create -n clair3 python=3.9
conda activate clair3

# 安装 Clair3 及其依赖（PyTorch 按需选择 CPU 或 GPU 版本）
conda install -c bioconda clair3 pytorch=1.13.1 cudatoolkit=11.6 -c pytorch

注意：GPU 加速目前仅在 Linux 和 Apple Silicon 上经过验证。若使用 NVIDIA GPU，请确认 CUDA 版本与 PyTorch 匹配，或直接使用预配置的 GPU Docker 镜像。

3. 预训练模型体系¶

Clair3 针对不同测序平台和化学试剂构建了系列模型，文件名通常包含孔蛋白版本、碱基识别版本、覆盖度及运行模式等信息。例如：

• ont_r1041_e82_400bps_sup_v520：适用于 ONT R10.4.1 流动池、E8.2 化学、400 bps 传输速度、SUP 碱基识别、v5.2.0 版本，并带有移动表（move table）信号感知功能。
• hifi_revio_400bps_sup_v500：适用于 PacBio HiFi Revio 系统等。

重要变更：v1 与 v2 模型不兼容

Clair3 v2.0.0 将深度学习框架从 TensorFlow 迁移至 PyTorch，旧版 .ckpt 或 .index/.data 格式的 TensorFlow 模型 无法直接被 v2 加载。社区已将部分 ONT 模型转换为 PyTorch 格式，存放于PyTorch 模型库。若需使用私人定制的旧版模型，请参照模型迁移指南自行转换。

对于 ONT 数据，v2.0.0 还引入了信号感知变异检测（详见高级功能），使用时需指定含有 Dorado mv 标签的 BAM 文件，并开启 --enable_dwell_time。

4. 基本使用流程¶

Clair3 的核心脚本是 run_clair3.sh（或 v2 新增的 run_clair3.py）。运行前需准备好：

• 排序并索引的 BAM/CRAM 文件（samtools index）
• 参考基因组 FASTA 文件（需与 BAM 头匹配，且已索引）
• 指定输出目录

最简命令示例（PacBio HiFi 数据）：¶

run_clair3.sh \
  --bam_fn /path/to/hifi.bam \            # 输入 BAM 文件
  --ref_fn /path/to/reference.fasta \     # 参考基因组
  --platform hifi \                       # 平台类型：ont / hifi / ilmn 等
  --model_path /path/to/model \           # 预训练模型的文件夹路径
  --output /path/to/output_dir            # 输出目录

参数说明： - --platform：指定测序平台，影响内部默认参数（如最小覆盖度、比对质量阈值）。常用值包括 ont（纳米孔）、hifi（PacBio HiFi）、ilmn（Illumina，仅供测试）。 - --model_path：必填，指向包含 model 文件和配置文件（如 pileup、full_alignment 子目录）的目录。程序会根据此路径自动查找所需模型结构。 - --threads（或 -t）：设置并行线程数，默认为 4。适当增加可加快桩文件处理和模型推理速度。 - --chunk_size：基因组切分片段大小（bp），默认值基于平台自动设定（ONT 通常 10M，HiFi 可更大）。 - --gvcf：输出 GVCF 格式，包含所有参考位点的基因型信息，适用于群体分析。

输出产物¶

运行结束后，输出目录下将包含：

• *.vcf.gz：压缩的 VCF 文件
• *.vcf.gz.tbi：VCF 索引
• *.gvcf.gz（若开启 --gvcf）
• 若干中间文件（如分片结果、pileup 统计文件等），可在大型项目调试时查看。

5. 高级功能与应用¶

5.1 信号感知变异检测（ONT 数据）¶

对于使用 Dorado 碱基识别并带有 mv 标签（通过 --emit-moves 产生）的 ONT 数据，Clair3 v2 可提取驻留时间（dwelling time）作为额外特征，输入到专门训练的神经网络中。这一功能有助于区分真实的变异与同聚体长度波动、碱基修饰等引起的系统误差。

启用方法：

run_clair3.sh \
  --bam_fn sample_with_mv.bam \
  ... \
  --enable_dwell_time

注意：该参数仅在 ONT 平台且模型支持 dwelling time 时才有效。未包含 mv 标签的 BAM 文件强行开启会导致运行失败或结果退化。更多细节参见 Dwelling Time 专题文档。

5.2 扩增子数据优化¶

扩增子测序（如 16S、靶向捕获）中，覆盖度极度不均匀且可能存在聚合酶扩增错误。Clair3 针对此类数据做了专门适配：

• 设置 --chunk_num=-1，程序将以每个读段堆积区域独立切分，而非按固定窗口。这避免了高覆盖度扩增子片段跨越多个分片，提升局部比对质量。
• 建议关闭或调低最小等位基因频率（AF）阈值（--min_snp_af 0.0 --min_indel_af 0.0），以保留低频变异。
• 若目标区域较小，可使用 --ctg_name 限制检测范围，进一步加速运行。

5.3 单倍型分型与后处理¶

Clair3 内建了简单的分型逻辑，但更精细的单倍型解析可通过以下途径实现：

• LongPhase 整合：Clair3 依赖 LongPhase 对长读长进行单倍型定相，提升全长比对模型的准确性。版本随 Clair3 一同分发，定期升级。
• 补充后处理脚本：
• AddPairEndAlleleDepth：为 VCF 输出添加 PEAD（双端等位基因深度）标签，适用于评估链特异性信号。
• split_haplotype_into_haploid_calling：将二倍体样本拆分为两个单倍型，再进行变异检测，可降低杂合位点的误判。

5.4 GPU 加速使用¶

在 GPU 节点上运行 Clair3，只需确保环境变量正确，程序会自动优先选择 GPU 设备。若使用 Docker，推荐拉取专用 GPU 镜像：

docker run --gpus all -v /data:/data hkubal/clair3:v2.0.1_gpu \
  run_clair3.sh --bam_fn /data/sample.bam --ref_fn /data/ref.fa ...

苹果芯片（M 系列）的用户可利用 MPS 后端加速，无需额外配置，安装 PyTorch 后即可透明启用。

代码实操¶

示例 1：Bioconda 安装并运行 PacBio HiFi 数据¶

# 1. 创建并激活环境
conda create -n clair3 -c bioconda clair3
conda activate clair3

# 2. 下载参考基因组并索引（以 hg38 为例）
wget ftp://ftp.ensembl.org/pub/release-109/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
gunzip Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
samtools faidx Homo_sapiens.GRCh38.dna.primary_assembly.fa

# 3. 下载对应测序平台的预训练模型（此处以 HiFi Revio 为例）
wget https://www.bio8.cs.hku.hk/clair3/clair3_models_pytorch/hifi_revio.tar.gz
tar -xzf hifi_revio.tar.gz

# 4. 运行 Clair3
run_clair3.sh \
  --bam_fn /path/to/hifi.bam \
  --ref_fn Homo_sapiens.GRCh38.dna.primary_assembly.fa \
  --platform hifi \
  --model_path hifi_revio \
  --output ./clair3_hifi_out \
  --threads 16 \
  --gvcf

示例 2：利用 Docker 运行 ONT 信号感知模型¶

# 假设 BAM 已包含 mv 标签（由 Dorado basecaller 生成）
# 拉取最新 GPU 镜像
docker pull hkubal/clair3:v2.0.1_gpu

# 运行（注意模型路径映射到容器内）
docker run --gpus all \
  -v /mnt/data:/data \
  hkubal/clair3:v2.0.1_gpu \
  /opt/bin/run_clair3.sh \
    --bam_fn /data/ont_mv.bam \
    --ref_fn /data/ref.fa \
    --platform ont \
    --model_path /data/ont_r1041_e82_sup_v520_model \
    --output /data/clair3_ont_gpu \
    --enable_dwell_time \
    --threads 32 \
    --gvcf

示例 3：使用 python 入口（v2 新增）¶

python run_clair3.py \
  --bam_fn sample.bam \
  --ref_fn reference.fa \
  --platform hifi \
  --model_path ./hifi_model \
  --output ./results

提示：run_clair3.py 是 v2 提供的全新 Python 实现，参数与原有 shell 脚本完全兼容，且更容易集成到其它 Python 工作流中。

常见问题¶

Q1: 升级到 v2 后，旧模型无法加载，如何解决？¶

Clair3 v2 的 PyTorch 后端无法直接读取 TensorFlow 格式的模型文件（.ckpt、.index）。请使用官方提供的预转换 PyTorch 模型，或按照迁移指南将自有旧模型转换为 .pt 格式。检查点文件结构已完全变化，不可混用。

Q2: 如何为我的 ONT 数据选择合适的模型？¶

首先确认基线识别的版本和模式（FAST、HAC、SUP）。Clair3 模型命名包含三个关键字段：孔蛋白型号（如 r1041）、化学版本（如 e82）、碱基识别档次（hac, sup）。选择与您的实验完全匹配的模型。若不确定 BAM 中的信息，可使用 samtools view -H | grep 'read_group' 查看头部的 DS 标签或碱基识别软件的日志。

信号感知模型仅适用于使用 Dorado 并开启了 --emit-moves 的数据，且能进一步提升特异性和敏感性。

Q3: 运行时报错“GPU not available”或内存不足？¶

• 检查 CUDA 驱动和 PyTorch 版本：在 Python 中执行 import torch; print(torch.cuda.is_available())。若返回 False，请重新安装匹配 CUDA 的 PyTorch 版本。
• 若使用 CPU 模式运行速度慢，可开启多线程（--threads 设为物理核心数），并确保内存足够。对于人类全基因组数据，建议至少 64 GB 内存。
• 当使用 Full‑alignment 模型时，极高覆盖度区域可能出现内存溢出。可尝试调低 --chunk_size 或利用 --chunk_num=-1 在扩增子场景下优化分片。

Q4: 输出 VCF 头部版本号始终显示 1.2.0？¶

如果安装的 Clair3 版本 ≥2.0.1，但 VCF 头部仍记录 clair3_version=1.2.0，这可能是旧版本残留的缓存文件导致。请彻底清空输出目录后重试，或确认安装无误（clair3 --version 检查版本号）。v2.0.1 已修复此问题。

Q5: 能不能同时获得 GVCF 和 VCF？¶

可以。在命令行中同时指定 --vcf_fn 和 --gvcf 即可分别输出常规 VCF 和基因组变异呼叫格式（GVCF）文件。注意，启用 GVCF 后计算量略有增加，输出文件体积会较大。

Q6: 如何分析序列开头或末端的变异？¶

默认情况下，由于比对可靠性和上下文不足，Clair3 跳过每个序列（contig）前 16bp 和末尾 16 bp 的变异检测。若需强行包含这些区域，可添加参数 --enable_variant_calling_at_sequence_head_and_tail，但结果假阳性可能会升高，请谨慎解读。

速查表¶

常用参数一览¶

推荐模型速查（PyTorch v2 模型）¶

完整模型列表请访问官方模型库：https://www.bio8.cs.hku.hk/clair3/clair3_models_pytorch/

输出文件说明¶

引用¶

若您在工作中使用了 Clair3，请引用其最新文章（具体引用信息请参考官方 GitHub 仓库或已发表的对应版本论文）。同时，若用到相关子模块（如 LongPhase、ClairS 等），也应遵循其各自的引用要求。

联系与反馈
Ruibang Luo, Zhenxian Zheng, Xian Yu
邮箱：rbluo@cs.hku.hk · zxzheng@cs.hku.hk · yuxian@connect.hku.hk
GitHub 仓库：https://github.com/HKU-BAL/Clair3

工具在持续更新中，使用前请确认最新版本和模型。遇到问题建议先在 GitHub Issues 中搜索，或提交新 Issue 并附上详细的运行日志。