Linear maps

Use layout = "linear" to draw a plasmid or phage genome across a user-defined number of lines. plot_line_num controls how many genome lines are drawn. This page gives four matching examples: single-side labels, diagonal connectors with a tuned layout, labels on both sides of the genome lines, and a cropped sequence region with labels above the map.

library(ggplasmidZY)

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

Demo 1: single-side labels

The default layout places labels above the gene arrows and uses vertical connector lines. Omitting label_line_angle keeps that default direction. The The primer palette gives this first demo a different visual starting point.

# Demo 1: single-side labels with default vertical connectors.
p_linear <- ggplasmid(
  annotation = gbk_data,
  name = "pSGNDM-5",
  layout = "linear",
  palette = "primer",
  plot_line_num = 4,
  max_labels = 36,
  linear_label_wrap_width = 18,
  linear_label_max_lines = 2,
  linear_row_spacing = 4.0,
  linear_label_offset = 0.14,
  linear_label_allow_gene_line_crossing = FALSE,
  label_text_angle = 0,
  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"
)

p_linear

Demo 2: diagonal connectors and a tuned layout

This example combines the earlier diagonal-connector and layout-tuning examples. It uses five genome lines, shorter wrapped labels, compact label lanes, a thicker GC track, and a bottom legend. The text remains horizontal while the connector lines are set to 45 degrees. label_text_colour = "category" demonstrates category-colored label text, and the jama palette changes the feature-arrow colors.

# Demo 2: five-line layout with diagonal connectors and compact label lanes.
p_linear_tuned <- ggplasmid(
  annotation = gbk_data,
  name = "pSGNDM-5",
  layout = "linear",
  palette = "jama",
  plot_line_num = 5,
  max_labels = 48,
  linear_label_wrap_width = 14,
  linear_label_max_lines = 2,
  linear_row_spacing = 3.4,
  linear_label_lane_step = 0.35,
  linear_label_offset = 0.14,
  linear_label_allow_gene_line_crossing = FALSE,
  label_line_angle = 45,
  label_text_angle = 0,
  label_text_size = 3.2,
  gc_skew_height = 0.22,
  gc_content_height = 0.10,
  gc_content_linewidth = 0.7,
  label_text_colour = "category",
  label_line_colour = "grey70",
  legend_position = "bottom",
  legend_columns = 4,
  gc_legend_columns = 4
)

p_linear_tuned

Use plasmid_data(p_linear_tuned)$linear_label_summary to see how many labels were placed and which labels were omitted. label_adjust() can then move one selected label manually without changing the rest of the layout.

Demo 3: labels on both sides

Set linear_label_side = "both" when labels should be distributed above and below each genome line. The label search is still local to each genome line, so labels from different genome lines are not treated as one shared vertical lane. This example uses the complete pSGNDM-5 sequence; the cropped-region example is shown separately in Demo 4. It uses the locuszoom palette and a larger but finite label budget so the two-sided layout remains readable. Category-colored text and dashed category-colored leader lines make the two-sided layout easy to distinguish. Labels that cannot fit without overlap are omitted.

# Demo 3: labels above and below the gene arrows.
p_linear_both <- ggplasmid(
  annotation = gbk_data,
  name = "pSGNDM-5",
  layout = "linear",
  palette = "locuszoom",
  plot_line_num = 4,
  max_labels = 24,
  linear_label_side = "both",
  linear_label_wrap_width = 14,
  linear_label_max_lines = 2,
  linear_row_spacing = 4.0,
  linear_label_lane_step = 0.35,
  linear_label_offset = 0.14,
  linear_label_allow_gene_line_crossing = FALSE,
  label_text_angle = 0,
  label_text_size = 3.2,
  label_text_colour = "category",
  label_line_colour = "category",
  label_line_linetype = "dashed",
  gc_skew_height = 0.28,
  gc_content_height = 0.14,
  gc_content_linewidth = 0.8,
  gc_legend_columns = 1,
  legend_position = "right"
)

p_linear_both

Use plasmid_data(p_linear_both)$linear_label_summary to inspect the number of labels placed on the top and bottom sides, along with any omitted labels.

Demo 4: cropped region with vertical top labels

Use region_start and region_end to plot a fixed 1-based, inclusive region of a GenBank sequence. The features and the GenBank ORIGIN sequence are clipped and rebased to that region before the map and GC tracks are drawn. Here linear_label_side = "top" keeps labels above the map and label_line_angle = 90 gives them vertical connector lines.

# Demo 4: plot only 1,300-16,890 bp with labels above the map.
p_linear_region <- ggplasmid(
  gbk = gbk_file,
  name = "pSGNDM-5",
  layout = "linear",
  region_start = 1300,
  region_end = 16890,
  palette = "futurama",
  plot_line_num = 2,
  linear_label_side = "top",
  max_labels = 36,
  linear_label_wrap_width = 18,
  linear_label_max_lines = 2,
  linear_row_spacing = 4.0,
  linear_label_offset = 0.14,
  linear_label_allow_gene_line_crossing = FALSE,
  label_line_angle = 90,
  label_text_angle = 0,
  gc_skew_height = 0.24,
  gc_content_height = 0.12,
  gc_content_linewidth = 0.8,
  gc_legend_columns = 1,
  label_text_colour = "black",
  label_line_colour = "grey70",
  legend_position = "right"
)

p_linear_region

Use plasmid_data(p_linear_region)$linear_label_summary to inspect placement and omitted labels for the selected region.

Label placement

Linear labels are tested row by row from left to right. Every label first tries the closest available position beside its gene. If that position overlaps an earlier label, the algorithm tries compact outer lanes. Labels are kept below the genome line and GC tracks above when linear_label_allow_gene_line_crossing = FALSE. Labels that cannot fit are omitted rather than being placed over another gene line.

The placement summary is stored on the returned plot:

plasmid_data(p)$linear_label_summary

Useful controls:

• plot_line_num or rows sets the number of genome lines.
• linear_label_side = "top", "bottom", or "both" controls the label side.
• linear_row_spacing changes the distance between genome lines.
• linear_label_wrap_width controls the approximate width before a label is split.
• linear_label_max_lines = 2 limits labels to two text rows.
• linear_label_lane_step changes the gap between successive label lanes.
• linear_label_offset changes the initial gap above or below the gene line.
• linear_label_allow_gene_line_crossing allows labels to cross the line above when set to TRUE.

Connector and text angles

With label_text_angle = 0, text stays horizontal and label_line_angle controls the connector line. For example:

ggplasmid(
  annotation = gbk_data,
  name = "pSGNDM-5",
  layout = "linear",
  plot_line_num = 4,
  label_line_angle = 45,
  label_text_angle = 0
)

label_text_angle accepts a numeric angle in degrees. A nonzero text angle overrides the connector direction so the connector meets the rotated text correctly. If the requested angle cannot place enough labels, the layout tests horizontal and vertical fallback angles and retains the option that places the most labels.

For a first stable layout, use label_text_angle = 0 and four genome lines.

Manual linear adjustments

Manual adjustment: after automatic placement is complete, use label_adjust to move one selected label and its connector without changing the rest of the layout. The single-label helper can target a gene_id:

ggplasmid(
  annotation = gbk_data,
  name = "pSGNDM-5",
  layout = "linear",
  plot_line_num = 4,
  label_adjust = label_adjust(
    "tetR",
    hjust = 0.20,
    vjust = 0.10
  )
)

For several labels, the same argument also accepts a data frame or a named list. The data-frame form can use gene_id, gene, label, or another recognized label column:

adjustments <- data.frame(
  gene_id = c("tetR", "qacE"),
  hjust = c(0.20, -0.10),
  vjust = c(0.10, 0.05)
)

adjustments_list <- list(
  tetR = list(hjust = 0.20, vjust = 0.10),
  qacE = list(hjust = -0.10, vjust = 0.05)
)

# Use either object in the ggplasmid() call:
p_linear_adjusted <- ggplasmid(
  annotation = gbk_data,
  name = "pSGNDM-5",
  layout = "linear",
  plot_line_num = 4,
  label_adjust = adjustments
)

p_linear_adjusted

Replace adjustments with adjustments_list when the named-list form is more convenient.

For label filtering, wrapping, manual movement, and omitted-label diagnostics, see Label control. For GC-track thickness, colors, legends, fonts, and output dimensions, see Styling.