Skip to content

options-reference.md

Latest commit

 

History

History
220 lines (186 loc) · 9.44 KB

options-reference.md

File metadata and controls

220 lines (186 loc) · 9.44 KB
Raw

Options Reference

OncoplotOptions controls layout and visual details. Pass it through the options argument:

from pyoncoplot import OncoplotOptions, oncoplot

result = oncoplot(
    mutations,
    gene_col="gene",
    sample_col="sample",
    mutation_type_col="mutation_type",
    backend="matplotlib",
    options=OncoplotOptions(width=1200, height=700),
)

Size and Layout

Option Default Meaning
width 1200 intended output width in pixels
height 650 intended output height in pixels
selection_type "none" Plotly selection mode: "none", "multiple", or "single"
tmb_height_ratio 0.14 relative height of the TMB bar area
gene_bar_width_ratio 0.18 relative width of the right gene bar
metadata_height_ratio 0.18 relative height of metadata tracks
metadata_position "bottom" "bottom" or "top"
buffer_metadata 0.08 spacing around metadata tracks
buffer_tmb 0.08 spacing around the TMB bar
buffer_gene_bar 0.02 spacing between the matrix and gene bar

Labels and Axes

Option Default Meaning
x_label "Sample" x-axis label
y_label "Gene" y-axis label
show_sample_ids False show sample labels
sample_id_position "bottom" sample label placement
sample_id_angle 90 sample label rotation
show_x_label False show x-axis label
show_y_label False show y-axis label
show_tmb_y_label False show TMB y-axis label
show_tmb_axis True show TMB tick labels
show_gene_bar_axis True show gene bar axis

Legends

Option Default Meaning
show_legend True draw mutation legend
show_legend_titles True draw legend titles
mutation_legend_position "bottom" "bottom", "right", or "none"
show_metadata_legends True draw categorical metadata legends and numeric metadata colorbars
metadata_legend_position "right" "right" or "bottom"
legend_key_size 1.0 mutation legend key size multiplier
legend_offsets {} per-legend {"x": ..., "y": ...} offsets in figure/paper coordinates
metadata_legend_nrow None optional metadata legend row limit
metadata_legend_ncol None optional metadata legend column count
metadata_legend_key_size 1.0 metadata legend key size multiplier
legend_label_max_chars None optional maximum displayed legend label length
legend_title_max_chars None optional maximum displayed legend title length

Plotly uses one shared interactive legend. mutation_legend_position="none" hides mutation traces while categorical metadata legends can remain visible. A bottom request creates a horizontal Plotly legend; otherwise visible legends are placed vertically on the right. Expanded main-grid variant-value colorbars are an exception: Plotly and Matplotlib place them horizontally below the plot area so they do not compete with right-side metadata legends. Matplotlib keeps separate static legend layout controls, including metadata_legend_nrow and metadata_legend_ncol.

legend_offsets targets individual legends by stable keys. Use source columns where available, such as mutation:type, tmb:tmb_type, metadata:clinical_group, or variant:vaf. Use stable fallback keys for legends without one source column: mutation, tmb, variant:shared, and gene_bar. Positive x moves right and positive y moves up. Plotly splits only targeted categorical legend groups into separate legend containers; untargeted legends keep the default shared position.

Tile Styling

Option Default Meaning
background_color "#E5E5E5" empty tile background
tile_height 1.0 mutated and empty tile height
tile_width 1.0 mutated and empty tile width
tile_linewidth 0.25 tile border width
row_separator_linewidth 0.8 row separator width
unspecified_mutation_color "#1A1A1A" fallback mutation color
multi_hit_color "black" multi-hit color

tile_width and tile_height are Matplotlib/static-layout controls. Plotly uses fixed interactive square markers; tile_linewidth applies to marker outlines in both renderers.

Fonts

Option Default Meaning
font_size_x_label 26 x-axis label size
font_size_y_label 26 y-axis label size
font_size_genes 12 gene label size
font_size_samples 9 sample label size
font_size_metadata 10 metadata row label size
font_size_metadata_bar_numbers 8 numeric metadata min/max label size
font_size_tmb_axis 10 TMB axis text size
font_size_gene_bar_axis 10 gene bar text size
font_size_legend_text None explicit mutation/TMB/Plotly legend label size
font_size_legend_title None explicit mutation/TMB/colorbar legend title size
font_size_metadata_legend_text None explicit metadata legend label size
font_size_metadata_legend_title None explicit metadata legend title size
font_size_title 14 top-level figure title size
font_size_subplot_title 12 named subplot title size
font_size_pathway None explicit pathway strip label size
gene_name_x_offset 0.0 extra leftward padding for expanded-grid gene labels
main_grid_rows_label_x_offset 10.0 extra leftward padding for expanded-grid row labels
font_family "Arial" renderer font family
gene_font_style "normal" gene label style
sample_font_style "normal" sample label style
font_style_metadata "normal" metadata row label style

Plotly applies practical font sizes for sample ticks, gene ticks, axis labels, TMB axes, gene-bar axes, and metadata row labels. Font face style controls such as gene_font_style, sample_font_style, and font_style_metadata are Matplotlib/static-layout oriented.

Titles

Option Default Meaning
title_text None optional top-level figure title
main_subplot_title None optional main mutation matrix title
tmb_subplot_title None optional TMB subplot title
gene_bar_subplot_title None optional gene-bar subplot title
metadata_subplot_title None optional metadata subplot title

TMB and Gene Bar

Option Default Meaning
log10_transform_tmb True log-transform TMB values
scientific_tmb False use scientific TMB labels where supported
gene_bar_mode "counts" "counts" for recurrence-width bars or "percent" for 100% mutation-type composition bars
show_gene_bar_labels False show recurrence percentage labels
gene_bar_label_round 0 rounding for recurrence labels
gene_bar_label_padding 0.24 extra x-axis room for gene-bar percentage labels
gene_bar_label_nudge 0.0 additional x-axis nudge for gene-bar labels
gene_bar_scale_breaks None explicit gene-bar axis tick positions
gene_bar_scale_n_breaks None requested number of gene-bar axis breaks

In Plotly, gene_bar_scale_n_breaks is passed through as an nticks request when gene_bar_scale_breaks is not supplied. gene_bar_mode="percent" keeps the same mutation-type colors but normalizes each gene's stacked bar to 100%.

Pathways

Option Default Meaning
pathway_text_color "white" pathway strip label color
pathway_background_color "#1A1A1A" pathway strip fill color
pathway_outline_color "black" pathway strip border color
pathway_text_angle 0 pathway strip label rotation

Metadata

Option Default Meaning
metadata_na_marker "!" legend label for missing metadata
metadata_na_marker_size 7 visible NA marker text size
metadata_max_levels 40 maximum categorical levels allowed per metadata track
metadata_numeric_plot_type "heatmap" "heatmap" or "bar"
metadata_legend_orientation_heatmap "vertical" orientation hint for numeric heatmap legends
metadata_default_colors color sequence fallback metadata colors

Categorical metadata tracks reuse metadata_default_colors from the beginning when there are more levels than fallback colors. metadata_numeric_plot_type="bar" and metadata legend row/column controls are Matplotlib/static metadata controls. metadata_legend_orientation_heatmap controls numeric metadata colorbar orientation in both backends. Plotly renders compact metadata heatmaps and categorical metadata legend entries that fit its interactive model.

Text Prettification

Option Default Meaning
prettify_legend_titles True prettify legend titles
prettify_legend_values True prettify legend values
prettify_function prettify function used for display labels

Common Bundles

Compact static plot:

OncoplotOptions(
    width=900,
    height=520,
    font_size_genes=8,
    tile_linewidth=0.1,
    row_separator_linewidth=0.2,
)

Gallery-style static plot:

OncoplotOptions(
    width=1800,
    height=900,
    log10_transform_tmb=False,
    show_gene_bar_labels=True,
    mutation_legend_position="right",
    metadata_legend_position="right",
    metadata_numeric_plot_type="bar",
)