tumor-heterogeneity-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: 'tumor-heterogeneity-agent'

description: 'AI-powered intratumor heterogeneity analysis for clonal architecture reconstruction, subclonal evolution tracking, and therapy resistance prediction using multi-region and longitudinal sequencing.'

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

allowed-tools:

• read_file
• run_shell_command

---

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

1. Clonal Deconvolution: Infer clonal populations and their frequencies.

1. Phylogeny Reconstruction: Build tumor evolutionary trees from variants.

1. Subclonal Tracking: Monitor subclone dynamics over time.

1. Resistance Prediction: Identify pre-existing resistant subclones.

1. Multi-Region Integration: Combine spatial heterogeneity data.

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

1. Input: Multi-region/longitudinal WES/WGS, copy number, tumor purity.

1. Preprocessing: Variant calling, CNV calling, purity estimation.

1. CCF Estimation: Calculate cancer cell fraction for each mutation.

1. Clustering: Group mutations into clonal populations.

1. Phylogeny: Reconstruct evolutionary tree.

1. Temporal Analysis: Track clone dynamics over time.

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

1. Sampling Bias: Multi-region captures more heterogeneity
2. Purity Effects: Low purity reduces clone resolution
3. CNV Complexity: High CNV burden complicates CCF
4. Single-Cell Validation: Ground truth from scDNA-seq
5. 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

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