Build layered sequence figures in R with ggplot2: compare multiple sequences, annotate a circular map, inspect HSP alignments and connect independent views.
Important
v0.29.0 is the final release using the legacy API. A major rewrite of ggchord is underway for v0.50.0, and existing plotting code may need changes when you upgrade. Projects that rely on the legacy API can pin v0.29.0.
Website · Usage guide · Figure gallery · Report an issue
| Module | Use it to | Views |
|---|---|---|
| I · Multi-sequence relationships | Compare sequence intervals, gene order and observed relationships. | Chord · Collinear · Radial · Sankey |
| II · Single-sequence circular maps | Place features, primers and restriction sites on one sequence. | Circular |
| III · HSP Dotplot | Inspect alignment intervals on query and subject axes. | Dotplot |
| IV · Multi-view composition | Connect independent plots through explicit source intervals. | Fusion |
The multi-sequence module has four Coord types. Circular and Dotplot add two more; Fusion is the composition layer. Layers, mappings, scales, positions and themes retain their ggplot2 roles.
Chord · relationships across four genomes![]() Combine mixed-curvature backbones, strand-aware CDS arrows, selected source labels and Identity-coloured ribbons. Features and HSPs are display subsets of the original records. Complete example → |
Collinear · order, orientation and cross-row links![]() Compare four genomes on a shared base-pair scale. Selected CDS sit on either side of each backbone; dashed outlines distinguish links across non-adjacent rows. Complete example → |
Radial · synteny along radial spokes![]() Derived from the Chord flagship, using its source preparation and selected features. Radial backbones expose interval relationships while preserving sequence identities and native positions. Complete example → |
Sankey · source intervals across two mirrored columns![]() Derived from the Collinear flagship, retaining its selected genes and HSPs. Mirrored sequence columns show observed interval relationships; ribbon width is not a conserved flow quantity. Complete example → |
A complete circular map with 20 features, five reference primers and 58 grouped cut positions from the declared enzyme set. Original sequence positions and annotation identities are retained.
32 original HSPs; Identity by colour, reported alignment length by line width.
Global relationships, ordered comparisons and a magnified source interval in one composition.
Figures share traceable inputs and plot definitions. See the source records and reproduction notes: Input files · Dotplot / Fusion source · Plot source · Data sources and attribution
R ≥ 4.1.0 · ggplot2 ≥ 4.0.0
Install the stable release from CRAN:
install.packages("ggchord")Install the v0.29.0 release from GitHub:
install.packages("remotes")
remotes::install_github("DangJem/ggchord", ref = "v0.29.0", dependencies = NA)The minimal example below needs only ggchord. Complete data-preparation examples declare optional dependencies such as dplyr, purrr and tidyr alongside their code.
Use bundled tables to draw sequence backbones, alignment ribbons and sequence names. No file download or alignment program is needed.
library(ggchord)
p <- ggchord(seq_data_example, ribbon_data_example) +
geom_seq() +
geom_link_ribbon() +
geom_seq_label() +
coord_chord()
pThis small example shows the layer grammar. The figures above add their own source annotations, display choices and styling.
Preview and save at the same explicit dimensions so labels are arranged for the intended figure size.
view_ggchord(p, width = 10, height = 8, units = "in")
ggplot2::ggsave("ggchord.png", p, width = 10, height = 8, units = "in", dpi = 144)The entries distinguish documented design influences from projects considered only in capability research. See the design-source audit for evidence.
- ggplot2 — Provides the layered grammar and the division of responsibilities between mappings, scales, guides, geometry, coordinates and themes. ggchord follows this model so users can compose layers and supply their own scales and styles.
- BLAST — Informs the compact query/subject field names used to trace alignment records, endpoints and sequence identifiers. Plotting consumes existing results rather than running an alignment program.
- Circos · circlize — Circos informs circular information hierarchy and ribbon presentation; circlize is a capability comparison for multi-track layouts and explicit track/ring contracts.
- clinker · gggenes · genoPlotR — Offer clear examples of strand-aware gene arrows, gene-cluster comparisons and linear synteny. They inform how sequence direction, feature placement and connections are presented together.
- gggenomes — Informs tidy multi-table inputs, focus/sync workflows, feature stacking, local anchoring and local display reversal. Its approach helps keep data preparation distinct from display choices.
- DNA Features Viewer — Provides a reference for readable feature annotations, crowded-label handling and local feature layouts. It informs the emphasis on connecting labels clearly to their source intervals.
- ggmagnify — Provides a reference for connecting an overview to a magnified inset. ggchord develops this presentation idea around explicit source intervals and independently registered sequence views.
- ggmsa — Listed as a character-view research reference in v0.20.0. In v0.28.0, its residue cells and chemistry palettes were inspected directly and informed geom_residue() background sizing and default fill scales. Glyph rendering, exact source registration and user-scale priority remain independently implemented. ggseqalign, ggseqlogo, Jalview and ESPript are research comparisons for aligned characters, sequence logos, column annotations or static output. Their integrations, logo, consensus and conservation layers are not implemented here. Historical records do not establish that each influenced the current layout algorithms.
- ggview — Informs the workflow of previewing a static figure at its intended export size. ggchord uses view_ggchord() for sized preview and standard ggsave() for saving.







