HKU-BAL/Clair3

什麼是 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「移動表」（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	HPC 集群中 Docker 不允許使用。	與 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 上的問題追蹤器，用於回報錯誤與功能請求。

---

簡要總結

Clair3 是一個 以深度學習驅動的長讀長測序變異檢測工具，在速度（pileup 模型）與準確度（full‑alignment 模型）之間取得平衡。它可在 CPU、GPU 或 Apple Silicon 上執行，支援透過 Docker、Singularity、Bioconda 或 Conda 環境安裝，並提供 ONT、PacBio 與 Illumina 資料的預訓練模型套件。若您需要從長讀長資料中取得高品質的體細胞 SNP/indel 檢測結果，Clair3 是一個成熟且持續維護的選擇。