AlignAIR logo

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.
Container: GHCR DOI GPLv3 Documentation

📖 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

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.

Documentation

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

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

Project links

Data verified by PyPI on Jul 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Thomas_Kon from gravatar.com Thomas_Kon

Credits

Author: Ayelet Peres

GitHub Statistics

Data verified by PyPI on Jul 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python >=3.10

Provides Extra

zstd hub cli reader wfa train viz server dev all

Tags

immunogenetics sequence-alignment bioinformatics AIRR antibody TCR

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

alignair-3.0.0.tar.gz (278.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

alignair-3.0.0-cp312-cp312-win_amd64.whl (353.4 kB view details)

Uploaded CPython 3.12Windows x86-64

alignair-3.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (467.1 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

alignair-3.0.0-cp312-cp312-macosx_11_0_arm64.whl (355.6 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

alignair-3.0.0-cp312-cp312-macosx_10_13_x86_64.whl (354.7 kB view details)

Uploaded CPython 3.12macOS 10.13+ x86-64

alignair-3.0.0-cp311-cp311-win_amd64.whl (352.9 kB view details)

Uploaded CPython 3.11Windows x86-64

alignair-3.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (460.2 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

alignair-3.0.0-cp311-cp311-macosx_11_0_arm64.whl (354.8 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

alignair-3.0.0-cp311-cp311-macosx_10_9_x86_64.whl (354.2 kB view details)

Uploaded CPython 3.11macOS 10.9+ x86-64

alignair-3.0.0-cp310-cp310-win_amd64.whl (352.9 kB view details)

Uploaded CPython 3.10Windows x86-64

alignair-3.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (451.6 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

alignair-3.0.0-cp310-cp310-macosx_11_0_arm64.whl (355.0 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

alignair-3.0.0-cp310-cp310-macosx_10_9_x86_64.whl (354.3 kB view details)

Uploaded CPython 3.10macOS 10.9+ x86-64

File details

Details for the file alignair-3.0.0.tar.gz.

File metadata

  • Download URL: alignair-3.0.0.tar.gz
  • Upload date:
  • Size: 278.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for alignair-3.0.0.tar.gz
Algorithm Hash digest
SHA256 57a7c34c240651d624ad814aed24749fdfa497c40d115aaa34ba5d644129c863
MD5 ab5f149519020be36980c31086b364e3
BLAKE2b-256 153ce9ca47db29d5a19be0d8ea21afb2148e1b4411a8f87ac02ba742970731ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0.tar.gz:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: alignair-3.0.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 353.4 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for alignair-3.0.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 2d70180005da0fd09d63b1691a9866739362f207f28ef68e8ee0bd39d69461c9
MD5 bc4f9115854e99b34708b66223e3d9c2
BLAKE2b-256 2e99f94887d64198b7bf8b37c27f49ae7fd174b6ee6359eeddc306e8ab3c79d7

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e79b0dbd7a4fa1935d38a69595d7088a142fa9a401ce3e21cd68450ec648635d
MD5 83d64feeec7b3f5ff967dd65087001a5
BLAKE2b-256 e6063997cf9bb06d203934340972ae33f8c616e039f0697772108a786fad625e

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1f8dc39c091ef446b93423883a36dd757f723b5efcc5fd88bd53f438468a5dfe
MD5 d8899188b8d7b71efbec77f67ac1a221
BLAKE2b-256 aa4f00e311078577b6b4544e527b15f081e0802bbcff2693a85df852bd244d19

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp312-cp312-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp312-cp312-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 f917640c6064376511aa481d9ac1ceffb60b9e755bdd263b650ff98e8a600bfd
MD5 5ce35a0c65525b6eac6c1e133a99fee5
BLAKE2b-256 67703fd66db3ad8a36bf937b82a08a6b9e6728da3f54e33ec3cf85b121245237

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp312-cp312-macosx_10_13_x86_64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: alignair-3.0.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 352.9 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for alignair-3.0.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 45e58c9cda7298e29c41535dc8b72b10ce43bad61b582c0b478345c3e2809db1
MD5 c7c3aadf5d06cbe57eee27214be008f3
BLAKE2b-256 1a381225151d3fd0b87472048fda052af435b9ec60ded9be985d58d068682684

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a5b1edf07396790a92ef33228c316d787c3b95419e9ccd4bf8b91c2de271eb83
MD5 1a95a6db3133e0bfcf320805bb47f1c4
BLAKE2b-256 448037f239d30a5c50875d279398372306bd1117e2a9f8ebf229814451c70268

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 299e0c414984a6af1d466da254932ae229eabb02fbf99ca373bde374caf0b661
MD5 5a844c10bd45f022d80cac87df59a584
BLAKE2b-256 73d1f3f6f2afd8082e97d8dc08fb792204e95a7ffa0b7c7d9c80bf5af03e49c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp311-cp311-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp311-cp311-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 55cb644a33ee89270e9add344d7f66758383e51f893050d0bfa4d7cde03650f6
MD5 af73cb23965d50f6f7e0c68c20f992a2
BLAKE2b-256 3e413aa5870d1b8c8565e1f7c14fee8c1373148be1dacab2e3bcc99fc6c4d0ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp311-cp311-macosx_10_9_x86_64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: alignair-3.0.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 352.9 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for alignair-3.0.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 a9217c8adfa51df29d2e5285e43e82695900448b59c8d3efa43a9ee2720093aa
MD5 f42f85bec78373ebe147ed3520bc9302
BLAKE2b-256 2b75cdb1ef71dadfdc77145caac93866ff017534b79f37fd1eccfc224b68c03f

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp310-cp310-win_amd64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 47e313f25ba0e2b52c55e25a9fef22253be194c370ab13f04814649442fc7a1e
MD5 3f3148f0c04f005bf5aaf6adfa8931b5
BLAKE2b-256 45d1b690d128726719aa14a847c67fb7966900fb5db3c91e80345364a963adba

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3fdaf7daa16a4107bcc9d8f2d165046159ef790932d4c84cca54ee29d73e29b9
MD5 da6b72659470bbd736ef8f98c7e5879b
BLAKE2b-256 647f49e5940da72b36134d53ad10f9a6e8ec3b78cbab25575d5527ef20b2581c

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file alignair-3.0.0-cp310-cp310-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for alignair-3.0.0-cp310-cp310-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 0c393ab5dbd020c49ebd9193c86a8a898ed430c10b13fbf9b30d4dd2d02e4284
MD5 9def1cf844106255180e82cc42c68641
BLAKE2b-256 4d647efad81029234f36f54b88533dd82c9ba90a74f773615b5c51ff6397c096

See more details on using hashes here.

Provenance

The following attestation bundles were made for alignair-3.0.0-cp310-cp310-macosx_10_9_x86_64.whl:

Publisher: release.yml on MuteJester/AlignAIR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page