bio-data-visualization-oncoprint-mutation-matrices

name	bio-data-visualization-oncoprint-mutation-matrices
description	Build OncoPrint and co-mutation matrix plots from somatic-variant cohorts using ComplexHeatmap, maftools, and comut.py with alteration-type stacking, sample ordering by mutational burden, mutual-exclusivity overlays, and clinical annotation tracks. Use when visualizing per-sample mutation patterns across recurrent driver genes, comparing alteration classes, or identifying mutually-exclusive / co-occurring driver pairs.
origin	openai4s
category	bioskills/data-visualization
metadata	{"tool_type":"mixed","primary_tool":"ComplexHeatmap","third_party":{"name":"GPTomics/bioSkills","repository":"https://github.com/GPTomics/bioSkills","commit":"d91ed3d563019e649dc854c56ccd62551359488a","license":"MIT"}}

Version Compatibility

Reference examples tested with: ComplexHeatmap 2.18+, maftools 2.18+, comut 0.0.3+, MAFtools requires R 4.0+; comut.py requires pandas 2.0+, matplotlib 3.8+.

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

• Python: pip show <package> then help(module.function) to check signatures
• R: packageVersion('<pkg>') then ?function_name

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

OncoPrint and Mutation Matrix Plots

"Plot mutations across a cohort" -> Render a gene-by-sample matrix where each cell stacks colored rectangles encoding alteration class (missense, truncating, splice, copy-gain, copy-loss, fusion). Sort samples by burden, optionally split by clinical group, and overlay co-mutation / mutual-exclusivity annotations. OncoPrint (Cerami 2012 Cancer Discov 2:401; canonical at cBioPortal) is the genre-defining visualization.

• R: ComplexHeatmap::oncoPrint, maftools::oncoplot
• Python: comut.CoMut, cbioportal-style implementations

The Single Most Important Modern Insight -- Cell Stacking Encodes Multiple Alterations Per Cell

OncoPrint differs from a generic heatmap because each cell can encode multiple alterations simultaneously through stacked rectangles. A patient with both a missense and a copy-gain in TP53 shows one cell with two overlapping colored rectangles (e.g., green diamond inside red square). This stacking is the whole point — it preserves the multi-modal alteration landscape that flattening to a single category destroys.

In ComplexHeatmap's oncoPrint, the alter_fun argument is the rendering specification: a named list of functions, one per alteration class, each drawing its rectangle inside the cell. Get this right and the figure works; get it wrong and overlapping alterations are invisible.

Decision Tree by Cohort and Question

Question	Sort by	Display
Which genes are most altered?	Gene frequency (default)	Bar above samples (sample TMB); bar right of genes (gene frequency)
Per-patient burden patterns	Sample burden	TMB bar on top; sample-name labels
Subtype-driver enrichment	Clinical group then burden	column_split by group; per-group frequency right bar
Mutual exclusivity (BRAF vs NRAS)	Custom (alphabetic-by-mutation pattern)	Memo sort; overlay log10(OR) heatmap
Co-occurrence (TP53 + MYC)	Custom	Same pattern; positive OR coloring
Driver vs passenger comparison	Two panels	Concatenate two oncoPrints horizontally

ComplexHeatmap::oncoPrint -- Canonical Implementation

Goal: Render a cohort mutation matrix with stacked alteration-class encoding, sample annotations, and a sample-sorted, gene-frequency-ranked layout.

Approach: Convert the MAF/variant table to a gene-by-sample matrix of ;-delimited alteration strings; define alter_fun rendering one rectangle per class; pass to oncoPrint() with column annotations.

library(ComplexHeatmap)
library(circlize)

# Input: matrix where each cell is a string like 'Missense;Amp' or '' for no alteration
# Rows = genes; columns = samples

# Color per alteration class
col <- c('Missense'   = '#56B4E9',
         'Truncating' = '#000000',
         'Splice'     = '#CC79A7',
         'Amp'        = '#D55E00',
         'HomDel'     = '#0072B2',
         'Fusion'     = '#009E73')

# alter_fun -- one function per class, each drawing inside the cell
alter_fun <- list(
    background = function(x, y, w, h)
        grid.rect(x, y, w - unit(0.5, 'mm' h  unit 
                  gp  gparfill   col  
    Amp  x y w h
        grid.rectx y w  unit  h  unit 
                  gp  gparfill  col col  
    HomDel  x y w h
        grid.rectx y w  unit  h  unit 
                  gp  gparfill  col col  
    Missense  x y w h
        grid.rectx y w  unit  h  
                  gp  gparfill  col col  
    Truncating  x y w h
        grid.rectx y w  unit  h  
                  gp  gparfill  col col  
    Splice  x y w h
        grid.rectx y w  unit  h  
                  gp  gparfill  col col  
    Fusion  x y w h
        grid.pointsx y pch   size  unit 
                    gp  gparcol  col


ha_clin  HeatmapAnnotation
    Subtype  clinicalsubtype
    Stage    clinicalstage
    col  Subtype  Luminal Basal HER2
               Stage    I II III IV

oncoPrintmat
          alter_fun  alter_fun
          col  col
          top_annotation  ha_clin
          column_title  
          row_names_gp  gparfontsize  
          pct_gp  gparfontsize  
          show_pct  
          remove_empty_columns  
          remove_empty_rows  

maftools::oncoplot -- Faster Onboarding

For TCGA-style MAF files, maftools::oncoplot is the lower-friction option:

library(maftools)
maf <- read.maf(maf = 'tcga.maf', clinicalData = clinical)
oncoplot(maf = maf,
         top = 20,                            # top 20 mutated genes
         clinicalFeatures = c('Subtype', 'Stage'),
         annotationColor = list(Subtype = c(Luminal='#0072B2', Basal='#D55E00'),
                                 Stage = c(I='#FFFFCC', IV='#BD0026')),
         sortByAnnotation = TRUE,
         removeNonMutated = FALSE)

maftools defaults handle alteration-class colors, sample sorting, and percentage bars automatically. Customization is more limited than ComplexHeatmap.

Mutual Exclusivity and Co-Occurrence

# maftools provides somaticInteractions
si <- somaticInteractions(maf = maf, top = 20,
                          pvalue = c(0.05, 0.01),
                          fontSize = 0.7)
# Plot returns a matrix of -log10(p) with sign by direction (+ co-occur, - mutex)

Mutual-exclusivity testing on small cohorts (N < 50) is underpowered; reported "significant" mutex on n=20 with 2 mutations each is uninterpretable. Aggregate to larger cohorts (TCGA + ICGC pan-cancer) or report effect size with CI rather than p-value.

Fisher exact vs DISCOVER: standard 2x2 Fisher tests sample-mutation pairs, ignoring per-gene mutation rate background. DISCOVER (Canisius 2016 Genome Biol 17:261) models per-tumor mutation probability and is preferred for pan-cancer analyses where mutation rate varies 100× across samples.

comut.py -- Python Equivalent

import comut
import pandas as pd

# Long-format: columns = sample, category (gene), value (alteration class)
toy_comut = comut.CoMut()
toy_comut.add_categorical_data(
    data=mutation_long_df,
    name='Mutations',
    category_order=top_genes,
    value_order=['Truncating', 'Missense', 'Splice', 'Amp', 'HomDel'],
    mapping={'Truncating': '#000000', 'Missense': '#56B4E9',
             'Splice': '#CC79A7', 'Amp': '#D55E00', 'HomDel': '#0072B2'})

toy_comut.add_categorical_data(
    data=clinical_long_df,
    name='Subtype',
    mapping={'Luminal': '#0072B2', 'Basal': '#D55E00'})

toy_comut.add_continuous_data(
    data=tmb_long_df,
    name='TMB',
    mapping='viridis',
    value_range=(0, 30))

toy_comut.plot_comut(figsize=(12, 8))
toy_comut.figure.savefig('comut.pdf', dpi=300, bbox_inches='tight')

Per-Method Failure Modes

Alterations flattened to a single class

Trigger: Reducing each cell to a single most-severe alteration, losing the stack.

Mechanism: Loses the multi-alteration biology (e.g., MYC amp + missense in TP53).

Symptom: OncoPrint looks like a simple heatmap; co-occurring multi-class events invisible.

Fix: Build the cell as ;-separated alteration string; define alter_fun for each class.

Sample sort by gene 1 frequency only

Trigger: Default oncoPrint sorts samples by altered-gene-1 status; weakens the "memo sort" pattern.

Mechanism: True OncoPrint uses memoSort (Cerami 2012) which sorts by the binary altered-or-not pattern across the top genes.

Symptom: Samples with the same alteration profile are not adjacent; "staircase" pattern lost.

Fix: ComplexHeatmap oncoPrint uses memoSort by default; do NOT override column_order unless intentional.

Showing only mutated samples (remove_empty_columns = TRUE)

Trigger: Default in some implementations.

Mechanism: Drops samples with no mutations in the displayed genes — but those samples ARE part of the cohort.

Symptom: Sample count differs from cohort N; denominator-based percentages wrong.

Fix: remove_empty_columns = FALSE to preserve all samples; percentages now reflect true cohort fraction.

Hypermutators dominate visual

Trigger: Cohort with 1-2 POLE-mutant or MSI-H samples; TMB bar saturates.

Mechanism: Hypermutator TMB is 10-100× the typical sample.

Symptom: All other samples' TMB bars are invisible; one column dominates.

Fix: Log-transform the TMB annotation: anno_barplot(log10(tmb + 1)); OR cap with ylim.

Mutex/co-occurrence p-values overinterpreted on small cohorts

Trigger: Fisher exact test on N < 50 with low mutation counts.

Mechanism: With 2 mutations vs 3 mutations in 20 samples, all p-values are dominated by noise.

Symptom: "Significant mutex" claim from a tiny pilot.

Fix: Aggregate to ≥100 samples for credible mutex; use DISCOVER (Canisius 2016) instead of Fisher when mutation rate varies 100× across samples.

Small-Cohort Regime (N = 20-50)

For rare-cancer cohorts where N < 50, the standard OncoPrint + Fisher mutex pipeline is statistically uninterpretable:

Action	What to do
Report per-gene frequencies	Use exact-binomial CI (Clopper-Pearson via binom.test) — Wald CI is invalid at low frequency
Do NOT report mutex p-values	Fisher exact on 2x2 with cell counts ≤ 5 has no power; the "significant" mutex finding is noise
Hypothesis generation only	Pool with TCGA Pan-Cancer + ICGC for credible mutex; treat the cohort as the replication not the discovery
Co-occurrence reporting	OR with Haldane-Anscombe 0.5 correction for zero cells; report alongside cohort N

Show the OncoPrint for visual transparency, but the per-gene-frequency table (with exact-binomial CIs) is the load-bearing scientific output, not the mutex test.

Reconciliation: When Implementations Differ

Pattern	Cause	Action
ComplexHeatmap and maftools show different sample orders	Different memoSort defaults	Specify sortByAnnotation explicitly; report sort criterion in caption
Percentage labels differ	remove_empty_columns = TRUE vs FALSE	Document denominator (cohort-N vs altered-N)
Some alterations missing from a sample	Filtering: silent SNVs, low VAF	Document filtering criteria upstream

Quantitative Thresholds

Threshold	Value	Source
Cohort N for valid mutex	≥100 (pan-cancer); ≥50 (single-cohort with effect-size focus)	Common practice
Display top genes	10-25 in single panel	More creates visual clutter
Sample N for OncoPrint	50-1000 (above: switch to summary panel)	Visualization practical

Common Errors

Error / symptom	Cause	Solution
Co-occurring multi-class events invisible	Single-class flattening	Use ;-separated cells + alter_fun list
Sample order doesn't show staircase	column_order override	Trust default memoSort
Sample count differs from cohort	remove_empty_columns = TRUE	Set to FALSE
TMB bar dominated by 1-2 samples	Hypermutators on linear scale	log10 + 1 transform
Mutex p-values on N=20	Underpowered	Aggregate cohorts; use DISCOVER
Gene frequency right-bar mismatches percentages	Denominator definition	Document cohort-N vs altered-N

References

• Canisius S, Martens JWM, Wessels LFA. 2016. A novel independence test for somatic alterations in cancer shows that biology drives mutual exclusivity but chance explains most co-occurrence. Genome Biol 17:261.
• Cerami E, Gao J, Dogrusoz U, et al. 2012. The cBio cancer genomics portal: an open platform for exploring multidimensional cancer genomics data. Cancer Discov 2(5):401-404.
• Gao J, Aksoy BA, Dogrusoz U, et al. 2013. Integrative analysis of complex cancer genomics and clinical profiles using the cBioPortal. Sci Signal 6(269):pl1.
• Gu Z, Eils R, Schlesner M. 2016. Complex heatmaps reveal patterns and correlations in multidimensional genomic data. Bioinformatics 32(18):2847-2849.
• Mayakonda A, Lin DC, Assenov Y, Plass C, Koeffler HP. 2018. Maftools: efficient and comprehensive analysis of somatic variants in cancer. Genome Res 28(11):1747-1756.

Related Skills

• data-visualization/heatmaps-clustering - Generic heatmap underlying oncoPrint
• data-visualization/lollipop-protein-maps - Per-gene mutation maps on protein domains
• data-visualization/color-palettes - Alteration-class palette selection
• clinical-databases/variant-prioritization - Filter variants before OncoPrint
• variant-calling/variant-annotation - Annotate consequences upstream
• copy-number/cnv-annotation - Integrate CNV calls into the oncoprint