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)

2025-10-23 01:11:27,700 | INFO | pyMut.input | Starting MAF reading: ../../../src/pyMut/data/examples/MAF/tcga_laml.maf.gz
2025-10-23 01:11:27,701 | INFO | pyMut.input | Loading from cache: ../../../src/pyMut/data/examples/MAF/.pymut_cache/tcga_laml.maf_bec334f3b1d679b0.parquet
2025-10-23 01:11:27,732 | 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.01)
• Dot (·): Moderately significant (0.01 ≤ p < 0.05)

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.01)
• show_counts: Display sample counts next to gene names. Default: True

In [3]:

py_mutation.somatic_interactions()

py_mutation.somatic_interactions()

2025-10-23 01:11:30,369 | INFO | pyMut.visualizations.somatic_interactions | Creating somatic interactions plot for top 25 genes
2025-10-23 01:11:30,372 | INFO | pyMut.visualizations.somatic_interactions | Using 1,732 variants for interaction analysis
2025-10-23 01:11:30,379 | INFO | pyMut.visualizations.somatic_interactions | Top mutated genes: FLT3, DNMT3A, NPM1, IDH2, IDH1...
2025-10-23 01:11:30,390 | INFO | pyMut.visualizations.somatic_interactions | Mutation matrix built: 192 samples x 1241 genes
2025-10-23 01:11:30,907 | INFO | pyMut.visualizations.somatic_interactions | Somatic interactions plot created successfully

Out[3]:

Customize Number of Genes¶

Use top_genes to analyze more or fewer genes:

In [ ]:

py_mutation.somatic_interactions(top_genes=15)

py_mutation.somatic_interactions(top_genes=15)

Advanced Options¶

Hide Sample Counts¶

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

In [ ]:

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

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

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 [ ]:

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

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