Label control

Label placement is the main difference between a readable map and a crowded map. ggplasmidZY keeps the gene arrows fixed, then places eligible labels in available positions around them. The controls below let you decide which labels are eligible, how long they may be, and how much space the layout may use.

Setup

library(ggplasmidZY)

annotation <- read_plasmid_annotation(
  gbk = system.file("extdata", "pSGNDM_5.gbk", package = "ggplasmidZY")
)

Reference demos

The Circular maps and Linear maps pages keep each displayed figure directly below the exact code that generated it. This page focuses on the label-specific controls used by those demos.

Select which labels are shown

These options affect labels, not the gene arrows:

# A fuller circular label layer.
p_compact <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "circular",
  palette = "npg",
  label_exclude_categories = "Other functions",
  max_labels = 48,
  label_wrap_width = 18,
  label_text_size = 3.0,
  label_linewidth = 0.45,
  label_line_linetype = "dashed",
  label_text_colour = "black",
  label_line_colour = "grey70",
  label_anchor_radius = 1.04,
  label_lane_step = 0.012,
  inner_radius = 0.30,
  legend_position = "right"
)

p_compact <- p_compact +
  ggplot2::theme(plot.margin = ggplot2::margin(120, 120, 120, 240))

p_compact

Change one control at a time to compare the result: use max_labels = Inf to show every eligible label, label_pattern = "NDM|CTX|OXA|TEM|Tra|Rep" to keep matching labels, label_min_gap_deg = 8 to require more angular space, or show_labels = FALSE to keep only the feature arrows.

Unknown and hypothetical genes are not labeled by default. Use label_unknown = TRUE when those labels are useful. To remove one category from the label set, use label_exclude_categories, for example:

ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  label_unknown = TRUE,
  label_exclude_categories = "Other functions"
)

Circular label placement

Circular labels are sorted by text length and placed from shorter to longer labels. The first available radial lane is used. If a label overlaps a label already placed, it is tested in a farther outer lane. The label line starts at the gene and ends at the near edge of the label.

Useful circular controls:

• label_wrap_width folds long labels before overlap testing.
• label_text_size changes the measured text size and visible label size.
• label_anchor_radius sets the initial distance of the label from the ring.
• label_line_length controls the radial connector length.
• label_lane_step controls the spacing between successive outside label layers.
• label_min_gap_deg requires extra angular space between labels.
• max_labels limits label count without hiding gene arrows.

For a dense circular map, start with max_labels, label_wrap_width, and label_text_size. Increase label_anchor_radius only when more outer space is available.

Linear label placement

Linear labels are handled independently for each genome line:

1. Genes are assigned to genome lines from left to right.
2. Labels are tested from left to right within each line.
3. Each label first tries the closest position beside its gene.
4. If that position overlaps an earlier label, the label moves to the next compact lane.
5. With linear_label_allow_gene_line_crossing = FALSE, a label cannot move above the genome line directly above it.
6. Labels that cannot fit are omitted and reported in the placement summary.

p_linear <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "linear",
  palette = "npg",
  plot_line_num = 4,
  max_labels = 36,
  linear_label_wrap_width = 18,
  linear_label_max_lines = 2,
  linear_row_spacing = 4.0,
  linear_label_allow_gene_line_crossing = FALSE,
  gc_skew_height = 0.28,
  gc_content_height = 0.14,
  gc_content_linewidth = 0.8,
  gc_legend_columns = 1,
  label_text_colour = "black",
  label_line_colour = "grey70",
  legend_position = "right"
)

plasmid_data(p_linear)$linear_label_summary

The most important linear controls are:

• plot_line_num or rows: number of genome lines.
• linear_label_wrap_width: approximate characters per text row.
• linear_label_max_lines: maximum number of rows for one label.
• linear_row_spacing: distance between adjacent genome lines.
• linear_label_lane_step: distance between successive pushed label lanes.
• linear_label_offset: initial gap between a gene and its label.
• linear_label_allow_gene_line_crossing: whether a label may cross the line above.
• linear_label_line_angle or label_line_angle: connector direction when text is horizontal.
• linear_label_text_angle or label_text_angle: rotation of the label text.

The default linear demo leaves label_line_angle unspecified, so it uses the default vertical direction. The comparison demo uses:

label_line_angle = 45
label_text_angle = 0

This changes the connector direction while keeping the text horizontal. A nonzero text angle takes priority over the connector direction and the connector endpoint is recalculated for the rotated text.

Manual adjustments

Use label_adjust() when one label needs a small final correction. The helper accepts one label directly, for example label_adjust("tetR", hjust = 0.2), and it also accepts a data frame or named list for several labels. Circular adjustments can target label text:

ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  label_adjust = label_adjust(
    label = "RelB/StbD replicon stabilization protein (antitoxin to RelE/StbE)",
    hjust = 0.02,
    vjust = -0.03
  )
)

The same adjustment can be supplied as a data frame or list. For linear maps, target a gene ID so the label and connector move together:

linear_adjustments <- data.frame(
  gene_id = "tetR",
  hjust = 0.20,
  vjust = 0.10
)

p_linear_adjusted <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "linear",
  plot_line_num = 4,
  label_adjust = linear_adjustments
)

Omitted labels and fonts

Inspect the linear placement summary before manually changing many labels:

summary <- plasmid_data(p_linear)$linear_label_summary
summary

If Windows reports a font database warning, use a portable font family:

ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  font_family = "sans"
)