AlignAIR

A neural aligner for immunoglobulin (IG) and T-cell receptor (TCR) repertoires. A single end-to-end model predicts V/D/J allele calls, segment coordinates, and the junction, and writes standard AIRR output. Constrain calls to a donor genotype (a subset of the model's reference), or train a model for your own reference / species.

📖 New to AlignAIR? Start on the docs site — reference, guides, and interactive lessons:
mutejester.github.io/AlignAIR

Overview

• End-to-end neural model. One network reads orientation, localizes the V/D/J segments, calls alleles, and estimates productivity and mutation rate from a shared representation in a single forward pass, with no multi-stage heuristic search. Deterministic post-processing then turns those predictions into refined coordinates, the junction, and a standard AIRR record.
• Self-contained models. Each model embeds a fingerprinted germline reference and loads without executing any pickle. Pretrained human IGH, IGK+IGL, and TRB models are a command away (--model <id>); the germline catalog travels with the model.
• Donor genotype constraint. At inference you can restrict calls to a subset of the model's reference (a donor genotype, as YAML or FASTA) with no retraining. Adding alleles, a new species, or a new locus requires training a new compatible model.
• Uncertainty-aware. When a read cannot distinguish alleles (e.g. short fragments), AlignAIR reports a candidate set (*_call_set) rather than forcing a single call. Optional per-allele confidence calibration is available as a separate step.
• AIRR output. Standard AIRR rearrangement TSV (V/D/J calls, coordinates, junction, productivity) that reads directly into Change-O / Scirpy / Immcantation.
• Validated on a frozen, ground-truth benchmark. AlignAIR is evaluated on a simulated 2,600-case / 13-stratum human-IGH benchmark with known truth (clean, SHM, indels, fragments, arbitrary orientation), scoring V/D/J allele accuracy, segment coordinates, the junction, productivity, and orientation. A verified v3.0.0 head-to-head against IgBLAST, with full model and IgBLAST provenance, is in preparation and will be published with the benchmark. See benchmarks and known failure modes.

Install

pip install "AlignAIR[cli]"            # core + CLI (recommended)
alignair doctor                        # verify Python / PyTorch+CUDA / GenAIRR

Install extras: [cli] (CLI + model download + AIRR validation + parasail), [train] (training extras), [all]. PyTorch is auto-detected for GPU; for a CPU-only install, pip install torch --index-url https://download.pytorch.org/whl/cpu first.

Or Docker (no local install needed):

docker pull ghcr.io/mutejester/alignair:latest
docker run --rm ghcr.io/mutejester/alignair:latest doctor

# align reads: mount an input dir + an output dir, and persist the model cache across runs
docker run --rm \
  -v "$PWD:/data" -v alignair-cache:/home/appuser/.cache/alignair \
  ghcr.io/mutejester/alignair:latest \
  predict --input /data/reads.fasta --out /data/out.tsv --model alignair-igh-human

The default image is CPU-only; pin a version tag (ghcr.io/mutejester/alignair:3.0.0) for reproducibility. The container runs as a non-root user, so mount a writable output dir (add --user $(id -u):$(id -g) if your host uid differs). Models are not baked in - the alignair-cache volume above keeps a downloaded --model <id> from being re-fetched on every run. GPU is auto-detected when you run in a CUDA base image.

Quick start

See it work end-to-end in one command - offline, no model download needed (it trains a tiny demo model, aligns simulated reads, validates the AIRR output, and runs the donor-genotype path):

alignair demo

Or use a pretrained model - downloaded automatically from the public model hub on first use, no login:

alignair models list                          # human IGH, IGK+IGL, TRB (fetched live from the hub)
alignair predict --input reads.fasta --out out.tsv --model alignair-igh-human

# restrict calls to a donor's genotype (a subset of the model's reference) - YAML or FASTA
alignair predict --input reads.fasta --out out.tsv --model alignair-igh-human --genotype donor.yaml

--model <id> downloads + hash-verifies + caches the model on first use (pin a version with --model <id>@<version>). --genotype constrains the run to a subset of the model's reference - no retraining.

Prefer your own reference or species? Train a model, then align with it:

alignair train --dataconfig HUMAN_IGH_OGRDB --out my_model --preset desktop   # ~minutes on a GPU
alignair predict --input reads.fasta --out out.tsv --model my_model/bundle/model.alignair

See examples/ for runnable data.

Reference: donor subsets now, new references by training

Each model is tied to the germline reference it was trained on (embedded and fingerprinted in the model file). What you can do with it:

• Constrain to a donor's genotype - a subset of the model's reference - with --genotype donor.yaml or donor.fasta at predict time. No retraining; calls are restricted to that donor's alleles.
• Add alleles / a new species / a new locus - this changes the model's allele universe, so train a new compatible model (novel alleles are not callable by a model that was not trained on them):

# train for any of GenAIRR's ~90 built-in references (human, mouse, rat, rabbit, dog, ...)
alignair train --dataconfig MOUSE_IGH_IMGT --out runs/mouse_igh --preset desktop

# or train from your OWN germline FASTAs (custom reference or species)
alignair train --v-fasta v.fasta --d-fasta d.fasta --j-fasta j.fasta \
  --chain-type BCR_HEAVY --out runs/my_ref --preset desktop

This writes checkpoints to runs/.../ plus a self-contained, pickle-free runs/.../bundle/model.alignair (the reference is embedded), a model_card.md, a reference_manifest.json, and a validation_report.json. Presets: quick (smoke), desktop, full (paper-grade). Preview the reference/config/model size without training with --plan. Then just alignair predict ... --model runs/.../bundle/model.alignair.

Output

alignair predict writes a schema-valid AIRR rearrangement TSV (validates against the official airr library; reads back with Change-O / Immcantation): sequence_id, sequence, rev_comp, productive, v_call/d_call/j_call, junction/junction_aa, gapped sequence_alignment / germline_alignment, per-gene *_cigar, *_identity, and sequence/germline coordinates, plus a per-gene candidate-set column (*_call_set) for alleles a read cannot distinguish. The gapped alignment fields are produced by AlignAIR's own IMGT-gap reconstruction (no external aligner required; parasail is bundled in [cli] for exact CIGARs and the fast reader).

Every run also writes a <output>.run.json provenance sidecar (model + fingerprint, reference, command, device, seed, and package versions). Validate any TSV explicitly:

alignair validate-airr out.tsv      # structural check: columns, coordinate/CIGAR bounds, productivity

Commands

Run alignair <command> --help for options.

Documentation

Full docs, reference, and interactive lessons: https://mutejester.github.io/AlignAIR/

• Getting started
• Pretrained models
• Command-line reference
• Benchmarks
• Design & internals
• Troubleshooting

Development

git clone https://github.com/MuteJester/AlignAIR && cd AlignAIR
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md and CHANGELOG.md.

Citation

If you use AlignAIR, please cite:

Thomas Konstantinovsky, Ayelet Peres, Ran Eisenberg, Pazit Polak, Ofir Lindenbaum, Gur Yaari. Enhancing sequence alignment of adaptive immune receptors through multi-task deep learning. Nucleic Acids Research, Volume 53, Issue 13, 22 July 2025, gkaf651. https://doi.org/10.1093/nar/gkaf651

License

GPL-3.0-or-later (see LICENSE).

Contact

Issues: GitHub issues · Email: thomaskon90@gmail.com · Site: https://alignair.ai