tcr-repertoire-analysis-agent

<!--

COPYRIGHT NOTICE

This file is part of the "Universal Biomedical Skills" project.

Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>

All Rights Reserved.

#

This code is proprietary and confidential.

Unauthorized copying of this file, via any medium is strictly prohibited.

#

Provenance: Authenticated by MD BABU MIA

-->

---

name: 'tcr-repertoire-analysis-agent'

description: 'AI-powered T-cell receptor repertoire analysis for cancer diagnosis, immunotherapy response prediction, and therapeutic TCR selection using deep learning and multi-layer ML approaches.'

measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.

allowed-tools:

• read_file
• run_shell_command

---

TCR Repertoire Analysis Agent

The TCR Repertoire Analysis Agent provides comprehensive T-cell receptor repertoire analysis for cancer immunology applications. It leverages deep learning and multi-layer machine learning approaches to analyze TCR diversity, predict immunotherapy response, identify tumor-reactive TCRs, and support therapeutic TCR selection for cancer immunotherapy.

When to Use This Skill

• When analyzing TCR repertoire for cancer diagnosis and staging.
• For predicting immunotherapy (anti-PD-1/PD-L1) response from TCR profiles.
• To identify tumor-reactive TCRs for adoptive cell therapy.
• When monitoring treatment response through TCR clonality changes.
• For selecting therapeutic TCRs for TCR-T cell therapy development.

Core Capabilities

1. Repertoire Diversity Analysis: Quantify TCR diversity, clonality, and convergence.

1. Cancer Diagnosis: Distinguish cancer types from TCR signatures.

1. Immunotherapy Response Prediction: Predict checkpoint inhibitor response.

1. Tumor-Reactive TCR Identification: Find neoantigen-specific TCRs.

1. TCR-pMHC Binding Prediction: Predict TCR epitope specificity.

1. Clonal Dynamics Tracking: Monitor TCR clones during treatment.

TCR Repertoire Metrics

| Metric | Definition | Clinical Significance |

|--------|------------|----------------------|

| Clonality | Gini coefficient of clone sizes | Immune focusing |

| Shannon Entropy | Diversity measure | Immune breadth |

| Richness | Unique clonotypes | Repertoire depth |

| Top Clone % | Largest clone fraction | Dominant response |

| Convergent TCRs | Shared across patients | Public epitope response |

| Tumor-Infiltrating % | TIL-derived TCRs | Tumor reactivity |

Workflow

1. Input: TCR-seq data (bulk or single-cell), clinical metadata.

1. Preprocessing: CDR3 extraction, error correction, clustering.

1. Repertoire Analysis: Calculate diversity, clonality, convergence.

1. ML Classification: Cancer type, stage, response prediction.

1. TCR Prioritization: Rank tumor-reactive TCR candidates.

1. TCR-pMHC Prediction: Predict epitope specificity.

1. Output: Repertoire metrics, predictions, therapeutic candidates.

Example Usage

User: "Analyze the TCR repertoire from this melanoma patient's tumor and blood to predict immunotherapy response and identify tumor-reactive TCRs."

Agent Action:

python3 Skills/Immunology_Vaccines/TCR_Repertoire_Analysis_Agent/tcr_repertoire_analysis.py \
    --tumor_tcr tumor_tils.tsv \
    --blood_tcr pbmc_tcrs.tsv \
    --cancer_type melanoma \
    --hla_type HLA-A*02:01,HLA-B*07:02 \
    --neoantigens patient_neoantigens.fasta \
    --task response_prediction,tcr_identification \
    --output tcr_analysis/

Input Formats

| Format | Source | Fields |

|--------|--------|--------|

| AIRR-seq | Standardized | CDR3, V/J genes, count |

| MiXCR | MiXCR pipeline | Clone info, counts |

| 10x VDJ | Single-cell | CDR3, cell barcode |

| Custom TSV | Any pipeline | Flexible mapping |

Output Components

| Output | Description | Format |

|--------|-------------|--------|

| Repertoire Metrics | Diversity scores | .json |

| Response Prediction | Immunotherapy probability | .json |

| Cancer Classification | Type/stage prediction | .json |

| Tumor-Reactive TCRs | Ranked candidates | .csv |

| TCR-pMHC Predictions | Epitope specificity | .csv |

| Clonal Tracking | Dynamics over time | .csv |

| Visualizations | Repertoire plots | .png, .pdf |

Response Prediction Features

| Feature Category | Features | Importance |

|------------------|----------|------------|

| Diversity | Shannon, Gini, richness | High |

| Clonality | Top clones, expansion | High |

| Convergence | Public TCRs, sharing | Moderate |

| Sequence Features | CDR3 length, motifs | Moderate |

| TIL Characteristics | TIL fraction, phenotype | High |

AI/ML Components

Cancer Classification:

• Multi-layer ensemble (XGBoost, RF, SVM)
• TCR embedding networks
• Attention-based sequence models

Response Prediction:

• Cox regression with TCR features
• Deep survival analysis
• Multi-task learning (response + survival)

TCR-pMHC Prediction:

• AlphaFold3-based structural prediction
• Transformer models (TCR-BERT)
• Contrastive learning embeddings

Clinical Applications

| Application | TCR Biomarker | Clinical Utility |

|-------------|---------------|------------------|

| Diagnosis | Cancer-specific TCRs | Early detection |

| Staging | Clonality patterns | Disease extent |

| Prognosis | Intratumoral diversity | Survival prediction |

| Response | Baseline clonality | IO response |

| Monitoring | Clone dynamics | Treatment tracking |

| Therapy | Tumor-reactive TCRs | TCR-T development |

Performance Benchmarks

| Task | Dataset | Performance |

|------|---------|-------------|

| Cancer vs Normal | Digestive cancers | AUC 0.91 |

| Metastasis Detection | CRC | AUC 0.85 |

| IO Response | Melanoma | AUC 0.78 |

| TCR-pMHC Prediction | IEDB benchmark | AUC 0.82 |

Prerequisites

• Python 3.10+
• MiXCR, TRUST4 for TCR calling
• immunarch, tcrdist3
• PyTorch, transformers
• AlphaFold3 (optional, for structure)

Related Skills

• TCR_pMHC_Prediction_Agent - Detailed TCR-epitope prediction
• Neoantigen_Prediction_Agent - Neoantigen identification
• TME_Immune_Profiling_Agent - Broader immune context
• TCell_Exhaustion_Analysis_Agent - T cell phenotyping

TCR Sequence Analysis

| CDR3 Feature | Analysis | Meaning |

|--------------|----------|---------|

| Length Distribution | Histogram | V(D)J usage |

| Amino Acid Usage | Positional frequency | Binding properties |

| Hydrophobicity | CDR3 profile | MHC interaction |

| Charge | Net charge | Peptide binding |

| Motif Enrichment | k-mer analysis | Epitope specificity |

Therapeutic TCR Selection Criteria

| Criterion | Threshold | Rationale |

|-----------|-----------|-----------|

| Tumor Enrichment | >10-fold vs blood | Tumor specificity |

| Clone Size | Top 1% in tumor | Functional expansion |

| Neoantigen Binding | Predicted positive | Target specificity |

| Safety (Cross-react) | No self-peptide hits | Safety |

| HLA Restriction | Common alleles | Broad applicability |

Special Considerations

1. Sample Quality: Fresh samples preferred for TIL analysis
2. Sequencing Depth: Sufficient depth for rare clones
3. Batch Effects: Normalize across sequencing runs
4. HLA Context: TCR analysis requires HLA typing
5. Paired Chains: Single-cell for alpha-beta pairing

Cancer-Specific TCR Signatures

| Cancer Type | Key TCR Features | Public TCRs |

|-------------|------------------|-------------|

| Melanoma | High clonality, MAA-reactive | Yes |

| NSCLC | Moderate diversity | Limited |

| CRC-MSI | Neoantigen-reactive | Variable |

| HPV+ HNSCC | HPV-E6/E7 reactive | Yes |

Author

AI Group - Biomedical AI Platform

<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->