Antibody Sequence Restoration

Completes truncated antibody variable-domain amino acid sequences: it restores the missing N-terminal FR1 residues from the best-matching germline V allele and the missing C-terminal FR4 residues from the germline J database, so a sequence that starts partway into framework 1 (or stops before framework 4) is rebuilt into a full variable domain.

Airflow DAG id: antibody_seq_restoration

---

When to use

Antibody (BCR / immunoglobulin) sequences from many sources are terminally truncated — the assay or the upstream tool captures the antigen-facing core but clips conserved framework residues off the ends. Use this pipeline when you have AIRR TSVs with an amino acid sequence column (default sequence_aa) and need the complete variable domain before downstream analysis such as Pseudo-Sequence Alignment, clustering, or any model that assumes full-length framework regions.

It is the antibody counterpart to TCR to Amino Acid Sequence: where that pipeline builds a TCR sequence from gene calls plus CDR3, this one restores the missing ends of an antibody sequence you already have.

Note

This pipeline covers immunoglobulin chains only — heavy (IGHV), kappa (IGKV), and lambda (IGLV). For T-cell receptors, use TCR to Amino Acid Sequence.

---

How it works

The two ends of a variable domain are the most conserved part of the molecule, so a missing end can be inferred from germline references. FR1 is encoded by the V gene; FR4 is encoded by the J gene. The pipeline aligns each query to those references and pastes back only the residues the query is actually missing.

1. Match a germline V gene — the query is aligned to every germline V allele (after the chosen species and chain filters) using a semi-global alignment (match +2, mismatch −1, gap −2). The best hit by score, then identity, is kept, provided it clears the minimum V-region identity. Sequences with no qualifying hit are passed through unchanged and marked no_v_match.

2. Restore the N-terminus (FR1) — the germline residues that sit before where the query starts aligning are the missing FR1. They are prepended to the query. If the query already begins at the germline start, nothing is added.

3. Restore the C-terminus (FR4) — when Restore FR4 is on, the query’s 3′ tail is aligned (local / Smith-Waterman) against the germline J database for the matching chain. FR4 begins at the conserved J-motif [F/W]-G-X-G (the J-TRP for heavy, J-PHE for light). Any germline residues past the end of the query are appended as FR4.

   Caution

   FR4 restoration is conservative by design. A J gene is only used when the alignment is anchored on that conserved motif, so appended residues are always genuine FR4 — never an invented CDR3 junction. If a query is truncated inside CDR3 (before FR4 begins), the pipeline appends nothing rather than guess the clone-specific junction.

4. Annotate — the completed sequence is written to the output column (default sequence_aa_modified) and per-row germline annotations are added: v_gene, v_identity, v_species, v_chain, v_accession, n_terminal_added, j_gene, fr4_added, and restoration_status. All original columns are preserved.

The completion rule is simply:

sequence_aa_modified = missing_FR1_residues + input_sequence + missing_FR4_residues

Tip

v_identity is the V-region identity computed over the germline footprint only. The query’s trailing CDR3 + FR4 residues have no V-germline counterpart, so they’re excluded — a near-perfect germline match reads ~99–100% rather than being diluted to ~75%.

---

Submitting a job

Required inputs

Field	Description
Job name	A label for this run
Input bundle (zip)	A zip of one or more AIRR TSVs, each with the input amino-acid column

Optional inputs

Field	Default	Description
Species filter	auto	Restrict germline matching to one species, or auto to search all: Human, Mouse, Rat, Rabbit, Alpaca, Rhesus monkey, Pig
Chain filter	auto	Restrict germline matching to one chain, or auto to search all: IGHV, IGKV, IGLV
Input amino-acid column	sequence_aa	Column holding the amino acid sequences to complete
Output completed-sequence column	sequence_aa_modified	Column to write the FR1/FR4-completed sequence into
Minimum V-region identity (%)	70	Minimum identity for a germline V match; rows below it are left unchanged
Restore FR4 (C-terminus)	true	Whether to restore missing C-terminal FR4 residues from the J database
Minimum J-gene FR4 identity (%)	70	Minimum identity for a J-gene FR4 match

Tip

Leaving Species and Chain on auto lets the pipeline pick the best germline across all references — convenient for mixed files. Setting them explicitly is faster and avoids cross-chain or cross-species mismatches when you already know your data.

---

Output files

Each input AIRR TSV is written back out as <name>_modified.tsv with the completed sequence column and the germline annotation columns added; every original column is preserved. All outputs plus a logs/error.txt are packaged into a single results.zip under the run’s output prefix.

Every row carries a restoration_status:

Status	Meaning
restored	FR1 and/or FR4 residues were added
already_complete	A germline matched but the sequence had no missing ends
no_v_match	No germline V cleared the identity threshold; row passed through unchanged
too_short	Sequence was under 10 aa after sanitizing; left unchanged
empty_sequence	The input cell was empty

---

Troubleshooting

Many rows marked no_v_match The germline V step isn’t clearing the identity threshold. Confirm the Input amino-acid column holds amino acids (not nucleotides), that the Species and Chain filters match your data (or set both to auto), and consider lowering the Minimum V-region identity.

FR4 not being added (fr4_added empty) Either the sequence already includes FR4 (already_complete), or it is truncated within CDR3 before FR4 begins — in which case restoration is intentionally skipped rather than guessing the junction. You can also lower the Minimum J-gene FR4 identity, or turn Restore FR4 off if you only want N-terminal completion.

“Column not found” The configured Input amino-acid column doesn’t exist in the file. Run head -1 file.tsv to list the columns and set the field to match (the default is sequence_aa).