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
- 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.
pip install "AlignAIR[cli]" # core + CLI (recommended)
alignair doctor # verify Python / PyTorch+CUDA / GenAIRRInstall 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-humanThe 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.
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 demoOr 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.alignairSee examples/ for runnable data.
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.yamlordonor.fastaat 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 desktopThis 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.
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| Command | Purpose |
|---|---|
alignair demo |
offline end-to-end trial (tiny train → predict → validate → genotype) |
alignair predict |
align reads → AIRR rearrangement TSV |
alignair train |
train a model for your own reference / species (built-in dataconfig or custom FASTA) |
alignair models |
list / download / manage pretrained models |
alignair reference |
list built-in references, or export a model's reference |
alignair compare |
agreement report between two AIRR TSVs (e.g. AlignAIR vs IgBLAST) on your data |
alignair validate-airr |
structural check of a rearrangement TSV (columns, coordinate/CIGAR bounds, productivity); not the official AIRR-C schema validator |
alignair doctor |
check the environment (Python, PyTorch+CUDA, GenAIRR, parasail) |
alignair convert |
convert a legacy checkpoint into a versioned, fingerprinted .alignair |
Run alignair <command> --help for options.
Full docs, reference, and interactive lessons: https://mutejester.github.io/AlignAIR/
- Getting started
- Pretrained models
- Command-line reference
- Benchmarks
- Design & internals
- Troubleshooting
git clone https://github.com/MuteJester/AlignAIR && cd AlignAIR
pip install -e ".[dev]"
pytestSee CONTRIBUTING.md and CHANGELOG.md.
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
GPL-3.0-or-later (see LICENSE).
Issues: GitHub issues · Email: thomaskon90@gmail.com · Site: https://alignair.ai