Package {glydraw}

Title:	Draw Beautiful Symbol Nomenclature for Glycans
Version:	0.8.0
Description:	A 'ggplot2'-native plotting engine for drawing reproducible beautiful Symbol Nomenclature for Glycans (SNFG) glycan cartoons from glycan structure objects or text notations, with support for batch export, structural highlighting, and deep appearance customization. It follows the SNFG specification described at https://www.ncbi.nlm.nih.gov/glycans/snfg.html.
License:	MIT + file LICENSE
Suggests:	ComplexHeatmap, ggraph, ggsketch (≥ 2.0.0), knitr, ragg, rmarkdown, systemfonts, testthat (≥ 3.0.0), tibble, vdiffr
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.3
URL:	https://glycoverse.github.io/glydraw/, https://github.com/glycoverse/glydraw
Imports:	glyrepr (≥ 0.10.0), rlang, dplyr, ggplot2 (≥ 4.0.0), igraph (≥ 2.2.0), purrr, png, glyparse, cli, checkmate, scales, fs
Depends:	R (≥ 4.1)
VignetteBuilder:	knitr
BugReports:	https://github.com/glycoverse/glydraw/issues
NeedsCompilation:	no
Packaged:	2026-08-02 06:45:15 UTC; fubin
Author:	Bin Fu [aut, cre, cph], Xisong Feng [aut]
Maintainer:	Bin Fu <23110220018@m.fudan.edu.cn>
Repository:	CRAN
Date/Publication:	2026-08-02 07:50:02 UTC

glydraw: Draw Beautiful Symbol Nomenclature for Glycans

Description

A 'ggplot2'-native plotting engine for drawing reproducible beautiful Symbol Nomenclature for Glycans (SNFG) glycan cartoons from glycan structure objects or text notations, with support for batch export, structural highlighting, and deep appearance customization. It follows the SNFG specification described at https://www.ncbi.nlm.nih.gov/glycans/snfg.html.

Author(s)

Maintainer: Bin Fu 23110220018@m.fudan.edu.cn (ORCID) [copyright holder]

Authors:

• Xisong Feng 1225774778@qq.com (ORCID)

See Also

Useful links:

• https://glycoverse.github.io/glydraw/

• https://github.com/glycoverse/glydraw

• Report bugs at https://github.com/glycoverse/glydraw/issues

Use glycan cartoons as ComplexHeatmap labels

Description

anno_glycan() creates a ComplexHeatmap::AnnotationFunction() that draws glycan cartoons in the order used by a ComplexHeatmap heatmap. The cartoons follow row or column clustering, reordering, and splitting.

Usage

anno_glycan(
  structure,
  which = c("column", "row"),
  side = NULL,
  size = 0.4,
  angle = 0,
  hjust = NULL,
  vjust = NULL,
  nudge_x = 0,
  nudge_y = 0,
  show_linkage = TRUE,
  style = style_glydraw(),
  width = NULL,
  height = NULL,
  show_name = FALSE,
  red_end = NULL,
  orient = NULL
)

Arguments

Details

Column annotations use the visual defaults of scale_x_glycan(): vertical cartoons anchored at their reducing ends and aligned along their bottom bounds. Row annotations use the defaults of scale_y_glycan(): horizontal cartoons aligned along their right bounds and anchored at their reducing ends. side should match the heatmap annotation side and defaults to "bottom" for columns and "left" for rows.

The required annotation width or height is calculated from the largest rendered cartoon, including rotation and perpendicular nudging. Supply width for row annotations or height for column annotations to override the calculated size.

Value

A ComplexHeatmap AnnotationFunction object.

Examples

if (requireNamespace("ComplexHeatmap", quietly = TRUE)) {
  mat <- matrix(
    seq_len(9),
    nrow = 3,
    dimnames = list(paste0("row", 1:3), paste0("column", 1:3))
  )
  structures <- c(
    "GlcNAc(??-",
    "Gal(??-?)GlcNAc(??-",
    "Neu5Ac(??-?)Gal(??-?)GlcNAc(??-"
  )

  ComplexHeatmap::Heatmap(
    mat,
    show_row_names = FALSE,
    show_column_names = FALSE,
    left_annotation = ComplexHeatmap::rowAnnotation(
      glycan = anno_glycan(structures, which = "row")
    ),
    bottom_annotation = ComplexHeatmap::HeatmapAnnotation(
      glycan = anno_glycan(structures, which = "column")
    )
  )
}

Draw a Symbol Nomenclature For Glycan (SNFG)

Description

Draw a Symbol Nomenclature For Glycan (SNFG)

Usage

draw_cartoon(
  structure,
  ...,
  show_linkage = TRUE,
  orient = c("left", "right", "up", "down"),
  highlight = NULL,
  style = style_glydraw(),
  red_end = NULL
)

Arguments

Value

a ggplot2 object

Examples

draw_cartoon("Gal(b1-3)GalNAc(a1-")
draw_cartoon(
  "Gal(b1-3)GalNAc(a1-",
  style = style_glydraw(font_family = "serif")
)

Draw a sketch-style glycan cartoon

Description

draw_cartoon_sketch() uses ggsketch::ggsketch-package geoms to give a glycan cartoon hand-drawn strokes and patterned residue fills. Its glycan layout, annotations, orientation, and sizing are otherwise identical to draw_cartoon().

Usage

draw_cartoon_sketch(
  structure,
  ...,
  show_linkage = TRUE,
  orient = c("left", "right", "up", "down"),
  highlight = NULL,
  style = style_glydraw(),
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "pencil_shade",
  hachure_angle = 45,
  hachure_gap = 0.03,
  fill_weight = 0.5,
  medium = NULL,
  red_end = NULL
)

Arguments

Details

Sketch cartoons always use a handwriting font, ignoring font_family in style. They prefer an installed sketch-style font that contains Greek alpha, Greek beta, and decimal digits so all linkage labels use one font.

Value

A glydraw_cartoon ggplot2 object.

Examples

if (requireNamespace("ggsketch", quietly = TRUE)) {
  draw_cartoon_sketch("Gal(b1-3)GalNAc(a1-", seed = 1)
}

Export all glycan structures to figures

Description

Draw and save one cartoon for each glycan structure in x.

Usage

export_cartoons(
  x,
  dirname,
  ...,
  file_ext = "png",
  dpi = 300,
  scale = 1,
  show_linkage = TRUE,
  orient = c("left", "right", "up", "down"),
  style = style_glydraw(),
  red_end = NULL
)

Arguments

Value

The function returns the list of cartoons implicitly.

File names

IUPAC-condensed nomenclatures are used as file names. If x is a named character vector or named glyrepr::glycan_structure() vector, the vector names are used as file names.

Why not width and height?

The familiar ggplot2::ggsave() interface uses width, height, and dpi because ordinary ggplot2 plots are drawn into a user-chosen device size. glydraw cartoons are different: the natural width and height are calculated from the glycan structure so residues, linkages, labels, and borders stay comparable across different glycans. If users supplied arbitrary width and height, glydraw would either distort that structure-derived layout or need to guess how to reconcile one requested size with the other.

dpi is also not the right control here because changing it alters how point- and inch-based ggplot2 elements are rasterized relative to the fixed cartoon canvas. glydraw therefore keeps an internal fixed design scale and uses scale as a single multiplier for the final pixel dimensions. This preserves the cartoon's aspect ratio and relative appearance while still allowing larger or smaller output files.

Examples

export_cartoons(
  c(
    "Man(a1-3)Man(b1-4)GlcNAc(b1-",
    "Gal(b1-4)GlcNAc(b1-"
  ),
  tempdir()
)

Draw glycans at ggplot2 positions

Description

geom_glycan() draws one glycan cartoon for each data row. Each cartoon is anchored at its mapped x and y position and retains the structure-derived dimensions and appearance used by draw_cartoon(). The optional size aesthetic scales the complete cartoon uniformly, including nodes, lines, text, and spacing, without changing their relative appearance. Like points and text, the cartoons do not expand the position scales beyond their anchor coordinates. Use scale expansion or explicit coordinate limits when the cartoons need more room around the panel edges. Unlike standalone cartoons returned by draw_cartoon(), cartoons in this layer have no output border or background.

Usage

geom_glycan(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  angle = 0,
  show_linkage = TRUE,
  orient = c("left", "right", "up", "down"),
  highlight = NULL,
  style = style_glydraw(),
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  red_end = NULL
)

Arguments

Value

A ggplot2 layer that can be added to a ggplot2::ggplot() object.

Aesthetics

geom_glycan() understands the following aesthetics. x, y, and structure are required; the remaining aesthetics are optional:

• x

• y

• structure, containing glycan structure strings or glyrepr::glycan_structure() values

• size, an optional whole-cartoon scale multiplier that defaults to 1. Mapped values are transformed by ggplot2's size scale; use ggplot2::scale_size_identity() when the mapped values are literal multipliers. This is distinct from node_size, which changes residue size within the cartoon.

• hjust, an optional horizontal justification that defaults to 0.5. Numeric 0 aligns the cartoon content's left bound with x, and 1 aligns its right bound. Use hjust_red_end() to anchor a vertical cartoon at its reducing end.

• vjust, an optional vertical justification that defaults to 0.5. Numeric 0 aligns the cartoon content's bottom bound with y, including the end of a reducing-end annotation line, and 1 aligns its top bound. Use vjust_red_end() to anchor a horizontal cartoon at its reducing end.

• angle, an optional rotation in degrees that defaults to 0. Rotation is applied after the cartoon is drawn, independently of orient.

• alpha, an optional whole-cartoon transparency. The default, NA, is opaque. Each cartoon is composited before alpha is applied so nodes continue to occlude the linkage edges beneath them. Non-opaque values require a graphics device that supports alpha masks and transformations; unsupported devices throw an error rather than render an inaccurate cartoon.

Examples

glycans <- data.frame(
  x = c(1, 3),
  y = c(1, 2),
  size = c(0.7, 1.1),
  structure = c(
    "Gal(b1-3)GalNAc(a1-",
    "Man(a1-3)[Man(a1-6)]Man(b1-4)GlcNAc(b1-"
  )
)

ggplot2::ggplot(
  glycans,
  ggplot2::aes(
    x = .data$x,
    y = .data$y,
    structure = .data$structure,
    size = .data$size
  )
) +
  geom_glycan() +
  ggplot2::scale_size_identity() +
  ggplot2::coord_cartesian(
    xlim = c(0, 4),
    ylim = c(0, 3),
    expand = FALSE
  )

# Bottom-align a row of vertical glycans with different heights.
ggplot2::ggplot(
  glycans,
  ggplot2::aes(x = .data$x, y = 1, structure = .data$structure)
) +
  geom_glycan(orient = "up", vjust = 0)

Draw glycans as ggraph nodes

Description

geom_node_glycan() is a ggraph node layer backed by geom_glycan(). It supplies the node layout's x and y columns as the default position aesthetics and supports ggraph's filter aesthetic.

Usage

geom_node_glycan(
  mapping = NULL,
  data = NULL,
  position = "identity",
  show.legend = NA,
  ...
)

Arguments

Value

A ggplot2 layer that can be added to a ggraph::ggraph() plot.

Aesthetics

geom_node_glycan() understands the same aesthetics as geom_glycan(). structure is required, while x and y default to the node layout coordinates. It additionally supports filter, a logical aesthetic that selects which nodes are drawn.

Examples

if (requireNamespace("ggraph", quietly = TRUE)) {
  graph <- igraph::make_ring(2)
  igraph::V(graph)$glycan <- c(
    "GalNAc(a1-",
    "Gal(b1-3)GalNAc(a1-"
  )

  ggraph::ggraph(graph, layout = "linear") +
    ggraph::geom_edge_link() +
    geom_node_glycan(ggplot2::aes(structure = .data$glycan))
}

Construct a glycan grob

Description

glycanGrob() prepares the complete drawing specification for one glycan as a grid grob. It is the low-level drawing primitive used by draw_cartoon().

Usage

glycanGrob(
  structure,
  ...,
  show_linkage = TRUE,
  orient = c("left", "right", "up", "down"),
  highlight = NULL,
  style = style_glydraw(),
  red_end = NULL
)

Arguments

Value

A glycanGrob object inheriting from grid::gTree().

Examples

grob <- glycanGrob("Gal(b1-3)GalNAc(a1-")
grid::grid.draw(grob)

Default color palette in glydraw

Description

This palette uses the SNFG standard defined in https://www.ncbi.nlm.nih.gov/glycans/snfg.html.

Usage

glydraw_colors()

Value

A named character vector of colors.

Examples

glydraw_colors()

Use glycan cartoons as legend labels

Description

guide_glycan() is a legend guide that replaces the usual text labels with glycan cartoons while retaining the legend keys drawn by the plot layers. Mapped discrete values and values returned by the scale's labels argument may be glycan structure strings supported by glyparse::auto_parse() or glyrepr::glycan_structure() vectors.

Usage

guide_glycan(
  title = ggplot2::waiver(),
  theme = NULL,
  position = NULL,
  direction = NULL,
  override.aes = list(),
  nrow = NULL,
  ncol = NULL,
  reverse = FALSE,
  order = 0,
  size = 0.4,
  orient = c("left", "right", "up", "down"),
  hjust = 0,
  vjust = vjust_red_end(),
  show_linkage = TRUE,
  style = style_glydraw(),
  red_end = NULL
)

Arguments

Value

A ggplot2 legend guide that draws glycan cartoons in place of text labels.

Examples

glycans <- data.frame(
  structure = c(
    "Gal(b1-3)GalNAc(a1-",
    "Man(a1-3)[Man(a1-6)]Man(b1-4)GlcNAc(b1-"
  ),
  abundance = c(12, 8)
)

ggplot2::ggplot(
  glycans,
  ggplot2::aes(
    x = .data$structure,
    y = .data$abundance,
    fill = .data$structure
  )
) +
  ggplot2::geom_col() +
  ggplot2::scale_fill_discrete(guide = guide_glycan())

Anchor glycan cartoons at their reducing ends

Description

These helpers align the reducing end of every glycan cartoon with its anchor in geom_glycan(), scale_x_glycan(), scale_y_glycan(), or guide_glycan(). Use hjust_red_end() for horizontal alignment when orient is "up" or "down", and use vjust_red_end() for vertical alignment when orient is "left" or "right". Because the required justification is calculated separately from each cartoon's rendered bounds, the helpers also work for collections of glycans with different asymmetric branches. Glycan scales and guides use reducing-end justification by default along the axis perpendicular to the drawing orientation; geom_glycan() remains centered by default.

Usage

hjust_red_end()

vjust_red_end()

Value

A reducing-end justification marker accepted by the glycan layer, scales, and guide.

Examples

glycan <- data.frame(
  x = 0,
  y = 0,
  structure = "Man(a1-3)[Man(a1-6)]Man(b1-4)GlcNAc(b1-"
)

ggplot2::ggplot(
  glycan,
  ggplot2::aes(x = .data$x, y = .data$y, structure = .data$structure)
) +
  geom_glycan(orient = "up", hjust = hjust_red_end())

ggplot2::ggplot(
  glycan,
  ggplot2::aes(x = .data$x, y = .data$y, structure = .data$structure)
) +
  geom_glycan(orient = "left", vjust = vjust_red_end())

Print glycan cartoon

Description

Print glycan cartoon

Usage

## S3 method for class 'glydraw_cartoon'
print(x, ..., newpage = is.null(vp), vp = NULL)

Arguments

Value

The original glycan cartoon, invisibly.

Save fixed-size glycan cartoon image to local device.

Description

This function saves the glycan cartoon to a file, with a suitable size.

Usage

save_cartoon(cartoon, file, ..., dpi = 300, scale = 1)

Arguments

Value

Path of the saved cartoon file.

Why not width and height?

The familiar ggplot2::ggsave() interface uses width, height, and dpi because ordinary ggplot2 plots are drawn into a user-chosen device size. glydraw cartoons are different: the natural width and height are calculated from the glycan structure so residues, linkages, labels, and borders stay comparable across different glycans. If users supplied arbitrary width and height, glydraw would either distort that structure-derived layout or need to guess how to reconcile one requested size with the other.

dpi is also not the right control here because changing it alters how point- and inch-based ggplot2 elements are rasterized relative to the fixed cartoon canvas. glydraw therefore keeps an internal fixed design scale and uses scale as a single multiplier for the final pixel dimensions. This preserves the cartoon's aspect ratio and relative appearance while still allowing larger or smaller output files.

Examples

cartoon <- draw_cartoon("Gal(b1-3)GalNAc(a1-")
save_cartoon(cartoon, tempfile(fileext = ".png"))

Use glycan cartoons as axis labels

Description

scale_x_glycan() and scale_y_glycan() are discrete position scales that replace text tick labels with compact glycan cartoons. Mapped discrete values and values returned by the scale's labels argument may be glycan structure strings supported by glyparse::auto_parse() or glyrepr::glycan_structure() vectors. X-axis cartoons are vertical and bottom-aligned by default, while y-axis cartoons are horizontal and right-aligned by default. The cartoon orientation and alignment adapt to the displayed axis, including when the axes are swapped by ggplot2::coord_flip().

Usage

scale_x_glycan(
  name = ggplot2::waiver(),
  ...,
  palette = seq_len,
  expand = ggplot2::waiver(),
  position = "bottom",
  sec.axis = ggplot2::waiver(),
  continuous.limits = NULL,
  size = 0.4,
  angle = 0,
  hjust = hjust_red_end(),
  vjust = 0,
  nudge_x = 0,
  nudge_y = 0,
  show_linkage = TRUE,
  style = style_glydraw(),
  red_end = NULL,
  orient = NULL
)

scale_y_glycan(
  name = ggplot2::waiver(),
  ...,
  palette = seq_len,
  expand = ggplot2::waiver(),
  position = "left",
  sec.axis = ggplot2::waiver(),
  continuous.limits = NULL,
  size = 0.4,
  angle = 0,
  hjust = 1,
  vjust = vjust_red_end(),
  nudge_x = 0,
  nudge_y = 0,
  show_linkage = TRUE,
  style = style_glydraw(),
  red_end = NULL,
  orient = NULL
)

Arguments

Value

A ggplot2 discrete position scale.

Examples

glycans <- data.frame(
  structure = c(
    "Gal(b1-3)GalNAc(a1-",
    "Man(a1-3)[Man(a1-6)]Man(b1-4)GlcNAc(b1-"
  ),
  abundance = c(12, 8)
)

ggplot2::ggplot(glycans, ggplot2::aes(x = structure, y = abundance)) +
  ggplot2::geom_col() +
  scale_x_glycan()

Glycan drawing styles

Description

Style constructors collect the rendering options shared by glydraw's standalone drawings, grobs, ggplot2 layers, guides, and glycan scales. style_glydraw() provides glydraw's default appearance, while the other constructors provide presets matching common glycan-drawing conventions. Supply a returned style with ⁠style =⁠ to reuse its visual specification.

Usage

style_glydraw(
  fuc_orient = "flex",
  red_end = "",
  red_end_length = 0.6,
  red_end_size = 6,
  edge_linewidth = 0.8,
  node_linewidth = 0.8,
  node_size = 1,
  font_family = "",
  colors = glydraw_colors()
)

style_glygen(
  fuc_orient = "flex",
  red_end = "~",
  red_end_length = 1,
  red_end_size = 6,
  edge_linewidth = 0.8,
  node_linewidth = 0.8,
  node_size = 1,
  font_family = "arial",
  colors = glydraw_colors()
)

style_snfg(
  fuc_orient = "up",
  red_end = "",
  red_end_length = 1,
  red_end_size = 6,
  edge_linewidth = 1.5,
  node_linewidth = 0.8,
  node_size = 1.15,
  font_family = "arial",
  colors = glydraw_colors()
)

style_glycoworkbench(
  fuc_orient = "flex",
  red_end = "~",
  red_end_length = 1,
  red_end_size = 6,
  edge_linewidth = 0.8,
  node_linewidth = 0.8,
  node_size = 1,
  font_family = "arial",
  colors = c(glyWhite = "#FFFFFF", glyBlue = "#0000F0", glyGreen = "#5AC54B", glyYellow =
    "#FFFF54", glyOrange = "#F7EAD7", glyPink = "#FFFFFF", glyPurple = "#B726C1",
    glyLightBlue = "#EDFEFF", glyBrown = "#8F663B", glyRed = "#E53222")
)

Arguments

Value

A glydraw_style object.

Functions

• style_glydraw(): Use glydraw's default style.

• style_glygen(): Use a GlyGen-style preset.

• style_snfg(): Use a Symbol Nomenclature for Glycans preset.

• style_glycoworkbench(): Use a GlycoWorkbench-style preset.

Examples

serif_style <- style_glydraw(font_family = "serif")
draw_cartoon("Gal(b1-3)GalNAc(a1-", style = serif_style)

draw_cartoon("Gal(b1-3)GalNAc(a1-", style = style_glygen())
draw_cartoon("Gal(b1-3)GalNAc(a1-", style = style_snfg())
draw_cartoon("Gal(b1-3)GalNAc(a1-", style = style_glycoworkbench())