Tumor Heterogeneity Agent
The Tumor Heterogeneity Agent provides comprehensive analysis of intratumor heterogeneity (ITH) for understanding clonal architecture, tracking subclonal evolution, and predicting therapy resistance. It integrates multi-region sequencing, single-cell data, and longitudinal samples to reconstruct tumor phylogenies and identify actionable subclones.
When to Use This Skill
- When analyzing multi-region tumor sequencing for clonal architecture.
- For tracking clonal evolution under treatment pressure.
- To predict resistance emergence from subclonal populations.
- When assessing tumor heterogeneity impact on treatment response.
- For integrating single-cell and bulk sequencing for ITH analysis.
Core Capabilities
Clonal Deconvolution: Infer clonal populations and their frequencies.
Phylogeny Reconstruction: Build tumor evolutionary trees from variants.
Subclonal Tracking: Monitor subclone dynamics over time.
Resistance Prediction: Identify pre-existing resistant subclones.
Multi-Region Integration: Combine spatial heterogeneity data.
Single-Cell ITH: Integrate scDNA-seq for ground-truth clones.
Heterogeneity Metrics
| Metric |
Definition |
Clinical Relevance |
| MATH Score |
Mutant-allele tumor heterogeneity |
ITH quantification |
| Shannon Index |
Clonal diversity |
Evolutionary potential |
| Clone Count |
Number of distinct clones |
Complexity |
| Truncal Fraction |
% truncal mutations |
Targetability |
| ITH Score |
Composite heterogeneity |
Prognosis |
Workflow
Input: Multi-region/longitudinal WES/WGS, copy number, tumor purity.
Preprocessing: Variant calling, CNV calling, purity estimation.
CCF Estimation: Calculate cancer cell fraction for each mutation.
Clustering: Group mutations into clonal populations.
Phylogeny: Reconstruct evolutionary tree.
Temporal Analysis: Track clone dynamics over time.
Output: Clone structures, phylogenies, heterogeneity metrics.
Example Usage
User: "Analyze the clonal architecture of this multi-region lung tumor sequencing to understand heterogeneity and identify resistant subclones."
Agent Action:
python3 Skills/Oncology/Tumor_Heterogeneity_Agent/ith_analysis.py \
--multi_region_vcfs region1.vcf,region2.vcf,region3.vcf \
--cnv_segments cnv_calls.seg \
--purity 0.7,0.65,0.72 \
--sample_names Primary,Met1,Met2 \
--method pyclone-vi \
--phylogeny_method citup \
--output ith_analysis/
Deconvolution Methods
| Method |
Approach |
Best For |
| PyClone-VI |
Variational inference |
Large datasets |
| SciClone |
Kernel density |
High purity |
| EXPANDS |
Probabilistic |
Multi-region |
| Canopy |
EM algorithm |
CNV integration |
| Clonevol |
Phylogeny-aware |
Longitudinal |
| CITUP |
Integer programming |
Tree optimization |
Input Requirements
| Input |
Format |
Required |
| Somatic Variants |
VCF with depth |
Yes |
| Copy Number |
SEG file |
Yes |
| Tumor Purity |
Float (0-1) |
Yes |
| Sample Metadata |
TSV |
Yes |
| Normal BAM |
BAM |
Recommended |
Output Components
| Output |
Description |
Format |
| Clone Assignments |
Mutation-to-clone mapping |
.csv |
| Clone Frequencies |
Per-sample clone fractions |
.csv |
| Phylogenetic Tree |
Newick and visualization |
.nwk, .pdf |
| ITH Metrics |
Heterogeneity scores |
.json |
| Subclone Variants |
Clone-specific mutations |
.vcf |
| Evolution Plot |
Clone dynamics over time |
.png |
| Actionable Subclones |
Druggable clone mutations |
.csv |
Clonal Classification
| Clone Type |
Definition |
Implications |
| Truncal |
Present in all samples |
Ideal targets |
| Branch |
Present in subset |
Regional targets |
| Private |
Single sample only |
Local significance |
| Resistant |
Expand under therapy |
Resistance mechanism |
AI/ML Components
Clone Inference:
- Variational autoencoders for CCF estimation
- Dirichlet process mixture models
- Graph neural networks for phylogeny
Resistance Prediction:
- Time-series models for clone trajectories
- Classification of resistant signatures
- Drug-clone interaction prediction
Multi-Region Integration:
- Multi-task learning across regions
- Spatial models for regional patterns
- Transfer learning across cancers
Clinical Applications
| Application |
ITH Insight |
Clinical Action |
| Treatment Selection |
Truncal vs branch targets |
Prioritize truncal targets |
| Resistance Monitoring |
Pre-existing resistant clones |
Early combination therapy |
| Prognosis |
ITH score |
Risk stratification |
| Biomarker Development |
Clonal biomarkers |
Robust biomarker selection |
Cancer-Specific Patterns
| Cancer Type |
Typical ITH |
Key Drivers |
| Lung (NSCLC) |
High |
EGFR, KRAS subclonal |
| Breast |
Moderate-High |
PIK3CA, ESR1 evolution |
| Colorectal |
Moderate |
KRAS, BRAF clonal |
| Renal |
Very High |
VHL truncal, diverse branches |
| Melanoma |
High |
BRAF/NRAS truncal |
Prerequisites
- Python 3.10+
- PyClone-VI, SciClone
- CITUP, Clonevol
- CNVkit/FACETS for CNV
- R with clonal evolution packages
Related Skills
- ctDNA_Dynamics_MRD_Agent - Liquid biopsy tracking
- Single_Cell_CNV_Agent - scDNA-seq analysis
- HRD_Analysis_Agent - Genomic instability
- Pan_Cancer_MultiOmics_Agent - Multi-omic integration
Phylogeny Visualization
| View Type |
Shows |
Best For |
| Fish Plot |
Clone dynamics over time |
Longitudinal |
| Tree Diagram |
Branching evolution |
Multi-region |
| Muller Plot |
Population dynamics |
Treatment response |
| Clone Map |
Spatial distribution |
Multi-region spatial |
Special Considerations
- Sampling Bias: Multi-region captures more heterogeneity
- Purity Effects: Low purity reduces clone resolution
- CNV Complexity: High CNV burden complicates CCF
- Single-Cell Validation: Ground truth from scDNA-seq
- Temporal Resolution: Frequent sampling improves tracking
Resistance Mechanisms
| Mechanism |
Detection |
Intervention |
| Pre-existing resistant clone |
Subclonal at baseline |
Combination therapy |
| Acquired resistance |
New clone emerges |
Switch therapy |
| Phenotypic plasticity |
Expression change |
Monitor phenotype |
| Microenvironment |
TME evolution |
Immunotherapy |
Author
AI Group - Biomedical AI Platform
1---2name: tumor-heterogeneity-agent3description: AI-powered intratumor heterogeneity analysis for clonal architecture reconstruction, subclonal evolution tracking, and therapy resistance prediction using multi-region and longitudinal sequencing.4---56<!--7# COPYRIGHT NOTICE8# This file is part of the "Universal Biomedical Skills" project.9# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>10# All Rights Reserved.11#12# This code is proprietary and confidential.13# Unauthorized copying of this file, via any medium is strictly prohibited.14#15# Provenance: Authenticated by MD BABU MIA1617-->18192021# Tumor Heterogeneity Agent2223The **Tumor Heterogeneity Agent** provides comprehensive analysis of intratumor heterogeneity (ITH) for understanding clonal architecture, tracking subclonal evolution, and predicting therapy resistance. It integrates multi-region sequencing, single-cell data, and longitudinal samples to reconstruct tumor phylogenies and identify actionable subclones.2425## When to Use This Skill2627* When analyzing multi-region tumor sequencing for clonal architecture.28* For tracking clonal evolution under treatment pressure.29* To predict resistance emergence from subclonal populations.30* When assessing tumor heterogeneity impact on treatment response.31* For integrating single-cell and bulk sequencing for ITH analysis.3233## Core Capabilities34351. **Clonal Deconvolution**: Infer clonal populations and their frequencies.36372. **Phylogeny Reconstruction**: Build tumor evolutionary trees from variants.38393. **Subclonal Tracking**: Monitor subclone dynamics over time.40414. **Resistance Prediction**: Identify pre-existing resistant subclones.42435. **Multi-Region Integration**: Combine spatial heterogeneity data.44456. **Single-Cell ITH**: Integrate scDNA-seq for ground-truth clones.4647## Heterogeneity Metrics4849| Metric | Definition | Clinical Relevance |50|--------|------------|-------------------|51| MATH Score | Mutant-allele tumor heterogeneity | ITH quantification |52| Shannon Index | Clonal diversity | Evolutionary potential |53| Clone Count | Number of distinct clones | Complexity |54| Truncal Fraction | % truncal mutations | Targetability |55| ITH Score | Composite heterogeneity | Prognosis |5657## Workflow58591. **Input**: Multi-region/longitudinal WES/WGS, copy number, tumor purity.60612. **Preprocessing**: Variant calling, CNV calling, purity estimation.62633. **CCF Estimation**: Calculate cancer cell fraction for each mutation.64654. **Clustering**: Group mutations into clonal populations.66675. **Phylogeny**: Reconstruct evolutionary tree.68696. **Temporal Analysis**: Track clone dynamics over time.70717. **Output**: Clone structures, phylogenies, heterogeneity metrics.7273## Example Usage7475**User**: "Analyze the clonal architecture of this multi-region lung tumor sequencing to understand heterogeneity and identify resistant subclones."7677**Agent Action**:78```bash79python3 Skills/Oncology/Tumor_Heterogeneity_Agent/ith_analysis.py \80 --multi_region_vcfs region1.vcf,region2.vcf,region3.vcf \81 --cnv_segments cnv_calls.seg \82 --purity 0.7,0.65,0.72 \83 --sample_names Primary,Met1,Met2 \84 --method pyclone-vi \85 --phylogeny_method citup \86 --output ith_analysis/87```8889## Deconvolution Methods9091| Method | Approach | Best For |92|--------|----------|----------|93| PyClone-VI | Variational inference | Large datasets |94| SciClone | Kernel density | High purity |95| EXPANDS | Probabilistic | Multi-region |96| Canopy | EM algorithm | CNV integration |97| Clonevol | Phylogeny-aware | Longitudinal |98| CITUP | Integer programming | Tree optimization |99100## Input Requirements101102| Input | Format | Required |103|-------|--------|----------|104| Somatic Variants | VCF with depth | Yes |105| Copy Number | SEG file | Yes |106| Tumor Purity | Float (0-1) | Yes |107| Sample Metadata | TSV | Yes |108| Normal BAM | BAM | Recommended |109110## Output Components111112| Output | Description | Format |113|--------|-------------|--------|114| Clone Assignments | Mutation-to-clone mapping | .csv |115| Clone Frequencies | Per-sample clone fractions | .csv |116| Phylogenetic Tree | Newick and visualization | .nwk, .pdf |117| ITH Metrics | Heterogeneity scores | .json |118| Subclone Variants | Clone-specific mutations | .vcf |119| Evolution Plot | Clone dynamics over time | .png |120| Actionable Subclones | Druggable clone mutations | .csv |121122## Clonal Classification123124| Clone Type | Definition | Implications |125|------------|------------|--------------|126| Truncal | Present in all samples | Ideal targets |127| Branch | Present in subset | Regional targets |128| Private | Single sample only | Local significance |129| Resistant | Expand under therapy | Resistance mechanism |130131## AI/ML Components132133**Clone Inference**:134- Variational autoencoders for CCF estimation135- Dirichlet process mixture models136- Graph neural networks for phylogeny137138**Resistance Prediction**:139- Time-series models for clone trajectories140- Classification of resistant signatures141- Drug-clone interaction prediction142143**Multi-Region Integration**:144- Multi-task learning across regions145- Spatial models for regional patterns146- Transfer learning across cancers147148## Clinical Applications149150| Application | ITH Insight | Clinical Action |151|-------------|-------------|-----------------|152| Treatment Selection | Truncal vs branch targets | Prioritize truncal targets |153| Resistance Monitoring | Pre-existing resistant clones | Early combination therapy |154| Prognosis | ITH score | Risk stratification |155| Biomarker Development | Clonal biomarkers | Robust biomarker selection |156157## Cancer-Specific Patterns158159| Cancer Type | Typical ITH | Key Drivers |160|-------------|-------------|-------------|161| Lung (NSCLC) | High | EGFR, KRAS subclonal |162| Breast | Moderate-High | PIK3CA, ESR1 evolution |163| Colorectal | Moderate | KRAS, BRAF clonal |164| Renal | Very High | VHL truncal, diverse branches |165| Melanoma | High | BRAF/NRAS truncal |166167## Prerequisites168169* Python 3.10+170* PyClone-VI, SciClone171* CITUP, Clonevol172* CNVkit/FACETS for CNV173* R with clonal evolution packages174175## Related Skills176177* ctDNA_Dynamics_MRD_Agent - Liquid biopsy tracking178* Single_Cell_CNV_Agent - scDNA-seq analysis179* HRD_Analysis_Agent - Genomic instability180* Pan_Cancer_MultiOmics_Agent - Multi-omic integration181182## Phylogeny Visualization183184| View Type | Shows | Best For |185|-----------|-------|----------|186| Fish Plot | Clone dynamics over time | Longitudinal |187| Tree Diagram | Branching evolution | Multi-region |188| Muller Plot | Population dynamics | Treatment response |189| Clone Map | Spatial distribution | Multi-region spatial |190191## Special Considerations1921931. **Sampling Bias**: Multi-region captures more heterogeneity1942. **Purity Effects**: Low purity reduces clone resolution1953. **CNV Complexity**: High CNV burden complicates CCF1964. **Single-Cell Validation**: Ground truth from scDNA-seq1975. **Temporal Resolution**: Frequent sampling improves tracking198199## Resistance Mechanisms200201| Mechanism | Detection | Intervention |202|-----------|-----------|--------------|203| Pre-existing resistant clone | Subclonal at baseline | Combination therapy |204| Acquired resistance | New clone emerges | Switch therapy |205| Phenotypic plasticity | Expression change | Monitor phenotype |206| Microenvironment | TME evolution | Immunotherapy |207208## Author209210AI Group - Biomedical AI Platform211212213<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->