Get Started with glydraw

glydraw draws SNFG glycan cartoons from glycan structure text or glyrepr::glycan_structure() objects.

draw_cartoon() returns a ggplot2 object with class glydraw_cartoon. You can print it directly, pass it to save_cartoon(), or add ggplot2 layers when needed. This vignette uses IUPAC-condensed strings because they are compact and easy to copy into examples.

library(glydraw)

Draw one glycan

The first argument, structure, is the glycan to draw. It can be a character string in a notation supported by glyparse::auto_parse(), or a glyrepr::glycan_structure() value.

n_core <- "Man(a1-3)[Man(a1-6)]Man(b1-4)GlcNAc(b1-4)GlcNAc(b1-"

draw_cartoon(n_core)

For a sketch-like appearance, use draw_cartoon_sketch() instead of draw_cartoon().

draw_cartoon_sketch(n_core)

Basic options

show_linkage

show_linkage controls whether glycosidic linkage annotations are shown. Substituent annotations are always shown.

draw_cartoon(n_core, show_linkage = FALSE)

orient

orient controls the direction in which the glycan extends from its reducing end. Choose "left", "right", "up", or "down"; the default is "left".

draw_cartoon(n_core, orient = "up")

red_end annotation

red_end controls what is drawn after the reducing-end line. Possible values are:

draw_cartoon(n_core, red_end = "")

draw_cartoon(n_core, red_end = "~")

draw_cartoon(n_core, red_end = "Asn")

To annotate an amino-acid sequence at the reducing end, wrap the glycosite in <site> and </site> tags.

draw_cartoon(n_core, red_end = "ABC<site>D</site>EFJHI")

Although this notation is slightly verbose, it lets you use arbitrary characters in the sequence without ambiguity.

draw_cartoon(n_core, red_end = "<site>N</site>-X-S/T")

Styles

glydraw provides many additional visual options, including linewidths, node sizes, colors, and fonts. The style system collects these options while preserving the information conveyed by the glycan notation.

Use the style argument to apply these customizations. By default, style = style_glydraw(), which returns a style object containing the available settings.

style_glydraw()
#> $fuc_orient
#> [1] "flex"
#> 
#> $red_end
#> [1] ""
#> 
#> $edge_linewidth
#> [1] 0.8
#> 
#> $node_linewidth
#> [1] 0.8
#> 
#> $node_size
#> [1] 1
#> 
#> $font_family
#> [1] ""
#> 
#> $colors
#>     glyWhite      glyBlue     glyGreen    glyYellow    glyOrange      glyPink 
#>    "#FFFFFF"    "#0072BC"    "#00A651"    "#FFD400"    "#F47920"    "#F69EA1" 
#>    glyPurple glyLightBlue     glyBrown       glyRed 
#>    "#A54399"    "#8FCCE9"    "#A17A4D"    "#ED1C24" 
#> 
#> $red_end_length
#> [1] 0.6
#> 
#> $red_end_size
#> [1] 6
#> 
#> attr(,"class")
#> [1] "glydraw_style"

The style contains the following parameters:

The following sections describe these settings in more detail.

fuc_orient

fuc_orient controls how Fuc-like triangles are rotated. The default, "flex", points non-reducing Fuc residues toward their rendered linkage direction. Use "up" when every Fuc triangle should point upward.

fucosylated <- "Gal(b1-3)[Fuc(a1-4)]GlcNAc(b1-"

draw_cartoon(fucosylated, style = style_glydraw(fuc_orient = "flex"))

draw_cartoon(fucosylated, style = style_glydraw(fuc_orient = "up"))

red_end in a style

This setting controls the same feature as the red_end argument described above. It is also available in the style object so that it can be reused across drawings. The explicit red_end argument in draw_cartoon() overrides style$red_end.

# The explicit argument overrides the style setting.
draw_cartoon(n_core, red_end = "Asn", style = style_glydraw(red_end = "~"))

red_end_length

red_end_length is the length of the reducing-end line in plot-coordinate units. It can be any non-negative number. Setting it to 0 omits the line and any reducing-end wave or custom text while retaining the core anomer annotation.

draw_cartoon(n_core, style = style_glydraw(red_end_length = 1))

# The custom text is omitted when `red_end_length = 0`.
draw_cartoon(n_core, red_end = "Asn", style = style_glydraw(red_end_length = 0))

red_end_size

red_end_size controls the size of custom text passed through red_end. It does not affect the "~" wave.

draw_cartoon(n_core, red_end = "Asn", style = style_glydraw(red_end_size = 10))

edge_linewidth and node_linewidth

edge_linewidth controls linkage line width. node_linewidth controls the border width of residue symbols.

draw_cartoon(
  n_core,
  style = style_glydraw(
    edge_linewidth = 1.4,
    node_linewidth = 0.4
  )
)

node_size

node_size is a multiplier for the default residue-symbol size. The default is 1. Larger nodes keep the same cartoon layout but draw larger symbols.

draw_cartoon(n_core, style = style_glydraw(node_size = 1.2))

draw_cartoon(n_core, style = style_glydraw(node_size = 1.6))
#> Warning: Linkage annotations are hidden because `node_size` is larger than 1.4.
#> ℹ Set `show_linkage = FALSE` to silence this warning, or use a smaller
#>   `node_size`.

Very large symbols can overlap, so values larger than 2 are rejected. Linkage annotations are hidden with a warning when the requested node size leaves too little annotation space.

Tip: To make a compact cartoon while keeping the symbols legible, increase node_size, node_linewidth, and edge_linewidth. If linkage information is not essential for the display, also set show_linkage = FALSE. This makes sure the cartoon still looks nice when you shrink in Adobe Illustration.

compact_style <- style_glydraw(
  node_size = 1.4,
  edge_linewidth = 1.5,
  node_linewidth = 1.5
)
draw_cartoon(n_core, show_linkage = FALSE, style = compact_style)

colors

colors is a complete named palette in the format returned by glydraw_colors(). Modify entries in that palette to customize the corresponding residue colors. By default, glydraw_colors() uses the colors defined by SNFG.

colors <- glydraw_colors()
colors[c("glyGreen", "glyBlue")] <- c("#4DAF4A", "#377EB8")

draw_cartoon(
  n_core,
  style = style_glydraw(colors = colors)
)

Reusing styles

Create a style object once and reuse it for multiple glycans.

glycans <- c(
  core = n_core,
  antenna = "Gal(b1-4)GlcNAc(b1-",
  fucosylated = "Gal(b1-4)[Fuc(a1-3)]GlcNAc(b1-"
)

my_style <- style_glydraw(
  node_size = 1.4,
  edge_linewidth = 1.5,
  node_linewidth = 1.5
)

draw_cartoon(glycans[[1]], style = my_style)
draw_cartoon(glycans[[2]], style = my_style)
draw_cartoon(glycans[[3]], style = my_style)

Bundled styles

glydraw also provides presets based on common glycan-drawing conventions.

draw_cartoon(n_core, style = style_glygen())

draw_cartoon(n_core, style = style_snfg())

draw_cartoon(n_core, style = style_glycoworkbench())

These styles can also be used with draw_cartoon_sketch().

draw_cartoon_sketch(n_core, style = style_glycoworkbench())

Node highlighting

highlight marks selected residue nodes. It is available when structure is a glyrepr::glycan_structure() object. Node indices match the monosaccharide order in the printed IUPAC-condensed structure.

highlight_glycan <- glyrepr::as_glycan_structure(
  "Gal(b1-3)[GlcNAc(b1-6)]GalNAc(a1-"
)

draw_cartoon(highlight_glycan, highlight = c(1, 3))

Save one cartoon

Use save_cartoon() when you already have one cartoon object.

cartoon <- draw_cartoon(n_core, style = style_glydraw(red_end = "~"))
outfile <- file.path(tempdir(), "n-core.png")

save_cartoon(cartoon, outfile, scale = 2)
outfile
#> [1] "/var/folders/hf/q986zhm912x577_6hxr3m74r0000gn/T//RtmpAUShZW/n-core.png"

glydraw does not expose separate width and height controls because each cartoon has a natural size calculated from its glycan structure. scale preserves the aspect ratio and relative symbol sizes.

Export many cartoons

Use export_cartoons() to draw and save a vector of glycans in one call. The input can be a character vector or a glyrepr::glycan_structure() vector.

glycans <- c(
  core = "Man(a1-3)Man(b1-4)GlcNAc(b1-",
  antenna = "Gal(b1-4)GlcNAc(b1-",
  fucosylated = "Gal(b1-4)[Fuc(a1-3)]GlcNAc(b1-"
)

outdir <- file.path(tempdir(), "glydraw-cartoons")
suppressMessages(
  cartoons <- export_cartoons(
    glycans,
    outdir,
    file_ext = "png",
    scale = 1.5,
    style = style_glydraw(red_end = "~", node_size = 1.1)
  )
)

list.files(outdir)
#> [1] "antenna.png"     "core.png"        "fucosylated.png"

export_cartoons() creates dirname when needed and returns the list of cartoons invisibly. File names come from vector names when present. Unnamed inputs use sanitized IUPAC-condensed structure text as file names, and duplicate names are made unique.