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

Set values by sequence and strand

On this page

• Prepare this page
• The capability remains supported
• Supported parameters
• Compatibility and design tradeoffs
• Check your result

Adjust geometry by sequence or strand, retaining useful flexible parameter formats while making their scope explicit.

Previously described as “flexible parameter formats”, this feature configures geometry per sequence or strand.

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

The capability remains supported

Sequence-local geometry often needs one value per sequence or strand; duplicating whole layers would obscure that intent. Keep scalars as the default, use vectors named by accver when values differ, and name strand pairs +/-.

Code

# Sequence IDs remain stable when the data is reordered; positional lists do not.
radii <- setNames(c(1.1, 1, 1, 1), seqs$accver)
widths <- c("+" = .045, "-" = .065)
p_parameters <- ggchord(seq_data = seqs, gene_data = genes) +
  geom_seq(seq_radius = radii) +
  geom_gene(
    width = widths,
    position = position_strand(c("+" = .08, "-" = -.1))
  ) +
  geom_seq_label(size = 4) +
  scale_seq_colour_manual(values = seq_palette) +
  scale_gene_fill_manual(values = gene_palette) +
  coord_chord() +
  doc_theme
p_parameters

Run this page’s preparation code first. Named radii survive sequence reordering; unnamed entries follow current positions. These are layout/geometry values, not a universal extension to colours or themes.

Supported parameters

Interface	Parameters	Matching scope
geom_seq()	seq_radius, seq_curvature, seq_gap, seq_orientation	Sequence; radius/curvature effects depend on coordinates
geom_seq_label()	labels, seq_label_radius, seq_label_rotation, size, seq_label_hjust, seq_label_vjust	Sequence; seq_label_orientation is one mode choice
geom_link_ribbon() / geom_link_line()	link_gap	Endpoint sequence; Cartesian control points are not per-sequence scalars
geom_gene() / geom_feature()	width	Sequence and/or +/- strand
position_strand() / position_plasmid()	offset	Sequence/strand; prefer Positions over compatibility offset inputs
Fixed geom_gene_label() / geom_feature_label()	label_radial_offset, label_circum_offset, label_circum_limit, label_rotation	Sequence/strand, not every text setting
position_track()	Numeric width, gap	Native numeric placement by sequence; physical unit() is a scalar absolute size

seq_order is itself an ordering. Automatic label_layout is a mode; manual angles and offsets belong to fixed label layers rather than automatic-label .... Axes/themes, aesthetics, scales and guides do not inherit the list extension. Manual scales do accept vectors named by data categories, under ordinary ggplot2 scale semantics; see styling.

Compatibility and design tradeoffs

Equal-length unnamed vectors, sequence-named lists, position-named lists and unnamed lists remain compatible. Gene/feature entries can additionally contain strand pairs. Each parameter still validates its own type, length, range and units. This does not make a list a valid container for any argument.

The v0.16.6 RC audit retains these equivalent forms: no deletion or deprecation is announced. Positional forms follow the current displayed sequence order after filtering; names take precedence when they match accession IDs. In width/fixed-label lists, a per-sequence entry is a strand pair; list(value) is the scalar recycling form. Position offsets also accept scalar entries per sequence. Explicit strand-named Position offsets are signed; an omitted strand or sequence uses zero. position_plasmid() uses one shared offset and rejects strand pairs. Use unique keys: accession IDs "1", "+" or "-" can be ambiguous with index/strand shorthand, so prefer sequence-named nested lists for strand values. Native track width/gap must cover all displayed sequences. These rules do not extend to themes.

Numeric values do not all share one unit: seq_gap is a proportion, rotations are degrees, and physical track sizes use explicit unit() values. seq_backbone_gap and seq_backbone_width are scalar style controls, not members of the list rule. Automatic collinear orientation belongs to coord_collinear(orientation = "auto"); geom_seq(seq_orientation = ...) supplies numerical +1/-1 sequence directions.

Check your result

Named-vector keys must match actual accver values or +/− strands. Recheck matching after reordering; list rules do not extend to themes, scales or aesthetics.

Continue: Mappings, scales, guides and themes →