Getting Started with gglycan
Author: Guangchuang Yu School of Basic Medical Sciences, Southern Medical University

`gglycan` is designed to visualize glycan structures using the `ggplot2` grammar of graphics. It builds upon `ggtangle` for network layout and `ggstar` for standard SNFG (Symbol Nomenclature for Glycans) symbols.

While `gglycan` provides a convenient `geom_glycan()` wrapper, its true power lies in the ability to deconstruct the plot into individual layers (`geom_edge`, `geom_star`, etc.), allowing for complete customization.

## Basic Usage

First, let’s look at the standard usage.

    library(ggplot2)
    library(gglycan)
    library(ggtangle)

    ggtangle v0.1.0.001 Learn more at https://yulab-smu.top/

    library(ggstar)
    library(ggrepel)

    # A complex N-glycan string
    s <- "Neu5Ac(a2-3)Gal(b1-4)GlcNAc(b1-2)Man(a1-3)[Neu5Ac(a2-3)Gal(b1-4)GlcNAc(b1-2)Man(a1-6)]Man(b1-4)GlcNAc(b1-4)GlcNAc"

The `gglycan()` function initializes the plot, parsing the IUPAC string into a graph structure and calculating the layout. `geom_glycan()` adds all the standard SNFG elements (edges, labels, and symbols).

    gglycan(s) +
      geom_glycan()

## Deconstructing Layers

`geom_glycan()` is essentially a wrapper that adds the following layers:

1. `geom_edge()`: The connecting lines.
2. `geom_edge_text()`: The linkage information (e.g., α1 − 3).
3. `geom_star()`: The SNFG monosaccharide symbols.
4. `scale_fill_manual()` & `scale_starshape_manual()`: The SNFG color and shape mappings.

You can compose these layers manually to have full control over the aesthetics.

### 1. The Base Plot

`gglycan(s)` returns a `ggplot` object with the data and layout. Note that without layers, it’s empty.

    p <- gglycan(s)
    # p + geom_blank() # Empty canvas

### 2. Customizing Edges

Let’s say we want dashed blue lines for edges instead of the standard solid black.

    p + geom_edge(color = "steelblue", linetype = "dashed", linewidth = 0.8)

### 3. Customizing Edge Labels

We can adjust the color, size, and position of the linkage labels.

    p +
      geom_edge(color = "grey80") +
      geom_edge_text(aes(label = label), color = "darkred", size = 3, vjust = -0.2)

### 4. Customizing Nodes (SNFG Symbols)

The nodes are drawn using `geom_star()` from the `ggstar` package. The plot data comes with `snfg_starshape` and `snfg_fill` columns pre-calculated.

We need to use `I()` (identity) to use these values directly, or set up manual scales.

    p +
      geom_edge(color = "grey80") +
      geom_star(aes(x = x, y = y, starshape = I(snfg_starshape), fill = I(snfg_fill)), size = 5)

### 5. Adding Text Labels

If you want to show the text names of the monosaccharides (e.g., “Neu5Ac”), you can add a `geom_text` or `geom_text_repel` layer.

    p +
      geom_edge(color = "grey80") +
      geom_star(aes(x = x, y = y, starshape = I(snfg_starshape), fill = I(snfg_fill)), size = 4) +
      geom_text_repel(aes(label = label), size = 2.5, box.padding = 0.3)

## Putting It All Together: A Highly Customized Plot

Here is an example combining all these techniques. We will: * Use a “right” growth direction. * Use thick, light-grey edges. * Color linkage labels in blue. * Add node labels. * Customize the theme.

    gglycan(s, direction = "right", length = 1.5) +
      # Custom Edges
      geom_edge(color = "grey70", linewidth = 1) +

      # Custom Linkage Labels
      geom_edge_text(aes(label = label), color = "steelblue", size = 3.5, fontface = "bold") +

      # Standard SNFG Nodes
      geom_star(aes(x = x, y = y, starshape = I(snfg_starshape), fill = I(snfg_fill)), size = 5) +

      # Node Text Labels
      geom_text_repel(aes(label = label), size = 3, color = "black", bg.color = "white", bg.r = 0.15) +

      # Theme
      theme_void() +
      ggtitle("Customized Glycan Plot")

## Motif Highlighting

`gglycan` also supports motif highlighting. This functionality modifies the `alpha` attribute of the graph data.

    motif <- "Neu5Ac(a2-3)Gal(b1-4)GlcNAc"

    # By default, gglycan() handles the alpha mapping if you use geom_glycan()
    # But manually, we map alpha:
    gglycan(s, motif = motif) +
      geom_edge(aes(alpha = I(alpha)), linewidth = 1) +
      geom_edge_text(aes(label = label, alpha = I(alpha))) +
      geom_star(aes(x = x, y = y, starshape = I(snfg_starshape), fill = I(snfg_fill), alpha = I(alpha)), size = 5)