How to Annotate Antibody Sequences with IgBLAST, AIRR TSV, and Mouse V(D)J Germlines

Table of contents

• Scientific introduction
  • Why antibody sequences need specialized annotation
  • V(D)J recombination and the annotated regions
  • AIRR rearrangement format
  • Input quality and interpretation boundaries
• Test progress
• Demo user request
• Demo data
• Installation and validated command
• Results and artifacts
• Validation and failure-driven repair
• Reproducibility
• Limitations
• References
• Try this workflow

IgBLAST annotates an immunoglobulin or T-cell receptor sequence by comparing it with curated germline V, D, and J gene databases and by locating the junction, complementarity-determining regions, and framework regions. In the worked mouse immunoglobulin heavy-chain example below, IgBLAST 1.22.0 assigned V gene 145A, D gene DFL16.1, and J gene JH1. It classified the rearrangement as productive and returned the junction amino-acid sequence CASFITTVVATYWYFDVW. The complete machine-readable result is retained as an AIRR rearrangement TSV, while a separately validated report exposes the biologically important fields without confusing the complete junction with CDR3.

Scientific introduction

Why antibody sequences need specialized annotation

Antibodies recognize antigens through variable domains assembled during B-cell development. Rather than encoding every possible receptor directly in the inherited genome, the immune system recombines variable, diversity, and joining gene segments. Heavy chains normally use V, D, and J segments, whereas light chains use V and J segments. Junctional nucleotide deletion and addition further diversify the rearrangement. Somatic hypermutation can subsequently introduce substitutions as activated B cells undergo affinity maturation. A sequenced receptor therefore cannot be interpreted reliably by ordinary local alignment alone: the analysis must account for a recombination model, germline segment alternatives, junction boundaries, reading frame, and receptor-specific region definitions.

IgBLAST extends BLAST methods for immunoglobulin and T-cell receptor analysis. Its germline-aware workflow identifies the best V, D, and J matches, reports alignments and coordinates, and delineates framework regions and complementarity-determining regions. The original IgBLAST publication describes a tool intended to combine the familiar BLAST search framework with immunoglobulin-domain annotation Ye et al., 2013. The software is maintained by the National Center for Biotechnology Information, and its setup documentation distinguishes the executable, internal annotation data, auxiliary files, and separately obtained germline search databases NCBI IgBLAST setup guide.

The choice of germline database is scientifically consequential. A database must match the organism and receptor type being analyzed. A mouse positive control cannot justify a human germline call, and a convenient mouse archive must never be substituted silently for a human analysis. Database release, source URL, checksum, and licensing conditions belong in the record because updated allele sets may alter the reported best match. The retained demonstration used the official NCBI mouse V/D/J archive, whose downloaded tar file had SHA-256 checksum ad977014c7515dd959bab085316a847726687512e841461af30e3499b54ba6fa.

V(D)J recombination and the annotated regions

The variable domain alternates relatively conserved framework regions with more variable complementarity-determining regions. Framework regions contribute to the immunoglobulin fold, while the CDR loops form much of the antigen-binding surface. CDR1 and CDR2 are largely encoded within the V segment. CDR3 spans the recombination junction and is especially diverse because it reflects segment choice, trimming, and junctional additions. The complete junction and the CDR3 are related but not interchangeable fields.

This distinction caused a meaningful failure during validation. An early generated report presented the AIRR cdr3_aa value as the complete junction and presented fwr3_aa as CDR3. The underlying TSV was correct, but the prose was scientifically mislabeled. A report can therefore look plausible while conveying the wrong sequence. The delivered instructions now require header-keyed parsing and an exact mapping: junction_aa is the complete junction, cdr3_aa is CDR3, and fwr3_aa is framework region 3. The final report must reopen the TSV and compare every displayed sequence with its named column.

Productivity is another derived annotation that needs careful interpretation. A productive rearrangement is generally in frame and lacks a disqualifying stop codon under the applied annotation rules. A T value supports the claim that the sequence is productively rearranged in this software output; it does not establish expression, folding, antigen binding, or physiological function. Conversely, an incomplete query or a sequence with poor germline coverage may yield missing fields. Missing D or J calls must be reported as missing rather than inferred from neighboring coordinates or from biological expectation.

AIRR rearrangement format

The Adaptive Immune Receptor Repertoire community developed standardized representations to improve interoperability among repertoire-analysis tools. The AIRR Data Representation specification defines fields used to describe rearranged receptor sequences, germline calls, coordinates, junctions, CDRs, framework regions, and analysis metadata AIRR Standards documentation. IgBLAST output format 19 produces an AIRR rearrangement table suitable for downstream parsing.

A TSV file is deceptively simple. It is a tab-delimited table with a header row, but robust interpretation must use header names rather than numerical column positions. Versions or configurations can expose many fields, and visually scanning a wide row is error-prone. A csv.DictReader with delimiter="\t" or an equivalent dataframe reader preserves the semantic association between each value and its header. Positional extraction is specifically unsafe for the junction, CDR3, and FWR3 fields because all three are plausible amino-acid strings.

Coordinates also provide useful integrity checks. For the accepted heavy-chain query, V coordinates should precede D coordinates, which should precede J coordinates. Coordinates alone do not validate every biological boundary, but reversed or overlapping values outside the expected model can reveal parsing errors or inappropriate input. The validator in this demonstration checked ordered V, D, and J sequence intervals, a nonempty V call, the expected calls, productivity, and exact region sequences.

Input quality and interpretation boundaries

IgBLAST requires a query containing at least part of a V gene. Short reads, sequencing errors, primer sequence, low-quality ends, chimeras, orientation errors, or non-receptor input can weaken or prevent annotation. A practical workflow should preserve the original sequence identifier, document trimming and consensus generation, and avoid overwriting raw input. Large repertoire studies also need sample-level metadata, clonotype methods, quality control, and statistical designs beyond a single-sequence annotation.

The synthetic positive control used here was composed from official NCBI mouse germline components so its expected V, D, and J identities were known before execution. That makes it suitable for a deterministic software test. It is not a biological repertoire sample, does not contain a measured somatic-mutation history, and cannot support population-level conclusions. The result demonstrates correct package installation, database use, annotation, parsing, and reporting on one controlled sequence.

Test progress

The package environment and downloaded database are retained for reproducibility and debugging. Installation success alone did not grant feature credit. Credit was assigned only after the executable produced the AIRR table, the conversational run generated both requested files, and the independent validator checked their biological labels and values.

Demo user request

Annotate data/query.fasta, a mouse immunoglobulin heavy-chain nucleotide FASTA, with IgBLAST. Use the official NCBI mouse V/D/J database identified in data/provenance.json. Export the complete AIRR rearrangement table as outputs/annotations.tsv and write outputs/summary.md reporting the V, D, and J calls, productivity, junction amino-acid sequence, CDR1–3 amino-acid sequences, FWR1–4 amino-acid sequences, package version, database provenance, and exact command. Read AIRR values by column name and verify every labeled sequence against its exact field. Do not infer missing annotations.

This request is intentionally conversational. It describes a scientific outcome and its audit requirements without supplying a finished analysis program. The workflow had to locate the retained package, prepare the official database prefixes, run the correct executable, reopen the output, and create human- and machine-readable deliverables.

Demo data

The tracked query FASTA contains one synthetic mouse immunoglobulin heavy-chain rearrangement named synthetic_mouse_igh_rearrangement. Its provenance and checksum are recorded in provenance.json. The official database archive itself is retained outside Git because downloaded packages and databases are developer evidence rather than application source.

The query SHA-256 is 751f333b8873acd48531ce1a3a9645064085cac1abf4b23d3fb33cb042f860fc. Checksums prevent a later database or fixture replacement from being mistaken for the validated input.

Installation and validated command

The tested package came from Bioconda in an isolated Conda environment owned by this skill. The bounded solver plan contained 67 packages totaling 358,067,801 bytes. The official NCBI database archive added 256,000 bytes, keeping the complete planned transfer below the local 500,000,000-byte policy. CUDA, a compiler, root access, and a system-wide package installation were not required.

python scripts/tool.py info
python scripts/tool.py install
python scripts/tool.py probe

The annotation used igblastn, output format 19, the mouse organism and immunoglobulin sequence type, all three germline database prefixes, and the mouse auxiliary file:

python scripts/tool.py run -- igblastn \
  -query data/query.fasta \
  -germline_db_V inputs/database/mouse_gl_V \
  -germline_db_D inputs/database/mouse_gl_D \
  -germline_db_J inputs/database/mouse_gl_J \
  -organism mouse -ig_seqtype Ig \
  -auxiliary_data ~/.mindplot/tools/igblast/env/share/igblast/optional_file/mouse_gl.aux \
  -show_translation -outfmt 19 -out outputs/annotations.tsv

The command block is provided for transparent reproduction. Scientific validity comes from the reopened artifacts and assertions, not merely from a zero process exit code.

Results and artifacts

The primary result is a productive mouse heavy-chain annotation with calls 145A, DFL16.1, and JH1. The exact region mapping is shown below.

The complete AIRR table preserves the full output row. The validated summary provides a readable interpretation, while the results report records the retained deliverables.

The first image is a focused locator capture of the report rendered through the real chat route. The other images derive from the retained attempt and show validated result information and deliverable sizes. Their checksums and sources are recorded in the screenshot and visual-asset manifests.

Validation and failure-driven repair

The native run first established that the installed executable and official database could produce the expected biological annotation. The conversational attempt then tested whether the instructions could guide an agent from a user request to correctly labeled deliverables. This second level matters because a correct computation can still be summarized incorrectly.

The initial summary confused three neighboring AIRR fields. The validator compared the human-readable label with the exact header-keyed TSV value and rejected the report. The skill instructions were updated with an explicit mapping table and a requirement to reopen both files. A subsequent report correctly mapped the eight fields but said “all 9,” so a count invariant was added. Attempt 3 then reported one junction, three CDRs, and four framework regions as eight labeled amino-acid fields and passed the semantic validator.

This feedback is retained in the delivered instructions rather than hidden in a temporary test log. Future analyses receive the stronger rules. The repair illustrates why content validation must go beyond file existence, process exit status, or substring matching.

Reproducibility

The validated host ran Ubuntu 22.04.5 LTS on Linux x86_64 without NVIDIA CUDA. IgBLAST version 1.22.0 was installed in the retained skill-owned environment. The scientific execution and conversational artifact generation both completed successfully on 2026-07-27, followed by independent semantic validation of the AIRR table and readable report.

Reproduction requires the exact query, database archive checksum, package version, auxiliary file, command, and AIRR parser. It should also record any preprocessing and the full stdout/stderr logs. A new database release or a different species requires a new scientific validation rather than reuse of these calls.

The semantic validator asserts a single row, the sequence identifier, all three expected germline calls, productivity, exact junction/CDR/framework values, and ordered V/D/J coordinates. It also requires the readable report to contain the package version, executable, database checksum, and each correctly labeled sequence.

Limitations

This is a one-sequence synthetic positive control, not a repertoire benchmark. It does not measure sensitivity to sequencing errors, novel alleles, truncated V regions, ambiguous D assignments, somatic hypermutation, mixed receptor types, or large-file throughput. The perfect agreement with expected components is designed into the fixture and is not an estimate of annotation accuracy on clinical or ecological samples.

Only Linux x86_64 CPU execution was validated. NCBI publishes programs for Linux, macOS, and Windows, and Bioconda publishes additional architectures, but those combinations remain unverified in this cycle. Human IMGT data have separate access and licensing considerations. No human database was downloaded, and the mouse archive must not be used as a human substitute.

An AIRR TSV improves interoperability but does not eliminate method choices. Germline database content, receptor type, organism, domain system, query quality, and downstream clonotype definitions affect interpretation. Researchers should preserve raw input, use appropriate consent and privacy controls for human immune-repertoire data, and validate conclusions with suitable biological and statistical methods.

References

1. Ye J, Ma N, Madden TL, Ostell JM. IgBLAST: an immunoglobulin variable domain sequence analysis tool. Nucleic Acids Research. 2013.
2. National Center for Biotechnology Information. How to set up IgBLAST.
3. AIRR Community. AIRR Data Representation: Rearrangements.
4. National Center for Biotechnology Information. IgBLAST documentation and cookbook.

Try this workflow

MindPlot has built-in support for the demonstrated IgBLAST scientific skill. A user can provide the natural-language request and data while the MindPlot agent writes and runs the required commands, validates the AIRR output, and returns the artifacts; users do not need to write the code shown above. Try it at mindplot.ai, or download the desktop version for a better integrated experience and stronger local-data privacy.