Analysis of Nanobody Sequences

[sarahyk]

Hi, I'd like to use MiXCR for analyzing nanobody VHH sequences. I've previously tried aligning my sequences to the built in MiXCR llama reference library but less than 1% of my reads successfully aligned. I saw a paper where another group used MiXCR for nanbody sequences by aligning to the IMGT alpaca reference library (https://www.nature.com/articles/s41467-023-43038-z), but has anyone else used MiXCR for these types of sequences? Do I need to build a custom reference library? I'm open to any suggestions, thanks!

mixcr align
--species lamaGlama
--rna
--write-all
--keep-non-CDR3-alignments
--tag-pattern "^N(UMI:N{6:12})attcGCCA(R1:)^N{18}(R2:)" \ #specify UMI and barcode sequences
--report dr081-2_align_report.txt
--json-report dr081-2_align_report.json
--threads 8
--verbose
~/data/dr081-2_read1.fastq \ # inputs
~/data/dr081-2_read2.fastq
dr081-2_alignments.vdjca # output

[mizraelson]

Hi, Can you share your align report?

[sarahyk]

Hi, I tried reproducing my results by running mixcr with the following command:

./mixcr align \ ~/data/test/raw_data/02_libraries/dr081-2_read1.fastq \ ~/data/test/raw_data/02_libraries/dr081-2_read2.fastq \ dr081-2_alignments.vdjca \ --preset generic-bcr-amplicon \ --floating-left-alignment-boundary \ --floating-right-alignment-boundary C \ --species lamaGlama \ --write-all \ --rna \ --report dr081-2_align_report.txt\ --verbose \ --threads 8

And I recieved this as my alignment report:

Analysis date: Tue Jun 10 18:45:19 UTC 2025
Input file(s): /home/jupyter/data/test/raw_data/02_libraries/dr081-2_read1.fastq,/home/jupyter/data/test/raw_data/02_libraries/dr081-2_read2.fastq
Output file(s): dr081-2_alignments.vdjca
Version: 4.3.2; built=Tue Apr 11 18:35:07 UTC 2023; rev=123d699964; lib=repseqio.v2.2
Command line arguments: align /home/jupyter/data/test/raw_data/02_libraries/dr081-2_read1.fastq /home/jupyter/data/test/raw_data/02_libraries/dr081-2_read2.fastq dr081-2_alignments.vdjca --preset generic-bcr-amplicon --floating-left-alignment-boundary --floating-right-alignment-boundary C --species lamaGlama --write-all --rna --report dr081-2_align_report.txt --verbose --threads 8
Analysis time: 18.89m
Total sequencing reads: 7063820
Successfully aligned reads: 20270 (0.29%)
Alignment failed: no hits (not TCR/IG?): 1819280 (25.75%)
Alignment failed: absence of V hits: 7 (0%)
Alignment failed: absence of J hits: 5224251 (73.96%)
Alignment failed: no target with both V and J alignments: 12 (0%)
Overlapped: 6947755 (98.36%)
Overlapped and aligned: 20124 (0.28%)
Overlapped and not aligned: 6927631 (98.07%)
Alignment-aided overlaps, percent of overlapped and aligned: 0 (0%)
Partial aligned reads, percent of successfully aligned: 177 (0.87%)
V gene chimeras: 11 (0%)
Realigned with forced non-floating bound: 232130 (3.29%)
Realigned with forced non-floating right bound in left read: 90 (0%)
Realigned with forced non-floating left bound in right read: 90 (0%)
IGH chains: 20270 (100%)
IGH non-functional: 149 (0.74%)
Trimming report:
  R1 reads trimmed left: 621 (0.01%)
  R1 reads trimmed right: 1171265 (16.58%)
  Average R1 nucleotides trimmed left: 0.00959495004119584
  Average R1 nucleotides trimmed right: 1.1312861879266458
  R2 reads trimmed left: 457 (0.01%)
  R2 reads trimmed right: 3543921 (50.17%)
  Average R2 nucleotides trimmed left: 0.004435277229600981
  Average R2 nucleotides trimmed right: 3.0740746508263235
======================================

[mizraelson]

Please try using the latest MiXCR version. Also in the command you say you used --species alpaca but form the logs it is crlear it was --species lamaGlama

[KlaraK]

Dear all,

I don’t know if my experience helps, but I have used MiXCR to align sequences from a llama naïve VHH library, and the mapping success rate was over 96%. However, I am unsure whether the germline reference truly corresponds to Lama glama, or whether it defaults to Vicugna pacos (alpaca), given that these references are sometimes interchanged.

On the documentation website, I found it a bit unclear which germline set is actually used under --species lamaGlama. Could you please clarify:

Which specific germline reference is used by MiXCR for --species lamaGlama?

Is this reference based on the IMGT database (and if so, which version), or is it a custom internal MiXCR set?

If the internal library differs from the official IMGT llama set, would you recommend building a custom library from IMGT llama sequences directly?

Here is an example of the command I used:

java -jar mixcr.jar align \
  --preset generic-amplicon \
  --species lamaGlama \
  --dna \
  --floating-left-alignment-boundary \
  --floating-right-alignment-boundary C \
  --assemble-clonotypes-by CDR3 \
  input.fastq \
  output.alignments.vdjca \
  -OsaveOriginalReads=true \
  --verbose \
  -t 8

Thanks in advance — I’d love to ensure our resource is properly annotated before sharing it more broadly with the community!

Best regards,
Klara

[mizraelson]

Hi, the reference is a custom-made one for Lama glama. It may differ from IMGT, but I recommend using the built-in version, as we have manually verified each gene using the genome sequence.
FYI, for alpaca, we have another dedicated IGH reference: --species alpaca