AssociationVisualizationBuilder#

class panorama.systems.systems_association.AssociationVisualizationBuilder(association, name, output_dir, formats=None)#

Bases: VisualizationBuilder

Builder for correlation matrix visualizations between systems and genomic associations.

This class creates comprehensive visualizations showing correlations between pangenome systems and various genomic elements (RGPs, modules, etc.), including coverage and frequency plots.

association#

Type of genomic association being visualized (e.g., ‘rgp’, ‘module’)

BELOW_HEIGHT = 138#

Space for bottom plots

Type:

int

CENTER_WIDTH = 1335#

Space for main heatmap

Type:

int

DEFAULT_FORMAT = 'html'#

Default output format when none specified

Type:

str

LEFT_WIDTH = 267#

Space for left bar plots

Type:

int

MIDDLE_HEIGHT = 644#

Space for main heatmap

Type:

int

OUTPUT_FORMATS = ['html', 'png']#

Supported output formats for saving figures

Type:

list

PNG_EXPORT_HEIGHT = 1080#

Height of PNG exports

Type:

int

PNG_EXPORT_WIDTH = 1920#

Width of PNG exports

Type:

int

RIGHT_WIDTH = 178#

Space for color bars

Type:

int

TOP_HEIGHT = 138#

int Space for top bar plots

TOTAL_HEIGHT = 920#

Total height of the complete visualization layout.

Type:

int

TOTAL_WIDTH = 1780#

Total width of the complete visualization layout.

Type:

int

__init__(association, name, output_dir, formats=None)#

Initialize the association visualization builder.

Parameters:

  • association (str) – Type of pangenome object being visualized (e.g., ‘rgp’, ‘module’)

  • name (str) – Name of the pangenome for visualization titles

  • output_dir (Path) – Directory path where output files will be saved

  • formats (Optional[List[str]]) – List of output formats to generate

static _configure_bar_plot_style(plot, x_label=None, y_label=None, flip_x=False, hide_x_axis=False, hide_y_axis=False)#

Configure styling for bar plots.

Parameters:

  • plot (figure) – The figure to configure

  • x_label (Optional[str]) – Label for x-axis

  • y_label (Optional[str]) – Label for y-axis

  • flip_x (bool) – Whether to flip the x-axis

  • hide_x_axis (bool) – Whether to hide the x-axis

  • hide_y_axis (bool) – Whether to hide the y-axis

Return type:

None

static _configure_minimal_plot(plot)#

Configure a minimal plot style (no axes, grid, etc.).

Parameters:

plot (figure) – The figure to configure with minimal styling

Return type:

None

_configure_plot_style()#

Configure plot styling specific to association visualizations.

Extends the base styling with association-specific axis labels.

Return type:

None

_create_main_figure(matrix, x_range=None, y_range=None, tooltips=None)#

Create the main heatmap figure with common configuration.

Parameters:

  • matrix (DataFrame) – Data matrix for determining ranges if not provided

  • x_range (Optional[FactorRange]) – X-axis range for the plot. If None, derived from matrix columns

  • y_range (Optional[FactorRange]) – Y-axis range for the plot. If None, derived from matrix index

  • tooltips (Optional[List[Tuple[str, str]]]) – List of tooltip specifications as (label, field) tuples

Return type:

None

_create_metric_plot(data_df, x_range, metric_name, color_palette, title)#

Create a generic metric visualization plot (coverage or frequency).

Creates a horizontal strip visualization with an associated color bar to show metric values across genomic elements.

Parameters:

  • data_df (DataFrame) – DataFrame containing the metric data

  • x_range (FactorRange) – X-axis range for consistent ordering

  • metric_name (str) – Name of the metric column in the DataFrame

  • color_palette (List[str]) – Color palette to use for the visualization

  • title (str) – Title for the color bar

Returns:

Tuple of (metric_plot, color_bar_plot)

Return type:

Tuple[figure, figure]

_save_figure(fig, filename_base)#

Save a Bokeh figure in the specified formats.

Parameters:

  • fig (figure) – The Bokeh figure object to save

  • filename_base (str) – Base filename without extension

Raises:

Exception – If an unsupported output format is specified

Return type:

None

property color_bar: figure#

Get the color bar figure.

create_bar_plots(correlation_matrix)#

Create bar plots showing system and element counts.

Creates both left (system counts) and top (element counts) bar plots to provide marginal summaries of the correlation matrix.

Parameters:

correlation_matrix (DataFrame) – Preprocessed correlation matrix

Return type:

None

create_color_bar(title)#

Create a color bar for the correlation matrix.

Parameters:

title (str) – Title to display on the color bar

Return type:

None

static create_color_palette(max_value)#

Create an appropriate color palette based on the maximum correlation value.

The palette selection adapts to the data range to provide optimal visual discrimination between different correlation values.

Parameters:

max_value (int) – Maximum correlation value in the matrix

Returns:

List of color hex codes for the palette, starting with white for zero values

Return type:

List[str]

create_coverage_plot(coverage_df, x_range)#

Create a coverage visualization plot.

Coverage represents how well each genomic element is covered by the systems, displayed as a horizontal strip below the main heatmap.

Parameters:

  • coverage_df (DataFrame) – DataFrame containing coverage data with coverage values

  • x_range (FactorRange) – X-axis range for consistent ordering with main plot

Return type:

None

create_frequency_plot(frequency_df, x_range)#

Create a frequency visualization plot.

Frequency represents how often each genomic element appears across genomes, displayed as a horizontal strip below the main heatmap.

Parameters:

  • frequency_df (DataFrame) – DataFrame containing frequency data with frequency values

  • x_range (FactorRange) – X-axis range for consistent ordering with main plot

Return type:

None

create_left_bar_plot(source, matrix, y_field='system_name', value_field='count', color='navy')#

Create a horizontal bar plot on the left side of the visualization.

Parameters:

  • source (ColumnDataSource) – ColumnDataSource containing the data for the bars

  • matrix (DataFrame) – Data matrix for determining the y-range

  • y_field (str) – Field name for the y-axis values

  • value_field (str) – Field name for the bar values

  • color (str) – Color for the bars

Return type:

None

create_main_figure(correlation_matrix, x_range, y_range)#

Create the main correlation matrix heatmap figure.

Parameters:

  • correlation_matrix (DataFrame) – Preprocessed correlation matrix with systems as rows and associations as columns

  • x_range (FactorRange) – X-axis range for consistent ordering across plots

  • y_range (FactorRange) – Y-axis range for consistent ordering across plots

Return type:

None

create_top_bar_plot(source, x_field, value_field='count', color='green', x_order=None)#

Create a vertical bar plot on the top of the visualization.

Parameters:

  • source (ColumnDataSource) – ColumnDataSource containing the data for the bars

  • x_field (str) – Field name for the x-axis values

  • value_field (str) – Field name for the bar values

  • color (str) – Color for the bars

  • x_order (Optional[List[str]]) – Custom ordering for x-axis. If None, uses source data order

Return type:

None

property glyph: Glyph#

Get the glyph from the renderer.

property glyph_renderer: GlyphRenderer#

Get the glyph renderer for the main plot.

property left_bar: figure#

Get the left bar plot figure.

property main_plot: figure#

Get the main heatmap plot figure.

plot()#

Create and save the complete association visualization layout.

Arranges all components (main heatmap, bar plots, color bars, and metric plots) in a grid layout and saves the result in the specified formats.

Return type:

None

property top_bar: figure#

Get the top bar plot figure.

On this page
Edit on GitHub
Show Source