Skip to contents
Chapters and reference

Module II · Single-sequence circular maps · Section 6 of 12

2.5 Circular labels and overlap handling

Download R scriptIncludes preparation and every page step. File examples need the input bundle; preview and save calls are retained.
On this page

Compare fixed and automatic labels on the same six source-backed pUC19 annotations. Placement, size, wrapping and device dimensions jointly affect readability; a hidden label is not a missing annotation.

1 Prepare this page independently

Requires optional dplyr. Original names remain in finish_features; display text merely appends actual coordinates. Intervals and strands stay fixed. All layers consume the same finish_labels, with 9 × 8 inch figures.

R · Example code
library(ggchord)
library(dplyr)
finish_dna <- plasmid_example_pUC19
finish_seq <- finish_dna[c("accver", "length")]
finish_features <- head(find_common_features(finish_dna), 6)
finish_circle <- ggchord(finish_seq) + geom_seq() + coord_circular()
finish_labels <- finish_features |>
  mutate(anno = paste0(anno, " [", start, "-", end, " bp]"))
finish_feature_base <- finish_circle + geom_feature(data = finish_labels)

2 Fixed labels: orientation, side and rotation

The feature orientation follows each feature. Each subsequent plot changes only horizontal orientation, inside placement or 30-degree rotation. Return to the common baseline instead of accumulating settings. Default overlap is hide, so crowded text may be omitted.

R · Example code
p_comparefixedfeature <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "feature")
view_ggchord(p_comparefixedfeature, width = 9, height = 8, units = "in")
Fixed labels follow feature direction.
Fixed labels follow feature direction. · Open full-resolution figure
R · Example code
p_comparefixedhorizontal <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "horizontal")
view_ggchord(p_comparefixedhorizontal, width = 9, height = 8, units = "in")
Change only fixed text orientation to horizontal.
Change only fixed text orientation to horizontal. · Open full-resolution figure
R · Example code
p_comparefixedinside <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "feature", label_side = "inside")
view_ggchord(p_comparefixedinside, width = 9, height = 8, units = "in")
Change only fixed label side to inside.
Change only fixed label side to inside. · Open full-resolution figure
R · Example code
p_comparefixedrotate <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "feature", label_rotation = 30)
view_ggchord(p_comparefixedrotate, width = 9, height = 8, units = "in")
Add only a 30-degree fixed-label rotation.
Add only a 30-degree fixed-label rotation. · Open full-resolution figure

3 Fixed-label parameters and conflicts

Parameter Default Meaning
label_orientation feature feature/horizontal/radial/tangent
label_side outside outside/inside/auto
label_overlap hide hide/nudge/allow; allow can overlap
label_rotation NULL Extra degrees, resolving to 0
label_radial_offset 0.04 Local-normal displacement, not bp
label_circum_offset NULL Resolves to 0 along the circumference
label_circum_limit NULL Resolves to TRUE for circumferential limits
label_wrap NULL Optional character wrapping width

Do not pass fixed placement controls to automatic repel layers. Match the feature Position; prefer unique feature_id values for subsets/reordering and never reuse an ID for a different interval. In linear mode radial/tangent mean vertical/horizontal rather than circular letter placement.

4 Compare four automatic layouts on identical text

Default feature first tries internal, then adjacent/external placement. Radial, auto and callout provide alternative placement strategies. Layout changes presentation, not source annotations. Keep identical text, requested size and dimensions across all four.

R · Example code
p_comparefeaturefit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature")
view_ggchord(p_comparefeaturefit, width = 9, height = 8, units = "in")
Same annotations with feature-first label placement.
Same annotations with feature-first label placement. · Open full-resolution figure
R · Example code
p_compareradialfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "radial")
view_ggchord(p_compareradialfit, width = 9, height = 8, units = "in")
Change only layout to radial.
Change only layout to radial. · Open full-resolution figure
R · Example code
p_compareautofit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "auto")
view_ggchord(p_compareautofit, width = 9, height = 8, units = "in")
Change only layout to auto.
Change only layout to auto. · Open full-resolution figure
R · Example code
p_comparecalloutfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "callout")
view_ggchord(p_comparecalloutfit, width = 9, height = 8, units = "in")
Change only layout to callout.
Change only layout to callout. · Open full-resolution figure

5 Wrapping, shrinking, hiding and leaders

Starting from feature, change only label_fit to shrink; then return to baseline and set only label_wrap=14. Shrink explicitly permits smaller text down to the default minimum 1.5. It does not shrink indefinitely to guarantee all names. Character wrapping width is not a fixed physical width.

R · Example code
p_compareshrinkfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", label_fit = "shrink")
view_ggchord(p_compareshrinkfit, width = 9, height = 8, units = "in")
Change only fitting to shrink; retain the default 1.5 minimum size.
Change only fitting to shrink; retain the default 1.5 minimum size. · Open full-resolution figure
R · Example code
p_comparewrapfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", label_wrap = 14)
view_ggchord(p_comparewrapfit, width = 9, height = 8, units = "in")
Set only a 14-character wrap width; text remains source names plus coordinates.
Set only a 14-character wrap width; text remains source names plus coordinates. · Open full-resolution figure

From the 14-character wrap example, change only label_fit to ellipsis. Then return to default feature placement and disable only external fallback. Omission/hiding changes display, not source names or features.

R · Example code
p_compareellipsisfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", label_wrap = 14, label_fit = "ellipsis")
view_ggchord(p_compareellipsisfit, width = 9, height = 8, units = "in")
Keep the 14-character width and change only fitting to ellipsis; full source names remain.
Keep the 14-character width and change only fitting to ellipsis; full source names remain. · Open full-resolution figure
R · Example code
p_compareexternaloff <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", external = FALSE)
view_ggchord(p_compareexternaloff, width = 9, height = 8, units = "in")
Disable only exterior fallback; unresolved names may hide while features remain.
Disable only exterior fallback; unresolved names may hide while features remain. · Open full-resolution figure

6 Important automatic-label defaults

Parameter Default Choices and limits
label_layout feature feature/radial/auto/callout; gene layouts differ
label_fit wrap wrap/none/ellipsis/auto/shrink; omission does not edit source text
label_max_lines 2 Inspect together with wrapping
label_min_size 1.5 Lower bound for shrinking
label_side outside outside/inside/auto
external TRUE FALSE prevents exterior fallback; linear mode rejects this constraint
max_overlaps Inf Does not guarantee zero collisions
label_segment_overlap fade Appearance of conflicting leaders
label_segment_overlap_alpha 0.18 Faded leader opacity
label_segment_linetype auto Automatic leader line type
label_segment_layer below below/above; text retains the label layer position
label_repeat individual bracket shares a counted label and arc bracket for consecutive matching short features
label_segment_colour auto Grey for leaders from inside features to exterior labels; accepts an explicit colour

Read exported label placement and fit diagnostics before changing dimensions, label subsets, layout or wrapping. Keep original full names rather than retaining only truncated figure text.

Feature layout uses direct leaders, allowing them to cross features without multi-bend detours. Filled features cover leaders drawn below; transparent fills keep their transparency. Internal single-line names follow circular tracks. Wrapped sources keep one annotation and a continuous glyph on closed circles; a visible coordinate gap retains separate display pieces. A shifted adjacent name receives a short attachment. To restore the label layer’s drawing order:

R · Example code
geom_feature_label_repel(label_segment_layer = "above")

7 Use your annotations

Change only label_max_lines to 3 and explain any improvement. At fixed dimensions, compare exterior fallback on/off. Fixed and automatic layers have different controls. Supply explicit label text or anno, checking IDs, intervals, strands and unique feature_id values. Continue with primer text and the dense pETDuet-1 case.

Neighbouring names compare radial travel with angular displacement; an empty inner track can preserve association better than squeezing names onto the nearest track. Dotted arrow boundaries can come from source segments or cleavage markers. Inspect segments, segment_name and cleavage_arrows; a boundary is not necessarily an independent feature. Top-level feature labels do not automatically add text for every named subsegment.

Dense inner annotations retain source-angle order. Candidate slots check text and leaders together. Leaders may cross features, but do not acquire multi-bend detours around text. With external placement enabled, compact repeated annotations in outer bands can use the exterior queue as a group; inner bands first try inner slots before exterior fallback. This bounded search does not guarantee every density fits inside; inspect visibility, convergence and conflict diagnostics at export dimensions.

8 Shared labels for consecutive repeats

label_repeat = "bracket" is an explicit display style; the default "individual" retains separate labels. Consecutive non-overlapping short features in one band can share a counted arc label and range bracket when name, type, direction and resolved fill agree. An intervening annotation breaks the run. Arrows, coordinates and biological rows remain independent. Visibility and fit exports report represented_by_shared_label for the shared sources. This applies to the feature layout on a single closed circular sequence; other coordinates retain individual labels. The curved range marker is distinct from the label’s simple leader.

R · Example code
features <- find_common_features(plasmid_example_pTRE_Tight_BI)
feature_position <- position_feature_stack(base_position = position_plasmid())
ggchord(plasmid_example_pTRE_Tight_BI[c("accver", "length")], feature_data = features) +
  geom_seq(seq_style = "double") +
  geom_feature_plasmid(position = feature_position) +
  geom_feature_label_repel(
    position = feature_position,
    label_repeat = "bracket",
    label_fit = "shrink",
    label_min_size = 2.5
  ) +
  coord_circular() +
  theme_ggchord_plasmid()

Automatic plasmid axis text hugs the backbone; explicit offsets keep their placement. Circular feature bands reserve gutters for names that cannot fit inside their arrows, and text tracks use measured heights and physical gaps. Explicit spacing remains a minimum. This bounded search does not guarantee conflict-free placement at every density; inspect actual-size export diagnostics.

Default grey dashed lines connect a feature inside the sequence circle to an exterior feature label. Internal neighbouring labels and restriction leaders retain their established style. A centred, isolated name close to its feature omits an unnecessary short attachment; displaced or competing names retain association leaders.

R · Example code
geom_feature_label_repel(
  label_segment_colour = "grey50",
  label_segment_linetype = "dashed"
)

Explicit parameters affect all feature leaders in the layer. A custom ggchord.feature.label.segment theme also overrides the automatic palette. Segment boundaries clip to the actual arrow contour without editing source segments. Wrapped internal labels use a separate concentric baseline for each line. Automatic coordinate text retains a small physical backbone gap; explicit offsets keep their contract.

Automatic coordinate text searches only a bounded channel near the backbone. With axis.text.check.overlap enabled, an unavailable nearby slot may hide ordinary intermediate text while retaining its tick. Origin/end and combined seam strings take priority and remain visible. Diagnostics report hidden_near_backbone and keep the original value in .axis_label. Hidden text uses an empty display string so missing-value markers cannot appear as literal “NA”.

Unresolved endpoint clearance reports endpoint_unresolved while retaining its text. External feature leaders also honour label_segment_overlap: fade reduces opacity under text, clip removes covered portions, and show keeps the full route. Clipping splits existing legs without adding bends.

Search documentation

↑ ↓ select · Enter open · Esc close; or browse by task. API and functions