GDS Plotting Functions

API reference for SNV/Indel visualization

1 GDS Plotting Functions

1.1 Overview

The plot_gds.R module provides ggplot2-based visualization for SNV/Indel data. It generates the SNV/Indel component of the IMPACT Plot, displaying variants stratified by IMPACT score (pre-computed during IMPACT-SNV preprocessing).

Location: app/logic/plot_gds.R

1.2 Key Functions

1.2.1 build_gds_plotly()

Builds the SNV/indel scatter plot as a plotly widget and returns both the plot and the y-axis range.

Parameters:

  • df (data.frame): SNV/indel data, typically from data_manager$load_gds_data(). Must include Chromosome, Position, IMPACT_Score, and Tier.
  • selected_chr (character): "All" for genome-wide view; otherwise a single chromosome (e.g., "5").
  • dynamic_y (logical): If TRUE, sets y-range based on observed scores (clamped to [0, 100]); otherwise uses [0, 100].
  • jitter_height (numeric): Vertical jitter height.
  • fields (character|NULL): Optional set of hover labels; defaults are provided.
  • source (character|NULL): Optional plotly source ID (used for event_data(..., source=...)).
  • variant_states (list|data.frame|NULL): Optional persisted annotations keyed by variant.

Returns: list(plot = <plotly>, y_range = c(y_min, y_max))

Details:

  • The x-axis is in Mb; in genome-wide mode, chromosome offsets from chr_lengths() are applied to create a cumulative coordinate.
  • Hover tooltips are constructed via build_hover_text() and the mapping in default_label_map().

1.3 Usage

box::use(
  app/logic/plot_gds[build_gds_plotly]
)

# Create SNV scatter plot for IMPACT Plot
res <- build_gds_plotly(
  df = snv_data,
  selected_chr = "All",
  source = "snv_panel"
)
res$plot

### Supporting helpers (exported)

- `tier_colors()`: returns a named vector mapping tiers (`"1"`-`"4"`) to colors.
- `chr_lengths()`: returns a data.frame of chromosome lengths and cumulative offsets (Mb).
- `baseline_gds_plot(chr_len_df, selected_chr)`: builds an empty ggplot canvas configured for the current view.
- `default_label_map()`: default label → column mapping for hover text.
- `truncate_smart(x, max_chars, suffix)`: truncates long fields at item boundaries.
- `build_hover_text(df, fields, label_map, truncate_map, trunc_suffix)`: produces HTML hover strings.

1.4 Interactivity

All plots return plotly objects with hover tooltips, zoom, and pan capabilities. The IMPACT Plot enables:

  • Zoom: Click and drag to zoom into any genomic region
  • Hover Tooltips: View detailed variant annotations (position, AF, IMPACT score, etc.)
  • Pan: Navigate along the x-axis to explore variants across the genome
  • Filter Integration: Use filter controls to dynamically update visible variants

1.5 See Also