0.16.6 documentation

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

Export, preview and diagnostics

On this page

• Prepare this page
• Save the intended size
• Consume geometry by name
• Interpret evidence
• Complete layout, tables and opt-in ordering
• Check your result

Inspect figures at their actual export dimensions, save with standard ggsave(), and understand what layout tables and diagnostics establish.

Prepare this page

In a fresh R session, run the code below, then follow this page in order. Colours and layout are optional display choices; inputs select only the fields needed.

Preparation code — run once on this page

Code

library(ggchord)
library(dplyr)
data(seq_data_example)
data(ribbon_data_example)
data(gene_data_example)
seqs <- seq_data_example |>
  select(accver, length)
links <- ribbon_data_example |>
  select(qaccver, saccver, qstart, qend, sstart, send)
# The fixture preserves biological strands separately from its old display strands.
genes <- gene_data_example |>
  transmute(accver, start, end, strand = source_strand)

# Optional appearance choices; none of these columns or scales is required input.
library(ggchord)
seq_palette <- setNames(
  c("#E64B35", "#233E4A", "#269B82", "#D59B17"),
  c("MT108731.1", "MT118296.1", "OQ646790.1", "OR222515.1")
)
gene_palette <- c("+" = "#CE1536", "-" = "#346B9D", "." = "#8291A6")

library(ggchord)
doc_background <- "#FFFCF5"
identity_palette <- c("#303B71", "#36537D", "#269B82", "#A5D52C", "#ECEB31")
identity_values <- c(0, 0.5, 0.8, 0.9, 1)
identity_breaks <- c(0, 50, 80, 90, 100)
doc_legend_theme <- theme(
  legend.title = element_text(size = 13, face = "bold"),
  legend.text = element_text(size = 11),
  legend.key.width = unit(9, "mm"), legend.key.height = unit(5, "mm"),
  legend.spacing.x = unit(9, "mm"), legend.spacing.y = unit(7, "mm"),
  legend.margin = margin(l = 4, r = 4, unit = "mm")
)
sequence_guide <- guide_ggchord_legend(nrow = 1, theme = doc_legend_theme)
strand_guide <- guide_ggchord_legend(
  nrow = 1, override.aes = list(strand = c("+", "-")), theme = doc_legend_theme
)
identity_guide <- guide_ggchord_colourbar(
  position = "left", direction = "vertical",
  theme = theme(
    legend.key.height = unit(75, "mm"), legend.key.width = unit(5, "mm"),
    legend.title = element_text(size = 13, face = "bold"),
    legend.text = element_text(size = 11), legend.margin = margin(r = 7, unit = "mm")
  )
)
doc_theme <- theme_ggchord_publication(
  axis.text = element_text(size = 11),
  axis.text.check.overlap = TRUE
) +
  theme(
    legend.position = "bottom",
    legend.title = element_text(size = 13, face = "bold"),
    legend.text = element_text(size = 11),
    legend.key.width = unit(9, "mm"), legend.key.height = unit(5, "mm"),
    legend.spacing.x = unit(9, "mm"), legend.spacing.y = unit(7, "mm"),
    legend.box.spacing = unit(6, "mm"),
    plot.background = element_rect(fill = doc_background, colour = NA),
    panel.background = element_blank(),
    plot.title = element_text(face = "bold", size = 18),
    plot.subtitle = element_text(size = 10, colour = "#5C625A"),
    plot.margin = margin(14, 18, 14, 18)
  )
doc_axis <- function(coordinates = "relative") {
  scale_seq_position_continuous(
    coordinates = coordinates, n.breaks = 3, minor_breaks = NULL,
    labels = function(x) format(x, scientific = FALSE, big.mark = ",", trim = TRUE)
  )
}

anchors <- genes |>
  group_by(accver) |>
  slice_max(end - start, n = 1, with_ties = FALSE) |>
  ungroup() |>
  select(accver, start, end)
p_collinear <- ggchord(seq_data = seqs, ribbon_data = links, gene_data = genes) +
  geom_link_ribbon(aes(ribbon_fill = qaccver), alpha = .7) +
  scale_ribbon_fill_manual(values = seq_palette, guide = "none") +
  geom_seq() +
  geom_gene(position = position_strand(.1)) +
  geom_seq_label(size = 4) +
  coord_collinear(anchor = anchors, align = "center", orientation = "auto") +
  doc_axis() +
  scale_seq_colour_manual(values = seq_palette) +
  scale_gene_fill_manual(values = gene_palette) +
  doc_theme
p_collinear

Save the intended size

After creating p_collinear in three modes:

Code

ggsave("comparison.png", p_collinear, width = 8, height = 5, units = "in", dpi = 144)

RStudio’s Plots pane uses the current panel size and can rearrange labels and guides. Preview at the same explicit dimensions before final ggsave():

Code

view_ggchord(p_collinear, width = 8, height = 5, units = "in")
diagnosis <- diagnose_ggchord(p_collinear, width = 8, height = 5, units = "in")

view_ggchord() returns a temporary image path; it does not keep a final export. The website, README and vignettes share PNG assets exported through standard ggsave() at sizes listed in the gallery. They do not capture an interactively resized panel. Use your intended PDF/SVG device explicitly for final vector output; font availability and embedding remain device-dependent.

Consume geometry by name

Code

geometry <- export_ggchord_layout(p_collinear, include = "seq")
rows <- geometry$seq |>
  distinct(layer_id, component, source_row)

export_ggchord_layout() is the recommended layer-aware table interface. get_chord_layout() retains the complete documented layout; neither is deprecated. Select named fields, not fixed column positions. source_row indexes resolved layer input; IDs are build-local resources, not permanent biological identifiers. See the complete layout contract.

Interpret evidence

diagnose_ggchord() separates measured panel size from geometry convergence. A measured panel does not certify collision-free text, font embedding or all applications. Inspect warnings, text/guide measurements and placement reasons. optimize_ggchord_layout() applies documented opt-in adjustments; retain a copy and inspect the result. Previews and diagnostics use independent render copies. Direct mutation of shared ggproto layer environments retains ordinary ggplot2 reference semantics; it is not an automatically isolated edit.

Complete layout, tables and opt-in ordering

Code

full_layout <- get_chord_layout(p_collinear)
layer_tables <- export_ggchord_layout(p_collinear, include = c("seq", "gene"), original_data = TRUE)
layout_choice <- optimize_ggchord_layout(seqs, links, optimize = c("order", "orientation"), weight = "count")

Create p_collinear in three modes first. full_layout retains the complete documented getter result. layer_tables selects sequence/gene tables and resolved original data; it is not a raw-file archive. Layer IDs and source-row roles distinguish independent same-kind layers. Empty components can lack a fixed column prototype. Select fields by name.

layout_choice optimizes declared order/orientation using count weighting because the minimal plotting table deliberately omits alignment-length statistics. It returns a choice for explicit use in sequence settings; it does not mutate the plot or establish biological orientation. Save the choice and compare the result before adopting it. The export asset manifest records exact documentation sizes.

Check your result

Use matching dimensions for preview and saving. Inspect text, guides and warnings; a successful measurement does not certify fonts or release quality across devices.

Continue: Frequently asked questions →