<!--
# 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.
2. **Cancer Diagnosis**: Distinguish cancer types from TCR signatures.
3. **Immunotherapy Response Prediction**: Predict checkpoint inhibitor response.
4. **Tumor-Reactive TCR Identification**: Find neoantigen-specific TCRs.
5. **TCR-pMHC Binding Prediction**: Predict TCR epitope specificity.
6. **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.
2. **Preprocessing**: CDR3 extraction, error correction, clustering.
3. **Repertoire Analysis**: Calculate diversity, clonality, convergence.
4. **ML Classification**: Cancer type, stage, response prediction.
5. **TCR Prioritization**: Rank tumor-reactive TCR candidates.
6. **TCR-pMHC Prediction**: Predict epitope specificity.
7. **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**:
```bash
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 -->
