Plot Combine Module

API reference for multi-plot composition and layout

1 Plot Combine Module

1.1 Overview

The plot_combine.R module provides utilities for composing the IMPACT Plot — a unified interactive visualization that combines SNV/indel, SV, and CNV data into a synchronized multi-panel display sharing a common genomic position (x-axis). The IMPACT Plot enables rapid visual assessment of all variant classes across the genome with drill-down capability for detailed inspection.

Location: app/logic/plot_combine.R

1.2 Exported Functions

1.2.1 combine_plots()

Composes the IMPACT Plot: a 3-panel visualization with shared x-axis (genomic position) showing SNV/Indel variants (bottom), CNVs (middle), and SVs (top).

Parameters: - sv_plot (plotly): Structural variant plotly object (typically from plot_sv$sv_plotly()) - cnv_plot (plotly): CNV plotly object (typically from plot_cnv$cnv_plotly()) - gds (list): GDS plot information with: - $plot (plotly): SNV/Indel plotly object (typically plot_gds$build_gds_plotly(...)$plot) - $y_range (numeric vector, length 2): y-axis range used for the SNV panel - selected_chr (character): “All” for genome-wide view, or single chromosome (default: “All”) - source (character): Optional plotly source ID for event registration (default: NULL)

Returns: plotly object with 3-panel IMPACT Plot layout

Details: Creates the IMPACT Plot visualization: - Top Panel (20% height): SV panel - Middle Panel (10% height): CNV panel - Bottom Panel (70% height): SNV/Indel panel

All three panels share a synchronized x-axis representing genomic position, enabling instant visual correlation of variant types across the genome. The plot is fully dynamic and interactive: - Zoom: Click and drag to zoom into any genomic region - Filter: Use filter controls to show only variants meeting specified criteria - Hover Tooltips: Hover over variants to view detailed annotations (position, allele frequency, impact scores, etc.) - Pan: Click and drag the plot area to navigate along the x-axis

When selected_chr = "All": - X-axis shows chromosome positions with cumulative coordinates - Vertical dashed lines mark chromosome boundaries - Shared x-axis across all three plots

When selected_chr is a single chromosome: - X-axis title becomes “Position (Mb)” (plotly auto-range is used) - Chromosome boundary markers are not added - The SNV y-axis range is still taken from gds$y_range

Example:

box::use(
  app/logic/plot_combine[combine_plots],
  app/logic/plot_gds[build_gds_plotly],
  app/logic/plot_sv[sv_plotly],
  app/logic/plot_cnv[cnv_plotly]
)

# Prepare individual plots
gds <- build_gds_plotly(snv_data, selected_chr = "All")
sv_plot <- sv_plotly("app/data/sample_1_SV_IMPACT.tsv", selected_chr = "All")
cnv_plot <- cnv_plotly("app/data/sample_1_CNV_IMPACT.txt", selected_chr = "All")

# Combine into IMPACT Plot layout
impact_plot <- combine_plots(
  sv_plot = sv_plot,
  cnv_plot = cnv_plot,
  gds = gds,
  selected_chr = "All"
)

1.2.2 Plot Layout Specifications

1.2.2.1 X-Axis Layout (Shared)

Genome-wide view (selected_chr = "All"): - Tick positions: Chromosome midpoints (cumulative coordinates) - Tick labels: Chromosome numbers (1-22, X, Y) - Range: 0 to max cumulative position (~3 billion for hg38) - Type: “array” (explicit tick positions)

Single chromosome view (e.g., selected_chr = "5"): - Title: “Position (Mb)” - Range: 0 to chromosome length - Type: Auto-scaled

1.2.2.2 Y-Axis (SNV Panel, yaxis3)

Configuration: - Title: “IMPACT Score” - Range: Specified via gds$y_range parameter - Tick mode: “auto” with 10 ticks - Fixed range prevents rescaling during interactions

1.2.2.3 Chromosome Boundary Markers

Active when selected_chr = "All": - Vertical dashed lines at each chromosome boundary - Color: grey50 - Dash style: dashed - Drawn across bottom (SNV) panel only - Helps visually separate chromosomes in multi-chr view

1.3 Internal Functionality

1.3.1 Subplot Composition

Uses plotly::subplot() with: - nrows = 3: Three panels stacked vertically - shareX = TRUE: Synchronized x-axis - titleY = TRUE: Y-axis titles enabled - heights = c(0.2, 0.1, 0.7): Proportional row heights

1.3.2 Layout Pipeline

  1. Create base subplot from three plots
  2. Configure x-axis based on selected_chr
  3. Configure SNV y-axis with fixed range
  4. Add chromosome boundary shapes (if genome-wide)
  5. Register click event source (if provided)

1.4 Common Workflows

1.4.1 Workflow 1: Create Full Multi-Variant View

box::use(
  app/logic/plot_combine[combine_plots],
  app/logic/plot_gds[build_gds_plotly],
  app/logic/plot_sv[sv_plotly],
  app/logic/plot_cnv[cnv_plotly]
)

# In reactive rendering:
output$multi_panel_plot <- renderPlotly({
  if (is.null(snv_data())) return(NULL)
  
  # Generate component plots
  gds <- build_gds_plotly(snv_data(), selected_chr = input$chr_selector)
  sv_plt <- sv_plotly(sv_path = sv_data_path(), selected_chr = input$chr_selector)
  cnv_plt <- cnv_plotly(cnv_path = cnv_data_path(), selected_chr = input$chr_selector)
  
  # Combine with selected chromosome
  combine_plots(
    sv_plot = sv_plt,
    cnv_plot = cnv_plt,
    gds = gds,
    selected_chr = input$chr_selector,
    source = "multi_panel_click"
  )
})

1.4.2 Workflow 2: Chromosome-Specific View

# Switch between genome-wide and chromosome-specific
observeEvent(input$chr_selector, {
  chr <- input$chr_selector
  
  # If "All", genome-wide view with boundaries
  # If specific chr, zoomed view
  combined_plot <- combine_plots(
    sv_plot = sv_plot,
    cnv_plot = cnv_plot,
    gds = list(plot = snv_plot, y_range = c(0, 100)),
    selected_chr = chr
  )
})

1.5 See Also

1.6 Development Notes

🚧 Future enhancements: - Interactive linked selection across panels - Togglable panel visibility - Panel height resizing - Export combined plot as publication figure