Plotting Multiple Sequence Alignment Chord Diagrams with 'ggchord'"

In ggchord: Multi-Sequence 'BLAST' Alignment Chord Diagram Visualization Tool

knitr::opts_chunk$set(
  echo = TRUE,
  warning = FALSE,
  message = FALSE,
  fig.width = 7,
  fig.height = 7
)

1. Introduction

ggchord is a ggplot2-based R package for plotting multiple sequence alignment chord diagrams, supporting visualization of alignment relationships between sequences and gene annotation information. This tutorial demonstrates its core functions and parameter usage through examples.

2. Installation and Loading

First, install and load the ggchord package (if not yet published on CRAN, install from local or GitHub):

# Install from local
devtools::install_local("path/to/ggchord_0.2.0.tar.gz")

# Load the package
library(ggchord)
library(dplyr)  # For data processing

library(ggchord)
library(dplyr)

3. Data Preparation

ggchord requires three types of data (sequence data is mandatory):
- Sequence data (seq_data): Contains sequence IDs and lengths
- Alignment data (ribbon_data): BLAST alignment results for drawing inter-sequence ribbons
- Gene annotation data (gene_data): Contains gene positions and annotation information

This tutorial uses built-in example data (added via usethis::use_data()):

# Load built-in example data
data(seq_data_example)    # Sequence data
data(ribbon_data_example) # BLAST alignment data
data(gene_data_example)   # Gene annotation data (short genes filtered out)

# Inspect data structure
head(seq_data_example)
head(ribbon_data_example)
head(gene_data_example)

4. Basic Usage

4.1 Using Only Sequence Data

Sequence data is fundamental for drawing chord diagrams, requiring at minimum seq_id (sequence ID) and length (sequence length):

# Basic chord diagram: sequences only
p1 <- ggchord(
  seq_data = seq_data_example
)
print(p1)

Adjusting Sequence Parameters

Customize sequence order, orientation, curvature, and colors via parameters:

p2 <- ggchord(
  seq_data = seq_data_example,
  seq_order = c("MT118296.1", "OR222515.1", "MT108731.1", "OQ646790.1"),  # Sequence order
  seq_orientation = c(1, -1, 1, -1),  # Direction (1 = forward, -1 = reverse)
  seq_curvature = c(0, 2, -2, 6),     # Curvature (0 = straight line, 1 = standard arc)
  seq_colors = c("steelblue", "orange", "pink", "yellow")  # Sequence colors
)
print(p2)

4.2 Adding Sequence Alignment Data

Alignment data (ribbon_data) visualizes sequence similarity, with colors defaulting to identity (pident):

# Show sequence alignment relationships
p3 <- ggchord(
  seq_data = seq_data_example,
  ribbon_data = ribbon_data_example
)
print(p3)

Customizing Ribbon Colors

Adjust ribbon color schemes via ribbon_color_scheme:

# Color by query sequence
p4 <- ggchord(
  seq_data = seq_data_example,
  ribbon_data = ribbon_data_example,
  ribbon_color_scheme = "query"  # Ribbon color matches query sequence
)
print(p4)

# Single color
p5 <- ggchord(
  seq_data = seq_data_example,
  ribbon_data = ribbon_data_example,
  ribbon_color_scheme = "single",  # Uniform color
  ribbon_colors = "orange"         # Custom color
)
print(p5)

Impact of Sequence Layout on Ribbons

Ribbons automatically adapt to sequence orientation, curvature, and spacing:

p6 <- ggchord(
  seq_data = seq_data_example,
  ribbon_data = ribbon_data_example,
  seq_orientation = c(1, -1, 1, -1),  # Sequence orientation
  seq_curvature = c(0, 2, -2, 6),     # Curvature
  seq_gap = c(0.1, 0.05, 0.09, 0.05), # Inter-sequence gaps
  seq_radius = c(1, 5, 1, 1)          # Sequence radii
)
print(p6)

4.3 Adding Gene Annotation Information

Gene annotation data (gene_data) marks gene positions on sequences, with colors defaulting to strand direction (strand):

# Show gene annotations
p7 <- ggchord(
  seq_data = seq_data_example,
  gene_data = gene_data_example
)
print(p7)

Customizing Gene Arrow Styles

Adjust gene colors via gene_color_scheme or display gene labels:

# Color by gene annotation category
p8 <- ggchord(
  seq_data = seq_data_example,
  gene_data = gene_data_example,
  gene_color_scheme = "manual"  # Color by gene annotation (anno)
)
print(p8)

# Display gene labels and adjust styles
p9 <- ggchord(
  seq_data = seq_data_example,
  gene_data = gene_data_example,
  gene_label_show = TRUE,        # Show labels
  gene_label_rotation = 45,      # Label rotation angle
  gene_label_radial_offset = 0.1, # Radial offset of labels
  panel_margin = list(l = 0.2)    # Left margin
)
print(p9)

5. Comprehensive Example

Using sequence, alignment, and gene data simultaneously with fine parameter adjustments:

p10 <- ggchord(
  seq_data = seq_data_example,
  ribbon_data = ribbon_data_example,
  gene_data = gene_data_example,
  title = "Multiple Sequence Alignment Chord Diagram (with Gene Annotations)",  # Title

  # Sequence parameters
  seq_gap = 0.03,
  seq_radius = c(3, 2, 2, 1),
  seq_orientation = c(-1, -1, -1, 1),
  seq_curvature = c(0, 1, -1, 1.5),

  # Gene parameters
  gene_offset = list(             # Gene arrow offset (strand-specific)
    c("+" = 0.2, "-" = -0.2),
    c("+" = 0.2, "-" = -0.2),
    c("+" = 0.2, "-" = 0),
    c("+" = 0.2, "-" = 0.1)
  ),
  gene_label_rotation = list(     # Gene label rotation (strand-specific)
    c("+" = 45, "-" = -45),
    c("+" = 0.2, "-" = -0.2),
    c("+" = 0.2, "-" = 0),
    c("+" = 0.2, "-" = 0.1)
  ),
  gene_width = 0.08,              # Gene arrow width
  gene_label_show = TRUE,         # Show gene labels

  # Ribbon parameters
  ribbon_gap = 0.1,
  ribbon_color_scheme = "pident", # Color by identity

  # Axis parameters
  axis_label_orientation = c(0, 45, 80, 130), # Tick label angles
  axis_tick_major_length = 0.03,
  axis_label_size = 2,

  # Overall style
  rotation = 45,  # Plot rotation angle
  show_axis = TRUE,
  panel_margin = list(t = 0.1)
)
print(p10)

6. Notes

• ggchord is currently in early development; some parameter combinations may cause graphical distortions, which will be optimized in future versions.
• Display effects of gene labels and ribbons may require multiple parameter adjustments for optimal results.
• For more parameter details, refer to the function documentation: ?ggchord.

ggchord documentation built on Aug. 8, 2025, 6:15 p.m.