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.
install.packages("ggplot2")
install.packages("ggnewscale")
install.packages("RColorBrewer")| Parameter Category | Parameter Name | Type | Default Value | Description |
|---|---|---|---|---|
| Core Data | seq_data |
data.frame/tibble | - | Data frame containing sequence information, must include columns: - seq_id: Unique sequence identifier- length: Sequence length |
ribbon_data |
data.frame/tibble | - | Data frame containing BLAST alignment results, optional. If provided, must include columns: - qaccver: Query sequence ID- saccver: Subject sequence ID- length: Alignment length- pident: Percentage of sequence identity- qstart: Query sequence start position- qend: Query sequence end position- sstart: Subject sequence start position- send: Subject sequence end position |
|
gene_data |
data.frame/tibble | - | Data frame containing gene annotation information, optional. If provided, must include columns: - seq_id: Unique sequence identifier- start: Gene start position- end: Gene end position- strand: Strand direction (+ or -)- anno: Gene annotation |
|
| Basic Style | title |
Character | NULL | Main title of the graph |
| Sequence Layout | seq_order |
Character vector | NULL | Specify the drawing order of sequences; if NULL, uses the order in seq_data
|
seq_labels |
Character vector or named vector | NULL | Labels for sequences; if NULL, uses seq_id
|
|
seq_orientation |
Numeric vector or single value | 1 | Orientation of each sequence: 1 (forward) or -1 (reverse); default is forward | |
seq_gap |
Numeric or vector | 0.03 | Length consistent with the number of sequences, defining the arc proportion [0,0.5) from the head of one sequence to the tail of the next | |
seq_radius |
Numeric or vector | 1.0 | Radius of sequence arcs, supports single value or vector with length equal to the number of sequences | |
seq_curvature |
Numeric or vector | 1.0 | Curvature of sequence arcs: 1 for standard arc, 0 for straight line, >1 for more curved | |
seq_colors |
Color vector or named vector | NULL | Define colors for each sequence arc; if NULL, automatically generated based on RColorBrewer Set1 | |
| Gene Style | gene_offset |
Numeric, vector, or list | 0.03 | Radial offset distance between gene arrows and sequence arcs. Supports: - Single value: same offset for all strands of all sequences - Vector: length consistent with the number of sequences, same offset for all strands of each sequence - List: named list where each element corresponds to a sequence; elements can be a single value (all strands of the sequence) or a named vector containing “+” and “-” (strand-specific) |
gene_width |
Numeric or vector | 0.1 | Width of gene arrows | |
gene_label_show |
Logical | FALSE | Whether to display gene labels | |
gene_label_rotation |
Numeric, vector, or list | 0 | Rotation angle (degrees) of gene labels, supports the same parameter format as gene_offset
|
|
gene_label_size |
Numeric | 2.5 | Font size of gene annotations | |
gene_label_radial_offset |
Numeric, vector, or list | 0 | Radial offset of gene labels relative to arrows (positive values outward, negative values inward), supports the same parameter format as gene_offset
|
|
gene_label_circum_offset |
Numeric, vector, or list | 0 | Circumferential offset proportion of gene labels along the sequence (relative to gene length), supports the same parameter format as gene_offset
|
|
gene_label_circum_limit |
Logical, vector, or list | TRUE | Whether to limit circumferential offset to no more than half the gene length, supports the same parameter format as gene_offset
|
|
gene_color_scheme |
Character | “strand” | Specify gene color scheme, optional “strand” (by strand direction) or “manual” (manual specification) | |
gene_colors |
Color vector | - | Fill colors for gene arrows, behavior depends on gene_color_scheme:- “strand” mode: supports named vectors (only “+”/“-”), unnamed vectors (first “+” then “-”), or single value (same color for both strands); defaults to red for “+” and blue for “-” - “manual” mode: supports named vectors (corresponding to anno), unnamed vectors (truncate excess, pad insufficiency); defaults to automatically generated colors |
|
gene_order |
Character vector | NULL | Specify the display order of genes in the legend; if NULL, uses the order of genes in the data | |
| Ribbon Style | ribbon_color_scheme |
Character | “pident” | Coloring scheme for ribbons, optional “single”, “query”, or “pident” |
ribbon_colors |
- | - | Color parameters for ribbons: - single: single color (single value or first element of vector) - query: map colors by query sequence (named/unnamed vector or single value) - pident: gradient color scale vector for generating gradients by similarity percentage, defaults to blue-to-yellow gradient |
|
ribbon_alpha |
Numeric | 0.35 | Transparency of ribbons [0,1] | |
ribbon_ctrl_point |
Vector or list | - | Bézier control points for adjusting ribbon shape: - Vector: length 2 (single control point) or 4 (c1x,c1y,c2x,c2y, dual control points) - List: each element is a sublist containing 1-2 control points, defaults to automatic calculation |
|
ribbon_gap |
Numeric or vector | 0.15 | Radial distance between sequence arcs and ribbons | |
| Axis Settings | axis_gap |
Numeric or vector | 0.04 | Radial distance between axes and sequence arcs, supports negative values |
axis_tick_major_number |
Integer or vector | 5 | Number of major ticks per sequence | |
axis_tick_major_length |
Numeric or vector | 0.02 | Length proportion of major ticks | |
axis_tick_minor_number |
Integer or vector | 4 | Number of minor ticks between two major ticks | |
axis_tick_minor_length |
Numeric or vector | 0.01 | Length proportion of minor ticks | |
axis_label_size |
Numeric or vector | 3 | Font size of axis tick labels | |
axis_label_offset |
Numeric or vector | 0 | Offset proportion of axis labels relative to ticks | |
axis_label_orientation |
Character, numeric, or vector | “horizontal” | Orientation of axis labels: - “horizontal”: horizontal direction - Numeric: rotation angle (degrees) - Vector: length consistent with the number of sequences or named vector |
|
| Layout Settings | rotation |
Numeric | 45 | Rotation angle (degrees) of the entire graph |
panel_margin |
List | list(t=0,r=0,b=0,l=0) | Margins around the graph (t=top, r=right, b=bottom, l=left) | |
| Legend & Debug | show_legend |
Logical | TRUE | Whether to display the legend |
show_axis |
Logical | TRUE | Whether to display axes and ticks | |
debug |
Logical | FALSE | Whether to output debug information |