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

Linear multi-sequence collinearity coordinates

On this page

• Usage
• Arguments
• Value
• Details
• Examples

Draws sequences as left-aligned horizontal backbones, ordered from top to bottom by geom_seq(seq_order = ...). All sequences share one linear bp scale. seq_orientation = -1 reverses a sequence together with its features, links and axis without modifying the input data.

Usage

Code

coord_collinear(
  ratio = 1,
  xlim = NULL,
  ylim = NULL,
  expand = FALSE,
  clip = "off",
  fit = c("labels", "geometry", "manual"),
  align = c("left", "center", "right"),
  anchor = NULL,
  orientation = c("manual", "auto"),
  min_support = 0.1,
  segments = NULL,
  segment_gap = 100
)

Arguments

ratio

Fixed y/x aspect ratio, default 1.

xlim, ylim

Optional user limits. Explicit limits take priority over automatically fitted limits.

expand

Logical. Expand coordinate limits, default FALSE. Automatic fitting already includes a small safety margin; set TRUE to request the additional ggplot2 coordinate expansion.

clip

Whether drawing is clipped to the panel, default "off".

fit

Fitting strategy: "labels" includes measured label boxes, "geometry" fits geometric elements only, and "manual" requires explicit xlim and ylim.

align

Display alignment: "left" (default), "center", or "right". Applied to the full sequence or the interval supplied by anchor.

anchor

Optional anchor positions as a numeric vector named by accver, or a data frame with accver and either position or start/end. Every displayed sequence must have exactly one anchor. Missing and duplicate anchors are errors; multiple-copy targets must be selected explicitly before constructing the coordinate system.

orientation

"manual" (default) uses sequence directions supplied by geom_seq(). "auto" derives display directions from interval-link evidence and records support and unresolved cases.

min_support

Minimum directional imbalance in [0, 1] for an automatic change. It is the absolute difference between forward and reverse support divided by their sum, default 0.1. A tie is always unresolved.

segments

Optional data frame with unique window accver, row_id and orientation (1 or -1). Every displayed accession must be declared. Each window has its own local coordinates and reversible source metadata.

segment_gap

Positive display gap in bp scale units when segments is supplied, default 100. It never implies genomic continuity.

Value

A ggplot2 Coord object for composition with a ggchord plot.

Details

In this coordinate system, geom_seq(seq_gap = ...) specifies the distance between consecutive backbones as a proportion of the longest backbone's width (default 0.3). Positive Position offsets point upward and negative offsets downward, independently of sequence orientation. Sequence labels appear to the left of their backbone. Automatic feature labels use local horizontal rows; fixed radial labels are vertical and tangent labels are horizontal. Label side "outside" means above and "inside" below.

Explicit sequence radius, curvature, ring mappings/scales and sequence-label radius cannot be converted and produce an error. Remove these arguments when switching from coord_chord(). Circular-only primer, restriction-site and centre-label layers require coord_circular(); use geom_feature() for general linear annotations. Cross-track links may cross intervening tracks. Explicit link control points use the exported linear layout x/y units; the longest backbone has width 2 (the longest complete display row when segments is supplied). The circular external = FALSE feature-label constraint cannot be converted; remove it to use linear label rows. Gene/feature repel layout modes share the linear row strategy rather than selecting circular label tracks.

align and anchor control a reversible display translation. With no anchor, the selected edge or centre of each complete sequence is placed at x = 0. With an anchor, the selected edge or centre of each anchor interval is placed at x = 0 instead. Left and right refer to the displayed interval, after orientation has been applied. Genomic input coordinates stay unchanged. Sequence order is never changed by alignment or automatic orientation.

orientation = "auto" evaluates interval links against earlier displayed sequences and chooses the direction supported by the larger aligned-interval weight. The first sequence fixes the reference direction. Ambiguous, insufficiently supported and unconnected sequences retain their initial direction, with evidence recorded in the exported layout diagnostics. This is a display heuristic, not a biological strand assignment or a guarantee of a global optimum. It cannot be combined with an explicit geom_seq(seq_orientation = ...).

With segments, each accession remains an independent window but windows sharing row_id occupy one display row. Their table order is left to right; align applies to the whole row. segment_gap reserves display space in bp scale units, independently of omitted genomic length. Internal ends receive break marks. Use segment_ggchord_data() to crop/split input first. Local reversal comes from the table's orientation, so automatic orientation, explicit sequence orientation and anchor conflict with this mode. Ribbon adjacency follows display rows; same-row ribbons are omitted with a report, and explicit same-row pairs or point links are unsupported.

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() +
  geom_seq_label() +
  coord_collinear(orientation = "auto")