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 またはインデルがあるかどうかを判断します。主なアイデアは、2 つの補完的なニューラルネットワークモデルを組み合わせることです：

モデル	機能	デメリット
Pileup	アライメントのコンパクトな要約（A/C/G/T、挿入、削除などのカウント）を処理。非常に高速で、簡単な変異の大部分を検出。	複雑な、または信頼性の低いサイトを見逃す可能性がある。
Full‑alignment	各候補に対して完全でハプロタイプ解決済みのアライメントを調べる。計算量は多いが、難しいケースを解決できる。	ゆっくりだが、難しい領域での精度を向上させる。

まず Pileup モデルでスキャンし、その後不確実な候補のみを Full‑alignment モデルで再検査することで、Clair3 は高い精度を維持しつつ、実行時間も合理的な水準に保つことができます。

だれが使うべきですか？

シナリオ	推奨ツール
長読取り DNA（ONT、PacBio）の胚細胞変異呼び出し	Clair3
長読取り RNA‑seq の胚細胞変異呼び出し	Clair3‑RNA（別リポジトリ）
体細胞（腫瘍/正常）呼び出し	ClairS
腫瘍のみの体細胞呼び出し	ClairS‑TO

このリポジトリには、AI コーディングアシスタント（Claude、Cursor、Codex など）が自動的に適切な Clair ツールを選択し、コマンドラインを構築し、結果を解釈できるプラグイン Clair‑skills も同梱されています。

主な機能（v2.0.3、2026年9月時点）

2段階の深層学習パイプライン – 高速な 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}

PacBio HiFi データの場合は --platform を hifi、Illumina データの場合は ilmn に置き換えてください。GPU 加速が必要な場合は、*_gpu Docker イメージを使用し、--use_gpu（または同等の Singularity フラグ）を追加してください。

インストール方法

方法	使用する場面	ハイライト
Docker	Docker を持っていて、ワンライナーで済ませたい場合	事前ビルド済みの CPU および GPU イメージ；すべての依存関係を隔離。
Singularity	Docker が許可されていない HPC クラスタで使用する場合	Docker と同じイメージを提供；GPU 使用には `--nv` を追加。
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）。

モデルは Conda の場合は ${PREFIX}/bin/models/、Docker の場合は /opt/models/ に保存されます。README には古い TensorFlow モデルの変換ツールへのリンクがあります。

ドキュメントとコミュニティ

リリースノート – 2021 年初回リリースから v2.0.3 までの詳細な変更履歴。
上級トピック – ドウェリングタイムの扱い、アミプリコンデータ、後処理スクリプト、トレーニングデータガイド。
引用 – Clair3‑v2 のパフォーマンスを説明する bioRxiv プリプリント（2026年2月）。
サポート – 3 人の主要開発者の連絡先メール；GitHub 上のイシュー追跡システムでバグや機能要望を報告可能。

TL;DR

Clair3 は、長読取りシーケンシング向けの深層学習駆動型変異呼び出しツールであり、速度（Pileup モデル）と精度（Full‑alignment モデル）のバランスを取っています。CPU、GPU、Apple Silicon で動作可能で、Docker、Singularity、Bioconda、Conda でインストールでき、ONT、PacBio、Illumina データ用の事前学習済みモデルを多数提供しています。長読取りデータから高品質な胚細胞 SNP/インデル呼び出しが必要な場合、Clair3 は成熟し、積極的にメンテナンスされている選択肢です。