---
name: tcr-bcr-analysis-vdjtools-analysis
description: Calculate immune repertoire diversity metrics, compare samples, and track clonal dynamics using VDJtools. Use when analyzing repertoire diversity, finding shared clonotypes, or comparing immune profiles between conditions.
tool_type: cli
primary_tool: VDJtools
---
## Version Compatibility
Reference examples tested with: MiXCR 4.6+, VDJtools 1.2.1+, matplotlib 3.8+, pandas 2.2+, scanpy 1.10+
Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show <package>` then `help(module.function)` to check signatures
- CLI: `<tool> --version` then `<tool> --help` to confirm flags
If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.
# VDJtools Analysis
**"Compute diversity and overlap for my TCR repertoires"** -> Calculate repertoire diversity metrics, sample overlap, and perform statistical comparisons between immune repertoire samples.
- CLI: `vdjtools CalcDiversityStats`, `vdjtools OverlapPair`, `vdjtools PlotFancySpectratype`
## Basic Usage
**Goal:** Run VDJtools commands for immune repertoire analysis.
**Approach:** Invoke VDJtools via Java JAR or wrapper script with appropriate subcommand and options.
```bash
# VDJtools requires Java
java -jar vdjtools.jar <command> [options]
# Or with wrapper script
vdjtools <command> [options]
```
## Calculate Diversity Metrics
**Goal:** Compute repertoire diversity indices (Shannon, Simpson, Chao1, Gini) across samples.
**Approach:** Run CalcDiversityStats with a metadata file linking sample files to sample IDs and conditions.
```bash
# Basic diversity (Shannon, Simpson, Chao1, etc.)
vdjtools CalcDiversityStats \
-m metadata.txt \
output_dir/
# Metadata format (tab-separated):
# #file.name sample.id condition
# sample1.txt S1 control
# sample2.txt S2 treated
```
## Diversity Metrics Explained
| Metric | Description | Interpretation |
|--------|-------------|----------------|
| Shannon | Entropy-based diversity | Higher = more diverse |
| Simpson | Probability two random clones differ | 0-1, higher = diverse |
| InverseSimpson | 1/Simpson | Effective number of clones |
| Chao1 | Richness estimator | Total estimated clonotypes |
| Gini | Inequality coefficient | 0=equal, 1=dominated by one |
| d50 | Clones comprising 50% of repertoire | Lower = more oligoclonal |
## Sample Comparison
**Goal:** Quantify clonotype sharing and repertoire overlap between samples or conditions.
**Approach:** Compute pairwise overlap metrics (Jaccard, Morisita-Horn, F2) on amino acid clonotype identities.
```bash
# Find overlapping clonotypes
vdjtools OverlapPair \
-p sample1.txt sample2.txt \
output_dir/
# Calculate overlap for all pairs
vdjtools CalcPairwiseDistances \
-m metadata.txt \
-i aa \
output_dir/
# Overlap metrics: F2 (frequency-weighted Jaccard), Jaccard, MorisitaHorn
```
## Spectratype Analysis
**Goal:** Analyze CDR3 length distributions and V/J gene segment usage patterns across samples.
**Approach:** Generate spectratype (CDR3 length histogram) and segment usage tables via VDJtools commands.
```bash
# CDR3 length distribution (spectratype)
vdjtools CalcSpectratype \
-m metadata.txt \
output_dir/
# V/J gene usage
vdjtools CalcSegmentUsage \
-m metadata.txt \
output_dir/
```
## Clonal Tracking
**Goal:** Track individual clonotype frequencies across longitudinal timepoints and identify public clones shared across individuals.
**Approach:** Use TrackClonotypes for temporal tracking and JoinSamples to find public (cross-individual) clonotypes.
```bash
# Track clones across timepoints
vdjtools TrackClonotypes \
-m metadata_timecourse.txt \
-x time \
output_dir/
# Identify public clones (shared across individuals)
vdjtools JoinSamples \
-m metadata.txt \
-p \
output_dir/
```
## Input Format
VDJtools accepts MiXCR output or standard format:
```
# Required columns (tab-separated):
count frequency CDR3nt CDR3aa V D J
# Example:
1500 0.15 TGTGCCAGC... CASSF... TRBV5-1*01 TRBD2*01 TRBJ2-7*01
```
## Convert from MiXCR
**Goal:** Convert MiXCR clonotype output into VDJtools-compatible format.
**Approach:** Use VDJtools Convert command specifying MiXCR as the source software format.
```bash
# Convert MiXCR output to VDJtools format
vdjtools Convert \
-S mixcr \
mixcr_clones.txt \
output.txt
```
## Parse VDJtools Output in Python
**Goal:** Load VDJtools diversity statistics and overlap matrices into Python for custom analysis and plotting.
**Approach:** Read tab-delimited VDJtools output files into pandas DataFrames and visualize diversity comparisons.
```python
import pandas as pd
def load_diversity_stats(filepath):
'''Load VDJtools diversity statistics'''
df = pd.read_csv(filepath, sep='\t')
return df
def load_overlap_matrix(filepath):
'''Load pairwise overlap matrix'''
df = pd.read_csv(filepath, sep='\t', index_col=0)
return df
# Plot diversity across samples
def plot_diversity(stats_df, metric='shannon_wiener_index_mean'):
import matplotlib.pyplot as plt
plt.figure(figsize=(10, 6))
plt.bar(stats_df['sample_id'], stats_df[metric])
plt.xlabel('Sample')
plt.ylabel(metric)
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig('diversity_plot.png')
```
## Related Skills
- mixcr-analysis - Generate input clonotype tables
- repertoire-visualization - Visualize VDJtools output
- immcantation-analysis - BCR-specific phylogenetics