Draw glycans at ggplot2 positions — geom

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

mapping: Set of aesthetic mappings created by ggplot2::aes(). The x, y, and structure aesthetics are required.
data: The data to be displayed in this layer. When NULL, the default, the data is inherited from the plot data.
stat: The statistical transformation to use on the data for this layer. Defaults to "identity".
position: A position adjustment to use on the data for this layer. Defaults to "identity".
...: Other arguments passed to ggplot2::layer().
angle: Rotation in degrees. Like ggplot2::geom_text(), this can be supplied as an aesthetic or a fixed layer value. It rotates each completed cartoon around its mapped position independently of orient. Defaults to 0.
show_linkage: Show glycosidic linkage annotations or not. Default is TRUE. Substituent annotations are always shown.
orient: Direction in which the glycan extends from its reducing end: one of "left", "right", "up", or "down". Defaults to "left".
highlight: An integer vector specifying the node indices to highlight. This argument is applicable only when structure is a glyrepr::glycan_structure(). Note that for a glyrepr::glycan_structure(), the node indices correspond exactly to the monosaccharides in its printed IUPAC nomenclature. For example, given glyrepr::as_glycan_structure("Gal(b1-3)[GlcNAc(b1-6)]GalNAc(a1-"), setting highlight = c(1, 3) will highlight the "Gal" and "GalNAc" nodes.
style: A style_glydraw() object that controls the cartoon's visual appearance.
na.rm: If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend: Logical. Should this layer be included in the legends?
inherit.aes: If FALSE, overrides the default aesthetics rather than combining with them.
red_end: Reducing-end annotation. NULL, the default, uses red_end from style. A non-NULL value overrides style$red_end. Ignored when style$red_end_length is 0. To annotate an amino-acid sequence, tag its single glycosite as, for example, "ABC<site>D</site>EFG".

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)