0.16.6 documentation

Complete canonical API text; task articles explain the workflows. Tutorials

Site guide · find your task

Setup and learning paths

HomeInstall and prepare the environmentChoose your learning module

Module I · Chord

1.1 Tables and field meanings1.2 Produce and import comparisons1.3 Build the layers step by step1.4 Direction, curvature and clearance1.5 Filter and summarize links1.6 Full source-file workflow1.7 Complete chord showcase

Module II · Collinear

2.1 Reuse chord input tables2.2 Switch coordinates and add layers2.3 Routes, clearance and the ruler2.4 Compare CDS neighbourhoods2.5 Focus, anchors and segments2.6 Complete collinear showcase

Module III · Plasmid

3.1 DNA, annotations and 13 references3.2 From a circle to annotation layers3.3 Features, primers and restriction3.4 Thirteen plasmid references3.5 Complete plasmid cases

Consult as needed · Data and layers

Prepare tables and coordinatesImport and convert dataImport nucleotide and protein alignmentsProject protein intervals to genomic coordinatesFeatures, stacking and genomic decorationLabels and local placementQuantitative tracksMappings, scales, guides and themesSet values by sequence and strandCommon adjustments and grammarExport, preview and diagnostics

Learning map and reference

Articles and complete workflowsFunction referenceReproducible galleryFrequently asked questionsMigrate to the candidate APITerminology and design sourcesDevelopment status and changes

Add an alignment ribbon layer

On this page

• Usage
• Arguments
• Value
• Examples

Draws alignment ribbons. Identity is mapped to ribbon_fill by default; When pident is absent, the default is a fixed grey fill with no Identity guide. Alignment length and identity are never inferred from endpoints. Alternative mappings and legends are controlled with aes(), scale_*() and guides().

Usage

Code

geom_link_ribbon(
  mapping = NULL,
  data = NULL,
  link_ctrl_point = NULL,
  link_gap = NULL,
  link_avoid = c("uniform", "none", "smooth"),
  link_branch = c("none", "query", "subject"),
  link_branch_fraction = 0.15,
  fill = NULL,
  alpha = 0.42,
  colour = "#59636D",
  linewidth = 0.08,
  linetype = NULL,
  adjacent_only = NULL,
  pairs = NULL,
  position = "identity",
  show.legend = TRUE,
  inherit.aes = FALSE,
  ...
)

Arguments

mapping

Default NULL (uses pre-computed data)

data

Default NULL (retrieved automatically from the layout)

link_ctrl_point

Optional vector/list of Bezier edge controls. Two numbers specify one shared control; four numbers specify controls for the two ribbon edges. A per-row list may contain pairs of coordinate vectors. NULL uses the origin c(0, 0) in chord layouts and derives controls from the sequence endpoints in collinear layouts. With shared branches, controls shape the far ends while the junction follows the shared trunk.

link_gap

Optional numeric/vector controlling spacing between sequences and ribbon endpoints. With the default link_avoid = "uniform", NULL uses one obstacle-aware clearance across each endpoint. Use "smooth" for clearance that changes only next to geom_gene() and geom_feature() polygons, or "none" for fixed spacing 0.035. Text and leader lines are ignored. Supplying a number disables the automatic rule and uses that exact spacing. Linear layouts reduce automatic baseline clearance to fit narrow channels; an explicit gap or feature clearance that cannot fit raises an error.

link_avoid

One of "uniform" (default), "none", or "smooth". Smooth avoidance changes clearance locally; uniform avoidance uses one clearance across an endpoint.

link_branch

Share equal query or subject endpoints: "none", "query", "subject".

link_branch_fraction

Shared length relative to the shortest member, in (0, 0.5].

fill

Optional fixed ribbon fill. NULL keeps the default Identity mapping.

alpha, colour, linewidth

Standard fixed ribbon styles. Explicit values take precedence over matching mappings; omitted defaults do not suppress user mappings. For example, omit alpha when mapping ribbon_alpha.

linetype

Fixed outline line type. The default NULL uses solid outlines for adjacent displayed sequences and dashed outlines for non-adjacent sequences. Chord adjacency includes the first/last pair. This follows the final display order, independently of alignment direction. Explicit fixed styles or aes(ribbon_linetype = ...) (also aes(linetype = ...)) replace the automatic styles. Use a matching scale for data mappings; automatic styles do not train a linetype scale. Global line-type mappings are used when inherit.aes = TRUE.

adjacent_only

Whether only neighbouring sequences are connected. NULL uses TRUE in coord_collinear() and FALSE in coord_chord(). Set FALSE to retain cross-track ribbons. Chord neighbours include the first/last sequence pair.

pairs

Optional data frame with qaccver and saccver selecting unordered comparison pairs. With adjacent_only = NULL, explicit pairs take precedence over the coordinate default. Omitted rows are reported by export_ggchord_layout().

position, show.legend, inherit.aes

Standard ggplot2 layer arguments.

...

Additional arguments passed to geom_polygon()

Value

A ggplot2 layer.

Examples

Code

library(dplyr)
data(seq_data_example)
seqs <- seq_data_example |>
  select(accver, length)
data(ribbon_data_example)
links <- ribbon_data_example |>
  select(qaccver, saccver, qstart, qend, sstart, send)
ggchord(seq_data = seqs, ribbon_data = links) +
  geom_seq() +
  geom_link_ribbon()