Guide & API

Overview

Database scope

Live counts per segment, locus and species are on the overview. What that page cannot tell you is where the scope boundaries are, so they are stated here.

An IGH constant region is assembled from the per-domain records IMGT publishes (CH1 + hinge + CH2 + CH3… + CHS, in domain order); IGK, IGL and IGI are published whole and stored as they come. Either way the ordered composition is kept as an annotation, so the domain boundaries stay recoverable from the stored sequence.

AIRBabel stores amino-acid sequence only where translation is defined for the represented record. A protein is stored only where a source published one or where translating the coding region is well‑defined; in the current scope this means V. Amino-acid search and the aa similarity view are absent on D, J and C records rather than empty; no stored translation is defined for those record classes.

What AIRBabel adds

Primary databases publish the reference sets. What this service adds is what can be asked of a sequence already in hand. Every row below is a live query, so the claim and its demonstration are the same thing.

Download. The dataset is available through public REST API endpoints: FASTA · JSON · manifest & terms. Both accept category, segment, species (and kind=nt|aa for FASTA). Reuse requires attribution; each source's licence and citation is on Sources & citations.

Naming & identifiers

Every sequence has one canonical Server UID and any number of names. The UID is the identity; names are labels attached to it, each tagged with the scheme it follows and the source that attributes it.

HUMAN-VQLNRZF6P
  │   │   │
  │   │   └────── base32 prefix of sha256(sequence)  (coding: 8 chars, leader/RSS: 5)
  │   └────────── segment / category code: V/D/J/C (coding), L (leader), R (rss)
  └────────────── species tag: HUMAN, MOUSE, RHESUS, GORILLA, …

A name is stored with a scheme (how the label is formatted) and a source (who attributes it), so the same allele usually carries several. In API responses you see them under allele_names (each with scheme + source), and the AIRR view exposes a primary label plus aliases (e.g. IGHV1-69*01 also surfaces IGHV1-69D*01).

Sources are recorded as CURIEs with attribution, currently IMGT/GENE-DB and OGRDB (internal sets HUSA / MUSA when loaded). The service aggregates and attributes names; it does not adjudicate nomenclature.

Using the website

From the Search page, enter an allele name (e.g. IGHV1-69*01), a Server UID, or paste a nucleotide or amino-acid sequence. The mode selector controls how the query is interpreted, and species restricts results.

An allele record page shows the nucleotide and amino-acid sequence, all aliases (names from each scheme), the contributing sources, cross-references, literature references, and any linked RSS. From a record you can list similar alleles by nucleotide or amino acid, within an identity threshold, restricted to the same species or across species.

Literature references. Each record lists PubMed publications for the allele. References marked verified come from the curated tables. Those marked unverified are auto-collected in v1 by matching the allele name (e.g. IGHV1-2*01) against the literature via Europe PMC. They are not manually checked, so some may be wrong or not actually about that allele. Treat unverified references as leads to follow, not as ground truth.

Tip: searches are capped (default 100 rows). When a result set is truncated the response is flagged capped: true. Narrow by species or use a more specific query.

Reading a result

Every hit carries a match type (the Match column on the site, matched_by in JSON). It says how the hit was found, which is not the same question as how similar it is; a name match, in particular, says nothing about the sequence. The same table is available one click away on any result page.

Two further distinctions worth keeping apart. Cross-species neighbour: a hit in another species, found by identity rather than by name; numbering schemes are independent, so allele names do not establish orthology. Verified vs mined literature evidence: a curator-published or GenBank-derived citation is an assertion someone stands behind; a mined name-only hit is a lead. They are shown apart and never summed; see searching by publication.

Searching by publication (PMID)

The reference list on a record answers “which papers cite this allele?”. PMID mode asks the reverse: given a paper, which AIRBabel allele records are linked to it? Enter a PubMed ID as bare digits (29163486), as PMID:29163486, or as a PubMed URL. In auto mode a bare PubMed ID is recognised without selecting the mode.

Every hit is tagged with how the paper attests it, and the tiers are reported separately rather than summed, because they are not equally strong claims:

Archived records are returned in PMID search and flagged. That is deliberate: a paper citing a name IMGT has since retired is precisely the case where the citation still has to lead somewhere. Where a newer record supersedes the one cited, the row links to it.

Coverage is partial, and an empty result is not negative evidence. Citations reach this database two ways: a source publishes them with its records, or AIRBabel mines a paper’s full text and supplements. Neither pass is exhaustive. Most of what is loaded today comes from curated sets that carry their own references. So an empty result means AIRBabel holds no citation linking that paper to an allele; it is not evidence that the paper describes none. Treat a linked record as evidence within AIRBabel and an empty result as absence of recorded linkage.

Also available as JSON: GET /api/pmid/{pmid}, which returns the same tiered hits and 422 for a string that is not a PubMed ID.

Sequence similarity calculation

The % identity between two sequences is their normalised Levenshtein (edit-distance) similarity over the optimal edit-distance alignment of the two stored ungapped sequences, reported as 1 - edits / length:

identity = 1 − edits / length

• An edit is a substitution, insertion, or deletion. One substitution between two equal-length sequences lowers identity by exactly 1 / length, so the numbers track a standard mismatch count.
• Computed separately for nucleotide and amino-acid sequences.
• Similarity is computed all-against-all within each species, and between species for the cross-species view, then stored as a precomputed cache, so a search is a fast lookup.
• Results are ranked by identity; each view shows neighbours at or above your chosen threshold.
• Alleles are only ever compared within one segment. V and J segments represent different biological classes, so they are not ranked against each other.

D alleles use a segment-specific rule. A D segment is 8–148 nt (median 19 nt). At that length an edit distance can open a gap to flatter a score, and almost any two D alleles look related. So a D allele is compared only against D alleles of exactly the same length, and scored by counting mismatching positions (Hamming distance) rather than by edit distance, so no gap can be introduced.

The consequence is visible: two D alleles of different lengths are not ranked against each other at all, so a D search returns fewer neighbours than a V search and can return none. This is a method boundary, not a metadata gap; separating short sequences of unequal length needs a multiple alignment, which this database does not compute.

Note: this is edit distance on the stored (ungapped) sequences, so it accounts for insertions and deletions as well as substitutions. It matches a position-by-position comparison for similar alleles, and can differ slightly for distantly related or different-length sequences.

Two limits of the amino-acid comparison, worth knowing before you read a score. First, every substitution costs the same: this is unit-cost edit distance, not a substitution matrix. I to V and I to D are both one edit, though only one of them is conservative. That is the right choice for ranking alleles of the same gene, which differ at a handful of positions; it is the wrong tool for detecting remote homology, where a BLOSUM-scored local alignment (BLAST, DIAMOND, MMseqs2, parasail) is what you want. Second, a short query in partial mode scores against its best window, so a handful of residues contained in an allele scores ~100%; true, and not informative. Read the score together with the query length shown beside it.

Full-length vs partial match. By default identity is computed over the full sequences, so a partial or truncated query is penalised for the length it does not cover (a 200 nt fragment of a 300 nt allele scores ~67%). Tick “partial / contained match” on a sequence or amino-acid search to score identity over the best-matching window instead: a fragment fully contained in an allele then scores ~100%. Use it when you paste an incomplete sequence and want to know which allele it came from.

Dataset release & how to cite a result

A served identity score depends on two things that move independently: which data is loaded, and how distance is computed over it. A build is therefore stamped with both; each is digested, so two deployments can be compared by one string instead of by counting rows.

All of it is at GET /version, repeated in /api/export and in the JSON export, and carried on a FASTA download as the X-Dataset-Release and X-Dataset-Digest headers, so a file that leaves here can still say which build it is. The Sources page shows the same record in full.

Citing a result. Quote the release and the date. If the exact comparison matters, such as a threshold, a neighbour list, or a reported % identity, quote the similarity_digest too: it is what makes the number reproducible. An instance reporting dataset: null has not been stamped; cite the access date instead of inventing a version.

REST API

The same query core is exposed as JSON over HTTP. Interactive, auto-generated documentation:

• /docs: Swagger UI (try requests in the browser)
• /redoc: ReDoc reference
• /openapi.json: raw OpenAPI schema

Base URL for this instance: /

A runnable, dependency-free Python client covering name resolution, sequence resolution, record retrieval, similarity, AIRR output and PMID lookup is on the tutorial page and as a downloadable file. The same page provides five worked examples.

Examples

Responses below are trimmed (long sequences shown as …, list tails as …) for readability.

# resolve an alias to its canonical record
curl "/api/resolve?query=IGHV1-69*01"

{
  "matched_by": "name",
  "record": {
    "native": {
      "uid": "HUMAN-VQLNRZF6P",
      "species": "HUMAN", "category": "coding", "segment": "V", "locus": "IGH",
      "sequence": "CAGGTGCAGCTGGTG…TGTGCGAGAGA",
      "sequence_aa": "QVQLVQSGAEVKKPGSSVKVSCKAS…VYYCAR",
      "protein_uid": "HUMAN-VP-J6QJRI",
      "functional": true, "length": 296,
      "allele_names": [
        { "name": "IGHV1-69*01",  "scheme": "imgt", "source": "IMGT" },
        { "name": "IGHV1-69D*01", "scheme": "imgt", "source": "IMGT" }
      ]
    }
  }
}

# the same record as an AIRR AlleleDescription
curl "/api/resolve?query=IGHV1-69*01&view=airr"

{
  "label": "IGHV1-69*01",
  "aliases": ["IGHV1-69D*01"],
  "coding_sequence": "CAGGTGCAGCTGGTG…TGTGCGAGAGA",
  "sequence_aa": "QVQLVQSGAEVKKPGSSVKVSCKAS…VYYCAR",
  "functional": true, "locus": "IGH", "sequence_type": "V",
  "species": { "id": "NCBITAXON:9606", "label": "Homo sapiens" },
  "germline_set_ref": null
}

# fuzzy name search, restricted to mouse
curl "/api/search/name?q=IGHV1&species=mouse"

{
  "query": "IGHV1",
  "count": 100,
  "capped": true,
  "hits": [
    { "uid": "MOUSE-VC6BUL56P", "label": "IGHV1-9*02", "species": "MOUSE",
      "locus": "IGH", "sequence_type": "V", "score": 0.5455,
      "matched_by": "name", "aliases": ["IGHV1-9*02"] },
    …
  ]
}

# alleles similar (amino acid) to a Server UID, same species, ≥95% identity
curl "/api/sequences/HUMAN-VBSLUZ7BO/similar?kind=aa&min_identity=0.95"

{
  "query": "aa similar to HUMAN-VBSLUZ7BO",
  "count": 15,
  "capped": false,
  "hits": [
    { "uid": "HUMAN-VEQGFHKOW", "label": "IGHV1-69*21", "species": "HUMAN",
      "locus": "IGH", "sequence_type": "V", "score": 1.0,
      "matched_by": "exact", "aliases": ["IGHV1-69*21"] },
    …
  ]
}

# search by a nucleotide sequence (exact / substring / edit-distance)
curl -X POST "/api/search/sequence" \
  -H "content-type: application/json" \
  -d '{"sequence": "CAGGTGCAGCTGGTGCAGTCTGGGGCTGAGGTGAAGAAGCCTGGGTCCTCGGTGAAGGTCTCCTGCAAGGCTTCTGGAGGCACCTTCAGC"}'

{
  "query": "<90 nt>",
  "count": 100,
  "capped": true,
  "hits": [
    { "uid": "HUMAN-VS2XWHE7J", "label": "IGHV1-69*03", "species": "HUMAN",
      "locus": "IGH", "sequence_type": "V", "score": 1.0,
      "matched_by": "substring", "aliases": ["IGHV1-69*03"] },
    …
  ]
}

# search by an amino-acid sequence
curl -X POST "/api/search/aa" \
  -H "content-type: application/json" \
  -d '{"sequence_aa": "QVQLVQSGAEVKKPGSSVKVSCKAS"}'

{
  "query": "<25 aa>",
  "count": 1,
  "capped": false,
  "hits": [
    { "uid": "HUMAN-VDZQSSG5X", "label": "IGHV1/OR16-3*01", "species": "HUMAN",
      "locus": "IGH", "sequence_type": "V", "score": 0.92,
      "matched_by": "similar", "aliases": ["IGHV1/OR16-3*01"] }
  ]
}

Responses are JSON. Search endpoints return {query, count, capped, hits[]}; each hit carries the uid, label, species, locus, match score, and aliases. Use ?view=airr on resolve or sequences for field names aligned with the AIRR AlleleDescription schema.