TCR/BCR Reportoire Analysis

· 3 min read · Analysis Notes

TCR/BCR Reportoire Analysis

TCR/BCR Reportoire Analysis

TCR/BCR Repertoire Analysis

TL;DR: Analyze immune repertoires by aligning V(D)J sequences with MiXCR or Cell Ranger, then visualizing clonality and diversity in R using the immunarch package.

What is Repertoire Analysis?

Adaptive immune cells (T cells and B cells) generate vast diversity through V(D)J recombination. Analyzing this repertoire helps understand:

  • Clonal expansion: Response to antigens/tumors
  • Diversity: Immune system health
  • Gene usage: Bias in V/J gene selection
  • Convergence: Public clones shared between individuals

Part 1: Upstream Processing (Alignment)

You need to convert raw FASTQ files into clonotype tables.

Option A: Cell Ranger (10x Single-Cell VDJ)

If you have 10x Genomics single-cell data:

cellranger vdj \
  --id=sample1 \
  --reference=/path/to/refdata-cellranger-vdj-GRCh38-alts-ensembl-7.0.0 \
  --fastqs=/path/to/fastqs \
  --sample=sample1

Output: filtered_contig_annotations.csv

Option B: MiXCR (Bulk RNA-seq / VDJ-seq)

For bulk sequencing or non-10x data, MiXCR is the gold standard.

1. Installation

# Install via Conda
conda install -c milaboratories mixcr

# Activate license (free for academics)
# Get key from: https://licensing.milaboratories.com/
mixcr activate-license

2. Running the Pipeline
MiXCR has presets for different data types.

# For bulk RNA-seq (extracts TCR/BCR reads)
mixcr analyze rna-seq \
  --species hsa \
  --output-file results \
  R1.fastq.gz R2.fastq.gz

# For specific amplicon data (e.g., TCR beta)
mixcr analyze amplicon \
  --species hsa \
  --starting-material rna \
  --5-end no-v-primers \
  --3-end c-primers \
  --adapters adapters-present \
  R1.fastq.gz R2.fastq.gz \
  results_amplicon

Output: results.clonotypes.txt (tab-delimited table)

Part 2: Downstream Analysis (Immunarch)

The immunarch R package provides a unified framework for analysis.

1. Installation & Data Loading

install.packages("immunarch")
library(immunarch)

# 1. Prepare metadata file (metadata.txt)
# Sample    Condition
# Sample1   Control
# Sample2   Treatment

# 2. Load data
# Point to directory containing MiXCR or Cell Ranger outputs
immdata <- repLoad("./results_directory")

# Verify
print(names(immdata$data))

2. Basic Statistics

# Count clonotypes and total volume
repExplore(immdata$data, .method = "volume") %>% vis()

# Clonotype abundance distribution
repExplore(immdata$data, .method = "clones") %>% vis()

3. Diversity Analysis

Measure the "richness" of the immune repertoire.

# Chao1 estimation (richness)
div_chao <- repDiversity(immdata$data, .method = "chao1")
vis(div_chao)

# Gini index (inequality - high Gini means oligoclonal expansion)
div_gini <- repDiversity(immdata$data, .method = "gini")
vis(div_gini, .by = "Condition", .meta = immdata$meta)

4. Clonality & Expansion

Identify expanded clones (e.g., responding to a tumor).

# Categorize into Rare, Small, Medium, Large, Hyperexpanded
imm_top <- repClonality(immdata$data, .method = "homeo")
vis(imm_top)

# Track top clones across samples
repOverlap(immdata$data, .method = "public") %>% vis()

5. Gene Usage

Check for biased use of V or J segments.

# V-gene usage heatmap
gene_stats <- geneUsage(immdata$data, .gene = "hs.trbv")
vis(gene_stats, .plot = "heatmap")

# Compare between conditions
vis(gene_stats, .by = "Condition", .meta = immdata$meta)

6. Kmer Analysis (Motifs)

Find shared amino acid motifs in the CDR3 region.

# Count k-mers
kmers <- getKmers(immdata$data, 5) # 5-mers

# Visualize motif logo
kmer_profile <- kmer_profile(kmers, "prob")
vis(kmer_profile)

Single-Cell Integration (scRepertoire)

For single-cell VDJ, integrate with Seurat using scRepertoire.

library(scRepertoire)
library(Seurat)

# 1. Load contig files
contig_list <- loadContigs(dir = "./vdj_outs", format = "10X")

# 2. Combine T/B cell data
combined <- combineTCR(contig_list, samples = c("S1", "S2"), ID = c("Ctrl", "Treat"))

# 3. Add to Seurat object
seurat_obj <- combineExpression(combined, seurat_obj, cloneCall = "gene+nt")

# 4. Visualize on UMAP
DimPlot(seurat_obj, group.by = "cloneType")

Troubleshooting

MiXCR: "No clonotypes found"

Cause: Wrong species or wrong preset.
Fix:

  • Check --species (hsa = human, mmu = mouse).
  • Ensure input data actually contains immune reads (standard RNA-seq might have low coverage).

Immunarch: "Metadata mismatch"

Cause: Sample names in metadata.txt don't match filenames.
Fix: Ensure the first column of metadata matches the file prefixes exactly.

High clonality in control samples?

Cause: PCR duplication or shallow sequencing.
Fix: Check library complexity and use UMIs if possible to deduplicate.

Resources

See also:

Originally posted on WeChat Official Account: bioinfo_studyroom

TCR/BCR