Variant Modal Helpers Module

API reference for variant detail extraction and modal utilities

1 Variant Modal Helpers Module

1.1 Overview

The variant_modal_helpers.R module provides utility functions for extracting and displaying detailed variant information in modal dialogs. It handles label-to-column mapping and field value retrieval with flexible matching.

Location: app/logic/variant_modal_helpers.R

1.2 Exported Functions

1.2.1 tooltip_labels

A character vector defining the standard labels displayed in variant detail modals.

Type: Character vector (exported constant)

Value:

c(
  "VarInfo", "Genes", "Chromosome", "Position", "IMPACT Score",
  "IMPACT Calc", "ClinVar", "ClinVar Disease", "REF", "ALT", "Bravo AF",
  "ALoFT Prediction", "ALoFT Score"
)

Details: Defines the set of variant fields to display in modal information grids. These labels are used as defaults when rendering SNV variant details. Custom labels can be provided to modal components.

Example:

box::use(app/logic/variant_modal_helpers[tooltip_labels])

labels <- tooltip_labels
# Use in modal rendering loop:
for (label in labels) {
  # Render label-value pair
}

1.2.2 get_field_value()

Retrieves a field value from a data frame row using tolerant label-to-column name matching.

Parameters: - lbl (character): Display label (e.g., “IMPACT Score”) - row (data.frame, one row): Row containing field values

Returns: - Character representation of field value, or - Empty string (““) if field not found

Details: Attempts multiple column name variations to find a match:

  1. Exact match (e.g., "IMPACT Score")
  2. Space→underscore (e.g., "IMPACT_Score")
  3. Space→dot (e.g., "IMPACT.Score")
  4. Remove spaces (e.g., "IMPACTScore")
  5. Case-insensitive fallback: matches tolower(lbl) against tolower(names(row))

This flexibility accommodates variations in naming between data sources and display labels.

Example:

box::use(app/logic/variant_modal_helpers[get_field_value])

# Suppose row has column "IMPACT_Score" but label is "IMPACT Score"
value <- get_field_value("IMPACT Score", row)
# Returns: "85" (if that's the value)

# For missing field, returns empty string
value <- get_field_value("Unknown Field", row)
# Returns: ""

1.3 Common Workflows

1.3.1 Workflow 1: Build Modal Info Grid

box::use(
  app/logic/variant_modal_helpers[tooltip_labels, get_field_value]
)

# In modal rendering code:
variant_row <- snv_data[selected_row, , drop = FALSE]

# Iterate through standard labels
for (label in tooltip_labels) {
  value <- get_field_value(label, variant_row)
  # Render label: value in info grid
}

1.3.2 Workflow 2: Custom Labels with Flexible Matching

box::use(app/logic/variant_modal_helpers[get_field_value])

custom_labels <- c("Gene", "ClinVar Significance", "Position Mb")

for (label in custom_labels) {
  value <- get_field_value(label, variant_row)
  # Note: matching is based on column-name variants of `label`.
  # It does not currently implement domain-specific synonyms.
}

1.4 Internal Implementation Details

1.4.1 Column Name Matching Algorithm

The function implements progressive fallback matching: 1. Try candidates: original label, space→underscore, space→dot, remove spaces 2. If no exact match, perform case-insensitive search on all column names 3. Return first match found, or empty string if no match

This approach tolerates minor naming inconsistencies between upstream processing and visualization: - GDS annotation nodes use underscores/dots - Display often uses spaces for readability - User data may have custom naming

1.5 Integration notes

These helpers are designed for use in modal rendering code that presents label/value rows. They are purely string/column matching utilities and do not depend on Shiny directly.

1.6 See Also

1.7 Scope

This module does not define modal UI; it only supports field extraction for display.