Somatic Interactions Example¶

This notebook demonstrates the somatic_interactions() plot, which visualizes how pairs of genes are mutated together (co-occurrence) or separately (mutual exclusivity) in a cohort of tumor samples.

For detailed documentation, see the Somatic Interactions 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_laml.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", consolidate_variants=False)

from pyMut.input import read_maf maf_path = "../../../src/pyMut/data/examples/MAF/tcga_laml.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", consolidate_variants=False)

2026-01-12 20:39:44,143 | INFO | pyMut.input | Starting MAF reading: ../../../src/pyMut/data/examples/MAF/tcga_laml.maf.gz
2026-01-12 20:39:44,143 | INFO | pyMut.input | Loading from cache: ../../../src/pyMut/data/examples/MAF/.pymut_cache/tcga_laml.maf_1f7f09f022a4f9cd.parquet
2026-01-12 20:39:44,176 | INFO | pyMut.input | Cache loaded successfully in 0.03 seconds

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

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()

Basic Somatic Interactions Plot¶

The somatic_interactions() function creates a triangular heatmap where each cell represents a gene pair. Color encodes the strength and direction of the interaction based on Fisher's exact test.

Interpretation:

• Blue/green cells: Co-occurrence (genes mutated together more than expected)
• Brown/orange cells: Mutual exclusivity (genes rarely mutated together)
• Asterisk (*): Highly significant (p < 0.05)
• Dot (·): Moderately significant (0.05 ≤ p < 0.1)

Parameters:

• top_genes: Number of most frequently mutated genes to include. Default: 25
• figsize: Figure size. Default: (12, 10)
• title: Custom plot title. Default: auto-generated
• vmin, vmax: Color scale bounds. Default: -3.0, 3.0
• pvalue: Tuple of p-value thresholds for significance markers. Default: (0.05, 0.1)
• show_counts: Display sample counts next to gene names. Default: True

In [3]:

py_mutation.somatic_interactions()

py_mutation.somatic_interactions()

2026-01-12 20:39:50,105 | INFO | pyMut.visualizations.somatic_interactions | Somatic interactions plot: 1,732 variants, 193 samples, 25 genes analyzed in 0.51s

Out[3]:

Customize Number of Genes¶

Use top_genes to analyze more or fewer genes:

In [4]:

py_mutation.somatic_interactions(top_genes=15)

py_mutation.somatic_interactions(top_genes=15)

2026-01-12 20:39:54,650 | INFO | pyMut.visualizations.somatic_interactions | Somatic interactions plot: 1,732 variants, 193 samples, 15 genes analyzed in 0.29s

Out[4]:

Advanced Options¶

Hide Sample Counts¶

Set show_counts=False to hide the sample counts next to gene names:

In [5]:

py_mutation.somatic_interactions(top_genes=15, show_counts=False)

py_mutation.somatic_interactions(top_genes=15, show_counts=False)

2026-01-12 20:40:00,200 | INFO | pyMut.visualizations.somatic_interactions | Somatic interactions plot: 1,732 variants, 193 samples, 15 genes analyzed in 0.30s

Out[5]:

Adjust Significance Thresholds¶

Use the pvalue parameter to customize p-value thresholds for significance markers. The smaller value controls asterisks (*), the larger value controls dots (·):

In [6]:

py_mutation.somatic_interactions(
    top_genes=20,
    pvalue=(0.01, 0.001)
)

py_mutation.somatic_interactions( top_genes=20, pvalue=(0.01, 0.001) )

2026-01-12 20:40:06,540 | INFO | pyMut.visualizations.somatic_interactions | Somatic interactions plot: 1,732 variants, 193 samples, 20 genes analyzed in 0.36s

Out[6]: