Tumor Heterogeneity AgentSAFE

The largest open-source medical AI skills library for OpenClaw🦞.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <[email protected]>
# 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.

2. **Phylogeny Reconstruction**: Build tumor evolutionary trees from variants.

3. **Subclonal Tracking**: Monitor subclone dynamics over time.

4. **Resistance Prediction**: Identify pre-existing resistant subclones.

5. **Multi-Region Integration**: Combine spatial heterogeneity data.

6. **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.

2. **Preprocessing**: Variant calling, CNV calling, purity estimation.

3. **CCF Estimation**: Calculate cancer cell fraction for each mutation.

4. **Clustering**: Group mutations into clonal populations.

5. **Phylogeny**: Reconstruct evolutionary tree.

6. **Temporal Analysis**: Track clone dynamics over time.

7. **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**:
```bash
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 |
| Mel

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

Gates applied: no_behavioural_pass.