mixcr-analysis

MiXCR Bulk TCR/BCR Analysis

Overview

MiXCR is a tool for analyzing T cell receptor (TCR) and B cell receptor (BCR) repertoires from bulk sequencing data. This skill covers the complete workflow from FASTQ files to interactive HTML reports with diversity metrics, V gene usage, and clonotype tables.

Key capabilities:

• Align reads to V(D)J reference genes
• Assemble clonotypes by CDR3 sequence
• Export chain-specific clonotype tables (TRA, TRB, TRD, TRG for TCR; IGH, IGK, IGL for BCR)
• Calculate diversity/clonality metrics
• Generate publication-quality visualizations

When to Use This Skill

• Processing bulk TCR or BCR sequencing data (QIAseq, Takara, custom amplicon panels)
• Analyzing clonal diversity between sample groups
• Comparing V/J gene usage across conditions
• Generating TCR/BCR repertoire reports for FGCZ projects
• Troubleshooting MiXCR preset or parameter issues

Core Workflows

1. MiXCR Processing

Preset Selection

Data Type	Preset	Notes
Generic bulk amplicon	generic-amplicon	Default for demultiplexed FASTQs
QIAseq TCR with UMI	qiagen-human-rna-tcr-umi-qiaseq	Only if barcodes in R2 sequence
10x VDJ	Use scRepertoire skill	Single-cell, not MiXCR
Takara SMARTer	takara-human-rna-bcr-umi-smartseq	Check kit version

Important: If using a kit-specific preset and getting >90% barcode failures, switch to generic-amplicon. This happens when FASTQs are already demultiplexed (barcodes in header, not sequence).

Standard Processing Command

mixcr analyze generic-amplicon \
    --species hsa \
    --threads 16 \
    --force-overwrite \
    --rna \
    --assemble-clonotypes-by CDR3 \
    --floating-left-alignment-boundary \
    --floating-right-alignment-boundary J \
    ${R1_FASTQ} ${R2_FASTQ} \
    ${OUTPUT_PREFIX}

Parameter explanations:

• --species hsa: Human (use mmu for mouse)
• --rna: Input is RNA-derived (affects alignment expectations)
• --assemble-clonotypes-by CDR3: Group by CDR3 only (standard for repertoire analysis)
• --floating-left-alignment-boundary: Flexible 5' alignment for variable primer positions
• --floating-right-alignment-boundary J: Flexible 3' alignment at J gene

2. Export Clonotypes

After processing, export chain-specific clonotype tables:

# Export TRB (beta chain - primary for αβ T cells)
mixcr exportClones \
    --chains TRB \
    -cloneId -count -fraction -sequence -quality \
    -vGene -dGene -jGene -cGene \
    -vHit -dHit -jHit -cHit \
    -aaFeature CDR3 -nFeature CDR3 \
    ${SAMPLE}.clns ${SAMPLE}.TRB.tsv

# Export other chains as needed
# TRA (alpha), TRD (delta), TRG (gamma) for TCR
# IGH, IGK, IGL for BCR

3. R Analysis Pipeline

Load clonotypes and analyze in R:

library(tidyverse)
library(ggplot2)
library(patchwork)
library(DT)

# Load clonotypes
files <- list.files("clonotypes/", pattern = "\\.TRB\\.tsv$", full.names = TRUE)
clonotypes <- map_dfr(files, ~read_tsv(.x) |> mutate(Sample = basename(.x)))

# Calculate diversity metrics
diversity <- clonotypes |>
  group_by(Sample) |>
  summarise(
    n_clones = n(),
    n_reads = sum(cloneCount),
    shannon = -sum((cloneCount/sum(cloneCount)) * log(cloneCount/sum(cloneCount))),
    clonality = 1 - (shannon / log(n_clones))
  )

FGCZ Conventions

Directory Structure

/srv/GT/analysis/pXXXXX/
├── mixcr_output/           # MiXCR binary outputs (.clns files)
├── clonotypes/             # Exported TSV files
├── logs/                   # Processing logs
└── TCR_Analysis_Report.html

/srv/gstore/projects/pXXXXX/Analyses_Paul/
├── TCR_Analysis_Report.html  # Final delivery
└── clonotypes/               # Clonotype tables

SBATCH Template

#!/bin/bash
#SBATCH --job-name=pXXXXX_mixcr
#SBATCH --output=/srv/GT/analysis/pXXXXX/logs/mixcr_%j.log
#SBATCH --error=/srv/GT/analysis/pXXXXX/logs/mixcr_%j.err
#SBATCH --time=12:00:00
#SBATCH --mem-per-cpu=8G
#SBATCH --cpus-per-task=16
#SBATCH --partition=employee

set -e
set -u

# Load environment with MiXCR
eval "$(/usr/local/ngseq/miniforge3/bin/conda shell.bash hook)"
conda activate ps_pgueguen  # Or your environment with MiXCR

# Process samples...

Delivery

# Copy report to gstore
g-req copynow /srv/GT/analysis/pXXXXX/TCR_Analysis_Report.html \
    /srv/gstore/projects/pXXXXX/Analyses_Paul/

# Copy clonotype tables
g-req copynow /srv/GT/analysis/pXXXXX/clonotypes/ \
    /srv/gstore/projects/pXXXXX/Analyses_Paul/

Visualization Standards

Diversity Boxplots

ggplot(diversity, aes(x = Group, y = clonality, fill = Group)) +
  geom_boxplot(outlier.shape = NA) +
  geom_jitter(width = 0.2, alpha = 0.7) +
  labs(y = "Simpson Clonality", x = NULL) +
  theme_minimal() +
  theme(legend.position = "none")

V Gene Usage

v_usage <- clonotypes |>
  group_by(Sample, allVHitsWithScore) |>
  summarise(count = sum(cloneCount)) |>
  mutate(proportion = count / sum(count))

ggplot(v_usage, aes(x = reorder(allVHitsWithScore, -proportion), y = proportion, fill = Group)) +
  geom_bar(stat = "identity", position = "dodge") +
  coord_flip() +
  labs(x = "V Gene", y = "Proportion") +
  theme_minimal()

Interactive Tables

# Top clones table
top_clones <- clonotypes |>
  group_by(Sample) |>
  slice_max(cloneCount, n = 10)

DT::datatable(top_clones,
  filter = "top",
  options = list(pageLength = 25, scrollX = TRUE)
)

Troubleshooting

Low Alignment Rate (<50%)

1. Check FASTQ quality with FastQC
2. Verify correct species (--species hsa vs mmu)
3. Try different preset if using kit-specific one
4. Check if reads are TCR/BCR (could be contamination)

>90% Barcode Failures

Switch from kit-specific preset to generic-amplicon. This happens when:

• FASTQs are already demultiplexed (barcodes in header)
• Barcode/UMI positions don't match preset expectations

Empty Clonotype Files

1. Check alignment report: grep "Successfully aligned" *.align.report.txt
2. Verify chain exists in data (TRD/TRG rare in some samples)
3. Check for processing errors in logs

Memory Issues

Increase --mem-per-cpu in SBATCH or reduce --threads

Resources

Skill Files:

• assets/tcr_analysis_template.Rmd - R Markdown report template
• scripts/sbatch_mixcr.sh - SBATCH processing template
• scripts/export_clonotypes.sh - Chain export helper
• references/mixcr_parameters.md - Parameter reference
• references/diversity_metrics.md - Diversity analysis guide

External:

• MiXCR Documentation
• MiXCR Presets
• MiXCR License - Free academic license required

Quick Start Example

# 1. Set up directories
PROJECT="p35802"
ANALYSIS_DIR="/srv/GT/analysis/${PROJECT}"
mkdir -p ${ANALYSIS_DIR}/{mixcr_output,clonotypes,logs}

# 2. Process one sample
mixcr analyze generic-amplicon \
    --species hsa --threads 16 --rna \
    --assemble-clonotypes-by CDR3 \
    --floating-left-alignment-boundary \
    --floating-right-alignment-boundary J \
    sample_R1.fastq.gz sample_R2.fastq.gz \
    ${ANALYSIS_DIR}/mixcr_output/sample

# 3. Export clonotypes
for chain in TRA TRB TRD TRG; do
    mixcr exportClones --chains ${chain} \
        -cloneId -count -fraction \
        -vGene -jGene -aaFeature CDR3 \
        ${ANALYSIS_DIR}/mixcr_output/sample.clns \
        ${ANALYSIS_DIR}/clonotypes/sample.${chain}.tsv
done

# 4. Generate report (copy template, edit parameters, render)
cp ~/.claude/skills/mixcr-analysis/assets/tcr_analysis_template.Rmd \
   ${ANALYSIS_DIR}/TCR_Analysis_Report.Rmd

module load Dev/R/4.5.0
Rscript -e "rmarkdown::render('${ANALYSIS_DIR}/TCR_Analysis_Report.Rmd')"

# 5. Deliver to gstore
g-req copynow ${ANALYSIS_DIR}/TCR_Analysis_Report.html \
    /srv/gstore/projects/${PROJECT}/Analyses_Paul/