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 또는 인델이 있는지 결정합니다. 핵심 아이디어는 서로 보완적인 두 개의 신경망 모델을 결합하는 것입니다:

모델	기능	트레이드오프
Pileup	정렬의 압축된 요약본(А/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월)

이단계 딥러닝 파이프라인 – 빠른 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 레시피(애플 실리콘 지원 포함).
풍부한 후처리 – 선택적 페이징(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 빌드 필요(예: 애플 실리콘, 특정 CUDA 버전).	모든 패키지에 대한 완전한 제어; M-시리즈 맥에서 작동.

모든 방법은 결국 동일한 스크립트(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월).
지원 – 세 명의 주요 개발자에게 연락 가능한 이메일; GitHub에서 버그 및 기능 요청에 대한 이슈 트래커 제공.

TL;DR

Clair3는 딥러닝 기반의 롱리드 시퀀싱 변이 호출기로, 속도(PILEUP 모델)와 정확도(FULL-ALIGNMENT 모델) 사이의 균형을 맞춥니다. CPU, GPU, 애플 실리콘에서 실행 가능하며, Docker, Singularity, Bioconda, 또는 Conda를 통해 설치할 수 있으며, ONT, PacBio, Illumina 데이터용 사전 훈련된 모델을 제공합니다. 롱리드에서 고품질의 유전적 SNP/인델 호출이 필요하다면, Clair3는 성숙하고 지속적으로 유지보수되는 옵션입니다.