Archipelago: Visualising Variant Set Association Results

Overview

The archipelago package provides a graphical method for joint visualisation of variant-level and variant-set association results.

The Archipelago plot displays variant set p-values together with individual variant signals within a unified genomic coordinate system.

Example data

The package provides example datasets.

data("vsat_pval", package = "archipelago")
data("variant_pval", package = "archipelago")

head(vsat_pval)
#>   set_ID           P
#> 1      1 0.002039443
#> 2      2 0.003459603
#> 3      3 0.060544051
#> 4      4 0.005597115
#> 5      5 0.006149054
#> 6      6 0.077753370
head(variant_pval)
#>   set_ID     BP         P CHR    SNP
#> 1      1 351696 0.9211610   6 351696
#> 2      2 988282 0.8652950   9 988282
#> 3      3 929171 0.6916336  12 929171
#> 4      4 688387 0.9191039  18 688387
#> 5      5 874337 0.6045032  15 874337
#> 6      6 464161 0.8299881  11 464161

Basic Archipelago plot

A plot can be generated directly using default settings. Temporary output paths are used so that no files are written to the package.

p_basic <- archipelago_plot(
  df1 = vsat_pval,
  df2 = variant_pval,
  output_path = tempfile(),
  output_raw  = tempfile()
)
#> Running Archipelago
#> Input df1 is for VSAT: set_ID and P
#> Input df2 is for SNP: set_ID, BP, P, CHR, SNP

p_basic

This produces the standard Archipelago plot with automatic colouring and layout.

Using colour themes

Built-in colour themes allow rapid visual changes.

p_theme <- archipelago_plot(
  df1 = vsat_pval,
  df2 = variant_pval,
  color_theme = "alice",
  output_path = tempfile(),
  output_raw  = tempfile()
)
#> Running Archipelago
#> Input df1 is for VSAT: set_ID and P
#> Input df2 is for SNP: set_ID, BP, P, CHR, SNP

p_theme

Several predefined themes are available.

Fully customised plot

All visual elements can be customised. A typical advanced use case:

custom_colors <- c("#9abfd8", "#cac1f3", "#371c4b", "#2a5b7f")

p_custom <- archipelago_plot(
  df1 = vsat_pval,
  df2 = variant_pval,
  add_title = TRUE,
  plot_title = "Custom Archipelago Plot",
  add_subtitle = TRUE,
  plot_subtitle = "Variant set and variant signals",
  show_legend = TRUE,
  legend_position = "bottom",
  chr_ticks = TRUE,
  point_size = 0.6,
  point_size_large = 1.2,
  custom_colors = custom_colors,
  color_labels = c(
    "Chromosome A",
    "Chromosome B",
    "Highlighted variants",
    "Variant set result"
  ),
  crit_val_VSAT = 0.05 / 300,
  crit_val_single_variant = 5e-8,
  annotate_thresholds = TRUE,
  fig_width = 10,
  fig_height = 5,
  output_path = tempfile(),
  output_raw  = tempfile(),
  file_type = "pdf"
)
#> Running Archipelago
#> Input df1 is for VSAT: set_ID and P
#> Input df2 is for SNP: set_ID, BP, P, CHR, SNP

p_custom

This example demonstrates full control over layout, colours, thresholds, labels, and output.

Output files

Plots are saved automatically using the specified output paths and formats. In this vignette, temporary paths are used so files are not persisted.

Summary

Archipelago provides a compact visual summary linking variant-level and variant-set association results, supporting interpretation of aggregation analyses in genetic studies.