Pseudo-Sequence Alignment

Turns a variable-domain amino acid sequence into a pseudo-sequence or paratope sequence: the antigen-contacting loop residues (CDR1, CDR2, CDR3) extracted at standardized IMGT positions, so that sequences of different lengths become fixed-width and directly comparable.

Web app slug: pseudo-sequence-alignment

---

When to use

Use this pipeline when you have AIRR TSVs with a full amino acid sequence column (e.g. sequence_aa produced by TCR to Amino Acid Sequence or the Adaptive Pipeline) and need the aligned paratope representation that Clustering and similarity search consume. It runs automatically when those upstream pipelines are launched with their “trigger alignment” option enabled, or on its own against any AIRR file.

---

How it works

Two sequences can’t be compared position-by-position if they differ in length or aren’t framed the same way. The fix is a shared coordinate system: IMGT numbering assigns every residue in a variable domain a canonical position number, so “position 105” means the same structural location in every receptor. This pipeline uses that to pull out just the binding loops into one fixed-width string.

1. Build a FASTA — each row’s sequence_id and its amino acid sequence (from the input column) are written out for alignment. Rows whose sequence is empty are set aside and merged back later, so the output keeps the original row order and count.

2. Number with ANARCI — ANARCI aligns each sequence to germline using the IMGT scheme, restricted to TR genes for TRA/TRB/TRG/TRD and IG genes otherwise, for the chosen species. The bit_score_threshold sets how confident a hit must be; sequences below it (or that don’t match the chain) fail to align. When assign germline is on, ANARCI also records the closest V/J germline.

3. Extract the CDR loops — from the IMGT-numbered output, only the three complementarity-determining loops are kept, each at its canonical IMGT positions (with room for length-varying insertions):

   • CDR1 — positions 27–38
   • CDR2 — positions 56–65
   • CDR3 — positions 105–117

   These are concatenated into the pseudo-sequence. Any canonical position a given receptor doesn’t fill is padded with a gap (-), so every pseudo-sequence has the same width and the same column meaning. If ANARCI returns more than one domain for a sequence, the best hit (lowest e-value) is used.

4. Merge back — the new pseudo-sequence is joined onto the original AIRR rows under the output column (default aligned_pseudo_seq); all the original columns are preserved.

Tip

The pseudo-sequence is the paratope — the residues that actually contact antigen — laid out on a fixed IMGT grid. That fixed grid is exactly what makes the position-by-position similarity (sid/cov) in the Clustering pipeline possible.

---

Submitting a job

Navigate to Dashboard → Pseudo-Sequence Alignment → Create New 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
Chain Type	TRB	TRA, TRB, TRG, TRD, IGH, IGK, or IGL
Species	human	One of human, mouse, rat, rabbit, rhesus, pig, alpaca, cow
Input amino-acid column	sequence_aa	Column holding the amino acid sequences to align
Output pseudo-seq column	aligned_pseudo_seq	Column to write the aligned pseudo-sequence into
ANARCI Bit Score Threshold	15	Minimum bit score for a valid alignment; raise it to be stricter
Assign Germline	false	Also assign the closest V/J germline during alignment
Number of CPU threads	cores − 4	Threads for ANARCI

Note

Pick the chain type that matches your data. ANARCI only emits output for the requested chain, so aligning TRB data as IGH (or vice-versa) yields no aligned sequences for that file.

---

Output files

Each input AIRR TSV is written back out with the output pseudo-seq column added (all original columns preserved). Sequences that failed alignment carry an all-gap value. All outputs plus a logs/error.txt (including per-file counts of how many sequences failed alignment) are packaged into a single results.zip under the run’s output prefix.

---

Troubleshooting

High fraction of unaligned sequences (all-gap output) Usually a mismatch between the data and the settings. Confirm the Chain Type matches the receptor in your file, the Input amino-acid column actually contains amino acids (not nucleotides), and the Species is correct. If alignments are borderline, lowering the Bit Score Threshold admits weaker hits; raising it rejects them.

“Input 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).

Output column already present If the input already has a column with the output name, it is dropped and regenerated for this run. Choose a different Output pseudo-seq column if you want to keep the original.