🌐 Language Switch: 【现代汉语（Han） | 英文（English）】

ggchord is an R function based on ggplot2 for visualizing BLAST alignment results of multiple sequences as intuitive chord diagrams. It supports extensive style customization, making it easy to display homologous regions and structural relationships between sequences. Version 0.1.0 of ggchord represents a breakthrough upgrade from simple multi-sequence chord diagrams to more feature-rich multi-sequence chord diagrams, capable of simultaneously showing alignment relationships between multiple sequences:

• Each sequence is presented as an arc or custom track, with length proportionally mapped.
• Colored ribbons represent alignment regions between sequences, supporting coloring by similarity or source.
• Equipped with customizable axes for precise annotation of sequence positions and lengths.
• Supports layout optimizations such as global rotation and sequence orientation adjustment to adapt to different analysis scenarios.

It is suitable for research in comparative genomics, pan-genome analysis, phage-host sequence relationship studies, etc., helping researchers quickly identify homologous patterns between sequences.

• Multi-sequence Support: Simultaneously display alignment relationships of 2 or more sequences, no longer limited to pairwise comparisons.
• Sequence-level Customization:
  • Customize sequence order, orientation (forward/reverse), gaps, and radii.
  • Automatically or manually specify sequence colors and labels to improve readability.
• Refined Axes:
  • Each sequence has independent axes with major/minor ticks, clearly labeling length positions.
  • Adjust tick lengths, label sizes, and offsets to balance aesthetics and information density.
• Flexible Ribbon Styles:
  • 3 coloring schemes (single color, by query sequence, gradient by similarity).
  • Adjustable gap between ribbons and sequences; supports customization of Bézier curve control points for smoothness.
• Layout Optimization: The entire graph can be rotated to meet different display needs.
• Debug Mode: Assists in troubleshooting data issues by displaying counts of valid/invalid alignments.

• R (≥ 3.6.0)
• ggplot2 (≥ 3.3.0)
• ggnewscale (≥ 0.5.0)
• RColorBrewer

install.packages("ggplot2")
install.packages("ggnewscale")
install.packages("RColorBrewer")

Install the stable version of ggchord from CRAN:

install.packages("ggchord")

If you want the development version, install it from GitHub:

devtools::install_github("DangJem/ggchord") or install.packages("ggchord_0.2.0.tar.gz")

Three types of input data need to be prepared:

A TSV (Tab-Separated Values) file containing basic sequence information, must include the following columns:

• seq_id: Unique sequence identifier (e.g., gene name, accession number)
• length: Sequence length (positive number)

Example:

seq_data <- read.delim("seq_track.tsv", sep = "\t", stringsAsFactors = FALSE)

The format of seq_track.tsv is as follows (example):

seq_id	length
MT108731.1	64323
MT118296.1	32090
OQ646790.1	57367
OR222515.1	83080

You can automatically generate this table from FASTA files using the following command:

seqkit fx2tab -nil *fna | sed '1i seq_id\tlength' > seq_track.tsv

A TSV (Tab-Separated Values) file containing BLAST alignment results (convertible from outfmt6 or outfmt7 formats), must include the following columns:

• qaccver: Query sequence ID (must exist in seq_data$seq_id)
• saccver: Subject sequence ID (must exist in seq_data$seq_id)
• length: Alignment length
• pident: Sequence similarity (percentage)
• qstart/qend: Start/end positions of the alignment on the query sequence
• sstart/send: Start/end positions of the alignment on the subject sequence

You can use the following script to perform BLAST alignments on example sequences and obtain results in outfmt7 format:

# Script to run BLAST alignments using example FASTA files
seqs=("MT108731.1" "MT118296.1" "OQ646790.1" "OR222515.1")
seqsNum=${#seqs[@]}
ext="fna"
for ((i=0; i<seqsNum-1; i++)); do
  for ((j=i+1; j<seqsNum; j++)); do
    echo -e "Running BLASTN: ${seqs[$i]} vs ${seqs[$j]}"
    blastn \
      -outfmt '7 qaccver saccver pident length mismatch gapopen qstart qend sstart send evalue bitscore qcovs qlen slen sstrand stitle' \
      -query "${seqs[$i]}.${ext}" \
      -subject "${seqs[$j]}.${ext}" \
      -out "${seqs[$i]}__${seqs[$j]}.o7"
  done
done

A TSV (Tab-Separated Values) file, which must include the following columns:

• seq_id: Unique sequence identifier, must correspond to seq_id in the sequence information data (seq_data), such as gene names, accession numbers, etc.
• start: Gene start position
• end: Gene end position
• strand: Strand direction (usually + for forward, - for reverse)
• anno: Gene annotation, such as functional description of the gene

The format of the example file gene_track.tsv is as follows:

seq_id	start	end	strand	anno
MT108731.1	100	200	+	DNA binding protein
MT118296.1	300	400	-	Transcription factor

You can convert GFF3 format files into a gene data table using the gff2gene_track.R script. The script content is as follows:

library(tidyverse)

# Get paths of all gff3 files in the current directory
gff3FilesPath <- list.files(path = ".", pattern = "*.gff3")

# Read all gff3 files and merge into a data frame
gff3Table <- map_df(gff3FilesPath,~read_tsv(.x,show_col_types = F,comment = "#",col_names = F) %>% set_names(c("seq_id", "source", "type", "start", "end", "score", "strand", "phase", "attributes")))

# Filter records of type CDS and extract annotation information
geneTrackTable <- gff3Table %>% filter(type=="CDS") %>% mutate(anno=str_extract(attributes,"(?<=product=)[^;]+(?=;)")) %>% select(seq_id,start,end,strand,anno)

# Save the processed data frame as a TSV file
write_tsv(geneTrackTable,"gene_track.tsv")

After running the above script, a gene_track.tsv file will be generated in the current directory, which can be used as gene data for subsequent analysis and visualization.

# Read sequence length data
seq_data <- read.delim("seq_track.tsv", sep = "\t", stringsAsFactors = FALSE)

# Read and process BLAST data
read_blast <- function(file) {
  df <- read.delim(file, sep = "\t", header = FALSE, stringsAsFactors = FALSE, comment.char = "#")
  colnames(df) <- c("qaccver","saccver","pident","length","mismatches","gapopen",
                    "qstart","qend","sstart","send","evalue","bitscore",
                    "qcovs","qlen","slen","sstrand","stitle")
  df
}
blast_files <- list.files(path = ".", pattern = "*.o7", full.names = TRUE)
all_blast <- do.call(rbind, lapply(blast_files, read_blast))
ribbon_data <- subset(all_blast, length >= 100)

# Read gene annotation data; to make the image more aesthetically pleasing, shorter gene annotations are filtered out here
gene_data <- read.delim("gene_track.tsv", sep = "\t", stringsAsFactors = FALSE) |> dplyr::slice_max(order_by = end-start, n = 5, by = seq_id)

For ggchord, sequence data is the most important and indispensable. By default, sequences will be arranged counterclockwise in the order of the input seq_data. Of course, these can be modified.

part1_1 <- ggchord(
  seq_data = seq_data,
)

For example, in the following example, you can control the order, orientation, and curvature of sequences using seq_order, seq_orientation, and seq_curvature, and set sequence colors using seq_colors.

part1_2 <- ggchord(
  seq_data = seq_data,
  seq_order = c("MT118296.1", "OR222515.1", "MT108731.1", "OQ646790.1"),
  seq_orientation = c(1,-1,1,-1),
  seq_curvature = c(0,2,-2,6),
  seq_colors = c("steelblue", "orange", "pink", "yellow")
)

For gene alignment chord diagrams, sequence alignment is undoubtedly our main focus, so ribbon_data is the most important data next to seq_data. By default, the fill color of ribbons is determined by the percentage identity in the BLAST results.

part2_1 <- ggchord(
  seq_data = seq_data,
  ribbon_data = ribbon_data
)

Of course, these can also be modified. For example, you can set the fill color to be based on the query sequence, making it easier for users to identify alignments between different sequences.

part2_2 <- ggchord(
  seq_data = seq_data,
  ribbon_data = ribbon_data,
  ribbon_color_scheme = "query"
)

If you think color is not important, you can also set it to a single color.

part2_3 <- ggchord(
  seq_data = seq_data,
  ribbon_data = ribbon_data,
  ribbon_color_scheme = "single",
  ribbon_colors = "orange"
)

In addition, ribbons will automatically adjust to perfectly match parameters such as sequence orientation, curvature, spacing, and radius (note: the same applies to axes and gene arrows).

The current version still has some issues; image distortion may occur with certain parameter combinations, which will be fixed in future versions.

part2_4 <- ggchord(
  seq_data = seq_data,
  ribbon_data = ribbon_data,
  seq_orientation = c(1,-1,1,-1),
  seq_curvature = c(0,2,-2,6),
  seq_gap = c(.1,.05,.09,.05),
  seq_radius = c(1,5,1,1)
)

With gene annotation information, we can more easily identify consistent regions in the gene regions of sequences, helping to explore evolutionary relationships between different species.

part3_1 <- ggchord(
  seq_data = seq_data,
  gene_data = gene_data
)

By default, the fill color of arrows follows the strand mode, i.e., using the strand direction of the gene sequence. You can also use the manual mode, where colors are filled based on the anno categories in gene_data.

part3_2 <- ggchord(
  seq_data = seq_data,
  gene_data = gene_data,
  gene_color_scheme = "manual"
)

Of course, gene annotation labels can also be displayed. However, as you can see, adjusting to achieve a perfect effect may take some effort.

part3_3 <- ggchord(
  seq_data = seq_data,
  gene_data = gene_data,
  gene_label_show = T,
  gene_label_rotation = 45,
  gene_label_radial_offset = .1,
  panel_margin = list(l=.2)
)

We usually plot using seq_data, ribbon_data, and gene_data simultaneously, resulting in a more visually appealing image.

part4_1 <- ggchord(
  seq_data = seq_data,
  ribbon_data = ribbon_data,
  gene_data = gene_data,
)

Of course, ggchord also provides rich parameters to control various details of the image.

part4_2 <- ggchord(
  seq_data = seq_data,
  ribbon_data = ribbon_data,
  gene_data = gene_data,
  title = "Multi-sequence Chord Diagram with Gene Annotations",
  seq_gap = .03,
  seq_radius = c(3,2,2,1),
  seq_orientation = c(-1, -1, -1, 1),
  seq_curvature = c(0,1,-1,1.5),
  gene_offset = list(c("+"=.2,"-"=-.2), 
                     c("+"=.2,"-"=-.2), 
                     c("+"=.2,"-"=0), 
                     c("+"=.2,"-"=.1)),
  gene_label_rotation = list(c("+"=45,"-"=-45), 
                             c("+"=.2,"-"=-.2), 
                             c("+"=.2,"-"=0), 
                             c("+"=.2,"-"=.1)),
  gene_label_radial_offset = c(0,0,0,0),
  gene_label_circum_offset = c(1, 0, -2, 0),
  gene_label_circum_limit = c(T,T,T,T),
  gene_width = .08,
  gene_label_show = T,
  gene_color_scheme = "strand",
  ribbon_gap = .1,
  ribbon_color_scheme = "pident",
  ribbon_ctrl_point = c(0,0),
  axis_label_orientation = c(0,45,80,130),
  axis_gap = 0,
  axis_tick_major_number = 5,
  axis_tick_major_length = 0.03,
  axis_tick_minor_number = 5,
  axis_tick_minor_length = 0.01,
  axis_label_size = 2,
  axis_label_offset = 2,
  rotation = 45, 
  show_axis = T,
  panel_margin = list(t=.1),
  debug = TRUE,
)

However, this is still an early version of the software, and there are many imperfect aspects or even bugs. These issues are expected to be resolved in future versions.

• Sequence Arcs: Each colored arc represents a sequence, with length proportionally mapped. Arrows indicate direction (forward/reverse).
• Ribbons: Colored regions connecting different sequences, representing alignment intervals:
  • When colored by similarity, the color gradient reflects sequence identity (e.g., from blue to red indicates increasing similarity).
  • When colored by query sequence, ribbons of the same color originate from the same query sequence.
• Axes: Ticks and numbers outside each sequence arc, labeling sequence positions (units match sequence length) for easy localization of alignment regions.

• Advanced Arc and Line Mode Optimization:
  • Through enhanced curve-fitting algorithms, "arc mode" and "line mode" in pairwise sequence visualization achieve smoother transitions between different alignment regions. For example, when visualizing two closely related sequences with multiple short alignments, arcs or lines can now connect these regions more elegantly, reducing visual clutter.
  • Ensures more accurate representation of alignment data. In previous versions, there might have been slight distortions in visualization, especially for long-distance alignments. Now, the lengths and positions of arcs and lines more accurately match actual alignment coordinates, providing a more realistic view of sequence relationships.
• Precise Curvature and Gap Control:
  • Users can now control the curvature of arcs in the chord diagram with finer precision. A new parameter has been introduced to allow step-by-step adjustment of arc curvature, enabling users to highlight different types of alignment patterns. For instance, more pronounced curvature can be used to emphasize highly conserved regions, while flatter curves can be used for less significant alignments.
  • The gap between sequences and ribbons can be adjusted with greater granularity. This is useful for visualizing complex alignment scenarios where different sequences have varying degrees of similarity. Users can now set different gap values for different sequence pairs, ensuring the visualization is both clear and informative.
• Enhanced Color Customization:
  • Version 0.2.0 offers a wider range of color palettes for sequences and ribbons. In addition to existing default color schemes, users can now choose from various predefined palettes optimized for different types of data visualization. For example, there are palettes designed to highlight high-contrast regions and those for creating more subtle and aesthetically pleasing visualizations.
  • When using the pident color scheme for ribbons, users can now customize gradient colors. This allows for more personalized visualization, better representing the distribution of sequence similarity. For example, users can choose a heatmap-like gradient to clearly show the range of similarity values from low to high.

• Supports separate management of sequence, alignment, and gene data via seq_data, ribbon_data, and gene_data.
• Added sequence orientation control, custom order, gap, and radius adjustment.
• Implemented customizable axes (major/minor ticks, label positions).
• Ribbons support 3 coloring schemes (single color, by query sequence, by similarity gradient).
• Added global rotation and debug mode.

• Added multi-sequence support (upgraded from pairwise).
• Added "arc mode" and "line mode" switching for pairwise sequences.
• Supported arc curvature adjustment and gap control.

• Initial release, supporting chord diagram visualization for pairwise BLAST alignments.

Issue reports for bugs or feature requests are welcome, as are contributions via Pull Requests. For usage issues, refer to example code or enable debug mode (debug = TRUE) to troubleshoot data problems.

This project is licensed under the MIT License - see the LICENSE file for details.