API Reference

API documentation for IMPACT-VIS Box modules
Authors
Affiliation

Nicholas Boehler

University of Toronto Mississauga

Hai-Ying Mary Cheng

University of Toronto Mississauga

Published

December 18, 2025

1 Overview

This section documents all public functions and modules in IMPACT-VIS. The API follows the Box module system, where each R file is a self-contained module with explicit imports and exports.

1.1 Import Syntax

Direct import (for ≤8 functions):

box::use(
  app/logic/data_manager[load_gds_data, load_sv_data],
)

# Use as
data <- load_gds_data(path)

Module-qualified import (for >8 functions):

box::use(
  app/logic/data_manager,
)

# Use as
data <- data_manager$load_gds_data(path)

2 Modules Overview

2.1 Core Data Loading (app/logic/data_manager)

Responsibility: Load GDS, AnnotSV, and CNV files with on-disk filtering

Key Functions:

  • load_gds_data() — Load SNV/Indel data from GDS with optional filtering
  • apply_gds_filters() — Apply in-place filters to GDS handle
  • load_sv_data() — Load structural variants from AnnotSV TSV
  • load_cnv_data() — Load copy number variants from TXT

See: data_manager Reference

2.2 Validation (app/logic/validators)

Responsibility: Validate file formats and data integrity

Key Functions:

  • validate_gds_file() — Check GDS schema and integrity
  • validate_sv_tsv() — Check AnnotSV TSV structure
  • validate_cnv_txt() — Check CNV TXT format

See: validators Reference

2.3 Plotting - SNV (app/logic/plot_gds)

Responsibility: Generate SNV/Indel visualizations

Key Functions:

  • tier_colors() — Color mapping for variant tiers
  • chr_lengths() — Chromosome coordinates for genome layout
  • baseline_gds_plot() — Base ggplot for SNV plots
  • default_label_map() — Default tooltip labels

See: plot_gds Reference

2.4 Plotting - SV (app/logic/plot_sv)

Responsibility: Generate structural variant visualizations

Key Functions:

  • sv_colors() — Color mapping for SV types
  • baseline_sv_plot() — Base ggplot for SV plots
  • baseline_sv_plotly() — Interactive plotly baseline
  • load_sv_data() — Load and normalize AnnotSV TSV

See: plot_sv Reference

2.5 Plotting - CNV (app/logic/plot_cnv)

Responsibility: Generate copy number visualizations

Key Functions:

  • cnv_colors() — Color mapping for CNV types
  • baseline_cnv_plot() — Base ggplot for CNV plots
  • baseline_cnv_plotly() — Interactive plotly baseline

See: plot_cnv Reference

2.6 Plot Combination (app/logic/plot_combine)

Responsibility: Compose multi-panel plots with shared axes

Key Functions:

  • combine_plots() — Create 3-row SNV/SV/CNV panel layout

See: plot_combine Reference

2.7 Error Handling (app/logic/error_handler)

Responsibility: Display user-friendly errors and notifications

Key Functions:

  • show_error() — Display error notification
  • show_warning() — Display warning notification
  • show_success() — Display success notification
  • load_with_fallback() — Validate+load helper returning structured result
  • load_all_files_with_fallback() — Load GDS/SV/CNV with partial-failure tolerance

See: error_handler Reference

2.8 Sample Management (app/logic/sample_loader)

Responsibility: Discover samples and load multi-file datasets

Key Functions:

  • get_sample_names() — Discover available samples
  • expected_sample_paths() — Construct file paths by naming convention
  • load_sample_files() — Load all files for a sample with partial-failure tolerance
  • close_gds_handle() — Safely close GDS handles

See: sample_loader Reference

2.9 Variant Detail Helpers (app/logic/variant_modal_helpers)

Responsibility: Extract and display variant details in modals

Key Functions:

  • tooltip_labels — Standard field labels for variant modals
  • get_field_value() — Flexible label-to-column matching

See: variant_modal_helpers Reference

3 Common Workflows

3.1 Workflow 1: Load and Display SNVs

box::use(
  app/logic/data_manager[load_gds_data],
  app/logic/plot_gds[baseline_gds_plot],
  app/logic/plot_combine[combine_plots]
)

# Load data
snv_data <- load_gds_data(
  gds_path = "app/data/sample001_SNV_IMPACT.gds",
  num_variants = 500,
  filters = list(tier = c("1", "2"))
)

# Plot
if (!is.null(snv_data) && nrow(snv_data) > 0) {
  plot_obj <- baseline_gds_plot(snv_data)
  print(plot_obj)
}

3.2 Workflow 2: Validate Data Before Loading

box::use(
  app/logic/validators[validate_gds_file],
)

# Check file validity
validation <- validate_gds_file("app/data/sample001_SNV_IMPACT.gds")

if (isTRUE(validation$is_valid)) {
  print("GDS file is valid, proceeding with analysis")
} else {
  print(paste("Validation failed:", validation$message))
}

3.3 Workflow 3: Load Full Sample with Error Handling

box::use(
  app/logic/sample_loader[load_sample_files],
  app/logic/error_handler[show_error, show_warning]
)

# Load all available files for a sample
result <- load_sample_files("sample001", "app/data")

if (result$any_data_loaded) {
  # Process loaded data
  if (!is.null(result$gds)) cat("SNV data loaded\n")
  if (!is.null(result$sv)) cat("SV data loaded\n")
  if (!is.null(result$cnv)) cat("CNV data loaded\n")
  
  # Show warnings if partial failure
  if (result$partial_failure) {
    show_warning(session, "Partial Load",
      paste("Some files failed:", paste(result$errors, collapse="; ")))
  }
} else {
  show_error(session, "Load Failed",
    "Could not load sample data",
    paste(result$errors, collapse="\n"))
}

3.4 Workflow 4: Error Handling Pattern

box::use(
  app/logic/data_manager[load_gds_data],
  app/logic/error_handler[show_error, show_success]
)

# Load with error handling
data <- load_gds_data(gds_path)

if (is.null(data)) {
  show_error(session, "Load failed", "Failed to load GDS file. Check file format.")
} else {
  show_success(session, "Loaded", paste("Loaded", nrow(data), "variants"))
}

4 Testing

4.1 Unit Test Pattern

box::use(app/logic/data_manager)

test_that("load_gds_data returns data.frame", {
  path <- "tests/testthat/fixtures/sample.gds"
  result <- data_manager$load_gds_data(path, num_variants = 100)
  
  expect_s3_class(result, "data.frame")
  expect_true(nrow(result) <= 100)
})

5 API Stability

Semantic Versioning: - v1.x: Stable API (no breaking changes within major version) - Functions marked #' @export are part of public API - Private functions (no @export) may change without notice

Deprecation Policy: Functions deprecated in v1.2 will be removed in v2.0.

Example:

#' @export
#' @note Deprecated: Use load_gds_data() instead
load_gds <- function() {
  warning("load_gds() is deprecated; use load_gds_data()")
  # ... implementation ...
}

Document Version: 1.0.0
Last Updated: 2025-12-10