Mutational Signature Analysis Example¶

This notebook demonstrates the mutational signature analysis visualizations. Somatic SNVs arise from different mutational processes (aging, UV exposure, APOBEC activity, etc.), each leaving a characteristic pattern across 96 trinucleotide mutation contexts.

For detailed documentation, see the Mutational Signature Analysis API Reference.

Load Data¶

Load the MAF file and create a PyMutation object.

In [15]:

Copied!

from pyMut.input import read_maf

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

# Read the MAF file and create the PyMutation object
py_mutation = read_maf(maf_path,assembly="37")
from pyMut.input import read_maf

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

# Read the MAF file and create the PyMutation object
py_mutation = read_maf(maf_path,assembly="37")

2026-01-12 20:36:46,856 | INFO | pyMut.input | Starting MAF reading: ../../../src/pyMut/data/examples/MAF/ms.maf.gz
2026-01-12 20:36:46,858 | INFO | pyMut.input | Loading from cache: ../../../src/pyMut/data/examples/MAF/.pymut_cache/ms.maf_d52c67387883b96e.parquet
2026-01-12 20:36:46,972 | INFO | pyMut.input | Cache loaded successfully in 0.12 seconds

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

Configure Plot Settings¶

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

In [16]:

Copied!

py_mutation.configure_high_quality_plots()
py_mutation.configure_high_quality_plots()

Complete Mutational Signature Analysis¶

The mutational_signature_analysis() function generates a comprehensive five-panel figure:

Panel A: Signature profiles showing trinucleotide distribution for each signature
Panel B: Cosine similarity heatmap comparing extracted signatures with COSMIC
Panel C: Heatmap of relative signature contributions per sample
Panel D: Stacked bar chart of signature distribution across samples
Panel E: Donut plot of cohort-level signature proportions

Key Parameters:

ref_genome: Path to reference genome FASTA file (required)
cosmic_path: Path to COSMIC signature catalog TSV file (required for comparison)
n_signatures: Number of signatures to extract. Default: 3
figsize: Figure size. Default: (24, 12)
title: Plot title. Default: "Mutational Signature Analysis"

In [17]:

Copied!





py_mutation.mutational_signature_analysis(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa",
    cosmic_path="../../../src/pyMut/data/examples/COSMIC_catalogue-signatures_SBS96_v3.4/COSMIC_72.tsv",
)
py_mutation.mutational_signature_analysis(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa",
    cosmic_path="../../../src/pyMut/data/examples/COSMIC_catalogue-signatures_SBS96_v3.4/COSMIC_72.tsv",
)

2026-01-12 20:36:46,996 | INFO | pyMut.core | Generating complete mutational signature analysis...
/home/xuscbart/miniconda3/envs/PyMutTFG/lib/python3.10/site-packages/sklearn/decomposition/_nmf.py:1728: ConvergenceWarning: Maximum number of iterations 500 reached. Increase it to improve convergence.
  warnings.warn(
2026-01-12 20:36:51,946 | INFO | pyMut.analysis.mutational_signature | NMF signature extraction completed in 0.01 seconds
2026-01-12 20:36:51,947 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating complete mutational signature analysis...
2026-01-12 20:36:51,963 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating signature bar chart...
2026-01-12 20:36:52,329 | INFO | pyMut.visualizations.mutational_signature_analysis | Signature bar chart generated in 0.37s
2026-01-12 20:36:52,339 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating cosine similarity heatmap...
2026-01-12 20:36:52,643 | INFO | pyMut.visualizations.mutational_signature_analysis | Cosine similarity heatmap generated in 0.30s
2026-01-12 20:36:52,653 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating signature contribution heatmap...
2026-01-12 20:36:52,940 | INFO | pyMut.visualizations.mutational_signature_analysis | Signature contribution heatmap generated in 0.29s
2026-01-12 20:36:52,950 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating signature stacked bar chart...
2026-01-12 20:36:53,022 | INFO | pyMut.visualizations.mutational_signature_analysis | Signature stacked bar chart rendered in 0.07s
/home/xuscbart/pyMut/src/pyMut/visualizations/mutational_signature_analysis.py:2065: UserWarning: This figure includes Axes that are not compatible with tight_layout, so results might be incorrect.
  fig.tight_layout(rect=(0, 0, 1, 0.8))
2026-01-12 20:36:53,038 | INFO | pyMut.visualizations.mutational_signature_analysis | Complete mutational signature analysis rendered in 1.09s
2026-01-12 20:36:53,047 | INFO | pyMut.core | Complete mutational signature analysis generated in 6.05s

Out[17]:

No description has been provided for this image

Individual Panel Components¶

Each panel from the complete analysis is also available as a standalone function.

Panel A: Signature Bar Chart¶

Multi-panel visualization showing each mutational signature as a bar chart with 96 trinucleotide contexts. Bars are grouped by the 6 substitution classes (C>A, C>G, C>T, T>A, T>C, T>G).

Parameters:

ref_genome: Path to reference genome FASTA file (required)
n_signatures: Number of signatures to extract. Default: 3
cosmic_path: Path to COSMIC catalog (optional, for signature annotation)
figsize: Figure size. Default: auto-calculated
title: Plot title. Default: "Mutational Signature Profiles"

In [18]:

Copied!

py_mutation.signature_bar_chart(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)
py_mutation.signature_bar_chart(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)

2026-01-12 20:36:54,409 | INFO | pyMut.core | Generating signature bar chart...
/home/xuscbart/miniconda3/envs/PyMutTFG/lib/python3.10/site-packages/sklearn/decomposition/_nmf.py:1728: ConvergenceWarning: Maximum number of iterations 500 reached. Increase it to improve convergence.
  warnings.warn(
2026-01-12 20:37:00,208 | INFO | pyMut.analysis.mutational_signature | NMF signature extraction completed in 0.01 seconds
2026-01-12 20:37:00,210 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating signature bar chart...
2026-01-12 20:37:00,429 | INFO | pyMut.visualizations.mutational_signature_analysis | Signature bar chart generated in 0.22s
2026-01-12 20:37:00,430 | INFO | pyMut.core | Signature bar chart generated in 6.02s

Out[18]:

Panel B: Cosine Similarity Heatmap¶

Heatmap comparing extracted signatures with the COSMIC catalog of known mutational signatures. High similarity values (≥ 0.85) suggest a close match to a known biological process.

Parameters:

ref_genome: Path to reference genome FASTA file (required)
cosmic_path: Path to COSMIC signature catalog (required)
n_signatures: Number of signatures to extract. Default: 3
figsize: Figure size. Default: (14, 3)
title: Plot title. Default: "Cosine Similarity: Extracted vs COSMIC Signatures"

In [19]:

Copied!





py_mutation.cosine_similarity_heatmap(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa",
    cosmic_path="../../../src/pyMut/data/examples/COSMIC_catalogue-signatures_SBS96_v3.4/COSMIC_72.tsv",
)
py_mutation.cosine_similarity_heatmap(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa",
    cosmic_path="../../../src/pyMut/data/examples/COSMIC_catalogue-signatures_SBS96_v3.4/COSMIC_72.tsv",
)

2026-01-12 20:37:01,071 | INFO | pyMut.core | Generating cosine similarity heatmap...
/home/xuscbart/miniconda3/envs/PyMutTFG/lib/python3.10/site-packages/sklearn/decomposition/_nmf.py:1728: ConvergenceWarning: Maximum number of iterations 500 reached. Increase it to improve convergence.
  warnings.warn(
2026-01-12 20:37:05,747 | INFO | pyMut.analysis.mutational_signature | NMF signature extraction completed in 0.01 seconds
2026-01-12 20:37:05,748 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating cosine similarity heatmap...
2026-01-12 20:37:05,900 | INFO | pyMut.visualizations.mutational_signature_analysis | Cosine similarity heatmap generated in 0.15s
2026-01-12 20:37:05,910 | INFO | pyMut.core | Cosine similarity heatmap generated in 4.84s

Out[19]:

Panel C: Signature Contribution Heatmap¶

Heatmap showing the proportion of mutations in each sample attributable to each signature. Values are column-normalized (each sample sums to 1).

Parameters:

ref_genome: Path to reference genome FASTA file (required)
n_signatures: Number of signatures to extract. Default: 3
cosmic_path: Path to COSMIC catalog (optional, for signature alignment)
cmap: Colormap name. Default: 'Blues'
show_values: Display numerical values in cells. Default: False
figsize: Figure size. Default: auto-calculated
title: Plot title. Default: "Signature Contributions per Sample"

In [20]:

Copied!

py_mutation.signature_contribution_heatmap(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)
py_mutation.signature_contribution_heatmap(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)

2026-01-12 20:37:06,183 | INFO | pyMut.core | Generating signature contribution heatmap...
/home/xuscbart/miniconda3/envs/PyMutTFG/lib/python3.10/site-packages/sklearn/decomposition/_nmf.py:1728: ConvergenceWarning: Maximum number of iterations 500 reached. Increase it to improve convergence.
  warnings.warn(
2026-01-12 20:37:11,102 | INFO | pyMut.analysis.mutational_signature | NMF signature extraction completed in 0.01 seconds
2026-01-12 20:37:11,103 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating signature contribution heatmap...
2026-01-12 20:37:11,323 | INFO | pyMut.visualizations.mutational_signature_analysis | Signature contribution heatmap generated in 0.22s
2026-01-12 20:37:11,326 | INFO | pyMut.core | Signature contribution heatmap generated in 5.14s

Out[20]:

Panel D: Stacked Bar Chart per Sample¶

Stacked bar chart showing signature contributions across samples. Each bar represents one sample with colored segments for each signature's proportion.

Parameters:

ref_genome: Path to reference genome FASTA file (required)
n_signatures: Number of signatures to extract. Default: 3
sort_samples: Sort samples by dominant signature. Default: False
max_samples: Maximum number of samples to display. Default: None
figsize: Figure size. Default: auto-calculated
title: Plot title. Default: "Signature Contributions per Sample"

In [21]:

Copied!

py_mutation.signature_stacked_bar_chart(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)
py_mutation.signature_stacked_bar_chart(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)

2026-01-12 20:37:11,610 | INFO | pyMut.core | Generating signature stacked bar chart...
/home/xuscbart/miniconda3/envs/PyMutTFG/lib/python3.10/site-packages/sklearn/decomposition/_nmf.py:1728: ConvergenceWarning: Maximum number of iterations 500 reached. Increase it to improve convergence.
  warnings.warn(
2026-01-12 20:37:17,437 | INFO | pyMut.analysis.mutational_signature | NMF signature extraction completed in 0.01 seconds
2026-01-12 20:37:17,438 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating signature stacked bar chart...
2026-01-12 20:37:17,628 | INFO | pyMut.visualizations.mutational_signature_analysis | Signature stacked bar chart rendered in 0.19s
2026-01-12 20:37:17,632 | INFO | pyMut.core | Signature stacked bar chart generated in 6.02 seconds

Out[21]:

Panel E: Donut Plot¶

Donut chart showing the overall distribution of mutational signatures across the entire cohort. Unlike per-sample views, this reflects both activity and prevalence of each signature.

Parameters:

ref_genome: Path to reference genome FASTA file (required)
n_signatures: Number of signatures to extract. Default: 3
figsize: Figure size. Default: (8, 8)
title: Plot title. Default: "Relative Contribution of Mutational Signatures"

In [22]:

Copied!

py_mutation.signature_donut_plot(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)
py_mutation.signature_donut_plot(
    ref_genome="../../../src/pyMut/data/resources/genome/GRCh37/Homo_sapiens.GRCh37.dna.toplevel.fa"
)

2026-01-12 20:37:18,232 | INFO | pyMut.core | Generating signature donut plot...
/home/xuscbart/miniconda3/envs/PyMutTFG/lib/python3.10/site-packages/sklearn/decomposition/_nmf.py:1728: ConvergenceWarning: Maximum number of iterations 500 reached. Increase it to improve convergence.
  warnings.warn(
2026-01-12 20:37:23,498 | INFO | pyMut.analysis.mutational_signature | NMF signature extraction completed in 0.01 seconds
2026-01-12 20:37:23,499 | INFO | pyMut.visualizations.mutational_signature_analysis | Generating signature donut plot...
2026-01-12 20:37:23,557 | INFO | pyMut.visualizations.mutational_signature_analysis | Signature donut plot rendered in 0.06s
2026-01-12 20:37:23,560 | INFO | pyMut.core | Signature donut plot generated in 5.33 seconds

Out[22]: