CoMut Plot Example¶

This notebook demonstrates the CoMut plot, a sample-centric multi-panel visualization that integrates multiple genomic and clinical features. Columns represent individual samples, and rows represent different data tracks (mutation burden, signatures, purity, gene mutations, copy number alterations, etc.).

For detailed documentation, see the CoMut Plot API Reference.

Load Data¶

Load the MAF file and create a PyMutation object.

In [1]:

from pyMut.input import read_maf

maf_path = "../../../src/pyMut/data/examples/MAF/TCGA_test.maf"
print(f'📂 Loading file: {maf_path}')

# Read the MAF file (CoMut filtering is applied automatically during visualization)
py_mutation = read_maf(maf_path, assembly="37", consolidate_variants=False)

from pyMut.input import read_maf maf_path = "../../../src/pyMut/data/examples/MAF/TCGA_test.maf" print(f'📂 Loading file: {maf_path}') # Read the MAF file (CoMut filtering is applied automatically during visualization) py_mutation = read_maf(maf_path, assembly="37", consolidate_variants=False)

2025-11-27 01:53:48,494 | INFO | pyMut.input | Starting MAF reading: ../../../src/pyMut/data/examples/MAF/TCGA_test.maf
2025-11-27 01:53:48,495 | INFO | pyMut.input | Loading from cache: ../../../src/pyMut/data/examples/MAF/.pymut_cache/TCGA_test_f7aef517091725ed.parquet
2025-11-27 01:53:48,495 | INFO | pyMut.input | Loading from cache: ../../../src/pyMut/data/examples/MAF/.pymut_cache/TCGA_test_f7aef517091725ed.parquet

📂 Loading file: ../../../src/pyMut/data/examples/MAF/TCGA_test.maf

2025-11-27 01:53:49,232 | INFO | pyMut.input | Cache loaded successfully in 0.74 seconds

Configure Plot Settings¶

Enable high-quality rendering settings for publication-ready figures.

In [2]:

py_mutation.configure_high_quality_plots()

py_mutation.configure_high_quality_plots()

Define Sample and Gene Order¶

All CoMut panels must share the same sample order for proper visual alignment. We also define gene orders for the mutation type and CNA panels.

In [3]:

import pandas as pd
from pathlib import Path

# Load sample order from reference file
ref_mb = pd.read_csv(Path("../../../src/pyMut/data/examples/TSV/mutation_burden.tsv"), sep="\t")
sample_col = next(c for c in ref_mb.columns if c.lower() in {"sample", "sample_id", "tumor_sample_barcode"})
sample_order = ref_mb[sample_col].astype(str).tolist()

# Define gene orders for Panels D and E
gene_order = ["MAP3K1", "CDH1", "TP53", "PIK3CA"]
cna_gene_order = ["ERBB2", "CDKN2A", "MYC"]

# Define paths to external data files
sig_tsv_path = "../../../src/pyMut/data/examples/TSV/sig_contribution.tsv"
purity_tsv_path = "../../../src/pyMut/data/examples/TSV/purity.tsv"
mutation_data_tsv_path = "../../../src/pyMut/data/examples/TSV/mutation_data.tsv"
cna_tsv_path = "../../../src/pyMut/data/examples/TSV/cna.tsv"
wgd_tsv_path = "../../../src/pyMut/data/examples/TSV/wgd.tsv"
sp_tsv_path = "../../../src/pyMut/data/examples/TSV/sp.tsv"

import pandas as pd from pathlib import Path # Load sample order from reference file ref_mb = pd.read_csv(Path("../../../src/pyMut/data/examples/TSV/mutation_burden.tsv"), sep="\t") sample_col = next(c for c in ref_mb.columns if c.lower() in {"sample", "sample_id", "tumor_sample_barcode"}) sample_order = ref_mb[sample_col].astype(str).tolist() # Define gene orders for Panels D and E gene_order = ["MAP3K1", "CDH1", "TP53", "PIK3CA"] cna_gene_order = ["ERBB2", "CDKN2A", "MYC"] # Define paths to external data files sig_tsv_path = "../../../src/pyMut/data/examples/TSV/sig_contribution.tsv" purity_tsv_path = "../../../src/pyMut/data/examples/TSV/purity.tsv" mutation_data_tsv_path = "../../../src/pyMut/data/examples/TSV/mutation_data.tsv" cna_tsv_path = "../../../src/pyMut/data/examples/TSV/cna.tsv" wgd_tsv_path = "../../../src/pyMut/data/examples/TSV/wgd.tsv" sp_tsv_path = "../../../src/pyMut/data/examples/TSV/sp.tsv"

Complete Multi-Panel CoMut Plot¶

The create_comut_plot() function generates a complete multi-panel visualization combining all seven panels (A-G) into a single vertically stacked figure with perfect sample alignment.

Key Parameters:

• sample_order: List of sample IDs for all panels alignment
• gene_order: List of gene names for Panel D (mutation type)
• cna_gene_order: List of gene names for Panel E (CNA)
• signatures_tsv: Path to TSV file for Panel B
• purity_tsv: Path to TSV file for Panel C
• mutation_data_tsv: Path to TSV file for Panel D
• cna_tsv: Path to TSV file for Panel E
• wgd_tsv: Path to TSV file for Panel F
• sp_tsv: Path to TSV file for Panel G
• territory_bp: Territory size in bp for TMB calculation. Default: 60456963
• figsize: Overall figure size. Default: auto-calculated

In [4]:

py_mutation.create_comut_plot(
    sample_order=sample_order,
    gene_order=gene_order,
    cna_gene_order=cna_gene_order,
    signatures_tsv=sig_tsv_path,
    purity_tsv=purity_tsv_path,
    mutation_data_tsv=mutation_data_tsv_path,
    cna_tsv=cna_tsv_path,
    wgd_tsv=wgd_tsv_path,
    sp_tsv=sp_tsv_path,
    territory_bp=60456963,
    somatic_only=False,
    pass_only=False,
    signature_labels=["Signature 1", "Signature 2", "Signature 3", "Signature 4"],
    figsize=(14, 14.9),
    max_samples=None
)

py_mutation.create_comut_plot( sample_order=sample_order, gene_order=gene_order, cna_gene_order=cna_gene_order, signatures_tsv=sig_tsv_path, purity_tsv=purity_tsv_path, mutation_data_tsv=mutation_data_tsv_path, cna_tsv=cna_tsv_path, wgd_tsv=wgd_tsv_path, sp_tsv=sp_tsv_path, territory_bp=60456963, somatic_only=False, pass_only=False, signature_labels=["Signature 1", "Signature 2", "Signature 3", "Signature 4"], figsize=(14, 14.9), max_samples=None )

2025-11-27 01:53:49,266 | INFO | pyMut.visualizations.comut_plot | Creating complete CoMut plot (Panels A-G)
2025-11-27 01:53:49,324 | INFO | pyMut.visualizations.comut_plot | Reloading MAF with silent variants for CoMut: ../../../src/pyMut/data/examples/MAF/TCGA_test.maf
2025-11-27 01:53:49,324 | INFO | pyMut.visualizations.comut_plot | Reloading MAF with silent variants for CoMut: ../../../src/pyMut/data/examples/MAF/TCGA_test.maf
2025-11-27 01:53:51,591 | INFO | pyMut.visualizations.comut_plot | CoMut filter: kept 64,585 coding+silent variants, excluded 12,620 non-coding variants (RNA, Intron, IGR, etc.)
2025-11-27 01:53:51,591 | INFO | pyMut.visualizations.comut_plot | CoMut filter: kept 64,585 coding+silent variants, excluded 12,620 non-coding variants (RNA, Intron, IGR, etc.)
2025-11-27 01:53:51,658 | INFO | pyMut.visualizations.comut_plot | Removed 18,162 duplicate variants
2025-11-27 01:53:51,671 | INFO | pyMut.visualizations.comut_plot | TMB calculation: 46,423 coding variants from 46,423 total variants
2025-11-27 01:53:51,679 | INFO | pyMut.visualizations.comut_plot | Calculated TMB for 525 samples (range: 0.07-80.34 Muts/Mb)
2025-11-27 01:53:51,658 | INFO | pyMut.visualizations.comut_plot | Removed 18,162 duplicate variants
2025-11-27 01:53:51,671 | INFO | pyMut.visualizations.comut_plot | TMB calculation: 46,423 coding variants from 46,423 total variants
2025-11-27 01:53:51,679 | INFO | pyMut.visualizations.comut_plot | Calculated TMB for 525 samples (range: 0.07-80.34 Muts/Mb)
2025-11-27 01:53:51,782 | INFO | pyMut.visualizations.comut_plot | Panel A created in 2.46s
2025-11-27 01:53:51,782 | INFO | pyMut.visualizations.comut_plot | Panel A created in 2.46s
2025-11-27 01:53:52,036 | INFO | pyMut.visualizations.comut_plot | Panel B created in 0.12s
2025-11-27 01:53:52,036 | INFO | pyMut.visualizations.comut_plot | Panel B created in 0.12s
2025-11-27 01:53:52,182 | INFO | pyMut.visualizations.comut_plot | Panel C created in 0.01s
2025-11-27 01:53:52,182 | INFO | pyMut.visualizations.comut_plot | Panel C created in 0.01s
2025-11-27 01:53:52,500 | INFO | pyMut.visualizations.comut_plot | Panel D created in 0.26s
2025-11-27 01:53:52,500 | INFO | pyMut.visualizations.comut_plot | Panel D created in 0.26s
2025-11-27 01:53:52,704 | INFO | pyMut.visualizations.comut_plot | Panel E created in 0.08s
2025-11-27 01:53:52,704 | INFO | pyMut.visualizations.comut_plot | Panel E created in 0.08s
2025-11-27 01:53:52,850 | INFO | pyMut.visualizations.comut_plot | Panel F created in 0.04s
2025-11-27 01:53:52,850 | INFO | pyMut.visualizations.comut_plot | Panel F created in 0.04s
2025-11-27 01:53:53,019 | INFO | pyMut.visualizations.comut_plot | Panel G created in 0.11s
2025-11-27 01:53:53,019 | INFO | pyMut.visualizations.comut_plot | Panel G created in 0.11s
2025-11-27 01:53:53,060 | INFO | pyMut.visualizations.comut_plot | Complete CoMut plot created successfully in 3.79s
2025-11-27 01:53:53,060 | INFO | pyMut.visualizations.comut_plot | Complete CoMut plot created successfully in 3.79s

Out[4]:

Individual Panel Components¶

Each panel can also be generated independently. All panels share the same sample_order for proper alignment.

Panel A: Mutation Burden¶

Stacked bar chart showing mutation burden per sample (Muts/Mb). Dark blue represents non-synonymous mutations, light blue represents synonymous mutations.

Parameters:

• territory_bp: Territory size in bp for normalization. Default: 60456963
• sample_ids: List of sample IDs to include in specified order
• max_samples: Maximum samples to display. Default: 50
• somatic_only: Filter to somatic variants. Default: True
• pass_only: Filter to PASS variants. Default: True
• figsize: Figure size. Default: (14, 1.8)

In [5]:

py_mutation.comut_mutation_burden(
    somatic_only=False,  # TCGA LAML data doesn't have Variant_Status column
    pass_only=False,      # TCGA LAML data doesn't have FILTER column
    territory_bp=60456963,
    sample_ids=sample_order,
    max_samples=None
)

py_mutation.comut_mutation_burden( somatic_only=False, # TCGA LAML data doesn't have Variant_Status column pass_only=False, # TCGA LAML data doesn't have FILTER column territory_bp=60456963, sample_ids=sample_order, max_samples=None )

2025-11-27 01:53:55,091 | INFO | pyMut.visualizations.comut_plot | Reloading MAF with silent variants for CoMut: ../../../src/pyMut/data/examples/MAF/TCGA_test.maf
2025-11-27 01:53:57,163 | INFO | pyMut.visualizations.comut_plot | CoMut filter: kept 64,585 coding+silent variants, excluded 12,620 non-coding variants (RNA, Intron, IGR, etc.)
2025-11-27 01:53:57,163 | INFO | pyMut.visualizations.comut_plot | CoMut filter: kept 64,585 coding+silent variants, excluded 12,620 non-coding variants (RNA, Intron, IGR, etc.)
2025-11-27 01:53:57,228 | INFO | pyMut.visualizations.comut_plot | Removed 18,162 duplicate variants
2025-11-27 01:53:57,228 | INFO | pyMut.visualizations.comut_plot | Removed 18,162 duplicate variants
2025-11-27 01:53:57,241 | INFO | pyMut.visualizations.comut_plot | TMB calculation: 46,423 coding variants from 46,423 total variants
2025-11-27 01:53:57,249 | INFO | pyMut.visualizations.comut_plot | Calculated TMB for 525 samples (range: 0.07-80.34 Muts/Mb)
2025-11-27 01:53:57,241 | INFO | pyMut.visualizations.comut_plot | TMB calculation: 46,423 coding variants from 46,423 total variants
2025-11-27 01:53:57,249 | INFO | pyMut.visualizations.comut_plot | Calculated TMB for 525 samples (range: 0.07-80.34 Muts/Mb)
2025-11-27 01:53:57,333 | INFO | pyMut.visualizations.comut_plot | Panel A created in 2.24s
2025-11-27 01:53:57,333 | INFO | pyMut.visualizations.comut_plot | Panel A created in 2.24s

Out[5]:

Panel B: Mutational Signatures¶

Stacked bar chart showing mutational signature contributions per sample. Each bar represents 100% with colored segments for each signature.

Parameters:

• signatures_tsv: Path to TSV file with signature data
• sample_order: List of sample IDs for alignment
• signature_labels: List of signature names
• normalize: Normalize rows to sum to 1. Default: True
• figsize: Figure size. Default: (12, 2.0)

In [6]:

py_mutation.comut_mutation_signatures_plot(
    signatures_tsv=sig_tsv_path,
    sample_order=sample_order,
    signature_labels=["Signature 1", "Signature 2", "Signature 3", "Signature 4"],
    normalize=True,
    figsize=(12, 2.0),
    title="Mutational Signatures"
)

py_mutation.comut_mutation_signatures_plot( signatures_tsv=sig_tsv_path, sample_order=sample_order, signature_labels=["Signature 1", "Signature 2", "Signature 3", "Signature 4"], normalize=True, figsize=(12, 2.0), title="Mutational Signatures" )

2025-11-27 01:53:57,602 | INFO | pyMut.visualizations.comut_plot | Panel B created in 0.13s

Out[6]:

Panel C: Tumor Purity¶

1-row heatmap showing tumor purity per sample. Color intensity represents the proportion of tumor cells.

Parameters:

• purity_tsv: Path to TSV file with purity data
• sample_order: List of sample IDs for alignment
• figsize: Figure size. Default: (12, 1.5)

In [7]:

py_mutation.comut_purity_plot(
    purity_tsv=purity_tsv_path,
    sample_order=sample_order,
    figsize=(12, 1.5)
)

py_mutation.comut_purity_plot( purity_tsv=purity_tsv_path, sample_order=sample_order, figsize=(12, 1.5) )

2025-11-27 01:53:57,783 | INFO | pyMut.visualizations.comut_plot | Panel C created in 0.02s

Out[7]:

Panel D: Mutation Type (Oncoprint)¶

Matrix showing mutation types across genes and samples. Cell colors indicate mutation type (Missense, Nonsense, Frameshift indel, Silent, Multiple).

Parameters:

• mutation_data_tsv: Path to TSV file with mutation data
• sample_order: List of sample IDs for alignment
• gene_order: List of gene names (top to bottom)
• figsize: Figure size. Default: (12, 4.0)

In [8]:

py_mutation.comut_mutation_type_plot(
    mutation_data_tsv=mutation_data_tsv_path,
    sample_order=sample_order,
    gene_order=gene_order,
    figsize=(12, 4.0),
    title="Mutation Type"
)

py_mutation.comut_mutation_type_plot( mutation_data_tsv=mutation_data_tsv_path, sample_order=sample_order, gene_order=gene_order, figsize=(12, 4.0), title="Mutation Type" )

2025-11-27 01:53:58,168 | INFO | pyMut.visualizations.comut_plot | Panel D created in 0.24s

Out[8]:

Panel E: Copy Number Alteration¶

Matrix showing CNA states across genes and samples. States include Baseline, Allelic amplification, Allelic deletion, and aCN = 0 (homozygous deletion).

Parameters:

• cna_tsv: Path to TSV file with CNA data
• sample_order: List of sample IDs for alignment
• gene_order: List of gene names (top to bottom)
• figsize: Figure size. Default: (12, 2.0)

In [9]:

py_mutation.comut_cna_plot(
    cna_tsv=cna_tsv_path,
    sample_order=sample_order,
    gene_order=cna_gene_order,
    figsize=(12, 2.0),
    title="Copy Number Alteration"
)

py_mutation.comut_cna_plot( cna_tsv=cna_tsv_path, sample_order=sample_order, gene_order=cna_gene_order, figsize=(12, 2.0), title="Copy Number Alteration" )

2025-11-27 01:53:58,417 | INFO | pyMut.visualizations.comut_plot | Panel E created in 0.09s

Out[9]:

Panel F: Whole Genome Doubling¶

Track showing WGD status per sample. Gray rectangles indicate WGD present.

Parameters:

• wgd_tsv: Path to TSV file with WGD data
• sample_order: List of sample IDs for alignment
• figsize: Figure size. Default: (12, 1.2)

In [10]:

py_mutation.comut_wgd_plot(
    wgd_tsv=wgd_tsv_path,
    sample_order=sample_order,
    figsize=(12, 1.2)
)

py_mutation.comut_wgd_plot( wgd_tsv=wgd_tsv_path, sample_order=sample_order, figsize=(12, 1.2) )

2025-11-27 01:53:58,627 | INFO | pyMut.visualizations.comut_plot | Panel F created in 0.05s

Out[10]:

Panel G: Same Patient¶

Track indicating samples from the same patient. Black dots represent samples, horizontal lines connect samples from the same patient.

Parameters:

• sp_tsv: Path to TSV file with patient grouping data
• sample_order: List of sample IDs for alignment
• figsize: Figure size. Default: (12, 1.2)

In [11]:

py_mutation.comut_same_patient_plot(
    sp_tsv=sp_tsv_path,
    sample_order=sample_order,
    figsize=(12, 1.2)
)

py_mutation.comut_same_patient_plot( sp_tsv=sp_tsv_path, sample_order=sample_order, figsize=(12, 1.2) )

2025-11-27 01:53:58,755 | INFO | pyMut.visualizations.comut_plot | Panel G created in 0.04s

Out[11]: