Styling, colors, and GC tracks

ggplasmidZY returns a normal ggplot object. Plot geometry, feature colors, label colors, GC-track height, and legend placement can all be changed through arguments to ggplasmid().

Setup

library(ggplasmidZY)

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

Choose a palette

palette controls the colors assigned across all feature categories. The package accepts every exported ggsci::pal_* palette. List the names available in your installed ggsci version with:

sort(sub("^pal_", "", getNamespaceExports("ggsci")[
  grepl("^pal_", getNamespaceExports("ggsci"))
]))

For example, palette = "locuszoom" and palette = "futurama" select two different named ggsci palettes. The package does not require ggplasmid_colors() for palette selection; that helper only lets you inspect the built-in category names and colors.

For example, this circular map uses the lancet palette, about 50 labels, and a bottom legend:

p_palette <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "circular",
  palette = "lancet",
  label_exclude_categories = "Other functions",
  max_labels = 48,
  label_wrap_width = 18,
  label_text_size = 3.3,
  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.24,
  gc_skew_radius = 0.82,
  gc_content_radius = 0.70,
  gc_content_linewidth = 0.45,
  legend_position = "bottom",
  legend_columns = 3,
  gc_legend_columns = 3
)

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

p_palette

The ggsci package must be installed for the named ggsci palettes. GC content and GC-skew colors remain fixed so those tracks keep their meaning.

For legend layout, use legend_position = "right", "left", "top", or "bottom" for an outside legend. Corner positions are "left_top", "right_top", "left_bottom", and "right_bottom"; these use one column by default and keep the legend outside the map. Top and bottom legends default to three feature columns and one GC legend row. Set legend_columns or gc_legend_columns explicitly when a different layout is desired.

Category palettes

Use a built-in palette or provide selected category overrides. A category column is recommended because it controls feature-arrow colors and can also control label text colors when label_text_colour = "category". Other common column names are detected automatically, and any annotation-table column that contains valid R colors can be used with label_text_colour or label_line_colour.

The following figure changes only three feature categories:

p_custom <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "circular",
  palette = "npg",
  max_labels = 48,
  label_text_size = 3.5,
  label_exclude_categories = "Other functions",
  gene_highlight = gene_highlight(
    "Antimicrobial resistance" = "#E41A1C",
    "Replication" = "#377EB8",
    "Mobile element" = "#4DAF4A"
  ),
  label_anchor_radius = 1.04,
  label_lane_step = 0.012,
  legend_position = "right"
)

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

p_custom

ggplasmid_colors() returns the package's built-in category-to-color mapping. It is optional and useful for inspecting built-in category names; users do not need to call it to choose a palette or to define their own category colors.

ggplasmid_colors("plasmid")
ggplasmid_colors("phage")

You can also supply a data frame when colors are easier to maintain outside the plot call:

my_colors <- data.frame(
  category = c("Antimicrobial resistance", "Replication"),
  color = c("#B2182B", "#2166AC")
)

p_custom_table <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  gene_highlight = gene_highlight(my_colors)
)

p_custom_table

gene_highlight() sets selected gene-arrow fill colors. Label text and leader-line colors are controlled separately. Use label_text_colour = "category" to make labels follow the feature/category colors, or pass the name of a column containing valid R colors for custom label text or lines.

Label and arrow appearance

p_label_style <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "linear",
  plot_line_num = 4,
  max_labels = 24,
  linear_label_wrap_width = 16,
  linear_label_max_lines = 2,
  linear_row_spacing = 4.0,
  label_text_size = 3.2,
  gene_border_linewidth = 0.45,     # gene arrow outline
  gene_arrow_head_fraction = 0.35,  # arrow-head size
  label_text_colour = "black",     # fixed label color
  label_line_colour = "grey60",    # leader line color
  label_line_linetype = "dashed",  # leader line style
  gc_skew_height = 0.24,
  gc_content_height = 0.12,
  gc_content_linewidth = 0.8,
  legend_position = "right",
  font_family = "sans"
)

p_label_style

GC content and GC skew

For GenBank input, GC tracks use the ORIGIN sequence directly. For annotation-table input, supply a FASTA file. For circular maps, radius controls position around the center; for linear maps, height controls track amplitude.

p_linear_gc <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "linear",
  palette = "igv",
  plot_line_num = 4,
  max_labels = 30,
  label_text_size = 3.5,
  gc_skew_height = 0.34,       # taller positive/negative skew bars
  gc_content_height = 0.18,    # taller GC-content line
  gc_content_linewidth = 1.0,  # thicker content line
  gc_legend_columns = 1,
  label_text_colour = "black",
  label_line_colour = "grey70",
  legend_position = "right"
)

p_linear_gc

The compact defaults are useful when the map is crowded. Increase these values when the GC tracks are difficult to see, as in the README linear figure.

For circular maps, the corresponding controls are:

p_circular_gc <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "circular",
  palette = "d3",
  max_labels = 48,
  label_wrap_width = 18,
  label_text_size = 3.5,
  gc_skew_radius = 0.82,
  gc_skew_height = 0.14,
  gc_content_radius = 0.70,
  gc_content_height = 0.06,
  gc_content_linewidth = 0.45,
  label_anchor_radius = 1.04,
  label_lane_step = 0.012,
  legend_position = "right"
)

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

p_circular_gc

Legends and output space

Use a right-side legend for a wide linear map:

p_right_legend <- 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,
  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_right_legend

Use a bottom legend when a circular map has enough width:

p_bottom_legend <- ggplasmid(
  annotation = annotation,
  name = "pSGNDM-5",
  layout = "circular",
  palette = "lancet",
  label_exclude_categories = "Other functions",
  max_labels = 48,
  label_wrap_width = 18,
  label_text_size = 3.3,
  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.24,
  gc_skew_radius = 0.82,
  gc_content_radius = 0.70,
  gc_content_linewidth = 0.45,
  legend_position = "bottom",
  legend_columns = 3,
  gc_legend_columns = 3
)

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

p_bottom_legend

The output dimensions are chosen automatically by layout. For custom files, use output = or save the returned plot with ggsave():

ggsave(
  "pSGNDM-5_linear.png",
  p_linear_gc,
  width = 20,
  height = 11,
  dpi = 180
)