index.md

pyoncoplot Documentation

pyoncoplot creates Python-native oncoplots from mutation-level cohort data. It supports interactive Plotly output and static Matplotlib output, with metadata tracks, TMB bars, gene recurrence bars, pathway grouping, palettes, tooltips, and deterministic gallery recreation from local TSV/JSON inputs.

The project is inspired by the R package ggoncoplot. The goal is feature and behavior parity, not pixel-identical ggplot output.

Start Here

• Installation
• Quickstart
• Data Inputs
• API Reference
• Gallery
• Migration From ggoncoplot

Minimal Example

import pandas as pd
from pyoncoplot import oncoplot

mutations = pd.DataFrame(
    {
        "sample": ["S1", "S1", "S2", "S3"],
        "gene": ["TP53", "EGFR", "TP53", "PTEN"],
        "mutation_type": [
            "Missense_Mutation",
            "Frame_Shift_Del",
            "Nonsense_Mutation",
            "Splice_Site",
        ],
    }
)

result = oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    draw_gene_bar=True,
    draw_tmb_bar=True,
)

result.save("oncoplot.html")

For static output, pass backend="matplotlib" and save a PNG, SVG, or PDF:

result = oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    backend="matplotlib",
    draw_gene_bar=True,
)
result.save("oncoplot.png", dpi=120)

Documentation Map

Page	Use it for
Quickstart	first working plot
Data Inputs	mutation table schema and validation
Metadata and TMB	clinical tracks and mutation burden bars
Pathways and Sorting	ordering genes, samples, and pathway groups
Palettes	mutation, metadata, and TMB colors
Options Reference	layout, text, legend, and rendering knobs
Rendering Backends	Plotly vs Matplotlib behavior
Gallery	deterministic local examples
Troubleshooting	common errors and fixes