Mastering Full-Length BCR Sequencing: A Comprehensive Guide to MiXCR Contig Assembly for Immune Repertoire Analysis

Abstract

This article provides a complete guide to assembling full-length B-cell receptor (BCR) sequences using MiXCR's contig assembly module. Targeted at immunologists, bioinformaticians, and therapeutic developers, we explore the fundamental principles of BCR biology and MiXCR's role, detail step-by-step protocols and advanced applications, address common pitfalls and optimization strategies, and validate performance against alternative tools. The guide synthesizes best practices for obtaining high-quality, biologically relevant contigs to advance antibody discovery, autoimmune disease research, and vaccine development.

Decoding the Immune Repertoire: Why Full-Length BCR Contigs Are Critical for Discovery

The study of B-cell receptor (BCR) repertoires is pivotal for understanding adaptive immunity, autoimmune diseases, and developing therapeutic antibodies. This document frames the biological process of antibody generation within the context of a broader thesis on MiXCR contig assembly for full-length BCR sequence research. MiXCR is a software tool for analyzing T-cell and B-cell receptor repertoires from next-generation sequencing (NGS) data. The core biological imperative—V(D)J recombination, somatic hypermutation (SHM), and affinity maturation—generates the raw sequence diversity that MiXCR assembles, annotates, and quantifies. Accurate contig assembly is essential for reconstructing complete, functional antibody variable region sequences from short-read data, enabling downstream analysis of clonality, somatic mutations, and lineage tracing for drug discovery.

Core Biological Processes: Application Notes

V(D)J Recombination: The Foundation of Diversity

V(D)J recombination is a site-specific somatic recombination event that assembles Variable (V), Diversity (D, for heavy chains), and Joining (J) gene segments to create the variable region exons of immunoglobulin genes.

Key Quantitative Data:

Table 1: Human Immunoglobulin Gene Segment Diversity (Germline)

Locus	Functional V Segments	Functional D Segments	Functional J Segments	Theoretical Combinatorial Diversity
Heavy Chain (IGH)	40-50	23	6	~ 6,900 (V x D x J)
Kappa Light Chain (IGK)	31-35	0	5	~ 175 (V x J)
Lambda Light Chain (IGL)	29-33	0	4-5	~ 145 (V x J)

Note: Theoretical combinatorial diversity for a paired heavy-light chain exceeds 1 million (e.g., 6,900 x 320).

Mechanism & Relevance to MiXCR: The recombination is mediated by RAG1/RAG2 enzymes, introducing random nucleotides (P-addition) and exonuclease trimming at junctions, adding junctional diversity. This results in a unique CDR3 region, the primary target for clonotype identification by MiXCR. The software aligns reads to a database of known V, D, and J germline segments to reconstruct the rearrangement event.

Somatic Hypermutation & Affinity Maturation

Following antigen exposure, B-cells proliferate in germinal centers, and the variable region genes undergo somatic hypermutation (SHM), introduced by Activation-Induced Cytidine Deaminase (AID). Point mutations are selected for increased antigen affinity.

Key Quantitative Data:

Table 2: Somatic Hypermutation Dynamics

Parameter	Typical Range	Measurement Context
Mutation Rate	10⁻³ to 10⁻⁴ per base per generation	In vivo germinal center B-cells
Hotspot Targeting	~5x higher in RGYW/WRCY motifs	Sequence motif analysis
Mutation Load in Memory B-cells	5-20 mutations per V region	Compared to germline sequence
Impact on Affinity (Kd)	Can improve by 10 to 10,000-fold	Pre- vs. post-maturation antibody clones

Relevance to MiXCR: MiXCR's assembleContigs function is critical for building full-length sequences from mutated reads. It must distinguish true somatic mutations from PCR/sequencing errors and accurately map them to clonal lineages, which is essential for studying affinity maturation trajectories.

Experimental Protocols for Validation

Protocol: Library Preparation for BCR Repertoire Sequencing (RNA-based)

Objective: Generate NGS libraries from B-cell RNA suitable for full-length variable region sequencing and MiXCR analysis.

Materials:

• Fresh PBMCs or sorted B-cells.
• RNA extraction kit (e.g., Qiagen RNeasy Plus Micro Kit).
• Reverse Transcription Primer: Oligo-dT or gene-specific primers targeting constant regions.
• PCR Primers: Multiplexed primers targeting all known human V gene families and a primer for the constant region.
• High-fidelity DNA polymerase (e.g., KAPA HiFi HotStart ReadyMix).
• NGS library prep kit (e.g., Illumina Nextera XT).

Procedure:

• RNA Isolation: Extract total RNA from ≥10⁵ B-cells. Include DNase I treatment.
• cDNA Synthesis: Perform reverse transcription using a primer anchored in the IgG/IgA/IgM constant region (e.g., Cγ, Cα, Cμ) to ensure full-length V(D)J-C transcript coverage.
• Primary PCR Amplification: Amplify the variable region using multiplexed V-gene forward primers and a reverse primer in the constant region. Use 18-25 cycles with high-fidelity polymerase.
• Purification: Clean PCR product using AMPure XP beads.
• Library Preparation & Indexing: Fragment and add sequencing adapters using the Nextera XT kit. Perform a second, limited-cycle (8-10 cycles) PCR with indexing primers.
• Quality Control & Sequencing: Validate library size (~500-700bp) via Bioanalyzer, quantify by qPCR, and sequence on an Illumina platform (2x300bp MiSeq recommended for full-length coverage).

Protocol: MiXCR Contig Assembly and Analysis for Full-Length BCRs

Objective: Process raw NGS reads to assemble contigs, reconstruct clonotypes, and analyze mutations.

Materials:

• Computational Resources: ≥16GB RAM, Unix-based system.
• Software: MiXCR (v4.0+), Java.
• Reference File: IMGT germline gene database (bundled with MiXCR).

Procedure:

• Import Sequences:
  Key Parameters: --contig-assembly enables the full-length contig reconstruction algorithm.

• Interpret Output: The analysis pipeline executes:

  • Align: Maps reads to V, D, J, and C gene segments.
  • Assemble: Overlaps aligned reads to build full-length contigs for each clonotype, resolving regions of SHM.
  • AssembleContigs: (Core function) Merges assembled sequences into clonotypes and refines alignments.
  • Export Clones: Generate a final clonotype table.

• Export for Downstream Analysis:

• Somatic Mutation Analysis: Use the exportClones output to calculate mutation counts relative to the assigned germline V and J genes.

Visualizations

Diagram 1: From V(D)J to Antibody: Biology & MiXCR Analysis Workflow (86 chars)

Diagram 2: Key Signaling for B-Cell Activation & SHM (78 chars)

The Scientist's Toolkit: Research Reagent Solutions

Table 3: Essential Reagents for BCR Repertoire Studies

Reagent / Material	Function / Role	Example Product / Note
B-Cell Isolation Kits	Negative or positive selection of human/mouse B-cells from PBMCs/spleen. Critical for reducing background.	Miltenyi Biotec Pan B Cell Isolation Kit; STEMCELL Technologies EasySep.
5' RACE-Compatible RT Kit	For unbiased amplification of full-length antibody transcripts without V-gene primer bias. Critical for novel antibody discovery.	SMARTer RACE 5'/3' Kit (Takara Bio).
Multiplex V-Gene PCR Primers	Amplify the vast majority of functional V-gene rearrangements from cDNA.	Published panels (e.g., Britanova et al. 2014) or commercially available mixes.
UMI Adapters	Unique Molecular Identifiers enable error correction and accurate quantification of original mRNA molecules, essential for SHM analysis.	Illumina TruSeq UD Indexes; custom double-stranded UMI adapters.
High-Fidelity Polymerase	Minimizes PCR errors that can be misidentified as somatic mutations.	KAPA HiFi, Q5 Hot Start (NEB).
MiXCR Software	Integrated analysis suite for end-to-end immune repertoire sequencing data analysis, including contig assembly.	Open-source (https://mixcr.com). Requires IMGT database.
IMGT/GENE-DB	The international reference for immunoglobulin germline gene sequences. Essential for accurate V(D)J alignment and SHM calculation.	Accessed via MiXCR or directly from IMGT website.

MiXCR is a comprehensive, alignment-based software pipeline for the analysis of T- and B-cell receptor repertoire sequencing data (immune repertoire sequencing, Rep-Seq). In the Next-Generation Sequencing (NGS) ecosystem, it serves as a critical intermediary between raw sequencing reads (from platforms like Illumina, Ion Torrent, or Oxford Nanopore) and high-level immunological interpretation. Its core function is to assemble clonotypes—groups of sequences originating from the same progenitor lymphocyte—from complex NGS data, providing quantitative and qualitative profiles of the adaptive immune response.

Key Advantages for B-Cell Receptor (BCR) Analysis:

• Full-Length Reconstruction: Capable of assembling complete V(D)J transcripts from both RNA and DNA data, which is paramount for studying antibody maturation, isotype switching, and somatic hypermutation patterns.
• High Accuracy and Sensitivity: Employs a sophisticated multi-stage alignment algorithm that minimizes false positive clonotypes while recovering rare clones, even from suboptimal sequencing data.
• Multi-Platform and Multi-Protocol Support: Processes data from bulk RNA/DNA, single-cell (10x Genomics, SMART-seq), and even metagenomic samples.
• Integrated Post-Analysis: Provides built-in functions for clonotype tracking, repertoire overlap analysis, and mutation profiling, forming a self-contained analysis suite.

Key Performance Data and Comparative Analysis

The following table summarizes quantitative performance metrics for MiXCR in BCR analysis, as benchmarked in recent literature and software publications.

Table 1: Performance Metrics of MiXCR for BCR Repertoire Analysis

Metric	Reported Performance	Context / Benchmark
Clonotype Recovery Accuracy	>99% (for abundant clones)	Simulation studies with known input repertoires.
Sensitivity for Rare Clones (<0.01%)	~85-95%	Dependent on sequencing depth and library quality.
Computational Speed	~100,000 reads/minute (single thread)	Faster than many de novo assemblers; alignment-based efficiency.
Memory Usage	Moderate (typically <16 GB for standard runs)	Efficient indexing of reference germline databases.
Error Correction Efficacy	Reduces PCR/sequencing errors by >90%	Via built-in molecular barcode (UMI) processing and quality-aware clustering.
V/J Gene Call Accuracy	~98-99% concordance with validated datasets	Against curated sets from projects like Adaptive Biotechnologies.
Full-Length Contig Assembly Rate (scRNA-seq)	~60-80% of productive cells	For 10x Genomics 5' V(D)J data, depending on cDNA quality.

Detailed Protocol: MiXCR-Based Contig Assembly for Full-Length BCR Sequences from Bulk RNA-Seq

This protocol outlines the generation of full-length, paired heavy-light chain BCR contigs from bulk RNA-sequencing data, a core methodology for thesis research on antibody discovery and repertoire dynamics.

A. Wet-Lab Protocol: Library Preparation for BCR Rep-Seq Objective: Generate amplicon libraries covering the full-length variable region of BCRs (IgH, IgK, IgL) with Unique Molecular Identifiers (UMIs).

• RNA Isolation & QC: Extract total RNA from PBMCs or B-cell populations using a column-based kit (e.g., Qiagen RNeasy). Assess integrity (RIN > 7) via Bioanalyzer.
• cDNA Synthesis: Perform reverse transcription using a template-switch oligo (TSO) and isotype-specific constant region primers or multiplexed V-gene primers to ensure full V(D)J capture. Include UMIs in the template-switch or primer design.
• Target Amplification: Perform two rounds of PCR.
  • 1st PCR: Use a primer mix covering all functional V genes and a primer anchoring in the C region. Use limited cycles (e.g., 20-25).
  • 2nd PCR (Indexing): Add Illumina adapters and sample-specific dual indices. Use minimal cycles (e.g., 10-15).
• Library QC & Sequencing: Purify libraries with size selection (e.g., SPRI beads), quantify by qPCR, and sequence on an Illumina platform (MiSeq/NextSeq) with paired-end 2x300 bp or 2x150 bp reads to span the full V(D)J region.

B. Computational Protocol: MiXCR Analysis Pipeline Input: Paired-end FASTQ files (R1, R2). Output: Clonotype table with full-length assembled sequences.

Table 2: Research Reagent Solutions for MiXCR-Based BCR Study

Item	Function/Description	Example Product/Kit
UMI-Compatible RT Kit	Reverse transcription with UMI incorporation for accurate error correction and molecule counting.	SMARTer Human BCR Profiling Kit (Takara Bio)
Multiplex V-Gene Primers	Primer sets designed to uniformly amplify all functional V genes across IGH, IGK, IGL loci.	ImmunoRECOVER primers (iRepertoire)
High-Fidelity Polymerase	PCR enzyme with low error rate to minimize amplification artifacts during library construction.	KAPA HiFi HotStart ReadyMix (Roche)
Size Selection Beads	Magnetic beads for clean-up and precise selection of amplicon libraries.	AMPure XP Beads (Beckman Coulter)
MiXCR Software Suite	The core analysis pipeline for alignment, assembly, and quantification of BCR sequences.	MiXCR (GitHub, Milaboratory)
Germline Database	Curated reference sequences for V, D, J, and C genes, essential for accurate alignment.	IMGT database, included with MiXCR
Downstream Analysis Tool	Platform for advanced visualization, lineage tracking, and repertoire comparison.	VDJtools, immunarch

Visualization of Workflows and Relationships

Title: MiXCR Position in BCR NGS Data Flow

Title: End-to-End Protocol for MiXCR BCR Contig Assembly

In immune repertoire sequencing, a contig (from "contiguous sequence") is a computationally reconstructed, full-length sequence of an immune receptor (e.g., BCR or TCR) assembled from shorter, overlapping sequencing reads. This process is critical for accurately determining the complete variable region sequence, which encodes the antigen-binding site, for downstream analysis of clonality, somatic hypermutation, and lineage tracking. Within the context of MiXCR software for full-length BCR research, contig assembly is the pivotal step that transforms raw, fragmented NGS data into biologically meaningful, complete immunoglobulin sequences.

Aspect	Description	Typical Metric/Value
Primary Input	Paired-end sequencing reads (RNA or DNA).	Read length: 150-300 bp. Read pairs per sample: 50k - 5M.
Contig Assembly Goal	Reconstruct full-length V(D)J region from overlapping reads.	Target length: ~400-500 bp for heavy chain.
Key Output	High-confidence, error-corrected consensus sequence.	Contigs per sample: 100s to 100,000s.
Success Metric	Percentage of reads assembled into contigs.	Assembly rate: 70-95% (dependent on library quality & coverage).
Critical Parameter	Overlap length and identity for read alignment.	Minimum overlap: 15-20 bp. Minimum identity: 90-95%.
Downstream Impact	Accurate clonotype calling and SHM analysis.	Error rate post-assembly: <0.1%.

Detailed Protocol: MiXCR Contig Assembly for Full-Length BCR Sequences

Objective: To generate full-length, high-fidelity BCR contigs from raw FASTQ files using the MiXCR pipeline.

Materials & Software:

• Raw paired-end FASTQ files (R1 & R2).
• High-performance computing server (Linux/macOS).
• Java Runtime Environment (JRE) version 11 or higher.
• MiXCR software (latest version).

Procedure:

1. Data Import and Alignment

• --species hs: Sets species to Homo sapiens.
• --starting-material rna: Specifies RNA-seq data (important for splicing awareness).
• --contig-assembly: Flags the pipeline to perform contig assembly.
• --receptor-type ig: Focuses on immunoglobulins (BCRs).

2. Contig Assembly Core Process This step is executed automatically within the analyze amplicon command. The algorithm: * Overlap Detection: Finds overlapping regions between read pairs based on sequence identity. * Clustering: Groups together reads originating from the same original BCR transcript. * Multiple Sequence Alignment (MSA): Aligns all reads within a cluster. * Consensus Calling: Builds a single, high-quality contig sequence from the MSA, correcting for PCR and sequencing errors.

3. Export Results

Visualization: Contig Assembly Workflow in MiXCR

Title: MiXCR Contig Assembly Pipeline for BCRs

The Scientist's Toolkit: Key Research Reagent Solutions

Item	Function in BCR Contig Research
5' RACE Primers	Ensures capture of the complete variable region start during cDNA synthesis, critical for full-length contigs.
Unique Molecular Identifiers (UMIs)	Short random nucleotide tags added during library prep to tag original molecules, enabling error correction and accurate consensus building.
High-Fidelity DNA Polymerase	Minimizes PCR errors during library amplification, preserving true sequence diversity for accurate assembly.
Pan-Immunoglobulin Reverse Transcription Primer	Targets the constant region of all BCR isotypes to comprehensively convert BCR mRNA into cDNA.
Size Selection Beads (e.g., SPRI)	Purifies and selects correctly sized amplicons, removing primer dimers to improve sequencing data quality for assembly.
MiXCR Software Suite	The primary bioinformatics tool that executes alignment, clustering, and consensus calling to generate contigs.
Reference Gene Database (IMGT)	Curated set of germline V, D, and J genes used as an alignment reference for accurate segment identification.

This application note details a standardized bioinformatics pipeline for processing raw B-cell receptor (BCR) repertoire sequencing data into assembled, full-length contig files. The protocols are framed within a thesis research context utilizing the MiXCR platform for contig assembly, which is critical for obtaining complete variable region sequences for downstream analysis in immunology, oncology, and therapeutic antibody discovery.

The pipeline consists of sequential quality control, alignment, and assembly steps. Key performance metrics for a typical human BCR repertoire sequencing run (150bp PE, 100M reads) are summarized below.

Table 1: Pipeline Stages, Key Tools, and Expected Output Metrics

Pipeline Stage	Primary Tool/Module	Input	Output	Key Metric (Typical Range)	Purpose
Raw QC & Trimming	FastP	Raw FASTQ	Trimmed FASTQ	Reads Retained: >95%	Remove adapters, low-quality bases.
Alignment & Assembly	MiXCR analyze	Trimmed FASTQ	Contigs, Clones	Clonotypes: 10^4 - 10^5	Align reads, assemble V(D)J contigs.
Contig Export	MiXCR exportContigs	MiXCR Clones	FASTA Contigs	Contigs per clone: 1-5	Extract full-length nucleotide sequences.
Contig QC & Filtering	In-house scripts	FASTA Contigs	Filtered Contigs	Contigs with Full V/J: >85%	Ensure contig completeness.

Table 2: MiXCR analyze Command Parameters for Full-Length BCR Contigs

Parameter	Setting	Explanation
--species	hs (Homo sapiens)	Species-specific germline reference.
--starting-material	rna	Specifies RNA-seq input for splicing handling.
--contig-assembly	--impute-germline-on-export	Enables contig assembly and germline imputation.
--assemble-clonotypes-by	CDR3	Clonotype grouping criterion.
--assemble	--write-alignments	Writes detailed read-to-contig alignments.

Detailed Experimental Protocols

Protocol 2.1: Initial Data QC and Adapter Trimming

Objective: To ensure input data quality for robust assembly.

• Tool: FastP (v0.23.2).
• Command:

• Validation: Inspect the HTML report for per-base quality scores, adapter content (<1%), and duplication levels.

Protocol 2.2: MiXCR-Based Contig Assembly

Objective: To align reads, assemble V(D)J sequences, and reconstruct clonotypes.

• Tool: MiXCR (v4.6.0).
• Command:

• Output Files: sample_output.clna (clone alignments), sample_output.clns (clones), sample_output.report (summary).

Protocol 2.3: Export and Filter Full-Length Contigs

Objective: To extract high-quality, full-length contig sequences in FASTA format.

• Export Contigs:

• Custom Filtering (Python Script Example):

Visualization of Workflows

Diagram 1: BCR sequencing data pipeline workflow.

Diagram 2: MiXCR internal alignment and assembly steps.

The Scientist's Toolkit: Essential Research Reagents & Materials

Table 3: Key Reagents and Computational Tools for BCR Contig Assembly

Item	Category	Function/Description
Total RNA from B Cells	Biological Sample	Starting material for library prep; requires high integrity (RIN > 8).
UMI-based BCR Kit	Library Prep	e.g., SMARTer TCR/BCR kits. Incorporates Unique Molecular Identifiers (UMIs) for accurate PCR error correction and contig assembly.
MiXCR Software Suite	Bioinformatics Tool	Core platform for alignments, assembly, and clonotyping.
hg38 (Human) Germline Reference	Reference Data	Curated set of V, D, J gene alleles from IMGT, required for alignment.
FastP	QC Tool	Performs fast, all-in-one preprocessing of FASTQ files.
High-Performance Computing (HPC) Cluster	Infrastructure	Essential for processing large-scale repertoire data (100M+ reads) within feasible time.

Within a thesis on MiXCR contig assembly for full-length BCR repertoire research, the final analysis hinges on the accurate interpretation of two core output files: clonotypes.tsv and contigs.fasta. These files represent the distilled, high-confidence results of the pipeline, transitioning from raw sequencing reads to quantifiable, biologically meaningful data. This protocol details the structure, interpretation, and downstream application of these files for researchers and drug development professionals aiming to characterize antibody repertoires for therapeutic discovery, biomarker identification, and immune monitoring.

File Interpretation and Data Structure

This tab-separated values file contains the final, collapsed list of unique clonotypes, each defined by its V, D, J, and C gene assignments and the CDR3 amino acid sequence. It is the primary file for quantitative immune repertoire analysis.

Key Columns and Quantitative Data Summary: Table 1: Core Quantitative Columns in clonotypes.tsv

Column Name	Data Type	Description	Typical Range/Example
cloneId	Integer	Unique identifier for each clonotype.	0, 1, 2, ...
cloneCount	Integer	Absolute count of reads (or UMIs) assigned to this clonotype.	1 - 10^5+
cloneFraction	Float	Proportion of the total reads in the sample belonging to this clonotype.	0.0 - 1.0
targetSequences	Integer	Number of input sequences contributing to the clonotype.	Correlates with cloneCount
cdr3aa	String	Amino acid sequence of the CDR3 region.	e.g., CAREGNYDYGFDF
vHit, dHit, jHit, cHit	String	Best-matched germline gene(s).	e.g., IGHV3-23*01, IGHD3-10*01
nSeqImputedCDR3	String	Nucleotide sequence of the CDR3 region.
aaSeqImputedFR1-4	String	Amino acid sequences of the Framework Regions.

Table 2: Additional Clonal Quality Metrics (MiXCR v4.0+)

Column Name	Function	Interpretation
cloneScore	Float	A composite quality score for the clonotype assembly.	Higher is better (e.g., > 50).
uniqueUMICount	Integer	If UMI-based correction applied, number of distinct UMIs.	More accurate count than cloneCount.
readCount	Integer	Total number of reads supporting the clonotype.	Can be > uniqueUMICount.

Thecontigs.fastaFile: Assembled Sequence Data

This FASTA file contains the full-length, assembled nucleotide sequences for the top contigs of each clonotype. Each sequence header contains metadata linking it back to the clonotypes.tsv file.

Header Format & Sequence Data: >CLONE_[cloneId]_[contigIndex]_[copyNumber] [additional info like vHit, cdr3aa]

Example: >CLONE_12_contig_1_abundance=150 IGHV4-34*01|IGHJ4*01|CAREGNYDYGFDF

Table 3: contigs.fasta File Content Breakdown

Component	Description	Use in Downstream Analysis
FASTA Header	Metadata identifier.	Links sequence to clonal ID and abundance.
Nucleotide Sequence	Full-length, high-quality assembled sequence of the BCR transcript.	Basis for recombinant antibody cloning, phylogenetic analysis, and somatic hypermutation (SHM) calculation.
Imputed V-D-J structure	Inferred from alignment during assembly.	Used for precise gene usage statistics and lineage tracing.

Experimental Protocols for Downstream Analysis

Protocol 2.1: Repertoire Diversity and Clonal Expansion Analysis

Objective: To quantify the breadth and skewness of the BCR immune repertoire from the clonotypes.tsv file.

Materials:

• clonotypes.tsv file from MiXCR.
• Statistical software (R with dplyr, ggplot2, vegan; or Python with pandas, scipy, skbio).

Methodology:

• Data Import: Load the clonotypes.tsv file, filtering by cloneCount ≥ 2 (or appropriate threshold) to exclude potential sequencing errors.
• Rank-Abundance Curve:
  • Sort clonotypes by cloneFraction in descending order.
  • Plot rank (log10) against cloneFraction (log10). A steep curve indicates a dominant, oligoclonal repertoire; a shallow curve suggests high diversity.
• Diversity Index Calculation:
  • Calculate standard ecological indices using the cloneFraction column as the abundance vector.
    • Shannon Index (H'): Measures entropy. H' = -sum(p_i * log(p_i)). Higher H' = greater diversity.
    • Simpson's Index (D): Probability two randomly selected reads belong to the same clonotype. D = sum(p_i^2). Lower D = greater diversity.
    • Pielou's Evenness (J): J = H' / log(S), where S is the total number of clonotypes. J接近1 indicates perfectly even clonal distribution.
• Clonal Expansion Flagging: Identify expanded clones, typically defined as those with a cloneFraction above a sample-specific threshold (e.g., > 0.01% of total repertoire or top 1% by fraction).

Protocol 2.2: Recombinant Antibody Expression Vector Construction

Objective: To clone the variable region of a selected BCR from contigs.fasta for functional validation.

Materials:

• contigs.fasta file.
• Gene-specific primers or synthetic gene fragment.
• Restriction enzymes (e.g., AgeI and SalI for IgG expression).
• Mammalian expression vector (e.g., pFUSE-based vectors from InvivoGen).
• HEK293F or Expi293F cells for transient expression.

Methodology:

• Target Selection: Identify the cloneId of interest from clonotypes.tsv analysis (e.g., a highly expanded, public, or antigen-specific clone).
• Sequence Retrieval: Extract the corresponding full-length V(D)J nucleotide sequence from contigs.fasta using the header CLONE_[id].
• Sequence Optimization & Synthesis:
  • Annotate the V(D)J region using IMGT/V-QUEST.
  • Back-translate the amino acid sequence using human codon-optimized tables.
  • Add appropriate restriction sites flanking the variable region.
  • Order the sequence as a synthetic gBlock or perform PCR amplification from cDNA using specific primers.
• Molecular Cloning:
  • Digest both the optimized PCR product/gBlock and the IgG1 expression vector with the chosen restriction enzymes.
  • Perform ligation and transform into competent E. coli.
  • Sequence-validate multiple clones to ensure fidelity.
• Antibody Expression & Purification:
  • Co-transfect the heavy and light chain vectors (light chain from a paired analysis or assumed partner) into HEK293F cells.
  • Harvest supernatant after 5-7 days.
  • Purify antibody using Protein A/G affinity chromatography.
  • Validate binding via ELISA or surface plasmon resonance (SPR).

Visualization of Analysis Workflows

Title: Downstream Analysis Workflow from MiXCR Outputs

Title: Structure of a contigs.fasta Entry

Table 4: Key Research Reagent Solutions for BCR Contig Analysis

Item	Function & Application	Example Product/Resource
MiXCR Software	Core analytical pipeline for assembling contigs and calling clonotypes from raw NGS data.	MiXCR (Commercial & Academic licenses).
IMGT/V-QUEST	Gold-standard database and tool for immunoglobulin gene alignment, annotation, and SHM analysis.	IMGT (Free for academic use).
IgBLAST	Alternative NCBI tool for V(D)J sequence alignment and germline identification.	Integrated into MiXCR, standalone via command line.
pFUSE Vectors	Modular mammalian expression vectors designed for easy cloning of antibody heavy and light chains.	InvivoGen pFUSE series.
Expi293 Expression System	High-efficiency system for transient expression of recombinant antibodies from cloned contigs.	Thermo Fisher Expi293F Cells & Kit.
Protein A/G Resin	Affinity chromatography resin for purification of IgG antibodies from culture supernatant.	Cytiva HiTrap Protein A HP.
R tidyverse / immunarch	R packages for robust data manipulation, visualization, and dedicated immune repertoire analysis.	CRAN, ImmunoMind.
Python scirpy	Python toolkit for analyzing immune repertoires and single-cell TCR/BCR data integrated with transcriptomics.	scirpy.

From Reads to Repertoire: A Step-by-Step Protocol for MiXCR Contig Assembly

Within the context of a broader thesis on MiXCR-based contig assembly for full-length B-cell receptor (BCR) repertoire research, the integrity and quality of input data are paramount. High-quality data acquisition and preprocessing directly dictate the accuracy of clonotype identification, contig assembly, and subsequent immunological interpretation. This document details the specific requirements and quality control (QC) protocols for raw sequencing data (FASTQ) and aligned data (BAM) to ensure robust and reproducible analysis of full-length BCR sequences.

Input Data Requirements

Recommended Sequencing Strategies

For full-length BCR analysis using MiXCR, specific sequencing approaches are recommended to capture the complete variable region.

Table 1: Sequencing Strategies for Full-Length BCR Analysis

Strategy	Target Region	Recommended Platform	Typical Read Length	Key Advantage for MiXCR
5' RACE (Single-cell)	Full V(D)J + constant region	Illumina MiSeq/NovaSeq, PacBio HiFi	2x300 bp, >1kb	Captures complete transcript from the 5' end, ideal for contig assembly.
V(D)J-enriched Bulk RNA-seq	V(D)J + partial constant	Illumina NextSeq/NovaSeq	2x150 bp	High throughput for repertoire diversity; requires precise primer set.
Full-length scRNA-seq (10x Genomics)	5' transcriptome includes V(D)J	Illumina NovaSeq	2x150 bp (paired-end)	Cell-by-cell analysis with UMI support for error correction.

FASTQ File Specifications

Raw sequencing data must conform to the following standards for optimal MiXCR processing.

Table 2: FASTQ Input Requirements for MiXCR

Parameter	Minimum Requirement	Optimal Target	QC Check
Read Type	Paired-end (R1, R2)	Paired-end with UMIs	File pair verification
Read Length	≥ 75 bp per read	≥ 150 bp per read	FastQC Per base sequence quality
Total Reads	≥ 100,000 per sample	1-5 million per sample	Read count from wc -l
Phred Quality Score (Q)	Q20 ≥ 80% of bases	Q30 ≥ 85% of bases	FastQC Per sequence quality scores
Adapter Contamination	< 10% of reads	< 5% of reads	FastQC Adapter Content module
GC Content	Within 5% of expected*	Within 2% of expected*	FastQC Per sequence GC content

*Expected GC content for human BCR transcripts is typically ~45-55%.

Quality Control Protocols

Protocol: Preprocessing and QC of Raw FASTQ Files

Objective: To assess raw read quality, remove technical sequences, and generate a cleaned FASTQ set for MiXCR import.

Materials & Software: FastQC (v0.12.0+), Trimmomatic (v0.39+) or cutadapt (v4.0+), MultiQC (v1.14+).

Procedure:

• Initial Quality Assessment:
  • Run FastQC on all raw FASTQ files: fastqc sample_R1.fastq.gz sample_R2.fastq.gz -o ./fastqc_raw/
  • Aggregate reports using MultiQC: multiqc ./fastqc_raw/ -o ./multiqc_report/
  • Review key metrics: Per base quality, adapter content, overrepresented sequences.

• Adapter & Quality Trimming:

  • Execute Trimmomatic in PE mode:

  • Alternative using cutadapt for UMI-based protocols is detailed in Supplementary Protocol A.

• Post-Trimming QC:

  • Run FastQC on the paired output files (*_paired.fq.gz).
  • Confirm improvements in quality scores and reduction of adapter content.

Protocol: BAM File Validation and Preparation

Objective: To validate and, if necessary, prepare aligned BAM files for use as MiXCR input (an alternative to FASTQ).

Materials & Software: samtools (v1.15+), picard (v2.27+), MiXCR.

Procedure:

• BAM File Integrity Check:
  • Check header and format: samtools quickcheck input.bam
  • Sort and index if required: samtools sort -@ 8 input.bam -o input_sorted.bam && samtools index input_sorted.bam

• Validate Alignment Suitability for BCR Analysis:

  • Ensure the BAM contains the CB (cell barcode) and UB (UMI) tags for single-cell data.
  • Verify that aligned reads encompass the BCR locus (e.g., IGH, IGK, IGL). Extract a subset: samtools view -b input_sorted.bam "chr14:105,000,000-107,000,000" > IGH_region.bam

• Convert BAM to FASTQ for MiXCR (if needed):

  • MiXCR can accept BAM directly. However, for specific workflows, conversion may be necessary using bedtools:

The Scientist's Toolkit: Research Reagent Solutions

Table 3: Essential Materials for BCR Sequencing Library Preparation

Item	Function	Example Product (Non-exhaustive)
5' Switching Oligo	Template switching for cDNA elongation in RACE protocols	SMARTScribe Oligo (Takara Bio)
BCR V(D)J Primer Panels	Multiplex PCR enrichment of BCR variable regions	Human BCR Ig Primer Set (iRepertoire)
UMI-containing RT Primers	Incorporates Unique Molecular Identifiers during reverse transcription for error correction	10x Genomics Single Cell 5' v2 RT Primer
Magnetic Beads for Size Selection	Purification of full-length cDNA or amplicons	SPRIselect Beads (Beckman Coulter)
High-Fidelity DNA Polymerase	Accurate amplification of BCR regions with minimal bias	KAPA HiFi HotStart ReadyMix (Roche)
Dual Indexing Kit	Multiplexing of samples with unique dual indices	IDT for Illumina UD Indexes

Visualization of Workflows

Diagram 1: FASTQ to Contig Assembly QC Pipeline

Diagram 2: BAM File Validation Pathway

Application Notes

The assembleContigs command in MiXCR is a critical step in reconstructing full-length B- or T-cell receptor (BCR/TCR) sequences from short-read (e.g., Illumina) or long-read sequencing data. Within the context of a thesis on MiXCR contig assembly for full-length BCR sequences, this module bridges the gap between initial alignment of raw reads and obtaining clonotype tables, enabling the study of complete, paired V-D-J-C sequences essential for understanding antibody repertoires in immunology, autoimmune disease research, and therapeutic antibody discovery.

The command functions by assembling aligned reads into contiguous sequences (contigs) for each clonotype. It resolves variations caused by PCR and sequencing errors, fills gaps in low-coverage regions, and corrects phasing issues in paired-end reads to produce a single, high-quality consensus sequence for each clonal rearrangement.

Essential Parameters and Quantitative Performance

The performance and output of assembleContigs are governed by key parameters that balance sensitivity, specificity, and computational efficiency. The following table summarizes these essential parameters and their quantitative impact on assembly outcomes based on benchmark studies.

Table 1: Essential Parameters for assembleContigs and Their Impact

Parameter	Default Value	Typical Range	Primary Function	Impact on Output & Performance
--overlap	20	10-50	Min. overlap length (bp) for merging reads.	Higher values increase specificity but may reduce contig length in low-coverage regions. <15 bp can induce false assemblies.
--minimal-reads	3	1-10	Min. # of reads required to form a contig.	Lower values increase sensitivity for rare clones but increase risk of noise. ≥3 is recommended for robust consensus.
--minimal-contig-length	150	100-500	Min. length (bp) of output contig.	Filters out short, uninformative contigs. For full-length BCR, >300 bp is often targeted.
--max-numnopedreads	5	0-10	Max. # of reads with poor alignment per clonotype.	Tolerates sequencing errors; higher values can rescue challenging reads but may incorporate artifacts.
--max-gap	15	5-30	Max allowed gap (bp) during contig extension.	Critical for spanning low-coverage V-J junctions. Larger gaps aid assembly but require higher overall coverage.
--threads	4	1-32	Number of CPU threads.	Directly scales processing speed. Near-linear scaling up to ~16 threads for typical datasets.

Performance Note: On a standard 50M read BCR-seq dataset, using default parameters, assembleContigs typically processes data at ~100,000-200,000 reads/minute per thread, with a peak memory usage of 8-12 GB RAM.

Experimental Protocols

Protocol 1: Standard Workflow for Full-Length BCR Contig Assembly from Paired-End RNA-Seq Data

This protocol details the steps from raw FASTQ files to assembled contigs, optimized for recovering complete V-D-J-C regions.

• Sample Preparation & Sequencing:

  • Extract total RNA from B cells (e.g., PBMCs, sorted B cells, tissue).
  • Prepare libraries using a 5' RACE-based protocol (e.g., SMARTer) targeting IgG/IgA/IgM constant regions to ensure full-length V-D-J capture.
  • Sequence on an Illumina platform (MiSeq, HiSeq, or NovaSeq) using 2x300 bp or 2x150 bp paired-end chemistry to adequately cover the ~500 bp V-D-J-C region.

• Data Preprocessing & Alignment with MiXCR:

  • Quality Control: Use FastQC to assess read quality. Trim adapters and low-quality bases using Trimmomatic or fastp.

  • Initial MiXCR Analysis: Run the standard mixcr analyze pipeline up to the assembleContigs step.

  • This generates intermediate files, including sample_output.vdjca (aligned reads).

• Targeted Contig Assembly:

  • Execute the assembleContigs command with parameters optimized for full-length assembly, focusing on the constant region.

  • Critical: The --minimal-contig-length should be set with the expected amplicon length in mind. For full-length heavy chain assembly, 350 bp is a safe minimum.

• Post-Assembly Analysis:

  • Export the final clonotype table with assembled contig sequences.

  • The output TSV file will contain columns contigSeq and contigQual with the consensus nucleotide sequence and its quality for each clonotype.

Protocol 2: Validation of Assembled Contigs via Sanger Sequencing

To experimentally validate the in silico assembled contigs, a complementary wet-lab protocol is employed.

• Primer Design and PCR:

  • From the assembleContigs output, identify the dominant clonotype(s).
  • Design clone-specific forward primers within the V region and a reverse primer in the constant region (e.g., IgG CH1).
  • Perform a nested PCR using cDNA from the original sample to amplify the specific full-length V-D-J-C region.

• Cloning and Sequencing:

  • Gel-purify the PCR product and clone it into a plasmid vector (e.g., using TA cloning).
  • Transform competent E. coli and pick at least 10-20 colonies for Sanger sequencing.
  • Align the Sanger-derived sequences with the MiXCR-generated contig sequence using tools like SnapGene or Geneious. Calculate percentage identity; successful assembly typically yields >99% identity.

Visualization

Title: MiXCR assembleContigs Command Internal Workflow

Title: Full-Length BCR Analysis Workflow with Contig Assembly

The Scientist's Toolkit

Table 2: Essential Research Reagent Solutions for BCR Contig Assembly Workflow

Item	Function in Workflow	Example Product/Kit
5' RACE-capable cDNA Synthesis Kit	Ensures capture of complete 5' variable region of antibody transcripts, critical for full-length contig assembly.	SMARTer RACE 5'/3' Kit (Takara Bio)
Immune Receptor-Specific PCR Primer Mix	Enriches sequencing libraries for BCR (Ig) or TCR transcripts, increasing on-target reads.	Human BCR or TCR Amplification Primer Sets (iRepertoire)
High-Fidelity DNA Polymerase	Used in amplification steps pre-sequencing to minimize PCR errors that complicate contig assembly.	KAPA HiFi HotStart ReadyMix (Roche)
Dual-Indexed Adapter Kit	Allows multiplexed sequencing of multiple samples, integrated with MiXCR's sample demultiplexing.	Illumina TruSeq DNA UD Indexes
TA Cloning Kit	For cloning PCR products of dominant contigs for validation via Sanger sequencing.	pGEM-T Easy Vector System (Promega)
MiXCR Software Suite	The core bioinformatics platform containing the assembleContigs command and all related analysis tools.	MiXCR (v4.0+)

Within the broader thesis on optimizing MiXCR for full-length BCR sequence assembly, the fine-tuning of specific advanced parameters is critical. This note details the application and impact of three such parameters: -OassemblingFeatures, --report, and --refine-clusters. Their strategic use is essential for enhancing contig assembly accuracy, enabling detailed quality control, and improving clonotype resolution, directly supporting high-stakes research in antibody discovery and therapeutic development.

Parameter Definitions and Quantitative Impact

Parameter	Default Value	Recommended Setting for BCR Assembly	Primary Function	Observed Impact on Full-Length Assembly
-OassemblingFeatures	VDJRegion	VDJRegion WithQuality	Defines which features of aligned reads are used during the overlapping and consensus building step of contig assembly.	Increases base-call accuracy in consensus sequences; reduces indel errors in CDR3 regions by ~15%.
--report	None (No report)	[file].report	Generates a detailed textual report file summarizing key steps, statistics, and assembly metrics.	Essential for QC; provides quantifiable metrics like initial/total alignments, assembled reads %, and cluster statistics.
--refine-clusters	off	byQuality	Applies an additional clustering refinement step to the initial sequence clusters before consensus assembly.	Reduces over-clustering of similar BCR sequences; can increase functional clonotype yield by 10-20% in complex repertoires.

Detailed Application Notes

1. -OassemblingFeatures=VDJRegion WithQuality This parameter instructs MiXCR to use both the sequence alignment and the per-base Phred quality scores from the input NGS reads during contig assembly. When building overlaps and consensus, higher-quality bases are weighted more heavily. This is particularly crucial for full-length BCR assembly where fidelity across the entire V(D)J segment is required. It mitigates the propagation of sequencing errors into final contigs, ensuring more reliable downstream analysis of somatic hypermutation.

2. --report=[file] The report file is a non-negotiable tool for rigorous experimental validation. It provides a step-by-step account of the assembly pipeline, allowing researchers to diagnose failures (e.g., a sudden drop in aligned reads) and confirm that each step performed within expected parameters. For thesis validation, this file offers concrete, auditable data on the efficiency of the assembly process.

3. --refine-clusters=byQuality Initial clustering by MiXCR may group sequences based on alignment coordinates and CDR3 similarity. The refine-clusters function performs an additional round of clustering using a different algorithm (byQuality uses sequence quality). This helps separate sequences that are genuinely distinct but were initially co-clustered due to overly liberal parameters, improving the resolution of clonally related but distinct BCR variants.

Experimental Protocols

Protocol 1: Optimized MiXCR Contig Assembly for Full-Length BCRs Objective: Generate high-fidelity, full-length BCR contigs from paired-end RNA-Seq data.

• Input Preparation: Provide demultiplexed, gzip-compressed FASTQ files (R1 and R2).
• Execute MiXCR Analyze Command:

• Report Analysis: Examine run123_report.txt. Key metrics: Final clonotype count, Assembled reads fraction, and Mean contig length per clonotype.
• Output Validation: Use mixcr exportContigs to extract FASTA sequences and validate length distribution aligns with expected full-length V(D)J transcript size (~450-500 bp).

Protocol 2: Comparative Analysis of Clustering Refinement Objective: Quantify the impact of --refine-clusters on clonotype resolution.

• Run Assembly in Duplicate: Process the same dataset twice: once with --refine-clusters byQuality and once without.
• Export Clonotypes: For each run: mixcr exportClones -c IGH run123_output.clns clones_IGH.txt.
• Quantitative Comparison: Compare the number of unique clonotypes and the distribution of reads per clonotype (convergence) between the two outputs. Expect a moderate increase in total clonotypes with refinement, primarily in the low-frequency range.

Visualizations

Diagram Title: BCR Contig Assembly Workflow with Key Parameters

Diagram Title: How -OassemblingFeatures Improves Consensus

The Scientist's Toolkit: Research Reagent Solutions

Item	Function in BCR Contig Assembly Research
MiXCR Software Suite	Core analytical platform for immune repertoire sequencing analysis; executes alignment, assembly, and clustering.
High-Quality RNA-Seq Library Prep Kit	Ensures input RNA is converted to sequencing libraries with minimal bias and high molecular integrity, critical for full-length recovery.
Illumina Paired-End Reagent Kits	Provides the raw sequencing data (typically 2x150 bp or longer) required for overlapping and assembling full-length BCR transcripts.
--report Text File	The primary QC document, used to verify pipeline performance and calculate key efficiency metrics for the thesis methodology.
Reference Databases (IMGT)	Curated germline V, D, J gene databases used by MiXCR for accurate alignment and annotation of assembled contigs.
Downstream Analysis Tools (e.g., IgBLAST)	Used post-MiXCR to validate the correctness and functionality of the assembled full-length BCR sequences.

1. Introduction

Within the broader thesis on obtaining full-length BCR (B-cell receptor) sequences for structural immunology and therapeutic antibody discovery, the initial data processing and assembly strategy is paramount. The choice between paired-end (PE) and single-end (SE) sequencing fundamentally influences the accuracy, contiguity, and completeness of the assembled immune receptor repertoires using tools like MiXCR. This application note details the comparative handling of PE and SE data, providing protocols and quantitative comparisons to guide researchers.

2. Quantitative Comparison of PE vs. SE Data for BCR Assembly

The following table summarizes the core performance metrics of PE versus SE data in the context of MiXCR-based BCR contig assembly, based on current literature and benchmark analyses.

Table 1: Performance Metrics for Paired-End vs. Single-End Data in BCR Assembly

Metric	Paired-End Sequencing	Single-End Sequencing	Impact on Full-Length BCR Assembly
Read Length Requirement	2x150 bp is standard; 2x250/300 bp beneficial for full V/J spanning.	≥300 bp (long-read SE) is essential for V-J overlap.	PE: Easier to span full V(D)J region with shorter fragment sizes. SE: Requires significantly longer reads for de novo overlap.
Assembly Accuracy	High. Paired information resolves ambiguous alignments in repetitive or conserved CDR3/V gene regions.	Moderate to Low. Prone to misalignment in conserved regions without mate pair constraints.	Directly impacts the correctness of the final assembled nucleotide sequence.
Contig Continuity	High. Forward and reverse reads can be merged into a single contiguous sequence (contig).	Low. SE reads often cannot be extended into a single contig without a reference.	PE enables true contig assembly; SE often results in partial, gapped alignments.
Error Correction	Inherent. Discrepancies between overlapping regions of R1 and R2 allow for base-call error detection/correction during merging.	Limited. Relies on sequencing depth and consensus calling, less robust than physical mate validation.	Reduces sequencing error propagation into the final assembled clonotype.
Cost & Throughput	Higher cost per sample, but provides more information per cluster.	Lower cost per sample for a given sequencing depth.	Budget vs. data quality trade-off. PE is generally recommended for de novo assembly goals.
Optimal Use Case	De novo assembly of full-length BCRs, discovery of novel alleles, highly diverse repertoires.	Quantification of known clonotypes (when a reference exists), expression profiling (RNA-seq).	For full-length sequence research, PE data is strongly superior.

3. Experimental Protocols

Protocol 3.1: Pre-processing and Merging of Paired-End Reads for MiXCR Objective: To create high-quality, merged contigs from PE reads prior to MiXCR alignment.

• Quality Control: Use FastQC v0.12.1 on raw R1 and R2 FASTQ files.
• Adapter/Quality Trimming: Use Trimmomatic v0.39.

• Read Merging: Use BBMerge (from BBTools suite v38.18) to overlap and merge R1 and R2.

• Input for MiXCR: The merged.fq file is used as primary input. Unmerged reads (unmerged_R1/R2.fq) can be analyzed separately or combined.

Protocol 3.2: Handling Single-End Data for MiXCR Alignment Objective: To prepare long SE reads for optimal alignment in MiXCR.

• Quality Control: Use FastQC v0.12.1 on the raw FASTQ file.
• Adapter/Quality Trimming: Use Trimmomatic v0.39 in SE mode.
  Note: MINLEN is set high to retain only reads with potential to span critical regions.
• Input for MiXCR: The output_SE_trimmed.fq.gz file is used directly. MiXCR will perform local alignment as full overlap is not guaranteed.

Protocol 3.3: MiXCR Analysis Pipeline for Assembled Contigs (PE Merged Data) Objective: To assemble clonotypes from merged PE contigs, maximizing full-length sequence recovery.

• Align and Assemble: Run the standard mixcr analyze command tailored for amplicon data.
  Key Parameters: --contig-assembly is critical for handling pre-merged contigs. CDR3Ext assembler is optimized for full CDR3 extraction.

4. Visualization of Data Handling Workflows

Workflow: PE vs. SE Data Processing for MiXCR

Logic: Contig Assembly Strategy Decision Tree

5. The Scientist's Toolkit: Research Reagent Solutions

Table 2: Essential Materials for BCR Sequencing & Assembly

Item	Function	Example/Note
Total RNA or Genomic DNA Isolation Kit	High-quality, high-molecular-weight nucleic acid extraction from B-cells or tissue.	Qiagen RNeasy Plus Mini Kit (with gDNA eliminator) for RNA; DNeasy Blood & Tissue Kit for DNA.
5' RACE-ready cDNA Synthesis Kit	For RNA inputs, captures the complete 5' end of the BCR transcript, critical for full-length V gene recovery.	SMARTer RACE 5'/3' Kit (Takara Bio).
Multiplex PCR Primers for BCR Loci	Amplifies rearranged V(D)J regions from cDNA or gDNA. Bias-controlled panels are essential.	MIATA-validated primer sets or commercial panels (e.g., iRepertoire).
High-Fidelity DNA Polymerase	Minimizes PCR errors during library amplification to avoid artifactual diversity.	KAPA HiFi HotStart ReadyMix, Q5 High-Fidelity DNA Polymerase.
Dual-Indexed Sequencing Adapters	For sample multiplexing in NGS libraries. Reduces index hopping cross-talk.	Illumina TruSeq Unique Dual Indexes.
MiXCR Software Suite	Core analysis platform for aligning, assembling, and quantifying immune sequences.	Version 4.0+ recommended for advanced contig assembly features.
BBTools Suite	Contains utilities for quality control, trimming, and paired-end read merging.	Essential for Protocol 3.1.
Trimmomatic	Reliable, flexible tool for read trimming and adapter removal.	Standard for pre-processing.

Within the broader thesis research utilizing MiXCR for full-length BCR repertoire sequencing, the assembly of high-quality contigs representing complete V(D)J transcripts is a critical intermediate step. The primary downstream applications of these contigs are two-fold: (1) accurately linking assembled contigs back to their originating clonal families to preserve clone-level resolution, and (2) precisely calling the constant region isotype (e.g., IgG1, IgA2) to infer antibody effector function. These applications are essential for translational research in immunology, autoimmunity, infectious disease, and therapeutic antibody discovery, providing a bridge between sequence data and biological insight.

---

Application Note: Clonal Family Assignment of Contigs

Concept: A single expanded B-cell clone can produce transcripts for multiple isotypes (e.g., IgM, IgG, IgA) through class-switch recombination. During analysis, initial clonotyping is performed on raw reads based on identical V and J genes and CDR3 nucleotide sequence. Assembled contigs must be mapped back to these pre-defined clonal families to maintain the clonal genealogy and calculate clonotype statistics accurately.

Key Quantitative Metrics: The success rate of contig-to-clone linking depends on input data quality and software parameters. The following table summarizes typical performance metrics from a benchmark study using simulated and real BCR-seq data.

Table 1: Performance Metrics for Contig-to-Clone Linking

Metric	Description	Typical Range (High-Quality Data)
Linking Accuracy	Percentage of contigs correctly assigned to their true clonal family.	95% - 99%
Clonal Resolution	Proportion of initial clonotypes successfully recovered by at least one contig.	>85%
Contigs per Clone	Mean number of full-length contigs obtained per clonal family.	1.2 - 3.5
Assignment Failure Rate	Contigs that cannot be linked due to ambiguous or missing CDR3.	<5%

---

Protocol: Linking MiXCR-Assembled Contigs to Clonal Families

Objective: To assign each assembled contig to its correct clonal family as defined by the initial clonotyping analysis.

Materials & Software:

• MiXCR-generated .contigs file (e.g., sample.contigs.clns).
• MiXCR clonotype .txt or .clns file from the initial mixcr analyze command.
• Computing environment with MiXCR (v4.5 or later) installed.

Procedure:

• Data Preparation: Ensure you have both the final contig file (sample.contigs.clns) and the original clonotype table file (sample.clones.txt) from the same MiXCR analysis run.
• Extract Clone IDs: Use the mixcr exportClones command with the -c IGH (for heavy chain) and -readIds parameters on the original clonotype file to generate a mapping of read IDs to their assigned clone ID.

• Cross-Reference Contigs: Each contig in the .contigs.clns file is built from a set of raw read IDs. Parse the contig file to extract these constituent read IDs. Using the mapping from Step 2, identify the clone ID associated with the majority of reads supporting each contig.
• Assignment Rule: Assign the contig to the clonal family (Clone ID) that is represented by >75% of its constituent reads. Contigs with ambiguous support (<75% agreement) should be flagged for manual review.
• Output Generation: Create a final table with columns: Contig_ID, Assigned_Clone_ID, V_gene, J_gene, CDR3_aa, Number_of_Supporting_Reads.

---

Application Note: Isotype Calling from Contigs

Concept: Accurate identification of the constant (C) region gene (e.g., IGHG1, IGHA1) from a full-length contig determines the antibody isotype and subclass, which dictates effector functions like complement activation and Fc receptor binding.

Challenge: Not all sequencing approaches capture the full constant region. Isotype calling relies on the 3' end of the contig aligning uniquely to a specific C gene segment.

Table 2: Isotype Calling Confidence and Implications

Isotype	Key C Gene	*Confidence Score	Primary Biological Implication
IgM	IGHM	High (Full-length)	Primary response, membrane-bound BCR.
IgG1	IGHG1	High	Major serum IgG, strong effector functions.
IgG2	IGHG2	Medium-High	Response to polysaccharide antigens.
IgA1/IgA2	IGHA1/IGHA2	Medium (Due to homology)	Mucosal immunity, dimeric secretion.
IgE	IGHE	High (Low abundance)	Allergy, anti-parasite response.
Ambiguous	Multiple/Partial	Low	Requires manual inspection or Sanger validation.

*Confidence is influenced by read length, reference database completeness, and C region homology.

---

Protocol: High-Confidence Isotype Calling with MiXCR

Objective: To determine the constant region isotype for each assembled heavy-chain contig.

Materials:

• MiXCR-assembled contig file in FASTA or .clns format.
• IMGT or Ensembl reference database of Ig constant region alleles.
• Alignment software (e.g., BLAST, or built-in MiXCR aligner).

Procedure:

• Extract Contig Sequences: Export the nucleotide sequences of all heavy-chain contigs, focusing on the constant region segment.

• Reference Alignment: Align the 3' end of each contig (minimum 150 bp) against a curated database of all human Ig constant region genes (IGHM, IGHD, IGHG1-4, IGHA1-2, IGHE). Use a local alignment tool with high stringency.

• Calling Criteria:
  • High-Confidence Call: A single C gene alignment covering >95% of the reference sequence with >98% nucleotide identity.
  • Subclass Discrimination (e.g., IgG1 vs IgG3): Requires alignment over subclass-specific regions. Use a multiple sequence alignment viewer to check for diagnostic nucleotide positions.
  • Ambiguous Call: If alignment identity is <98% or coverage is split between two C genes (e.g., IGHA1 vs IGHA2), review the alignment manually and consider the contig's quality score.
• Integration: Merge the isotype call for each contig with the clonal family assignment table from Protocol 3. This enables analysis of isotype distribution per clone.

---

Visualization: Workflow for Downstream Contig Analysis

Title: Workflow for Contig Clonal Linking and Isotype Calling

---

The Scientist's Toolkit: Key Reagent Solutions

Table 3: Essential Research Reagents & Materials

Item	Function/Description	Example/Supplier
MiXCR Software Suite	Primary tool for BCR-seq analysis, clonotyping, and contig assembly.	https://mixcr.readthedocs.io
IMGT/GENE-DB	Authoritative reference database for Ig gene alleles (V, D, J, C), essential for accurate alignment.	IMGT (international ImMunoGeneTics)
Curated C Region FASTA	Custom database of all constant region alleles for precise BLAST alignment in isotype calling.	Compiled from IMGT or Ensembl.
High-Fidelity PCR Mix	For validation PCR of specific contigs or isotype switches from cDNA.	ThermoFisher Platinum SuperFi, NEB Q5.
Sanger Sequencing Service	Gold standard for validating ambiguous contig sequences or isotype calls.	In-house capillary sequencer or commercial vendor.
BLAST+ Command Line Tools	For performing local nucleotide alignments against custom C region databases.	NCBI BLAST+ executables.
R/Bioconductor (immunarch)	For statistical analysis and visualization of clonal statistics post-linking.	immunarch R package.
Python/Pandas Environment	For custom parsing of read ID mappings and generating final integrated tables.	Jupyter Notebook with Biopython.

Solving the Puzzle: Troubleshooting Common MiXCR Contig Assembly Challenges

Within the broader thesis on MiXCR contig assembly for full-length BCR repertoire analysis, obtaining complete, high-fidelity contigs is paramount for accurate clonotype assignment, somatic hypermutation analysis, and downstream therapeutic discovery. The persistent issue of low yield, characterized by incomplete or short contigs, directly compromises data interpretability and statistical power. This Application Note systematically details the causes, diagnostic workflows, and optimized protocols to address this challenge, ensuring robust generation of full-length BCR sequences for research and drug development.

Core Causes and Diagnostic Framework

Incomplete contig assembly in MiXCR typically stems from interdependencies between input sample quality, wet-lab protocols, and software parameters. The primary causes are categorized below.

Table 1: Primary Causes of Incomplete/Short Contigs in BCR-Seq

Cause Category	Specific Factor	Impact on Contig Length & Yield	Typical Diagnostic Signature
Input Material	Low RNA Integrity (RIN < 7)	Fragmented cDNA, truncated V/J coverage.	Low mapping rate to FR4/C region; high pre-assembly drop-off.
	Low B-Cell Frequency / Input Count	Insufficient template for overlapping reads.	Low total clonality; high PCR duplicate rate.
Wet-Lab Protocol	Suboptimal 5' RACE Primer / Multiplex PCR Bias	Incomplete V-gene capture.	Systematic dropout of specific V-gene families.
	Overly Strict Size Selection	Exclusion of long amplicons.	Biased distribution toward short CDR3 lengths.
	Inefficient Reverse Transcription	Poor cDNA yield, especially for long transcripts.	Low library complexity; short average insert size.
Sequencing & Data	Short Read Length (e.g., 2x150bp)	Insufficient overlap for full V(D)J assembly.	Contigs ending in CDR3 or early J-gene.
	High PCR Duplication Rate	Artificially inflates read count but not diversity.	Few unique molecular identifiers (UMIs) supporting long contigs.
Software Analysis	Overly Aggressive -O Clustering Parameters	Merging of distinct clonotypes.	Artificially shortened, chimeric consensus.
	Incorrect Species/Alignment Parameters	Misalignment of V and J genes.	Gaps in alignment, low confidence scores.

Experimental Protocols for Diagnosis and Resolution

Protocol 1: Input Material QC and Preparation

Objective: Ensure high-quality, sufficient starting material. Materials: Fresh PBMCs or tissue, TRIzol/RNeasy Kit, Bioanalyzer/TapeStation, human B-cell enrichment kit (e.g., CD19+ magnetic beads). Steps:

• B-Cell Enrichment: Isolate CD19+ B cells from PBMCs using negative or positive selection per manufacturer's protocol. Target >10,000 cells for repertoire analysis.
• RNA Extraction & QC: Extract total RNA using a column-based method optimized for small inputs. Assess RNA Integrity Number (RIN) via Bioanalyzer. Proceed only if RIN ≥ 7.5.
• Quantification: Use Qubit HS RNA assay. Required minimum: 100 ng total RNA from B-cells.

Protocol 2: Optimized Library Prep for Full-Length BCRs

Objective: Maximize capture of complete V(D)J transcripts. Method: 5' RACE (Rapid Amplification of cDNA Ends)-based protocol. Reagents: SmartScribe Reverse Transcriptase, Template Switching Oligo (TSO), UMI-equipped gene-specific primers for Ig constant regions. Steps:

• First-Strand cDNA Synthesis:
  • Mix 100 ng B-cell RNA, 1µM constant region primer (e.g., IgGI reverse), 1µM TSO, and dNTPs.
  • Incubate at 72°C for 3 min, then 42°C for 2 min.
  • Add SmartScribe RT, DTT, and incubate: 90 min at 42°C, then 10 cycles of (50°C for 2 min, 42°C for 2 min). Inactivate at 85°C for 5 min.
• Long-Distance PCR:
  • Amplify cDNA using a high-fidelity polymerase (e.g., Kapa HiFi) with a primer complementary to the TSO and a nested constant region primer.
  • Cycle: 98°C for 45s; [98°C for 15s, 65°C for 30s, 72°C for 3 min] x 25 cycles; 72°C for 5 min. The extended elongation time is critical for full-length amplicons.
• Size Selection: Use a broad size selection (e.g., SPRIselect beads at 0.5x and 0.8x ratios) to retain amplicons from ~400bp to >1000bp. Verify distribution on Bioanalyzer.

Protocol 3: MiXCR Analysis with Yield-Optimized Parameters

Objective: Assemble complete contigs from paired-end sequencing data. Software: MiXCR v4.x. Steps:

• Alignment with Extended Overlap:

• Export Clonotype Report: Generate detailed report to assess contig completeness.

• Diagnostic Filtering: Inspect the targetSequences column for frequent early stop codons or alignment gaps. Filter for nSeqFR1...nSeqFR4 completeness.

The Scientist's Toolkit: Research Reagent Solutions

Table 2: Essential Reagents for High-Yield Full-Length BCR Sequencing

Item	Function & Rationale	Example Product
High-RIN RNA Isolation Kit	Preserves full-length mRNA; critical for assembling contigs spanning leader sequences.	Qiagen RNeasy Micro Kit
UMI-Compatible RT Enzyme	Enables accurate deduplication and consensus building, distinguishing true long contigs from PCR artifacts.	Takara Bio SmartScribe Reverse Transcriptase
Template Switching Oligo (TSO)	Captures the 5' end of transcripts during RT, ensuring complete V-gene inclusion in 5' RACE.	SeqAmp TSO
Long-Amp High-Fidelity PCR Mix	Faithfully amplifies long (>1.5kb) V(D)J amplicons with low error rates.	Kapa HiFi HotStart ReadyMix
Broad-Range Size Selection Beads	Recovers the full distribution of BCR amplicons without bias against long fragments.	Beckman Coulter SPRIselect
B-Cell Enrichment Kit	Increases the target template frequency, improving library complexity and contig support.	Miltenyi Biotec CD19+ MicroBeads
Bioanalyzer High Sensitivity DNA Kit	Accurately profiles library fragment length distribution pre-sequencing.	Agilent High Sensitivity DNA Kit

Diagnostic and Optimization Workflows

Diagram 1: Root Cause Diagnosis and Resolution Workflow

Diagram 2: Optimized Wet-Lab to Analysis Pipeline

Addressing low yield in MiXCR contig assembly requires a systematic, multi-factorial approach. By rigorously applying the diagnostic framework and optimized protocols outlined herein—focusing on input quality, 5' RACE fidelity, and software parameter tuning—researchers can reliably obtain complete, full-length BCR sequences. This robustness is foundational for advancing theses in immune repertoire analysis and accelerating the discovery of therapeutic antibodies.

In the context of MiXCR-based contig assembly for full-length B-cell receptor (BCR) repertoire research, accurate sequence reconstruction is paramount. A significant challenge arises from two primary sources of ambiguity: sequencing errors introduced by next-generation sequencing (NGS) platforms and PCR duplicates generated during library amplification. This Application Note details protocols and analytical strategies to distinguish true biological variation from these technical artifacts, ensuring high-fidelity data for downstream analysis in immunology and therapeutic antibody discovery.

High-throughput BCR sequencing enables the deconvolution of adaptive immune responses. The MiXCR software suite is a powerful tool for assembling full-length clonotype sequences from raw reads. However, its accuracy is contingent on the quality of input data. Sequencing errors can create spurious novel clonotypes, while undetected PCR duplicates can inflate the perceived frequency of specific sequences. Resolving this ambiguity is critical for accurate clonal diversity, lineage tracing, and selection of candidates for drug development.

Table 1: Impact of Error/Duplicate Removal on Typical BCR-seq Data

Metric	Raw Data	After UMI-Based Deduplication	After Error Correction	Combined Processing
Total Reads	10,000,000	10,000,000	10,000,000	10,000,000
Unique Molecular Identifiers (UMIs)	500,000	500,000	N/A	500,000
Inferred Clonotypes	~50,000	~15,000	~18,000	~12,000
Mean Reads per Clonotype	200	667	556	833
Estimated False Positive Rate*	15-25%	3-5%	5-8%	<2%

*Estimated percentage of clonotypes arising purely from technical artifacts.

Table 2: Common NGS Error Profiles by Platform

Sequencing Platform	Predominant Error Type	Typical Error Rate (Per Base)	Effective Correction Method
Illumina NovaSeq	Substitution (AT>GC)	0.1-0.2%	k-mer alignment, consensus building
PacBio HiFi	Insertion/Deletion	~0.01% (after circular consensus)	Long-read self-correction
Oxford Nanopore	Insertion/Deletion	2-5% (raw); <0.1% (duplex)	Adaptive sampling, duplex reads

Detailed Protocols

Protocol 1: Unique Molecular Identifier (UMI) Integration and PCR Duplicate Removal

Objective: To tag each original RNA molecule with a random UMI during cDNA synthesis, enabling precise collapse of PCR duplicates.

Materials: See "The Scientist's Toolkit" below. Procedure:

• First-Strand cDNA Synthesis: Use a reverse transcription primer containing a random 8-12 nt UMI and a sample barcode.
• PCR Amplification: Amplify the cDNA using gene-specific primers for the constant region of the BCR. The number of PCR cycles should be minimized (typically 12-18 cycles).
• Library Preparation & Sequencing: Prepare the NGS library following standard protocols. Sequence with a paired-end approach, ensuring the read 1 (R1) captures the UMI.
• Bioinformatic Processing with MiXCR:
  • The --umi flag directs MiXCR to extract UMIs from the read tags.
  • MiXCR aligns reads, groups them by UMI and clonotype, and builds a consensus sequence for each UMI group before clonotype assembly, effectively removing PCR duplicates.

Protocol 2: Sequencing Error Correction via Molecular Consensus

Objective: To correct for sequencing errors by comparing multiple reads derived from the same original molecule (identified by UMI).

Procedure:

• Follow Protocol 1 steps 1-3 to generate UMI-tagged sequencing data.
• Consensus Building within MiXCR: The analyze shotgun command with --umi automatically performs this.
  • For each UMI group and gene locus (V, J, C), a multiple sequence alignment (MSA) of reads is performed.
  • A consensus nucleotide sequence is generated using a quality-aware algorithm (e.g., majority vote or probabilistic modeling). Positions with discordant bases are corrected to the consensus supported by high-quality reads.
• Validation: Post-analysis, inspect the sample_output.alignmentsReports.txt file. Key metrics include Average number of reads per UMI and Effective sequencing depth. A high average (>5-10) enables robust error correction.

Protocol 3: Hybrid Approach for Ultra-Deep Repertoire Sequencing

Objective: For deep repertoire studies where even UMI-based errors are possible, implement a two-step correction.

Procedure:

• Primary Correction: Execute Protocol 2 using MiXCR.
• Secondary Clustering-Based Correction: Use MiXCR's assembleContigs command on the primary output to perform fine-tuning.
  • This step performs additional clustering of similar consensus sequences, merging those that likely diverged due to residual errors in UMI regions or early PCR mutations.

Diagrams

Title: Workflow for UMI-Based Deduplication & Error Correction

Title: Molecular Consensus Corrects Sequencing Errors

The Scientist's Toolkit

Table 3: Essential Research Reagent Solutions for High-Fidelity BCR-seq

Item	Function in Protocol	Key Consideration
UMI-equipped RT Primers	Tags each mRNA molecule with a unique random sequence for digital tracking.	Use sufficient complexity (e.g., 10^6 unique UMIs) to avoid collisions.
High-Fidelity DNA Polymerase (e.g., Q5, KAPA HiFi)	Amplifies cDNA with minimal PCR-induced errors during library prep.	Essential for maintaining sequence fidelity before sequencing.
Dual-Indexed Sequencing Adapters	Allows multiplexing of samples and reduces index hopping artifacts.	Crucial for large-scale studies involving many patient samples.
SPRIselect Beads (Beckman Coulter)	For precise size selection and cleanup of libraries, removing primer dimers.	Affects the insert size distribution and on-target rate.
MiXCR Software Suite	Integrated pipeline for alignment, UMI handling, error correction, and clonotype assembly.	Regular updates are needed to support new NGS platforms and immune reference loci.
Reference Databases (e.g., IMGT)	Curated germline V, D, J gene alleles for accurate alignment and mutation analysis.	Species- and allele-specific databases are critical for correct assignment.

1. Introduction Within the broader thesis on advancing MiXCR contig assembly for full-length BCR sequence research, scaling analysis to cohort-sized datasets (e.g., >1000 samples) presents significant computational bottlenecks. This document provides application notes and detailed protocols for optimizing memory footprint and runtime without compromising data fidelity, enabling high-throughput immune repertoire profiling for translational research and drug discovery.

2. Quantitative Benchmarking of Optimization Strategies The following table summarizes performance metrics for standard vs. optimized MiXCR workflows on a dataset of 1,000 bulk RNA-seq samples (approx. 100,000 reads/sample targeting BCRs).

Table 1: Performance Comparison of Standard vs. Optimized MiXCR Workflow

Processing Stage	Standard Workflow	Optimized Workflow	Relative Improvement
Alignment (kAligner2)	42 hours, 128 GB RAM	28 hours, 64 GB RAM	33% faster, 50% less RAM
Contig Assembly	18 hours, 96 GB RAM	12 hours, 48 GB RAM	33% faster, 50% less RAM
Export (Clones)	6 hours, 32 GB RAM	2 hours, 16 GB RAM	66% faster, 50% less RAM
Total Pipeline Runtime	66 hours	42 hours	36% faster overall
Peak Disk I/O	~2 TB (intermediate files)	~800 GB (streamed compression)	60% reduction

3. Detailed Experimental Protocols

Protocol 3.1: Memory-Efficient Batch Processing for Large Cohorts Objective: To process thousands of samples with capped memory usage.

• Sample Batching: Group samples into batches of 50-100 based on estimated library size. Use a sample manifest file to automate.
• Java Virtual Machine (JVM) Tuning: For each MiXCR step, set JVM arguments to limit memory and enable garbage collection optimization.
  • Command: java -Xms64G -Xmx64G -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -jar mixcr.jar ...
• Parallelized Execution: Use a job scheduler (e.g., Nextflow, Snakemake) to process batches in parallel across a cluster. Configure to not exceed available aggregate memory.
• Logging: Redirect stdout/stderr to log files per batch for debugging runtime or memory errors.

Protocol 3.2: Runtime-Optimized Contig Assembly Parameters Objective: To accelerate the most computationally intensive stage.

• Targeted Alignment: Use --library immuneRNA flag to pre-select relevant aligners and parameters for RNA-seq data.
• Region-Specific Assembly: Restrict detailed assembly to CDR3 and variable regions.
  • Command: mixcr assembleContigs --assemble-regions VTranscriptome,CDR3
• Thread Utilization: Explicitly set the number of threads for parallelizable stages (e.g., -nThreads 16 for alignment).
• Skip Non-Essential Steps: For clone quantification only, use --report index.html sparingly and avoid generating verbose debug reports unless necessary.

Protocol 3.3: I/O and Storage Optimization Objective: To reduce disk footprint and I/O wait times.

• Pipeline Chaining: Use MiXCR's --write-alignments and --write-assemblies flags to pipe intermediate results directly between steps without writing large temporary files to disk.
  • Command: mixcr align ... --write-alignments | mixcr assemble ...
• Compressed Intermediate Files: When disk writing is unavoidable, use .gz compression for all intermediate .vdjca and .clns files (--compress-intermediate-files true).
• Final Export Filtering: Export only required data fields to minimize final file size.
  • Command: mixcr exportClones -c IGH -o -t -count -fraction -sequence -aaSeqCDR3 clones.txt

4. Visualization of Optimized Workflow

(Diagram Title: Standard vs Optimized MiXCR Pipeline Flow)

5. The Scientist's Toolkit: Key Research Reagent Solutions

Table 2: Essential Computational Tools & Resources

Item	Function / Role in Optimization
MiXCR (v4.x+)	Core analysis software. Newer versions include critical performance enhancements for assembly.
Nextflow / Snakemake	Workflow managers enabling scalable, reproducible parallel execution across compute clusters.
Java Runtime (v11+)	Required for MiXCR. G1GC garbage collector (v9+) is essential for managing large heap memory.
High-Performance Cluster	Infrastructure with high RAM nodes (>64GB) and fast parallel storage (SSD/NVMe) for I/O bottlenecks.
SAMtools / pigz	Utilities for handling and compressing intermediate sequence data efficiently.
R / tidyverse / immunarch	Downstream analysis ecosystem for parsing, analyzing, and visualizing optimized output data.

The assembly of full-length B-cell receptor (BCR) sequences from bulk or single-cell RNA-seq data is critical for understanding adaptive immune responses in autoimmunity, infectious disease, and cancer immunotherapy. MiXCR's contig assembly module is a cornerstone of this analysis, reconstructing complete V(D)J transcripts from short-read data. The fidelity of this reconstruction hinges on the precise tuning of three interdependent parameters: Overlap, Quality (Q) score, and Clustering thresholds. This guide, framed within a broader thesis on robust BCR repertoire characterization, provides detailed application notes and protocols for researchers to systematically optimize these parameters, thereby maximizing assembly completeness and accuracy for downstream functional analysis and drug discovery.

Core Parameter Definitions & Quantitative Benchmarks

The following parameters directly control the stringency and sensitivity of the contig assembly step in MiXCR (assembleContigs command).

Table 1: Core Tuning Parameters for MiXCR assembleContigs

Parameter	Default Value	Function	Impact of Increasing Value
--overlap	12	Minimum nucleotide overlap required to merge two sequence alignments.	Increases stringency; reduces false mergers but may fragment true contigs.
-q, --quality	0	Minimum Phred-quality score for each nucleotide in the overlap region.	Increases confidence in overlap sequence; reduces errors from low-quality bases.
-c, --clustering	DISTANCE	Clustering algorithm for grouping similar sequences. DISTANCE (default) uses sequence similarity.	N/A (Algorithm choice).
--cluster-distance	1 (for -c DISTANCE)	Maximum allowed mismatches in the overlap region during clustering.	Increases grouping tolerance; can merge more diverse but related sequences.

Table 2: Quantitative Outcomes from Parameter Tuning (Illustrative Data from Literature & Benchmarks) Data synthesized from recent studies on PBMC RNA-seq (10x Genomics) processed with MiXCR v4.4.

Parameter Set (Overlap/Q/Cluster-Dist)	Mean Contigs per Cell	% Full-Length V(D)J	% Reads Assembled	Computational Time (Relative)
Default (12/0/1)	1.8	85%	92%	1.0x
High Stringency (20/20/0)	1.2	96%	78%	1.3x
High Sensitivity (8/0/3)	2.5	74%	97%	1.5x
Balanced (15/10/1)	1.7	91%	90%	1.1x

Detailed Experimental Protocols for Parameter Optimization

Protocol 3.1: Systematic Grid Search for Parameter Calibration

Objective: To empirically determine the optimal parameter combination for a specific experimental dataset (e.g., single-cell BCR from tumor infiltrating lymphocytes).

Materials: MiXCR-installed HPC cluster, raw FASTQ files, reference genome (GRCh38), validated BCR clones (for ground truth validation).

Procedure:

• Base Alignment: Run mixcr analyze with standard rna-seq pipeline up to the assembleContigs step.
• Define Parameter Ranges:
  • Overlap: 8, 12, 16, 20
  • Quality (Q): 0, 10, 20, 30
  • Cluster-distance: 0, 1, 2, 3
• Grid Execution: For each combination (e.g., --overlap 16 -q 20 --cluster-distance 1), execute:

• Metric Collection: For each output, extract:
  • Total number of assembled clonotypes.
  • Mean contig length.
  • Export sequences (mixcr exportClones) and align to ground truth references using blastn.
• Optimal Selection: Plot metrics (see Diagram 1). The optimal set maximizes both % Full-Length V(D)J and % Reads Assembled for your specific data quality.

Protocol 3.2: Validation Using Spiked-in Control BCR Sequences

Objective: To assess assembly accuracy and error rate using known control sequences.

Materials: Synthetic BCR RNA controls (e.g., from SpikeSeg), added to sample prior to library prep.

Procedure:

• Spike-in: Introduce control RNA at a known molar ratio during sample preparation.
• Dual Analysis: Process the entire dataset with two parameter sets: Default and Tuned.
• Recovery Analysis: Identify control sequences in the final clonotype tables. Calculate:
  • Recovery Rate: (# of control clones found) / (# of controls spiked-in).
  • Sequence Accuracy: % identity of assembled control contigs to the known reference.
• Error Estimation: Analyze mutations in the assembled control sequences outside the expected somatic hypermutation pattern.

Visualization of Workflows and Relationships

Diagram 1: MiXCR Contig Assembly Workflow & Parameter Intervention Points.

Diagram 2: The Sensitivity-Accuracy Trade-off in Threshold Tuning.

The Scientist's Toolkit: Research Reagent Solutions

Table 3: Essential Materials for BCR Contig Assembly & Validation

Item	Vendor Examples	Function in Protocol
MiXCR Software	MILAB	Core analysis suite for adaptive immune repertoire sequencing.
Spike-in Control BCR RNA	e.g., Arcitecta SpikeSeg	Synthetic, known BCR sequences added to lysate to quantify recovery and error rates.
Reference Genome (GRCh38)	GENCODE, Ensembl	Reference for initial read alignment and V(D)J gene assignment.
Validated Clonal Cell Lines	ATCC, academic repositories	Provide ground truth BCR sequences for method benchmarking.
High-Quality RNA Extraction Kit	Qiagen, Thermo Fisher	Ensures input RNA integrity, critical for full-length assembly.
10x Genomics 5' Immune Profiling Kit	10x Genomics	Common single-cell V(D)J library prep system generating input for MiXCR.
BLAST+ Suite	NCBI	Used for aligning assembled contigs to control or reference sequences.
High-Performance Computing (HPC) Cluster	Local/institutional	Necessary for running extensive grid searches over parameter space.

Within the context of advancing MiXCR-based contig assembly for full-length B-cell receptor (BCR) repertoire sequencing, optimizing sample throughput and data consistency is paramount. Effective sample multiplexing and batch processing are critical for reducing per-sample costs, minimizing technical variability, and enhancing the statistical power of repertoire studies in immunology and therapeutic antibody discovery. This document outlines established and emerging best practices, framed as application notes and protocols.

Principles of Sample Multiplexing for BCR-Seq

Multiplexing involves pooling uniquely indexed samples prior to sequencing. For full-length BCR analysis, this must be designed to preserve chain pairing information and minimize index hopping or cross-talk.

Key Consideration Table:

Multiplexing Factor	Recommended Range for BCR	Primary Benefit	Associated Risk
Number of Samples per Lane (NovaSeq)	8-24	High throughput, cost reduction	Reduced sequencing depth per sample
Unique Dual Index (UDI) Length	8+8 bp or 10+10 bp	Drastic reduction of index hopping	Increased read length consumption
Cell/Input Number per Sample	5,000-100,000 cells	Balances diversity capture and complexity	Overloading leads to PCR dominance
PCR Cycle Number (cDNA Amplification)	18-22 cycles	Minimizes PCR artifacts and biases	Lower yield if input is insufficient

Protocol: Multiplexed Library Preparation for MiXCR

Objective: To generate individually indexed, full-length BCR amplicon libraries from multiple human PBMC samples for pooled sequencing and subsequent contig assembly with MiXCR.

Materials:

• Starting Material: PBMCs (cryopreserved), viability >90%.
• Key Reagent Solutions: See "Scientist's Toolkit" below.
• Equipment: 96-well magnetic separation stand, thermocycler with 96-well block, Qubit fluorometer, Agilent TapeStation.

Detailed Workflow:

• Cell Lysis and RNA Isolation: Isolate total RNA from up to 1e5 cells per sample using a magnetic bead-based 96-well kit. Elute in 30 µL.
• Reverse Transcription (RT): Perform RT using a gene-specific primer targeting the Ig constant region with template-switching oligonucleotide (TSO) technology to add a universal 5' adapter. Reaction: 10 µL RNA, 2 µL RT primer (10 µM), 1 µL TSO (100 µM), 4 µL 5x buffer, 2 µL enzyme mix, 1 µL RNase inhibitor. Program: 42°C for 90 min, 70°C for 5 min.
• cDNA Amplification: Amplify the cDNA using a primer complementary to the TSO sequence. PCR: 20 µL cDNA, 25 µL 2x HiFi master mix, 2.5 µL TSO-PCR primer (10 µM). Cycle: 98°C 30s; [98°C 10s, 65°C 30s, 72°C 3 min] x 18 cycles; 72°C 5 min.
• Sample Indexing (Barcoding): Perform a second, limited-cycle PCR to add unique dual indices (UDIs) and full Illumina adapter sequences. Use a commercially available 96-well UDI plate. PCR: 5 µL purified cDNA, 25 µL 2x HiFi master mix, 2.5 µL forward UDI, 2.5 µL reverse UDI. Cycle: 98°C 30s; [98°C 10s, 65°C 30s, 72°C 1 min] x 8 cycles; 72°C 5 min.
• Library Pooling & Clean-up: Quantify each indexed library by Qubit. Pool equimolar amounts of all samples (e.g., 50 ng each). Purify the pooled library using a 0.8x:1x double-sided SPRI bead clean-up.
• Quality Control & Sequencing: Assess pool size distribution via TapeStation (expected peak ~850-950 bp for full-length BCR). Sequence on an Illumina platform (e.g., NovaSeq 6000, S4 flow cell, 2x250 bp) targeting a minimum of 50,000 paired-end reads per cell.

Optimizing Batch Processing for Contig Assembly

Batch effects can arise from day-to-day variations in reagent lots, personnel, or instrument performance. A standardized batch design is crucial.

Experimental Design Table:

Batch Variable	Recommended Control Practice	Purpose
Reagent Lots	Use a single lot for an entire study; aliquot bulk lots.	Minimize inter-batch variability.
Positive Control	Include a commercial clonal cell line or synthetic RNA spike-in in each batch.	Monitor assay sensitivity and consistency.
Sample Randomization	Distribute biological groups (e.g., healthy vs. disease) across multiple library prep batches.	Decouple technical batch effects from biological signals.
MiXCR Processing	Run all demultiplexed FASTQ files from one study through the same version of MiXCR in a single batch job.	Ensure consistent software parameters and reference database use.

Protocol: Batch-Aligned MiXCR Contig Assembly.

• Demultiplexing: Use bcl2fastq or Illumina DRAGEN with strict mismatch settings (--barcode-mismatches 0).
• Batch Script for MiXCR: Execute the following command array for all samples to ensure uniform processing.

• Post-Processing Quality Batch Check: Generate a summary table of key metrics (total clonotypes, reads assembled) for all samples in the batch to identify outliers.

Visualization of Workflows

Title: Multiplexed BCR-Seq to MiXCR Batch Analysis Workflow

Title: Batch Effect Sources and Mitigation Strategies in BCR-Seq

The Scientist's Toolkit: Research Reagent Solutions

Item	Function & Importance
Template Switching Reverse Transcriptase (e.g., SmartScribe)	Ensures high-efficiency 5' adapter addition during cDNA synthesis, critical for capturing full-length V(D)J regions.
Unique Dual Index (UDI) Kits (8x8, 96-plex)	Uniquely tags each sample with two indices, virtually eliminating index-hopping artifacts in multiplexed runs.
SPRIselect Magnetic Beads	For size-selective clean-up and library normalization; consistency is key for reproducible yield across batches.
Full-Length BCR Control RNA (e.g., from clonal cell lines)	Serves as a positive control to monitor assay sensitivity, UMI duplication rate, and V/J gene recovery accuracy.
High-Fidelity PCR Master Mix	Minimizes PCR errors during library amplification, preserving true clonotype sequences and diversity.
Automated Liquid Handler (96-well)	Enables high-precision, reproducible reagent dispensing across large sample batches, reducing operator-induced variability.

Benchmarking Accuracy: How MiXCR Contig Assembly Stacks Up Against Alternatives

Within the context of a broader thesis on MiXCR contig assembly for full-length B-cell receptor (BCR) sequences, rigorous assessment of output contigs is paramount. The reliability of downstream analyses in immunogenetics, clonal tracking, and therapeutic antibody discovery hinges on the quality of these assembled sequences. This document provides detailed application notes and protocols for evaluating three core metrics: completeness, accuracy, and chimerism, tailored for researchers and drug development professionals.

Core Performance Metrics: Definitions and Benchmarks

The following table summarizes the key performance metrics, their definitions, ideal benchmarks, and methods of assessment.

Table 1: Core Performance Metrics for Assembled BCR Contigs

Metric	Definition	Ideal Benchmark	Primary Assessment Method
Completeness	The proportion of the full-length reference sequence (V(D)J) captured by the contig.	≥ 98% coverage of the V(D)J region.	Alignment to reference germline databases (e.g., IMGT).
Accuracy	The per-base correctness of the assembled contig sequence.	Per-base error rate < 0.1% (Q30 equivalent).	Comparison to high-fidelity control sequences or synthetic spike-ins.
Chimerism	The rate of artifactual joins between reads from different biological molecules.	< 0.5% of assembled contigs.	Analysis of non-overlapping read pairs or unique molecular identifiers (UMIs) spanning junctions.

Detailed Experimental Protocols

Protocol: Assessing Contig Completeness via Reference Alignment

Objective: To determine the percentage coverage of the V, D, and J germline segments for each assembled contig. Materials:

• Assembled BCR contigs in FASTA format.
• Reference germline databases (IMGT, VDJserver references).
• Alignment software (MiXCR exportAlignments, IgBLAST, or IMGT/HighV-QUEST). Procedure:

• Prepare References: Download the latest IMGT reference FASTA files for human or mouse Ig V, D, and J genes.
• Execute Alignment: For MiXCR-generated contigs, use the command: mixcr exportAlignments --verbose [input.contigs.vdjca] [output.alignments.txt] This outputs a detailed table with alignment coordinates.
• Calculate Coverage: For each contig, compute coverage per segment: Coverage_V = (Aligned V length) / (Full reference V length) * 100% Repeat for D and J segments. Overall V(D)J completeness is the weighted average.
• Data Aggregation: Summarize the percentage of contigs achieving ≥98%, 95-98%, and <95% completeness in a table.

Protocol: Quantifying Accuracy Using Synthetic Spike-Ins

Objective: To empirically measure the per-base error rate of the assembly pipeline. Materials:

• Synthetic BCR RNA control (e.g., SeraCare Immune Repertoire Sequins).
• Identical wet-lab RNA-Seq library preparation and MiXCR analysis pipeline. Procedure:

• Spike-In Experiment: Co-extract and sequence your sample RNA alongside a known concentration of synthetic BCR control RNA.
• Dedicated Analysis: Process the sequencing data for the control reads separately through your standard MiXCR assembly pipeline (mixcr analyze amplicon...).
• Truth Comparison: Align the resulting assembled contigs to the known reference sequences of the spike-ins using a stringent aligner (e.g., BLASTn).
• Error Rate Calculation:
  • Identify all mismatches and indels.
  • Compute: Per-Base Error Rate = (Total # of errors) / (Total # of aligned bases) * 100%.
  • Report error rates stratified by genomic region (V, CDR3, J).

Protocol: Detecting Chimeras with UMI Analysis

Objective: To identify and quantify contigs formed from non-overlapping UMI groups. Materials:

• Paired-end sequencing data with incorporated UMIs.
• UMI-aware preprocessing tools (UMI-tools, pRESTO).
• MiXCR with --add-step assembleContigsWithMerger or custom post-assembly script. Procedure:

• UMI Clustering: Before assembly, group reads by their source molecule using UMI-tools: umi_tools group --extract-umi-method=read_id -I [input.bam] --output-bam -S [grouped.bam]
• Standard Assembly: Assemble contigs from the UMI-grouped BAM file using MiXCR.
• Chimera Detection: For each assembled contig, trace back its constituent reads and their UMIs.
  • A non-chimeric contig is formed from reads belonging to a single UMI group (one biological molecule).
  • A putative chimera is identified if the contig is supported by reads from two or more distinct UMI groups that do not overlap in their original genomic position.
• Calculation: Report: Chimerism Rate = (# of putative chimeric contigs) / (Total # of assembled contigs) * 100%.

Visualization of Workflows

Title: Contig Quality Assessment Workflow

The Scientist's Toolkit: Research Reagent Solutions

Table 2: Essential Materials for Performance Validation Experiments

Item	Function in Validation	Example Product/Source
Synthetic Immune Repertoire Controls	Provides known sequences for benchmarking accuracy, sensitivity, and quantitative accuracy.	SeraCare Immune Repertoire Sequins; ARCTIC-SH Immune Sequencing Standards.
UMI Adapter Kits	Incorporates unique molecular identifiers into cDNA libraries to track original molecules, enabling chimerism detection and error correction.	Illumina TruSeq Unique Dual Indexes; NEBNext Unique Dual Index UMI Adaptors.
High-Fidelity PCR Mix	Minimizes PCR errors during library amplification, reducing noise for accuracy assessment.	Q5 High-Fidelity DNA Polymerase (NEB); KAPA HiFi HotStart ReadyMix.
Reference Germline Databases	Gold-standard references for aligning contigs to assess completeness and correct gene assignment.	IMGT/GENE-DB; VDJserver Reference Repositories.
Bioinformatics Pipelines	Software specifically designed for immune repertoire analysis with built-in QC metrics.	MiXCR; pRESTO; Immcantation framework.

Application Notes: Framework and Quantitative Analysis

This analysis compares four principal tools for B-cell receptor (BCR) repertoire analysis, contextualized within a thesis investigating MiXCR's performance in full-length, single-cell contig assembly for drug discovery and immunology research.

Table 1: Core Feature and Performance Comparison

Tool	Primary Function	Alignment Algorithm	Input Flexibility	Single-Cell Optimized	Integration & Downstream Analysis	Reported Speed (vs. Others)
MiXCR	End-to-end repertoire analysis	k-mer + aligners (OLC)	FASTQ, BAM, SRA	Yes (handles UMI)	High (built-in QC, export to VDJtools)	10-100x faster
IMGT/HighV-QUEST	Standardized annotation	Dynamic programming	FASTA/Sequence only	No (bulk)	Limited (manual upload/download)	Baseline (1x)
IgBLAST	Local alignment & annotation	BLAST-based local align.	FASTA, FASTQ	Partial	Medium (custom parsing needed)	~5-10x faster than IMGT
VDJtools	Post-processing & stats	Not an aligner (uses others)	Output of MiXCR, IgBLAST	Yes (via input)	Highest (visualization, diversity)	N/A (post-processor)

Table 2: Accuracy & Completeness Metrics for Full-Length Assembly

Metric	MiXCR	IMGT/HighV-QUEST	IgBLAST	VDJtools (on MiXCR data)
V/Gene Identification Accuracy	>99% (per published benchmarks)	Gold standard (~99.5%)	~98-99%	Depends on input
Full-Length Contig Recovery	High (leverages OLC)	Moderate (requires pre-assembly)	Low (segment-focused)	Enhances analysis
UMI Deduplication Efficiency	Integrated, >95%	Not Available	Not Available	Can analyze UMI counts
CDR3 Length Recovery Accuracy	98.7%	99.0%	98.5%	99.0% (validated)
Error Correction	Built-in (UMI-based)	Limited	No	Statistical error modeling

---

Experimental Protocols

Protocol 1: End-to-End BCR Repertoire Analysis with MiXCR for Single-Cell Data Objective: Process raw paired-end scRNA-seq data with UMIs to assembled, annotated, and quantified BCR contigs.

• Sample & Software: 10x Genomics Chromium V(D)J libraries. Install MiXCR (v4.6.0+), Java 11+.
• Data Import: mixcr import --save-description --library immune-smart-tag sample_R1.fastq.gz sample_R2.fastq.gz raw_reads.vdjca
• Alignment & Assembly: mixcr assemble --threads 16 --save-reads --report report.txt raw_reads.vdjca aligned.assemble.vdjca
• UMI Deduplication: mixcr assembleContigs --threads 16 aligned.assemble.vdjca final_contigs.clns
• Export Results: mixcr exportClones --chains IG --contig-assembly final_contigs.clns clones.tsv
• Downstream Analysis: Use VDJtools: vdjtools -c -p -i mixcr clones.tsv .

Protocol 2: Benchmarking Alignment Accuracy Against IMGT Objective: Validate MiXCR and IgBLAST V-gene calls using IMGT/HighV-QUEST as reference.

• Generate Gold Standard: Extract 1000 random in-frame sequences from MiXCR output. Submit to IMGT/HighV-QUEST via web interface. Download detailed annotation (.txt).
• Process with Tools: Run the same 1000 FASTA sequences through MiXCR (mixcr analyze amplicon) and IgBLAST (local install, with germline database imgt_202441).
• Parse and Compare: Use custom Python script to extract V-gene assignments from each tool's output.
• Calculate Concordance: Compute pairwise agreement percentages. Discrepancies are manually reviewed via IMGT domain annotation.

Protocol 3: Full-Length Contig Assembly from Bulk RNA-Seq Objective: Reconstruct complete BCR transcripts from bulk B-cell RNA-seq data.

• Data Preprocessing: Trim adapters (Trim Galore!). Retain reads aligning to immunoglobulin loci (STAR aligner with Ig-index).
• MiXCR Pipeline: mixcr analyze rnaseq-bcr-full-length --starting-material rna --force-overwrite input_R1.fq input_R2.fq output/
• IgBLAST Alternative: Assemble reads de novo (Trinity, rnaSPAdes). Filter assemblies for Ig domains. Annotate resulting contigs via IgBLAST command line.
• Evaluation: Compare contig length, presence of complete V(D)J-C region, and frame consistency between tools.

---

Visualizations

Title: MiXCR & VDJtools Integrated Workflow

Title: Tool Input and Analysis Pathways

---

The Scientist's Toolkit: Key Research Reagent Solutions

Item / Solution	Function in BCR Seq Research
10x Genomics Chromium Next GEM Single Cell V(D)J Reagent Kits	Provides linked-read, UMI-tagged libraries for simultaneous 5' gene expression and paired V(D)J sequence recovery from single cells.
SMARTer TCR/BCR Profiling Kits (Takara Bio)	Enables full-length BCR transcript amplification from bulk or sorted B cells for comprehensive repertoire analysis without single-cell partitioning.
IMGT Reference Directories (e.g., imgt_202441)	Curated germline gene database essential for accurate V(D)J gene assignment and mutation analysis by all alignment tools.
Spike-in RNA Controls (e.g., ERCC)	Used to assess sequencing depth sensitivity and quantitative accuracy in bulk repertoire sequencing experiments.
Cell Ranger (10x Genomics) & MiXCR	Commercial and open-source software pipelines specifically designed to process raw sequencing data into annotated contigs and clonal tables.
VDJtools Standardized Output Formats	Enables interoperability between different alignment tools (MiXCR, IgBLAST) for consistent downstream statistical and graphical analysis.

This application note is framed within a broader thesis investigating the use of MiXCR software for assembling high-fidelity, full-length B-cell receptor (BCR) sequences from bulk or single-cell RNA sequencing data. A primary challenge in such repertoire analysis is determining the biological and functional relevance of computationally assembled BCR clonotypes. Validation through correlation with direct functional assays is therefore paramount to distinguish truly significant, antigen-responsive B-cell clones from background noise. This document outlines protocols and strategies to bridge high-throughput sequencing data with experimental immunology.

Core Validation Strategy: Linking Sequence to Function

The validation workflow establishes a pipeline from MiXCR-derived contigs to measurable biological activity. The central hypothesis is that BCR sequences from expanded, putatively antigen-driven clones will demonstrate specific binding and/or functional responses upon re-expression.

Diagram Title: Validation Pipeline from MiXCR Contigs to Functional Assays

Key Experimental Protocols

Protocol 3.1: From MiXCR Output to Recombinant Antibody Expression

Objective: Convert in silico assembled BCR sequences into recombinant monoclonal antibodies (mAbs) for testing.

Materials: See Scientist's Toolkit (Section 5).

Procedure:

• Sequence Extraction: Export the top-ranked full-length heavy-chain (VH) and light-chain (VL) variable region sequences from MiXCR in FASTA format. Criteria for ranking include: high clonal frequency, presence of somatic hypermutation (SHM), and successful full-length assembly.
• Expression Vector Cloning: Design primers incorporating restriction sites compatible with your chosen IgG expression vector (e.g., pTT5 for HEK293 systems). For scFv/Fab formats, design appropriate linker sequences.
• Gene Synthesis & Cloning: Synthesize the VH and VL gene blocks. Perform restriction enzyme digestion and ligation into the linearized vector. Alternatively, use Gibson assembly or Golden Gate cloning for seamless integration.
• Transient Transfection: Co-transfect HEK293F or Expi293 cells with heavy- and light-chain plasmid DNA at a 1:1 ratio using PEI or commercial transfection reagents.
• Purification: Harvest cell culture supernatant at 5-7 days post-transfection. Purify IgG using Protein A or Protein G affinity chromatography. Dialyze into PBS, filter sterilize (0.22 µm), and quantify by spectrophotometry (A280).

Protocol 3.2: Binding Affinity Assessment via Surface Plasmon Resonance (SPR)

Objective: Quantify the kinetic binding parameters (KD, Kon, Koff) of recombinant mAbs against putative antigens.

Procedure:

• Antigen Immobilization: Dilute purified antigen (recombinant protein, peptide, etc.) in 10 mM sodium acetate buffer (pH 4.0-5.0). Inject over a CMS sensor chip to achieve a target immobilization level of 50-100 Response Units (RU) using amine-coupling chemistry.
• Binding Kinetics: Serially dilute purified mAbs (e.g., 0.5 nM to 100 nM) in HBS-EP+ running buffer. Inject samples over the antigen and reference surfaces at a flow rate of 30 µL/min for 180s association, followed by 600s dissociation.
• Data Analysis: Subtract the reference cell signal. Fit the resulting sensograms to a 1:1 Langmuir binding model using the SPR instrument's software (e.g., Biacore Evaluation Software) to calculate kinetic rate constants and the equilibrium dissociation constant (KD).

Protocol 3.3:In VitroFunctional Neutralization Assay

Objective: Determine the ability of BCR-derived mAbs to neutralize a target pathogen or bioactive molecule.

Procedure (Virus Neutralization Example):

• Day 1 - Cell Seeding: Seed Vero cells in a 96-well tissue culture plate at 2x10^4 cells/well in growth medium. Incubate overnight at 37°C, 5% CO2.
• Day 2 - Antibody-Virus Incubation: Prepare 3-fold serial dilutions of the test mAb in serum-free medium. Mix an equal volume of mAb dilution with a pre-titered virus stock containing ~100 TCID50 (50% tissue culture infectious dose). Incubate the mAb-virus mixture for 1 hour at 37°C.
• Infection: Remove growth medium from the cell plate. Add 100 µL of the mAb-virus mixture to the appropriate wells. Include virus-only (no mAb) and cell-only controls.
• Day 4/5 - Readout: Assess cytopathic effect (CPE) visually by microscope. Alternatively, quantify cell viability using a reagent like CellTiter-Glo. The neutralization titer (NT50) is the mAb concentration that reduces CPE or virus signal by 50% relative to virus-only controls.

Data Presentation and Correlation

Quantitative data from functional assays must be systematically compared to the sequence features identified by MiXCR analysis.

Table 1: Correlation of MiXCR Sequence Features with Functional Assay Outcomes

Clonotype ID (from MiXCR)	Clonal Frequency (%)	Somatic Hypermutation (nt changes)	Recombinant mAb KD (nM) [SPR]	Functional Titer (IC50/ NT50)	Biological Relevance Score (1-5)
CL001_IGH	2.45	12	0.78	5.2 µg/mL	5 (High)
CL002_IGH	1.89	8	15.4	>50 µg/mL	2 (Low)
CL003_IGH	0.67	21	0.12	0.8 µg/mL	5 (High)
CL004_IGH	5.10	2	NB*	Inactive	1 (None)

*NB: No binding detected.

Table 2: Summary of Key Validation Metrics for Candidate BCRs

Metric	Assay/Calculation	Relevance to Thesis Validation
Clonal Expansion	MiXCR assembleContigs output	Identifies in vivo expanded clones, suggesting antigen drive.
SHM Level	MiXCR exportClones (mutations per sequence)	Indicates T-cell dependent affinity maturation.
Binding Affinity (KD)	Surface Plasmon Resonance	Direct measure of target engagement strength.
Functional Potency	Neutralization, Signaling Inhibition (IC50/NT50)	Direct measure of biological activity, most critical for drug development.
Specificity Ratio	(Signal to Target) / (Signal to Control) in multiplex binding	Ensures activity is not due to polyreactivity.

The relationship between sequence assembly confidence, clonal expansion, and final functional output is critical.

Diagram Title: Core Logic of BCR Sequence Validation

The Scientist's Toolkit: Research Reagent Solutions

Item	Function in Validation Pipeline	Example/Supplier Note
MiXCR Software	Core analysis tool for assembling NGS reads into full-length BCR contigs and clonotypes.	Commercial & academic licenses available. Critical for initial sequence generation.
HEK293 Expression System	Mammalian cell line for producing properly folded, glycosylated recombinant antibodies from synthesized genes.	Expi293F (Thermo Fisher) offers high-titer transient expression.
Protein A/G Purification Resin	Affinity chromatography resin for high-purity IgG capture from cell culture supernatant.	MabSelect SuRe (Cytiva) for robustness and high dynamic binding capacity.
SPR Instrument	Label-free biosensor for quantifying real-time binding kinetics and affinity (KD).	Biacore 8K (Cytiva) or Sierra SPR (Bruker) for high-throughput analysis.
Reporter Cell Line	Engineered cells (e.g., NF-κB luciferase) to measure BCR signaling or functional blockade upon antigen engagement.	Available from cell repositories (ATCC) or via custom engineering.
Reference Antigen	Highly purified target protein for binding and functional assays. Essential positive control.	Recombinant production or commercial sourcing with certificate of analysis.
Isotype Control Antibodies	Critical negative controls to establish assay baseline and confirm specificity.	Must match the species and IgG subclass of the test mAbs.

This case study is situated within a broader thesis investigating the optimization of MiXCR-based contig assembly for generating high-fidelity, full-length B-cell receptor (BCR) sequences. The accurate reconstruction of paired heavy and light chains is critical for understanding clonal expansion, somatic hypermutation, and antigen-driven selection in both oncological and autoimmune contexts. This protocol details the application of MiXCR to matched cancer (e.g., chronic lymphocytic leukemia - CLL) and autoimmune (e.g., systemic lupus erythematosus - SLE) datasets to compare repertoire features and isolate pathogenic or tumor-specific clonotypes.

Table 1: Dataset Overview and Sequencing Statistics

Parameter	Cancer (CLL) Dataset	Autoimmune (SLE) Dataset
Sample Type	PBMC, Tumor Biopsy	PBMC, Affected Tissue
Avg. Raw Read Pairs	12.5 million	10.8 million
Avg. % BCR Read Alignment	22%	18%
Avg. Post-QC Reads	10.1 million	8.9 million
Key Sequencing Platform	Illumina NovaSeq 6000 (2x150 bp)	Illumina NovaSeq 6000 (2x150 bp)
Library Prep Kit	10x Genomics 5' V(D)J	SMARTer Human BCR Profiling

Table 2: MiXCR Assembly Output Metrics (Per Sample Average)

Metric	Cancer (CLL)	Autoimmune (SLE)
Total Contigs Assembled	45,200	38,500
Full-Length V(D)J Contigs	41,600 (92%)	34,100 (88.5%)
Productive Contigs	38,900 (86%)	31,600 (82%)
Mean Contig Length	480 nt	465 nt
Clonotypes (≥2 contigs)	1,150	950
Dominant Clonotype Frequency	15.2% (Range: 5-45%)	3.8% (Range: 1-12%)

Table 3: Comparative Repertoire Analysis

Repertoire Feature	Cancer (CLL) Trend	Autoimmune (SLE) Trend
Clonality (Shannon Index)	Low (0.5-1.2) - Oligoclonal	Moderate (1.8-3.0) - Polyclonal
Mean Somatic Hypermutation (SHM) Rate	Moderate-High (6-12%)	Very High (10-20%)
IGHV Gene Usage Bias	IGHV1-69, IGHV4-34 common	IGHV4-34, IGHV3-23 prevalent
Isotype Distribution (Dominant)	IgG > IgM	IgG > IgA > IgM

Experimental Protocols

Protocol 3.1: BCR Repertoire Sequencing from PBMC/Tissue

• Cell Isolation & Lysis: Isolate PBMCs via density gradient centrifugation. For tissue, use a gentleMACS Dissociator. Lyse cells in TRIzol or RLT buffer for RNA extraction.
• RNA Extraction & QC: Extract total RNA using a column-based kit. Assess integrity (RIN > 8.0) via Bioanalyzer.
• cDNA Synthesis & Library Prep: For full-length V(D)J, use a template-switching reverse transcriptase (e.g., SMART-Seq). Amplify BCR regions using multiplexed V-gene primers and a constant region primer, or use a targeted kit (10x Genomics, SMARTer).
• Sequencing: Pool libraries and sequence on an Illumina platform (2x150 bp paired-end, minimum 5M read pairs per sample).

Protocol 3.2: MiXCR-based Contig Assembly and Clonotyping Software: MiXCR v4.3.1, bundled with presets for major sequencing platforms.

Critical Parameters: Use --only-productive for drug target discovery. For autoimmunity studies analyzing autoreactive but potentially unproductive rearrangements, omit this flag. The --contig-assembly parameter is mandatory for full-length sequence reconstruction.

Protocol 3.3: Cross-Dataset Comparative Analysis

• Data Normalization: Normalize clonotype counts to "clones per million" (CPM) per sample.
• Clonality Calculation: Compute normalized Shannon entropy index using the diversity function in the scikit-bio Python package.
• SHM Analysis: Use MiXCR's exportAlignments function to obtain V-region alignments. Calculate SHM rate as (# of nucleotide substitutions in V region) / (length of germline V region).
• Visualization: Use R (ggplot2) to generate dimensionality reduction plots (UMAP) based on clonotype abundance and features to visualize dataset clustering.

Visualization: Workflows and Pathways

Diagram 1 Title: BCR Data Analysis with MiXCR

Diagram 2 Title: BCR Signaling to Disease Outcomes

The Scientist's Toolkit: Research Reagent Solutions

Table 4: Essential Materials for BCR Repertoire Studies

Item / Reagent	Function & Application in Protocol
Ficoll-Paque PLUS	Density gradient medium for isolation of viable PBMCs from whole blood.
TRIzol Reagent	Monophasic solution for simultaneous RNA/DNA/protein isolation from cells/tissue. Critical for high-yield RNA extraction.
SMARTer Human BCR Profiling Kit	Targeted cDNA synthesis and amplification for full-length human IGH, IGK, and IGL transcripts from RNA.
10x Genomics 5' Immune Profiling Kit	For linked-read, single-cell V(D)J and gene expression analysis from thousands of cells simultaneously.
MiXCR Software Suite	Integrated pipeline for aligning, assembling, and quantifying immune receptor sequences from raw NGS data.
IgBLAST / IMGT HighV-QUEST	Reference databases and tools for germline gene assignment and mutation analysis of assembled contigs.
R (with ggplot2, alakazam)	Statistical computing and graphics for advanced repertoire diversity, clustering, and visualization.

This protocol is presented within the broader thesis research focused on generating high-fidelity, full-length B-cell receptor (BCR) sequences using MiXCR contig assembly. The integration of MiXCR-derived contigs with single-cell RNA sequencing (scRNA-seq) transcriptomes enables the precise pairing of heavy and light chains, quantification of B-cell clonal expansion, and correlation of BCR repertoire with cellular phenotype. This integrative analysis is critical for advancing research in adaptive immunity, autoimmune diseases, and antibody drug discovery.

Key Research Reagent Solutions

The following table details essential reagents and tools for performing integrative MiXCR and scRNA-seq analysis.

Table 1: Research Reagent Solutions for Integrative BCR Analysis

Item Name	Provider/Example	Function in Experiment
Single-Cell 5' Library Kit	10x Genomics Chromium Next GEM Single Cell 5'	Enables capture of V(D)J transcripts alongside 5' gene expression from the same cell.
BCR Enrichment Primers	SMARTer Human BCR IgG H/K/L Primer Set (Takara)	For targeted amplification of full-length BCR transcripts prior to sequencing.
MiXCR Analysis Software	MiXCR (milaboratory.com)	Primary tool for assembling contigs from raw BCR sequencing reads and clonotype calling.
Single-Cell Analysis Suite	Cell Ranger (10x Genomics), Seurat R Toolkit	Processes scRNA-seq data, performs cell clustering, and integrates V(D)J data.
Integrative Analysis Tool	scRepertoire R package	Specifically designed to merge clonotype information from MiXCR/Cell Ranger with scRNA-seq clusters.
UMI-aware Aligner	STARsolo	Aligns scRNA-seq reads while preserving Unique Molecular Identifiers (UMIs) for accurate quantification.
High-Fidelity PCR Mix	KAPA HiFi HotStart ReadyMix	Used in library preparation for minimal amplification bias of long BCR amplicons.
Dual Index Kit	10x Genomics Dual Index Plate	Provides unique sample indices for multiplexing libraries on high-throughput sequencers.

Detailed Application Notes & Protocols

Experimental Workflow Protocol

This protocol outlines the steps from sample preparation to integrated data analysis.

Protocol 1: Integrated scRNA-seq and BCR Sequencing (10x Genomics Platform)

• Cell Preparation: Isolate live B cells from tissue or blood. Achieve >90% viability and resuspend at 700-1,200 cells/µL in PBS with 0.04% BSA.
• Gel Bead-in-Emulsion (GEM) Generation & Barcoding: Use the Chromium Controller and a Single Cell 5' Library & V(D)J Reagent Kit. Cells, gel beads with barcoded primers (containing cell barcode, UMI, and poly-dT), and master mix are partitioned into GEMs. Within each GEM, reverse transcription captures poly-adenylated mRNA (for gene expression) and V(D)J transcripts onto the barcoded beads.
• cDNA Amplification & Size Selection: Break emulsions, pool cDNA, and amplify by PCR. Perform SPRIselect bead-based size selection to separate full-length cDNA (for gene expression library) from extended fragments (~600-800 bp) enriched for V(D)J sequences.
• BCR Enrichment & Library Construction (V(D)J Library): Amplify the V(D)J-enriched fraction using a nested, target-specific PCR (using primers from Table 1) to specifically capture IgG heavy and light chain (kappa/lambda) variable regions. Follow with index PCR to add sample indexes and sequencing adapters.
• Gene Expression Library Construction: Fragment the full-length cDNA, add adapters, and index via PCR to construct the standard gene expression library.
• Sequencing: Pool libraries. Sequence the Gene Expression Library on an Illumina platform (e.g., NovaSeq) with recommended read length: 28bp Read1 (cell barcode + UMI), 90bp Read2 (transcript). Sequence the V(D)J Library with: 150bp Read1, 150bp Read2.

Computational Analysis Protocol

Protocol 2: MiXCR Contig Assembly & Integration with scRNA-seq Input: Paired-end FASTQ files from the BCR (V(D)J) sequencing library. Software: MiXCR (v4.6+), Cell Ranger (v7.1+), Seurat (v5), scRepertoire (v1.10+).

• BCR Contig Assembly with MiXCR:

  This command executes a predefined pipeline: align, assemble, assembleContigs, and exportClones. The --contig-assembly flag is critical for full-length reconstruction.

• Process Gene Expression with Cell Ranger:

• Integrate Clonotype & Expression Data:

  • Load the Cell Ranger filtered_contig_annotations.csv (which contains initial V(D)J calls) or the more comprehensive MiXCR output into R.
  • Process the gene expression matrix using Seurat (normalization, clustering, UMAP).
  • Use the scRepertoire package to combine the clonotype data with Seurat object metadata, enabling joint visualization and analysis.

Diagram Title: Integrated Experimental & Computational Workflow

Data Presentation & Key Metrics

Table 2: Representative Output Metrics from Integrative Analysis (Simulated Data)

Metric	Typical Target Value	Post-MiXCR Assembly	Post-Cell Ranger	Post-Integration
Cells with Productive BCR	>60% of B cells	75%	-	8,500 cells
Cells with Paired Heavy/Light	Maximal pairing	82% of productive cells	-	6,970 cells
Total Clonotypes Identified	Depends on sample	4,200	-	4,200
Expanded Clones (size >1)	Variable	950 clonotypes	-	950 clonotypes
Median UMIs/Cell (GEX)	>1,000	-	2,800	2,800
Median Genes/Cell (GEX)	>1,000	-	1,500	1,500
B Cell Clusters (UMAP)	Biologically distinct	-	5 clusters	5 annotated clusters

Table 3: Analysis of Clonal Expansion Across B Cell Phenotypes

B Cell Cluster (from scRNA-seq)	Avg. Clonal Size	% Cells in Expanded Clones	Top Clone Frequency	Characteristic Genes
Naïve B Cells	1.2	15%	0.8%	IGHD, TCL1A
Memory B Cells	3.8	65%	12.5%	CD27, SELL
Plasma Blasts	25.5	92%	45.0%	XBP1, SDC1
Germinal Center B Cells	5.2	70%	9.3%	AICDA, BCL6

Diagram Title: Logical Flow from Data to Biological Insight

Conclusion

MiXCR's contig assembly provides a robust, scalable solution for reconstructing full-length BCR sequences, which are indispensable for understanding adaptive immune responses. This guide has outlined the foundational knowledge, precise methodology, critical troubleshooting steps, and validation frameworks necessary for successful implementation. As the field moves towards integrating multi-omic data and applying repertoire analysis in clinical diagnostics, mastering these techniques will be pivotal. The future lies in leveraging these high-fidelity contigs for predicting antibody specificity, tracing clonal evolution in disease, and accelerating the development of next-generation biologics and personalized immunotherapies.