ClairS-TO — 基于深度学习的肿瘤单样本长读长体细胞小变异检测工具¶

概述¶

ClairS-TO（Somatic Tumor-Only）是Clair系列工具中专为长读长测序数据开发的肿瘤单样本体细胞小变异（small variant）检测工具。在缺乏配对正常样本的情况下，传统流程难以通过肿瘤-正常样本的共有信号消除非体细胞噪声，因此对变异检出器的判别能力提出了更高要求。ClairS-TO 创造性地提出双神经网络集成架构，让两个在相同数据上训练但任务截然相反的神经网络协同工作：

• 肯定型神经网络（Affirmative Neural Network, AFF）：估计候选位点是体细胞变异的概率 P_AFF(y|x)；
• 否定型神经网络（Negational Neural Network, NEG）：估计候选位点不是体细胞变异的概率 P_NEG(¬y|x)。

最终通过结合两个网络的输出与训练样本的先验概率，计算每个候选位点的后验概率 P(y|(P_AFF(y|x), 1 - P_NEG(¬y|x)))。这种类似“对抗互验”的思想有效提升了仅从肿瘤样本区分体细胞变异、胚系变异（germline variant）以及背景噪声的能力。

除核心神经网络外，ClairS-TO 还提供一套完整的后处理过滤策略： 1. 9 个硬过滤规则，用于剔除明显低质量候选； 2. 群体正常样本面板（Panel of Normals, PoN），支持内置 4 个公共 PoN 及任意数量的用户自定义 PoN； 3. 统计分离模块，利用估计的肿瘤纯度和拷贝数轮廓进一步区分体细胞与胚系变异。

该工具已发表于《Nature Communications》，同时可在 bioRxiv 获取预印本。对于需要进行配对肿瘤/正常样本体细胞变异检测的用户，可使用 ClairS；胚系变异检测（DNA-seq）请使用 Clair3；长读长 RNA-seq 胚系变异检测请使用 Clair3-RNA；若需要 AI 代理技能（如 Claude Code、Cursor、Codex）辅助操作，可参考 Clair-skills。

核心知识点¶

双神经网络集成机制¶

ClairS-TO 的核心创新在于AFF 与 NEG 两个网络的协同工作。两者均基于相同的合成或真实肿瘤样本进行训练，但目标函数完全相反： - AFF 的目标是最大化真体细胞变异的检测概率，输出高置信度当且仅当位点为体细胞变异； - NEG 的目标是最小化将非体细胞变异（胚系变异或噪声）错误判为体细胞变异的概率，即输出“不是体细胞变异”的高置信度。

推理阶段，对于每个候选变异，同时运行两个网络，得到 p_AFF 和 p_NEG（其中 p_NEG 表示“不是体细胞变异”的概率）。然后通过贝叶斯框架融合这两路信息与训练集得到的类别先验，输出最终的后验概率。该架构有效缓解了单一模型易受胚系位点干扰的问题，尤其在肿瘤纯度较低或测序深度不均时优势显著。

模型类型：SS 与 SSRS¶

ClairS-TO 提供两种训练策略的模型，以满足不同应用场景： - SS（Synthetic Samples）：仅使用合成样本训练，当担心真实数据中缺少某种癌症类型而导致模型偏倚时，可选择该模型。 - SSRS（Synthetic Samples + Real Samples augmented）：在合成样本基础上，混合已知癌症类型的真实细胞系数据（如乳腺癌 HCC1937、HCC1954；肺癌 H1437、H2009）进行增强训练。通常 SSRS 模型具有更好的性能，推荐默认使用。

模型命名规则如 ont_r10_dorado_sup_5khz_ssrs（ONT 平台 R10 化学、Dorado 碱基识别、5 kHz 采样频率的 SSRS 模型）和 ont_r10_dorado_sup_5khz_ss（对应的 SS 模型）。对于 PacBio Revio 平台及 Illumina 平台也提供相应版本。

后置过滤流水线¶

硬过滤¶

内置 9 条经验性规则，直接剔除不符合质量标准的变异，例如覆盖度极低、等位基因频率异常、附近区域存在复杂结构等。硬过滤可快速过滤大量假阳性，减少下游计算压力。

正常样本面板（PoN）标签化¶

通过比较候选变异在大量正常样本中的出现频率，标记出常见的胚系变异或反复出现的系统性假阳性。ClairS-TO 默认内置来自公共数据库（如 CoLoRSdb）的 4 个 PoN，并支持用户添加自定义 PoN VCF 文件。该模块对低等位基因频率的胚系变异特别有效，可大幅降低假阳性。

克隆性统计分离¶

该模块利用用户提供的肿瘤纯度和拷贝数轮廓（可通过其他工具计算），对等位基因频率分布进行统计建模，将候选变异划分为“体细胞”或“胚系”两类。这一步能捕捉到那些因克隆造血等生物过程产生的胚系背景信号。

工作流程概览¶

下图展示了 ClairS-TO 的典型运行流程： 1. 输入肿瘤 BAM/CRAM 文件及参考基因组； 2. 生成候选变异位点； 3. 利用集成神经网络进行打分； 4. 依次通过硬过滤、PoN 标签化、统计分离模块； 5. 输出带注释的 VCF 文件。

性能亮点¶

ClairS-TO 在多种深度（25×/50×/75×）和平台（ONT Q20+、PacBio Revio、Illumina）上与现有工具（Clair3、DeepSomatic、Mutect2 等）进行了系统比较。主要结论： - 在 ONT 和 PacBio 平台上，ClairS-TO 的 SSRS 模型在精密-召回曲线（Precision-Recall curves）和最高 F1 分数上均处于领先地位； - 在 Illumina 短读长数据上，ClairS-TO 仍展现出与专用工具相当的竞争力，但其核心优势仍在长读长领域； - 在低覆盖度场景（如 25×肿瘤覆盖度）下，ClairS-TO 的优势更为明显，这得益于双网络设计对噪声的稳健性。

（具体性能曲线和对比数据请参见仓库文档中的示意图）

代码实操¶

环境准备¶

推荐使用 Docker 镜像，以避免依赖冲突。以下为基本安装方式：

方式1：Docker 预构建镜像¶

# 拉取官方镜像
docker pull hkubal/clair3:tag  # 实际镜像名称以官方为准，此处仅为示例

# 或使用 singularity
singularity pull docker://hkubal/clair3:tag

方式2：micromamba / conda 虚拟环境¶

# 创建环境（假设已有 micromamba）
micromamba create -n clairs-to python=3.10 pytorch cudatoolkit=11.8 -c pytorch -c conda-forge
micromamba activate clairs-to

# 安装 ClairS-TO 所需依赖
git clone https://github.com/HKU-BAL/ClairS-TO.git
cd ClairS-TO
pip install -r requirements.txt

基本使用命令¶

ClairS-TO 提供简洁的命令行接口，以下为典型分析命令的详细注释。

# 基本体细胞变异检测命令
run_clairS-TO.sh \
  --bam_fn /data/tumor.bam \             # 肿瘤样本 BAM 文件路径
  --ref_fn /data/ref.fa \                 # 参考基因组 FASTA 文件路径
  --platform ont \                        # 测序平台：ont / hifi_revio / ilmn
  --model_path /models/ont_r10_dorado_sup_5khz_ssrs \  # 预训练模型路径或名称
  --output /output/prefix \               # 输出文件前缀
  --threads 16 \                          # 使用的 CPU 线程数
  --tumor_purity 0.6 \                    # 肿瘤纯度（可选，用于统计分离）
  --cnv_profile /data/cnv.bed \           # 拷贝数变异轮廓文件（可选）
  --pon_list pon1.vcf.gz,pon2.vcf.gz      # 自定义 PoN VCF 列表，逗号分隔

参数说明¶

• --platform：必须与模型匹配，可选 ont（牛津纳米孔）、hifi_revio（PacBio Revio HiFi）、ilmn（Illumina 短读长）。
• --model_path：支持直接指定下载的模型目录，或使用内置模型名称（如 ont_r10_dorado_sup_5khz_ssrs），脚本会自动下载。
• --pon_list：用户提供的额外 PoN 文件（gzip 压缩的 VCF），多个文件用逗号分隔。若未指定，仅使用内置的 4 个公共 PoN。
• --tumor_purity 和 --cnv_profile 为可选参数，当提供时，可激活统计分离模块，进一步区分体细胞与胚系变异；若不提供，则该步骤会被跳过，最终输出仍会保留胚系标签但分离能力下降。

使用自定义 PoN 进行非体细胞标记¶

PoN 模块是独立步骤，也可单独运行：

# 使用 PoN 标签化已生成的 VCF（可选）
python scripts/tag_non_somatic.py \
  --candidate_vcf /output/candidates.vcf \   # 输入候选 VCF
  --pon_vcf_list pon1.vcf,pon2.vcf \        # PoN VCF 列表
  --output /output/tagged.vcf               # 输出带标签的 VCF

输出文件解读¶

运行完成后，主要输出文件包括： - *.vcf.gz：主结果文件，包含 FILTER 列标记（PASS 或非体细胞标签）及 INFO 字段（如 P_AFF、P_NEG、POSTERIOR、SOMATIC_FLAG 等）。 - *.hard_filtered.vcf：仅经硬过滤的中间文件，可用于诊断。 - 日志文件：记录每一步的执行情况和统计信息。

常见问题¶

1. 运行过程中出现 OOM（内存溢出）错误怎么办？¶

当提供超大 PoN 文件时，v0.4.3 以前版本可能触发内存溢出。解决办法：升级到 v0.4.3 及以上版本，该版本将 PoN 处理改为流式（stream-based）处理，内存占用大幅降低并加入了安全检查。同时对于超百万候选变异的单倍型过滤步骤，可使用 --haplotype_filtering_chunk_mode True 开启分块处理模式。

2. 输出 VCF 中没有变异记录，文件为空或仅有头部？¶

此问题在 v0.4.1 已修复（#35）。若旧版本出现该情况，请升级。另外检查输入 BAM 是否包含有效比对、参考基因组是否一致、平台参数是否与数据匹配。

3. 缺失紧接插入的缺失变异（del-ins）的替代等位基因表示异常？¶

v0.4.1 修复了此问题（#38）。若使用旧版本，请升级或对复杂 indel 区域结果进行人工复核。

4. 指定 --sample_name 后，临时文件或输出文件命名冲突？¶

v0.4.4 优化了管道，确保当用户提供特定样本名称时，临时目录和输出文件名称唯一且隔离（#43）。建议始终使用最新的稳定版。

5. 模型加载时 PyTorch 版本兼容性报错？¶

v0.4.1 添加了模型加载检查，适应最新 PyTorch 版本（#37）。若仍有问题，可尝试在相应虚拟环境中升级 PyTorch 至 2.0+ 并重新安装工具依赖。

6. 如何决定使用 SS 还是 SSRS 模型？¶

• 如果您的肿瘤类型与 SSRS 训练所用的细胞系（乳腺癌、肺癌）相同或高度相似，请优先使用 SSRS 模型，可获得更高的精度和召回。
• 如果担心泛化性，或肿瘤类型罕见，合成样本训练的 SS 模型可避免真实数据引入的潜在偏差。两种模型均提供，可分别运行后比较结果的一致性。

7. 如何获取肿瘤纯度和拷贝数轮廓文件？¶

ClairS-TO 本身不提供纯度/拷贝数分析，用户可借助其他工具（如 PURPLE、Sequenza、CNVkit 等）从同一 BAM 文件或配对的核型数据中获取，并整理成 ClairS-TO 要求的 BED 格式（包含分段 log2 比值或绝对拷贝数信息）。若不提供，统计分离模块将自动跳过。

8. 如何正确禁用中间分相（phasing）？¶

v0.4.4 修复了当指定 --disable_intermediate_phasing 时仍无法完全禁用单倍型过滤的 bug（#57）。请使用最新版本，并通过该标志明确禁用。

速查表¶

主要命令速查¶

平台与模型对应速查¶

VCF 输出关键 INFO 字段¶

版本与关键更新速览¶

如何引用¶

若您在工作中使用了 ClairS-TO，请引用以下文献： - Zheng, Z., Chen, L., Luo, R. et al. ClairS-TO: a deep-learning method for tumor-only somatic variant calling using long-read sequencing. Nat Commun (2025). DOI: 10.1038/s41467-025-64547-z - 预印本：ClairS-TO: a deep-learning method for long-read tumor-only somatic small variant calling. bioRxiv (2025). DOI: 10.1101/2025.03.10.642523v1

免责声明¶

ClairS-TO 为开源工具，按 BSD-3-Clause 许可证发布。其分析结果应视为研究用途的初步证据，临床应用需进一步验证。开发者不对因使用本工具造成的任何损失承担责任。详细条款见仓库中的 LICENSE 文件。