ggplasmidZY

ggplasmidZY creates circular and multi-line linear maps of plasmids and bacteriophage genomes with ggplot2. It combines gene arrows, GC content, GC skew, category-based colors, legends, and automatic label placement in standard ggplot objects.

Start here

Install the development version and load the publicly available GenBank example in RStudio:

install.packages("remotes")
remotes::install_github("yzhong005/ggplasmidZY")

library(ggplasmidZY)

# The GenBank ORIGIN sequence is read together with the feature annotation.
annotation <- read_plasmid_annotation(
  gbk = system.file("extdata", "pSGNDM_5.gbk", package = "ggplasmidZY")
)

The publicly available pSGNDM-5 reference plasmid is 84,257 bp in length. It was described by Zhong Y, Guo S, Schlundt J, and Kwa AL in JAC-Antimicrobial Resistance (2022;4(4):dlac071). See the publication.

To use your own GenBank file, replace the system.file() path with the path to your .gbk file. A separate FASTA is not needed when the GenBank file contains its ORIGIN sequence. For annotation-table input, read the corresponding FASTA file and pass it as fasta; the Installation and input formats page shows that workflow in detail.

Demo figures

Each figure is generated by the exact code block immediately above it.

Circular map: IGV palette and dashed labels

This circular-map example uses the igv palette from ggsci, displays a relatively large number of labels, and uses light-gray dashed leader lines. label_exclude_categories removes labels only; the corresponding gene arrows remain in the map.

p_circular <- ggplasmid(
  annotation = annotation,                    # features and GenBank sequence
  name = "pSGNDM-5",                          # plot name
  layout = "circular",                        # circular map
  palette = "igv",                            # ggsci palette
  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 testing overlap
  label_text_size = 3.5,                       # readable label size
  label_linewidth = 0.55,                      # thicker leader lines
  label_line_linetype = "dashed",              # dashed leader lines
  label_text_colour = "category",              # label text follows feature colors
  label_line_colour = "grey70",                # light-gray leader lines
  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.05,                    # short initial connector
  inner_radius = 0.30,                          # center-hole size
  legend_position = "right"                    # reserve height for the map
)

p_circular

For detailed circular-map changes, see the Circular maps page.

Linear map: five rows with default connectors

This linear-map example uses a different palette and displays the genome across five rows. The plot_line_num argument controls how the genome is divided across multiple horizontal lines. The connector direction is intentionally left at its default vertical setting. The 45-degree connector option is documented on the detailed Linear maps page rather than on this front page.

p_linear <- ggplasmid(
  annotation = annotation,                    # features and GenBank sequence
  name = "pSGNDM-5",                          # plot name
  layout = "linear",                          # multi-line linear map
  palette = "aaas",                           # a different ggsci palette
  plot_line_num = 5,                           # split the genome across five rows
  max_labels = 48,                             # allow more labels overall
  linear_label_wrap_width = 16,                # keep long labels compact
  linear_label_max_lines = 2,                  # use at most two text rows
  linear_row_spacing = 3.8,                    # gap between genome rows
  linear_label_offset = 0.14,                  # initial gap above each gene row
  linear_label_allow_gene_line_crossing = FALSE,
  label_text_angle = 0,                        # keep text horizontal
  label_text_colour = "black",                 # fixed label text color
  label_line_colour = "grey70",                # fixed leader-line color
  gc_skew_height = 0.28,                        # make GC skew visible
  gc_content_height = 0.14,                     # make GC content visible
  gc_content_linewidth = 0.8,                  # thicker GC-content line
  gc_legend_columns = 1,                        # keep GC keys together
  legend_position = "right"                    # reserve height for five rows
)

p_linear

For labels on both sides, a cropped sequence region, label angles, or manual placement controls, continue to the Linear maps and Label control pages.

Documentation map

• Installation and input formats: install the package and prepare GenBank, FASTA, or annotation-table input.
• Circular maps: reproduce several circular figures and tune ring, GC, legend, palette, and label settings.
• Linear maps: compare single-side, diagonal, two-sided, and cropped-region layouts.
• Label control: select labels, avoid overlap, wrap text, inspect omitted labels, and make manual adjustments.
• Styling, colors, and GC tracks: tune palettes, arrows, labels, GC tracks, legends, fonts, and output.

Source repository

The package source, public demo data, issue tracker, and example script are at github.com/yzhong005/ggplasmidZY.