bio-copy-number-subclonal-copy-number

What this skill does

## Version Compatibility

Reference examples tested with: R 4.3+ with Battenberg 2.2.10+ and TitanCNA 1.40+, MEDICC2 1.0+, Python 3.10+; impute2/Beagle phasing reference panels.

Before using code patterns, verify installed versions match. If versions differ:
- R: `packageVersion('Battenberg')` / `'TitanCNA')` then `?function`
- CLI: `medicc2 --help`
- Battenberg is GitHub-only (`Wedge-lab/battenberg`) and needs a 1000 Genomes impute/phasing reference and allele-counter; confirm reference data is installed

Battenberg and TITAN both consume allele-specific data (logR + BAF at heterozygous SNPs); they cannot run on relative copy ratio alone.

# Subclonal Copy Number and Tumor Evolution

**"This copy number is non-integer — is it noise, or are there subclones"** -> A tumor is a mixture of cell populations. When a copy-number change is present in only some cancer cells, bulk sequencing averages it into a *non-integer* state. A long non-integer segment is not noise — it is a subclonal copy-number alteration, and resolving it reveals the tumor's clonal architecture.

- R: `Battenberg` (phased clonal + subclonal CN), `TitanCNA` (HMM mixture of cell populations)
- CLI: `medicc2` (whole-genome-doubling-aware copy-number phylogenies)
- Input: allele-specific data — see allele-specific-copy-number for the clonal layer

## Clonal vs Subclonal — What the Tools Output

| Concept | Meaning |
|---------|---------|
| Clonal CNA | Present in all cancer cells; one copy-number state per segment |
| Subclonal CNA | Present in a fraction of cancer cells; the segment needs two states plus a fraction |
| Cancer cell fraction (CCF) | Fraction of cancer cells carrying the event |
| Mirrored subclonal allelic imbalance | Different subclones lose opposite haplotypes of the same region |

Battenberg fits a clonal allele-specific profile (ASCAT internally), then where a segment fits poorly as a single integer state, it models it as a mixture of two states with a subclonal fraction. TITAN uses an HMM whose states span multiple clonal clusters, jointly estimating per-cluster cellular prevalence. Both need haplotype phasing — subclonal allelic imbalance is only resolvable when SNPs are phased.

## Tool Selection

| Tool | Model | Best for | Fails when |
|------|-------|----------|------------|
| Battenberg | Phased clonal fit + per-segment subclonal mixture | WGS, subclonal CN to ~3% of cells, clonal-evolution studies | Low depth/purity; heavy compute; needs phasing reference |
| TITAN | HMM mixture across clonal clusters | WGS/WES, joint CN+LOH+subclonal prevalence, few clusters | Many subclones; cluster number must be chosen and swept |
| MEDICC2 | WGD-aware minimum-event copy-number phylogeny | Multi-sample / multi-region evolution | Single sample (no tree to build) |
| ASCAT/FACETS | Clonal allele-specific only | When subclonal resolution is not needed | Treats subclonal segments as noisy clonal — see allele-specific-copy-number |

## Whole-Genome Doubling — Detection and Timing

Whole-genome doubling (WGD) is a discrete, common (~30% of advanced cancers) evolutionary event, and it must be called explicitly because it changes how every copy number is read.

- **Detection:** A tumor has undergone WGD if more than ~50% of the autosomal genome has a major (more frequent) allele copy number >= 2. WGD tumors have median ploidy ~3.3 versus ~2.1 for non-WGD.
- **Relative vs absolute:** Depth gives *relative* copy number; WGD calling needs *absolute* allele-specific copy number (BAF anchors ploidy). A depth-only profile cannot distinguish a WGD genome from a non-WGD genome — this is the identifiability problem of allele-specific-copy-number in another guise.
- **Timing:** WGD is timeable relative to point mutations. Mutations that arose before WGD are carried at multiple copies (mutation copy number ~2); mutations after WGD sit at one copy. This dates WGD within the tumor's mutational history.

## Calling Subclonal CN with Battenberg

**Goal:** Fit clonal and subclonal allele-specific copy number genome-wide.

**Approach:** Generate phased allele counts against a 1000 Genomes reference, run the Battenberg pipeline; segments that fit poorly as one integer state are split into a two-state subclonal mixture with a cellular fraction.

```r
library(Battenberg)

# Battenberg orchestrates allele counting, phasing, ASCAT clonal fit, and the
# subclonal mixture step. Reference data (1000G impute panel) must be installed.
battenberg(
    samplename          = 'tumour_id',
    normalname          = 'normal_id',
    sample_data_file    = 'tumour.bam',
    normal_data_file    = 'normal.bam',
    ismale              = TRUE,
    imputeinfofile      = 'impute_info.txt',
    g1000prefix         = '1000G_loci/1000genomesloci2012_chr',     # SNP loci data
    g1000allelesprefix  = '1000G_alleles/1000genomesAlleles2012_chr', # SNP alleles (WGS)
    problemloci         = 'probloci.txt',
    gccorrectprefix     = 'GC_correction_hg38_chr',
    repliccorrectprefix = 'RT_correction_hg38_chr',
    genomebuild         = 'hg38',                                   # default is hg19
    nthreads            = 8)
# Output *_subclones.txt: per segment, nMaj1/nMin1 (state 1) + frac1, and nMaj2/nMin2 +
# frac2 when the segment is subclonal (two states).
```

## Calling Subclonal CN with TITAN

**Goal:** Jointly infer copy number, LOH, and the cellular prevalence of clonal clusters.

**Approach:** TITAN needs both allele counts (het SNPs) and corrected read depth. Load the allele counts; correct tumour/normal read depth for GC and mappability bias; overlay the resulting logR onto the het positions and log-transform; filter; then run the EM and sweep the cluster number — model selection picks the best.

```r
library(TitanCNA)

# Allele counts at het SNPs.
data <- loadAlleleCounts('tumour.allelicCounts.tsv', genomeStyle = 'UCSC')

# Read-depth correction is mandatory: correctReadDepth needs tumour + normal coverage
# WIGs and GC + mappability WIGs. genomeStyle MUST match loadAlleleCounts above
# (default 'NCBI' vs 'UCSC') or getPositionOverlap matches no chromosomes and logR is NA.
cnData <- correctReadDepth('tumour.wig', 'normal.wig', 'gc.wig', 'map.wig',
                           genomeStyle = 'UCSC')
data$logR <- log(2 ^ getPositionOverlap(data$chr, data$posn, cnData))
data <- filterData(data, 1:24, minDepth = 10, maxDepth = 200, map = NULL)

params <- loadDefaultParameters(copyNumber = 8, numberClonalClusters = 2,
                                symmetric = TRUE, data = data)
conv <- runEMclonalCN(data, params, maxiter = 20, txnExpLen = 1e15)
results <- viterbiClonalCN(data, conv)
# Sweep numberClonalClusters (1..5) and compare model fit; the S_Dbw validity index
# or the model log-likelihood selects the cluster number.
```

## Failure Modes

### Subclonal call from insufficient depth or purity

**Trigger:** Calling subclonal CN on shallow WGS or a low-purity tumor.

**Mechanism:** A subclonal segment's signal is the clonal deviation scaled by the subclone's cell fraction — already small, and below the noise floor at low depth/purity.

**Symptom:** Many "subclonal" segments with implausibly low fractions; calls not reproducible across reruns or regions.

**Fix:** Battenberg's ~3%-of-cells sensitivity assumes adequate WGS depth and purity. For low-depth or low-purity samples, treat only clonal CN as reliable and report subclonal calls as exploratory.

### Mirrored subclonal allelic imbalance misread

**Trigger:** A region where different subclones lost opposite haplotypes.

**Mechanism:** Bulk BAF averages the two opposite losses toward 0.5, so the region can look balanced (clonal, no LOH) when it is in fact subclonally rearranged on both haplotypes.

**Symptom:** A segment called clonal-balanced that conflicts with multi-region or single-cell data; BAF near 0.5 with an odd logR.

**Fix:** Phasing (Battenberg) is required to detect mirrored subclonal allelic imbalance. Multi-region or single-cell data resolves it def