tooluniverse-immune-repertoire-analysis

What it does

Comprehensive skill for analyzing T-cell receptor (TCR) and B-cell receptor (BCR) repertoire sequencing data to characterize adaptive immune responses, clonal expansion, and antigen specificity.

How it works

The skill provides an 8-phase workflow:

• Phase 1: Data Import & Clonotype Definition
  • Load AIRR-seq data from formats like MiXCR, ImmunoSEQ, AIRR, or 10x Genomics output.
  • Define clonotypes using criteria such as CDR3 amino acid, CDR3 nucleotide, or V/J+CDR3 composition, then aggregate by clonotype to obtain counts and frequencies.
• Phase 2: Diversity & Clonality Analysis
  • Calculate diversity metrics: Shannon entropy, Simpson index, inverse Simpson, Gini coefficient, richness, and clonality/evenness.
  • Perform rarefaction analysis via resampling to assess sampling depth and richness.
• Phase 3: V(D)J Gene Usage Analysis
  • Analyze V and J gene usage, including V-J pairing frequencies, and perform a chi-square test for biased usage.
• Phase 4: CDR3 Sequence Analysis
  • Assess CDR3 length distribution (weighted by counts) and report mean/median lengths.
  • Analyze amino acid composition of CDR3 regions weighted by clonotype frequencies.
• Phase 5: Clonal Expansion Detection
  • Identify expanded clonotypes using frequency thresholds (e.g., top percentile) and report counts and relative expansion.
• Longitudinal Clonotype Tracking
  • Track clonotype frequencies across timepoints, computing persistence, mean, and max frequencies, and output a persistence-ranked table.
• Throughout, the tool uses provided code blocks to load data, define clonotypes, compute metrics, and generate plots such as rarefaction curves and CDR3 length distributions.

When to use it

Use when you have AIRR-seq data and want to quantify clonality, diversity, V(D)J usage, CDR3 properties, clonal expansion, and longitudinal clonotype dynamics; also to integrate with single-cell phenotyping for clonotype-phenotype associations.

What it can touch

• Uses data inputs via Python code paths for formats: 'mixcr', '10x', 'airr'.
• Reads columns like cloneId, count, frequency, cdr3aa, cdr3nt, v_gene, j_gene, chain, cdr3_length.
• Performs computations and plotting with libraries such as pandas, numpy, scipy, and matplotlib.

Caveats

• License: NOASSERTION
• The skill relies on having compatible input column names; mismatches may require data preprocessing.
• Statistical tests assume proper normalization; observed frequencies are used for some analyses.
• Plots require rendering in an environment with plotting support (matplotlib).