taf-clair3

taf-clair3 packages Clair3 2.0.2, a deep-learning germline small-variant caller for long-read sequencing data. Clair3 combines fast pileup calling with full-alignment calling for more difficult candidate sites.

This TAFFISH app uses the official Clair3 CPU runtime as its upstream source and keeps the bundled pre-trained PyTorch models under /opt/models.

Package Identity

• name: clair3
• command: taf-clair3
• kind: tool
• TAFFISH version: 2.0.2-r1
• container: ghcr.io/taffish/clair3:2.0.2-r1
• native platforms: linux/amd64
• upstream: Clair3 2.0.2
• upstream source: https://github.com/HKU-BAL/Clair3
• upstream release: https://github.com/HKU-BAL/Clair3/releases/tag/v2.0.2
• runtime source: hkubal/clair3:v2.0.2@sha256:14796ed1c93367d352d7f421e9689fb3bec4b6b7d12979c5387ed65ffe3b641e
• upstream license: BSD-3-Clause

The official hkubal/clair3:v2.0.2 CPU image is linux/amd64. The TAFFISH wrapper therefore requests --platform linux/amd64 for Docker and Podman. On arm64 hosts this is backend emulation, not native arm64 support.

Installation

taf install clair3

Then run:

taf-clair3 --help
taf-clair3 run_clair3.sh --help
taf-clair3 run_clair3.sh -v

Basic Usage

The default upstream command is /opt/bin/run_clair3.sh:

taf-clair3 \
  --bam_fn sample.bam \
  --ref_fn ref.fa \
  --threads 8 \
  --platform ont \
  --model_path /opt/models/ont \
  --output clair3-out

Explicit command-mode calls are also available:

taf-clair3 run_clair3.sh --help
taf-clair3 python3 /opt/bin/run_clair3.py --help
taf-clair3 samtools quickcheck sample.bam
taf-clair3 whatshap --version
taf-clair3 longphase --version

Pass Clair3 runner options directly to taf-clair3. Use taf-clair3 <executable> ... to run helper commands, upstream help, or upstream version checks in the same container.

Common Calling Modes

ONT:

taf-clair3 \
  --bam_fn sample.bam \
  --ref_fn ref.fa \
  --threads 8 \
  --platform ont \
  --model_path /opt/models/ont \
  --output clair3-ont

PacBio HiFi:

taf-clair3 \
  --bam_fn sample.bam \
  --ref_fn ref.fa \
  --threads 8 \
  --platform hifi \
  --model_path /opt/models/hifi \
  --output clair3-hifi

Signal-aware ONT calling with Dorado move-table tags:

taf-clair3 \
  --bam_fn sample.with_mv.bam \
  --ref_fn ref.fa \
  --threads 8 \
  --platform ont \
  --model_path /opt/models/r1041_e82_400bps_sup_v520_with_mv \
  --output clair3-mv \
  --enable_dwell_time

Inputs

Clair3 requires:

• --bam_fn: sorted and indexed BAM/CRAM reads
• --ref_fn: indexed reference FASTA
• --model_path: a Clair3 v2 PyTorch model directory with pileup.pt and full_alignment.pt
• --threads: total thread budget
• --platform: ont, hifi, or ilmn
• --output: output directory

The app does not align reads or prepare production BAM/CRAM files. Use suitable upstream aligners and indexing tools before running Clair3.

Outputs

Important output files include:

• merge_output.vcf.gz: final Clair3 calls
• merge_output.vcf.gz.tbi: tabix index for the final VCF
• pileup.vcf.gz: pileup model calls
• full_alignment.vcf.gz: full-alignment model calls
• run_clair3.log: run log
• tmp/: intermediate files and command records

Use upstream options such as --gvcf, --bed_fn, --ctg_name, --include_all_ctgs, and phasing flags when appropriate for the dataset.

Models

This app keeps the official CPU image's bundled model directories in /opt/models. Common model paths include:

• /opt/models/ont
• /opt/models/hifi
• /opt/models/ilmn
• /opt/models/r1041_e82_400bps_sup_v520
• /opt/models/r1041_e82_400bps_sup_v520_with_mv
• /opt/models/r1041_e82_400bps_hac_v520
• /opt/models/r1041_e82_400bps_hac_v600
• /opt/models/hifi_revio

You can inspect the bundled model names with:

taf-clair3 find /opt/models -maxdepth 1 -mindepth 1 -type d

Clair3 v2 uses PyTorch model files. Older Clair3 v1 TensorFlow models are not compatible with this v2 runtime unless converted by upstream-supported tools.

Container Contents

The runtime includes:

• run_clair3.sh and run_clair3.py
• Clair3 Python modules and C extension helpers
• PyTorch CPU runtime and Python packages used by Clair3
• pypy3
• samtools
• whatshap
• longphase
• GNU parallel
• pigz, bgzip, and tabix
• official pre-trained model directories under /opt/models

Platform and GPU Boundary

This TAFFISH app packages the official CPU image. It does not package hkubal/clair3:v2.0.2_gpu and does not declare GPU runtime arguments.

The upstream --use_gpu option requires a GPU-capable Clair3 image, NVIDIA runtime support, and compatible CUDA/driver setup. Treat that as a future clair3-gpu style app or site-specific runtime, not as part of this CPU app.

Although Bioconda lists Clair3 packages for additional platforms such as linux-aarch64, this app intentionally follows the official bundled-model CPU Docker image for r1, so the native platform is linux/amd64.

Scope and Boundaries

This app supports the upstream Clair3 CPU command-line workflow:

• germline small-variant calling from sorted and indexed BAM/CRAM
• ONT, PacBio HiFi, and Illumina-style model choices exposed by upstream
• bundled v2 PyTorch model directories from the official CPU image
• optional dwell-time feature when the BAM contains Dorado mv tags and a matching *_with_mv model is used
• helper commands needed by the upstream runtime

This app does not:

• run read alignment, BAM sorting, or production BAM indexing for users
• provide reference genomes or truth sets
• provide CUDA/GPU execution
• provide somatic, tumor-normal, RNA-seq, or ClairS/Clair3-RNA workflows
• validate model choice for a particular basecaller, chemistry, organism, or sequencing protocol

Testing

The smoke test covers:

• TAFFISH metadata parsing with taf check
• Clair3 version and help output
• bundled helper commands and Python/PyTorch imports
• selected bundled model directories and model files
• an offline tiny no-read BAM/FASTA path that produces a valid indexed merge_output.vcf.gz
• dynamic-library checks for compiled Clair3 helpers and selected binaries

Smoke tests are offline and self-contained. They do not benchmark variant calling accuracy or replace validation on real long-read datasets.

License and Citation

The TAFFISH app packaging code and documentation are licensed as Apache-2.0. Upstream Clair3 is BSD-3-Clause. Bundled Python packages, helper tools, and model files keep their own upstream license terms.

See upstream citation guidance:

• Clair3: https://github.com/HKU-BAL/Clair3#citation
• original Clair3 paper: Zheng et al., "Symphonizing pileup and full-alignment for deep learning-based long-read variant calling"
• Clair3 v2 signal-aware preprint and GPU paper are listed in the upstream citation table for those modes.