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.

# 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.

# 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