Skip to content
DangJemPublic

About

An R package for sequence visualization with a unified ggplot2 grammar, flexible parameter formats, and support for multiple layouts and composite figures.

Topics

Resources

Stars

16 stars

Watchers

0 watching

Forks

Repository files navigation

ggchord

English · 现代汉语

ggchord: sequences, annotations and relationships

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

Four plotting modules

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.

Real-data figures

I · Multi-sequence relationships

Chord · relationships across four genomes
Four-genome Chord flagship with labelled genes and alignment ribbons
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
Four-genome Collinear flagship with strand-separated genes and cross-row ribbons
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
Radial flagship derived from the four-genome Chord example
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
Sankey flagship derived from the four-genome Collinear example
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 →

II · Single-sequence circular maps

pETDuet-1 circular flagship with features, primers and restriction sites

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.

Complete example

III · HSP Dotplot

Four-sequence matrix of 32 original HSPs

32 original HSPs; Identity by colour, reported alignment length by line width.

Complete example

IV · Multi-view composition

Linked Chord, Collinear, Radial and local-detail views

Global relationships, ordered comparisons and a magnified source interval in one composition.

Complete example

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

Get started

Installation

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.

Draw a first plot

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()

p

This small example shows the layer grammar. The figures above add their own source annotations, display choices and styling.

Preview and save

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)

Design inspiration

The entries distinguish documented design influences from projects considered only in capability research. See the design-source audit for evidence.

Graphical grammar and sequence relationships

  • 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.

Gene arrows, annotation placement and local comparison

  • 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.

Local magnification, aligned characters and figure preview

  • 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.

Report an issue · MIT license

About

An R package for sequence visualization with a unified ggplot2 grammar, flexible parameter formats, and support for multiple layouts and composite figures.

Topics

Resources

Stars

16 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages