HKU-BAL/Clair3

What is Clair3?

Clair3 is an open‑source germline small‑variant caller designed for long‑read sequencing data (Oxford Nanopore, PacBio HiFi, Illumina). It uses deep‑learning models to decide whether a position in the genome contains a SNP or an indel. The key idea is to combine two complementary neural‑network models:

Model	What it does	Trade‑off
Pileup	Works on a compact summary of the alignment (counts of A/C/G/T, insertions, deletions, etc.). Very fast and catches the bulk of easy variants.	May miss complex or low‑confidence sites.
Full‑alignment	Looks at the complete, haplotype‑resolved alignment for each candidate. More computationally heavy but resolves the hard cases.	Slower, but improves accuracy on difficult regions.

By first scanning with the pileup model and then re‑examining only the uncertain candidates with the full‑alignment model, Clair3 gets high accuracy while keeping runtime reasonable.

---

Who might use it?

Scenario	Recommended tool
Germline variant calling on long‑read DNA (ONT, PacBio)	Clair3
Germline variant calling on long‑read RNA‑seq	Clair3‑RNA (separate repo)
Somatic (tumor/normal) calling	ClairS
Tumor‑only somatic calling	ClairS‑TO

The repository also ships a plug‑in called Clair‑skills that lets AI coding assistants (Claude, Cursor, Codex, …) automatically pick the right Clair tool, build the command line, and interpret the results.

---

Main features (as of v2.0.3, Sep 2026)

• Two‑stage deep‑learning pipeline – fast pileup + precise full‑alignment.
• PyTorch backend (migrated from TensorFlow in v2.0.0). All v2 models are PyTorch .pt files; older TensorFlow models are incompatible.
• GPU acceleration – native CUDA support (Linux) gives ~5× speed‑up over CPU; a pre‑built GPU Docker image is provided.
• Signal‑aware calling – can use ONT “move‑table” (mv) tags from Dorado base‑callers via the --enable_dwell_time flag.
• Sex‑chromosome handling – --gender option lets the caller treat X/Y with the correct ploidy.
• Robust output – always produces a valid, indexed VCF/gVCF, even when no variants are found.
• Cross‑platform installation – Docker, Singularity, Bioconda, or a step‑by‑step Conda recipe (including Apple‑Silicon support).
• Extensive post‑processing – optional phasing with WhatsHap or LongPhase, GVCF compression, and scripts for amplicon data, dwelling‑time features, etc.

---

Getting started (quick demo)

# Example using the pre‑built CPU Docker image
INPUT=/data   # folder containing input.bam and 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}

Replace --platform with hifi or ilmn for PacBio HiFi or Illumina data, respectively. For GPU acceleration, use the *_gpu Docker image and add --use_gpu (or the equivalent Singularity flags).

---

Installation options

Method	When to use	Highlights
Docker	You have Docker and want a one‑liner.	Pre‑built CPU and GPU images; isolates all dependencies.
Singularity	HPC clusters where Docker is not allowed.	Same images as Docker, plus --nv for GPU.
Bioconda	You prefer a Conda environment and only need CPU.	Installs PyTorch (CPU‑only), samtools, whatshap, LongPhase, and bundled models.
Step‑by‑step Conda	Need custom PyTorch build (e.g., Apple Silicon, specific CUDA version).	Full control over every package; works on M‑series Macs.

All methods ultimately call the same script (run_clair3.sh or the newer run_clair3.py).

---

Model zoo

Pre‑trained models are shipped with the package and also available for download:

• ONT models – various chemistries (R10.4, R9.4, etc.) and base‑caller versions (Guppy 5, Dorado v5.2). Some are signal‑aware (require --enable_dwell_time).
• PacBio HiFi models – including a Revio‑specific model.
• Illumina model – for short‑read data (Clair3‑Illumina).

Models are stored under ${PREFIX}/bin/models/ (Conda) or /opt/models/ (Docker). The README links to conversion tools for older TensorFlow models.

---

Documentation & community

• Release notes – detailed changelog from the first 2021 release up to v2.0.3.
• Advanced topics – handling dwelling time, amplicon data, post‑processing scripts, and training‑data guides.
• Citation – a bioRxiv pre‑print (Feb 2026) describing Clair3‑v2 performance.
• Support – contact emails for the three lead developers; issue tracker on GitHub for bugs and feature requests.

---

TL;DR

Clair3 is a deep‑learning‑powered variant caller for long‑read sequencing that balances speed (pileup model) and accuracy (full‑alignment model). It runs on CPU, GPU, or Apple Silicon, is installable via Docker, Singularity, Bioconda, or Conda, and provides a suite of pre‑trained models for ONT, PacBio, and Illumina data. If you need high‑quality germline SNP/indel calls from long reads, Clair3 is a mature, actively maintained option.