Bio Clinical Databases Tumor Mutational Burden

Version Compatibility

Reference examples tested with: cyvcf2 0.30+, VEP 111+ (or snpEff 5.2+), pandas 2.2+, numpy 1.26+, LOHHLA 1.0+ (McGranahan 2017), DASH 1.0+ (Pyke 2022). v4.1 (May 2024) gnomAD is current for germline subtraction. Friends of Cancer Research TMB harmonization framework (Vega 2021 Ann Oncol) and ESMO 2024 (Mosele Ann Oncol) define the operational thresholds.

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying. TMB calculation requires VCF with VEP / snpEff / Funcotator consequence annotations; the panel size used as denominator MUST match the assay's actual scored region, NOT the panel's total content.

Tumor Mutational Burden; Calculation, Harmonization, ICI Eligibility

'Calculate TMB from this somatic VCF and apply ICI eligibility cutoff' -> Count nonsynonymous coding variants passing VAF/depth/germline filters; divide by assay scored region in Mb; apply assay-calibrated TMB-H cutoff; integrate with MSI / HLA-LOH / neoantigen quality.

• Python: cyvcf2.VCF() + VEP/snpEff consequence parsing + panel-size normalization
• CLI: bcftools view filtering + custom counting
• HLA-LOH: LOHHLA (McGranahan 2017 Cell) or DASH (Pyke 2022 Nat Commun)
• Neoantigen quality: pVAC-tools, NetMHCpan-4.1, Luksza 2017 fitness model

Regulatory and Trial Landscape

Friends of Cancer Research Harmonization: Cross-Panel Calibration

Merino 2020 J Immunother Cancer: in silico panel sampling from TCGA WES truth showed panel-specific TMB can differ 3-fold for identical samples. Vega 2021 Ann Oncol derived per-panel calibration equations to translate panel TMB to WES-aligned TMB-Mb.

Per-panel calibration to FoundationOne 10/Mb sensitivity:

TMB =/= TMB across vendors. Manuscripts that compare TMB across panels without per-assay calibration are unreviewable. Use the Vega 2021 calibration equations or WES re-projection.

Variant-Counting Subtleties

These choices alter TMB by 5-20%:

Hypermutator Tiering

MSI-H typically 30-50 mut/Mb; pure POLE-exo P286R 100-300 mut/Mb; POLE-exo + MMR-D exceeds 500. MSI-H and TMB-H overlap substantially (~83% of MSI-H are TMB-H) but only ~16% of TMB-H solid tumors are MSI-H (Chalmers 2017 Genome Med 9:34).

The Tumor-Type-Specific Cutoff Debate

McGrail 2021 Ann Oncol is the most damning paper for the universal 10/Mb cutoff. TMB-H predicts ICI response in melanoma, NSCLC, bladder; but FAILS in breast, prostate, glioma. ORR in TMB-H melanoma/NSCLC/bladder was 39.8%; TMB-H breast/prostate/glioma was 15.3%. Mechanistic explanation: TMB only predicts when baseline CD8 T-cell infiltrate is present.

Sha 2020 Cancer Discov: TMB-H predicts ICI benefit in MSS subset but adds nothing on top of MSI-H (because MSI-H is uniformly hypermutator and uniformly responsive).

Samstein 2019 Nat Genet (MSK-IMPACT 1,662 ICI-treated): cancer-specific TMB cutoffs (top 20% within each tumor type) outperform universal 10/Mb.

ESMO 2024 retained TMB-H >= 10/Mb pan-tumor (tumour-agnostic, ESCAT IB). The tumour-type limits (poor performance in breast, prostate, glioma) come from McGrail 2021, not ESMO.

Blood TMB (bTMB): The Negative-Trial Story

Gandara 2018 Nat Med: bTMB on Foundation Medicine FoundationACT panel; POPLAR + OAK retrospective. bTMB >= 16 mut/Mb showed PFS benefit with atezolizumab in NSCLC.

B-F1RST (Kim 2022): prospective phase 2 test of bTMB >= 16 as a first-line atezolizumab predictor in NSCLC; did NOT meet its pre-specified primary endpoint (bTMB-H improved ORR 28.6% vs 4.4%, only a non-significant PFS/OS trend).

BFAST Cohort C (Peters 2022): FAILED primary endpoint; atezolizumab vs chemo in bTMB-H NSCLC did not improve investigator-assessed PFS. Dominant confounder: low ctDNA shed fraction produces false-negative bTMB.

Operational state: bTMB is research-grade in tissue-naive settings; tissue TMB remains the regulatory standard.

Neoantigen Quality: Beyond Raw TMB

Luksza 2017 Nature: neoantigen fitness model. Combines "non-selfness" (TCR recognition probability via IEDB similarity) + "selfness" (MHC binding affinity differential vs WT peptide). Pancreatic-cancer validation (Balachandran 2017 Nature): long-term survivors had higher-quality neoantigens. Luksza 2022 Nature: immunoediting over 10 years.

McGranahan 2016 Science: clonal neoantigen burden (mutations present in all tumor cells) predicts ICI response better than total. Subclonal-rich tumors evade despite high TMB.

HLA-LOH (McGranahan 2017 Cell, LOHHLA; Pyke 2022 Nat Commun, DASH; Montesion 2021 Cancer Discov for the ~17% pan-cancer estimate): HLA-LOH occurs in ~40% of NSCLC and abolishes neoantigen presentation for the lost allele. ~17% pan-cancer; >30% in HNSCC / NSCLC / cervical. Co-occurs with high subclonal burden + APOBEC + immune escape.

Decision Tree by Scenario

Standard Workflow

Goal: Compute TMB from a VEP-annotated somatic VCF with full filtering.

Approach: Parse cyvcf2; apply VAF + depth + germline (gnomAD) filters; count nonsynonymous coding consequences; divide by scored Mb.

from cyvcf2 import VCF
import re

NONSYNONYMOUS_CONSEQUENCES = {
    'missense_variant', 'stop_gained', 'stop_lost', 'start_lost', 'start_retained',
    'frameshift_variant', 'inframe_insertion', 'inframe_deletion',
    'splice_donor_variant', 'splice_acceptor_variant',
    'protein_altering_variant', 'initiator_codon_variant'
}

# Vega 2021-calibrated scored regions (Mb)
PANEL_SCORED_REGION = {
    'FoundationOne_CDx': 0.8,           # Scored region; NOT 1.1 panel total
    'MSK_IMPACT_v3': 0.98,
    'MSK_IMPACT_v4': 1.22,
    'TSO500': 1.3,                       # Scored from 1.94 total
    'Oncomine_TML': 1.2,
    'Caris_MI': 1.2,
    'Tempus_xT_v3': 0.6,                 # Borderline reliability
    'WES': 30.0,
    'WGS': 3000.0
}

# TMB2 (Ramos-Paradas 2021) equivalent thresholds for FDA 10/Mb FoundationOne sensitivity
ASSAY_TMB_H_CUTOFF = {
    'FoundationOne_CDx': 10.0,
    'TSO500': 7.8,
    'Oncomine_TML': 8.4,
    'MSK_IMPACT_v3': 10.0,  # Approximate; full Vega 2021 calibration recommended
    'MSK_IMPACT_v4': 10.0,
    'WES': 10.0
}


def parse_consequences_from_vep(csq_field, csq_header):
    '''Parse VEP CSQ INFO field; returns list of per-transcript consequence types.'''
    if not csq_field:
        return []
    cons_idx = csq_header.index('Consequence')
    out = []
    for transcript in csq_field.split(','):
        fields = transcript.split('|')
        if len(fields) > cons_idx:
            out.append(fields[cons_idx])
    return out


def is_nonsynonymous(consequences, include_synonymous=False):
    '''Check if variant has nonsynonymous coding consequence.

    FoundationOne CDx convention INCLUDES synonymous (set include_synonymous=True).
    MSK-IMPACT and most academic pipelines exclude.
    '''
    target = set(NONSYNONYMOUS_CONSEQUENCES)
    if include_synonymous:
        target.add('synonymous_variant')
    for cons_str in consequences:
        for cons in cons_str.split('&'):
            if cons in target:
                return True
    return False


def calculate_tmb(vcf_path, scored_region_mb, csq_header,
                   min_vaf=0.05, min_depth=100, max_gnomad_af=0.005,
                   include_synonymous=False, exclude_hotspots=True,
                   hotspot_bed=None):
    '''Calculate TMB with filtering per Vega 2021 harmonization.

    Args:
        scored_region_mb: panel's SCORED region (NOT total panel)
        min_vaf: 0.05 (FoundationOne) to 0.10 (tumor-only no UMI)
        max_gnomad_af: 0.005 (0.5%) typical for tumor-only germline filter
        include_synonymous: True for FoundationOne CDx-compatible; False for MSK-IMPACT
        exclude_hotspots: COSMIC drivers excluded (not random mutations)
    '''
    vcf = VCF(vcf_path)
    cons_idx = csq_header.index('Consequence') if 'Consequence' in csq_header else 1
    nonsyn_count = 0
    total_pass = 0

    for v in vcf:
        if v.FILTER is not None:  # FILTER == None means PASS in cyvcf2
            continue
        depth = v.INFO.get('DP', 0)
        if depth < min_depth:
            continue
        vaf = _get_vaf(v)
        if vaf is None or vaf < min_vaf:
            continue
        gnomad_af = v.INFO.get('gnomAD_AF', 0) or v.INFO.get('AF_popmax', 0) or 0
        if gnomad_af > max_gnomad_af:
            continue
        total_pass += 1

        csq = v.INFO.get('CSQ', '')
        consequences = parse_consequences_from_vep(csq, csq_header)
        if is_nonsynonymous(consequences, include_synonymous=include_synonymous):
            nonsyn_count += 1

    tmb = nonsyn_count / scored_region_mb
    return {
        'tmb': round(tmb, 2),
        'nonsynonymous_count': nonsyn_count,
        'total_passing_filters': total_pass,
        'scored_region_mb': scored_region_mb
    }


def _get_vaf(variant):
    '''Extract VAF from genotype FORMAT fields (Mutect2 AD or AF).'''
    try:
        ad = variant.format('AD')
        if ad is not None and len(ad) > 0:
            ad0 = ad[0]
            total = sum(ad0)
            return ad0[1] / total if total > 0 else None
    except Exception:
        pass
    try:
        af = variant.format('AF')
        if af is not None and len(af) > 0:
            return float(af[0])
    except Exception:
        pass
    return None


def classify_tmb(tmb_value, assay='FoundationOne_CDx'):
    '''Apply ESMO 2024 / FDA pembrolizumab cutoff with Vega 2021 calibration per assay.'''
    cutoff = ASSAY_TMB_H_CUTOFF.get(assay, 10.0)
    if tmb_value >= 500:
        category = 'Ultra-hypermutator (>=500/Mb; POLE+MMR likely)'
    elif tmb_value >= 100:
        category = 'Hypermutator (>=100/Mb; MMR-D or POLE)'
    elif tmb_value >= cutoff:
        category = f'TMB-H (>= {cutoff}/Mb {assay}-calibrated; pan-tumor ICI eligible per FDA 2020)'
    else:
        category = 'TMB-low'
    return category

TMB-MSI Concordance and Reconciliation

Goal: When MSI-H is present, TMB-H adds no information (Sha 2020).

def tmb_msi_reconcile(tmb_value, msi_status, tumor_type=None):
    '''Reconcile TMB + MSI for ICI decision.'''
    tmb_high = tmb_value >= 10
    msi_high = msi_status == 'MSI-H'

    if msi_high:
        return ('ICI eligible by MSI-H (FDA 2017 pembrolizumab); TMB-H adds no information '
                '(Sha 2020 Cancer Discov).')
    if tmb_high and tumor_type in ('breast', 'prostate', 'glioma'):
        return ('TMB-H present but does not enrich ICI response in this tumor type (McGrail 2021). '
                'Tumor-specific cutoffs recommended.')
    if tmb_high:
        return ('TMB-H pan-tumor; ICI eligible (FDA pembrolizumab 2020). '
                'Confirm baseline CD8 infiltrate; check HLA-LOH (McGranahan 2017 LOHHLA).')
    return 'TMB-low; MSS. Standard-of-care chemo.'

Per-Operation Failure Modes

1. Using panel total size as denominator (NOT scored region)

• Trigger: Compute TMB = nonsynonymous count / 1.1 Mb for FoundationOne.
• Mechanism: FoundationOne CDx total panel is 1.1 Mb; SCORED region (counted for TMB denominator) is 0.8 Mb.
• Symptom: TMB underestimated by ~37%.
• Fix: Use 0.8 Mb for FoundationOne CDx scored region per Vega 2021.

2. Cross-panel comparison without calibration

• Trigger: TSO500 reports TMB = 9.5; compared to FoundationOne 10/Mb cutoff.
• Mechanism: the TMB2 project (Ramos-Paradas 2021) showed the equivalent threshold is 7.8/Mb on TSO500 (not 10/Mb).
• Symptom: TSO500 TMB-H called positive at incorrect threshold.
• Fix: Apply assay-specific calibration; the TSO500 equivalent cutoff = 7.8/Mb (Ramos-Paradas 2021).

3. FoundationOne synonymous mis-handling

• Trigger: Compare academic pipeline (no synonymous) to FoundationOne reference (synonymous included).
• Mechanism: FoundationOne CDx counts synonymous; MSK-IMPACT and most academic pipelines exclude.
• Symptom: Academic pipeline TMB systematically lower than FoundationOne by ~10-20%.
• Fix: Match the counting convention to the comparison reference; document explicitly.

4. Tumor-only TMB inflated

• Trigger: Tumor-only WES with naive germline filter (gnomAD AF > 1%).
• Mechanism: Population-specific common variants leak through if gnomAD AF threshold not stratified by ancestry.
• Symptom: AFR/EAS patient TMB inflated 1.5-3x; misclassified as TMB-H.
• Fix: Stratify gnomAD AF by patient ancestry; use grpmax FAF95; threshold <= 0.5%.

5. bTMB applied without ctDNA shed check

• Trigger: Report bTMB low in a metastatic patient.
• Mechanism: Low ctDNA shed fraction produces false-negative bTMB (BFAST Cohort C failure mechanism).
• Symptom: Patient with high tissue TMB labeled bTMB-low; ICI not offered.
• Fix: Check tumor fraction (e.g., ichorCNA, MAF of known driver) before trusting bTMB-low; consider tissue TMB.

6. TMB-H applied to breast / prostate / glioma

• Trigger: ICI prescribed for TMB-H breast cancer based on pan-tumor approval.
• Mechanism: McGrail 2021 demonstrated TMB fails to enrich for ICI response in breast, prostate, glioma.
• Symptom: ICI offered with low expectation of benefit; patient bears unnecessary toxicity.
• Fix: Apply tumor-type-specific cutoffs (Samstein 2019); document the McGrail 2021 tumor-type caveat in report.

7. Hotspots inflating TMB

• Trigger: Include BRAF V600E and KRAS G12C in TMB count.
• Mechanism: Driver hotspots are non-random; including biases TMB upward in driver-mutated samples.
• Symptom: TMB inflated in samples with strong drivers.
• Fix: Exclude COSMIC-confirmed hotspots (provide hotspot BED).

8. MSI-H -> add TMB-H -> additive ICI confidence

• Trigger: Report TMB-H as additional support for ICI in MSI-H patient.
• Mechanism: MSI-H is uniformly hypermutator + uniformly ICI-responsive; adding TMB-H is statistical tautology (Sha 2020).
• Symptom: Reviewer flag.
• Fix: Report MSI-H + TMB-H concurrence but explicitly note TMB-H is NOT additive given MSI-H.

9. Ignoring HLA-LOH

• Trigger: TMB-H + neoantigen prediction without LOH check.
• Mechanism: HLA-LOH abolishes neoantigen presentation for lost allele in ~17% pan-cancer (>30% HNSCC / NSCLC / cervical).
• Symptom: Apparent neoantigen burden inflated.
• Fix: Run LOHHLA (McGranahan 2017) or DASH (Pyke 2022); flag HLA-LOH-positive tumors.