pathways-and-sorting.md

Pathways and Sorting

Gene and sample ordering are central to making an oncoplot readable.

Default Gene Ranking

By default, genes are ranked by the number of distinct samples with a mutation.

oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    top_n=15,
)

Explicit Gene Order

Use include_genes when a gene panel should be fixed:

oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    include_genes=["TP53", "PIK3CA", "PTEN", "EGFR"],
)

Pathway Input

Pathway input has exactly two columns: one gene column and one pathway column.

pathway = pd.DataFrame(
    {
        "gene": ["TP53", "RB1", "PIK3CA", "PTEN"],
        "pathway": ["Cell cycle", "Cell cycle", "PI3K", "PI3K"],
    }
)

oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    pathway=pathway,
    pathway_gene_col="gene",
)

Validation rules:

• pathway input must have exactly two columns.
• pathway genes cannot be missing.
• pathway names cannot be missing.
• pathway gene values must be unique.
• "Other" is reserved for unmapped genes.

Sample Ordering

By default, samples are ordered to emphasize mutations in high-ranked genes.

Use sample_order for exact control:

oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    sample_order=["S3", "S2", "S1"],
)

Metadata Sorting

Use metadata sorting to group samples by clinical categories.

oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    metadata=metadata,
    metadata_cols=["Subtype", "Response"],
    metadata_sort_cols=["Subtype", "Response"],
    metadata_sort_by=["alphabetical", "frequency"],
    metadata_sort_desc=[False, True],
)

Common values for metadata_sort_by:

Value	Meaning
"alphabetical"	sort category labels alphabetically
"frequency"	sort category labels by frequency

Showing All Samples

Use show_all_samples=True when metadata or custom TMB inputs should define the cohort, even if some samples have no mutations in the selected gene panel.

oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    metadata=metadata,
    metadata_cols=["Subtype"],
    show_all_samples=True,
)