Circular maps

Circular maps are the default layout for plasmids and circular phage genomes. The examples below use the public pSGNDM-5 GenBank file, whose ORIGIN sequence is read together with its feature annotation.

Setup

library(ggplasmidZY)

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

Demo 1: category-colored labels and solid connectors

This is a label-rich circular layout. It uses the jco palette, keeps labels outside the ring, colors label text by category, and uses solid light-gray leader lines. The legend is placed above the map in a compact five-column layout with larger color keys. The sample ID is larger, dark gray, and set in a bold serif font, while the feature labels use bold sans-serif text and the legends use bold serif text. The circular ruler labels are bold too. The arrows remain visible even when a category is excluded from the label layer.

p_circular_main <- ggplasmid(
  annotation = annotation,                    # features and sequence
  name = "pSGNDM-5",                          # plot name
  layout = "circular",                        # circular map
  palette = "jco",                            # ggsci palette for feature categories
  label_exclude_categories = "Other functions", # hide these labels only
  max_labels = 48,                             # show about 50 selected labels
  label_wrap_width = 18,                       # wrap long labels before overlap testing
  label_text_size = 3.5,                       # readable label size
  label_linewidth = 0.30,                      # thinner leader lines
  label_line_linetype = "solid",               # solid leaders for contrast
  label_text_colour = "category",              # category-colored label text
  label_line_colour = "grey75",                # lighter-gray leader lines
  inner_radius = 0.30,                          # center-hole size
  label_anchor_radius = 1.04,                  # keep text close to the gene ring
  label_lane_step = 0.012,                      # compact radial label layers
  label_line_length = 0.04,                    # short initial connector
  center_text_size = 6.5,                       # larger sample ID
  center_text_colour = "grey30",                # dark-gray sample ID
  font_family = "sans",                         # base and ruler font
  label_font_family = "sans",                   # bold feature-label font
  center_text_font_family = "serif",            # bold center-title font
  legend_font_family = "serif",                # bold legend font
  ruler_fontface = "bold",                      # bold ruler labels
  legend_position = "top",                     # place legends above the map
  legend_columns = 5,                           # compact feature legend
  gc_legend_columns = 3                         # compact GC legend
)

p_circular_main <- p_circular_main +
  ggplot2::guides(
    fill = ggplot2::guide_legend(
      order = 2, ncol = 5, byrow = TRUE,
      keyheight = grid::unit(0.46, "cm"),
      keywidth = grid::unit(0.62, "cm")
    ),
    colour = ggplot2::guide_legend(
      order = 1, ncol = 3, byrow = TRUE,
      keyheight = grid::unit(0.46, "cm"),
      keywidth = grid::unit(0.82, "cm")
    )
  )

p_circular_main

The selected palette changes feature-arrow colors. label_text_colour = "category" applies the same category colors to label text, while label_line_colour controls the leader lines independently.

Demo 2: category-colored dashed labels

This version uses the observable palette, category-colored label text, and category-colored dashed leader lines. It brings the GC-skew and GC-content tracks closer together while keeping a clear gap between the GC-content track and the inner ruler. The ruler labels and border are emphasized, and the map shows a fuller, controlled set of labels.

p_circular_gc <- ggplasmid(
  annotation = annotation,                    # features and sequence
  name = "pSGNDM-5",                          # plot name
  layout = "circular",                        # circular map
  palette = "observable",                     # a different ggsci palette
  max_labels = 55,                             # show a fuller set of labels
  label_wrap_width = 18,                       # shorter label lines
  label_text_size = 3.5,                       # slightly smaller labels
  label_line_linetype = "dashed",              # dashed connectors
  label_text_colour = "category",              # category-colored label text
  label_line_colour = "category",              # category-colored leader lines
  label_anchor_radius = 1.04,                  # keep text close to the gene ring
  label_lane_step = 0.012,                      # compact radial label layers
  gc_skew_radius = 0.80,                        # keep GC skew near GC content
  gc_skew_height = 0.18,                        # emphasize skew amplitude
  gc_content_radius = 0.67,                     # keep a gap to the ruler
  gc_content_height = 0.08,                     # moderate content amplitude
  gc_content_linewidth = 0.60,                  # strengthen content line
  ruler_radius = 0.52,                          # smaller inner ruler ring
  ruler_text_size = 3.0,                         # larger ruler labels
  ruler_fontface = "bold",                      # bold ruler labels
  ruler_linewidth = 0.55,                        # stronger ruler border
  ruler_major_linewidth = 0.50,                 # stronger major ticks
  ruler_minor_linewidth = 0.28,                 # visible minor ticks
  legend_position = "right"                    # keep the map vertically open
)

p_circular_gc

gc_skew_radius, gc_content_radius, and the corresponding height settings change the ring position and track amplitude without changing the sequence or feature coordinates.

Demo 3: map with an upper-left legend

This version uses npg, a smaller center hole, smaller regular-weight black label text, and a compact one-column legend anchored to the upper-left edge of the outer label envelope. It shows about 50 labels without reserving an external legend band.

p_circular_bottom <- ggplasmid(
  annotation = annotation,                    # features and sequence
  name = "pSGNDM-5",                          # plot name
  layout = "circular",                        # circular map
  palette = "npg",                            # a third palette
  max_labels = 48,                             # show about 50 selected labels
  label_wrap_width = 18,                       # short wrapped labels
  label_text_size = 3.0,                       # smaller compact text
  label_fontface = "plain",                    # regular-weight labels
  label_linewidth = 0.45,                      # compact leader lines
  label_line_linetype = "dashed",              # dashed leader lines
  label_text_colour = "black",                 # fixed black label text
  label_line_colour = "grey70",                # light-gray leaders
  label_anchor_radius = 1.04,                  # keep text close to the gene ring
  label_lane_step = 0.012,                      # compact radial label layers
  inner_radius = 0.24,                          # smaller center hole
  gc_skew_radius = 0.82,                        # move skew outward
  gc_content_radius = 0.70,                     # move content outward
  gc_content_height = 0.07,                     # balanced GC-content track
  gc_content_linewidth = 0.55,                  # balanced content line
  legend_position = "left_top",                # legend inside upper-left corner
  legend_text_size = 10,                        # enlarge the corner legend
  legend_columns = 1,                           # one-column feature legend
  gc_legend_columns = 1                         # one-column GC legend
)

p_circular_bottom

The circular controls that most affect space are inner_radius, label_anchor_radius, label_line_length, and legend_position. Move the legend to the right when a bottom legend makes the map too tall. Corner positions use ggplot2's legend.position = "inside" mode. For circular maps, the package extends the four inside anchors to the measured label envelope: the upper-left legend follows (xmin, ymax), upper-right follows (xmax, ymax), lower-left follows (xmin, ymin), and lower-right follows (xmax, ymin). This aligns each legend with the outermost label text rather than with the gene ring.

Main circular controls

• inner_radius controls the size of the center hole.
• gc_skew_radius and gc_content_radius set the GC-track positions.
• gc_skew_height and gc_content_height set track amplitude.
• gc_content_linewidth changes the visible GC-content line thickness.
• ruler_radius controls the radius of the inner ruler ring; smaller values move the ruler closer to the center.
• label_anchor_radius sets the starting distance of outside labels.
• label_line_length sets the radial connector length.
• label_lane_step controls the spacing between successive outside label layers; smaller values keep dense labels closer together.
• label_text_colour accepts a fixed R color, "category", or a column containing valid R colors.
• label_line_colour accepts a fixed R color or a column containing valid R colors.
• Side and corner legends default to one column. Top and bottom legends default to three feature columns, while the GC legend uses three columns so its three entries stay on one row. Set legend_columns or gc_legend_columns explicitly to change this layout.
• legend_position = "right" gives the map more vertical room; legend_position = "bottom" gives a compact wide layout; legend_position = "top" places the legends above the map; and legend_position = "left_top" anchors the legend to the upper-left edge of the label envelope. The other corner positions are "right_top", "left_bottom", and "right_bottom".

For detailed label selection and manual movement, see Label control. For all supported palettes, GC-track styling, and output dimensions, see Styling.

Phage maps

Use the phage wrapper when the annotation categories follow a phage classification scheme:

plot_phage_map(
  gbk = "phage.gbk",
  layout = "circular",
  phage_topology = "linear"
)

phage_topology = "linear" adds a terminal boundary marker to a circular map; it does not switch the map to the multi-line linear layout. Use layout = "linear" for that layout.