Convert to Glycan Structure Vector — as_glycan

Convert an object to a glycan structure vector.

Usage

as_glycan_structure(
  x,
  on_failure = c("error", "na"),
  progress = FALSE,
  warn = TRUE
)

Arguments

x: An object to convert to a glycan structure vector. Can be an igraph object, a list of igraph objects, a character vector of IUPAC-condensed strings, or an existing glyrepr_structure object.
on_failure: The failure policy for element-local parsing, validation, and canonicalization errors. "error" preserves the default strict behavior. "na" replaces failed elements with NA and emits one warning that reports their positions and failure reasons. Existing missing elements remain missing without a warning. Vector-level incompatibilities still produce an error.
progress: FALSE (default) for silent operation, TRUE for a cli progress bar, or a function with arguments stage, current, and total. A callback owns its display; no cli bar is created. Counts are local to each stage, not an overall percentage. Character parsing counts unique non-missing inputs; graph construction may count deduplicated canonical structures. Updates are throttled, with stage boundaries always reported. Empty or already-converted inputs may report no stages. Callback errors abort the operation, including with on_failure = "na". The cli bar is closed when the call exits, including on errors or interrupts, and follows cli display settings (short or non-interactive calls may show no visible bar).
warn: Whether to warn about recovered failures with on_failure = "na". Validation is always performed.

Value

A glyrepr_structure object.

Details

Character input assumes the natural absolute configuration for unprefixed monosaccharides. Less common configurations use a leading D- or L-, such as D-Fuc, L-Gul, and D-Fucf. Alditols use -ol on the main reducing-end residue, for example Gal(b1-4)GlcNAc-ol(a1-. The reducing-end anomer annotation remains part of the canonical representation.

Character input supports floating-part blocks before the main IUPAC-condensed structure. {Neu5Ac(a2-3)}<main> allows every feasible node outside its own component as a candidate parent, while an explicit |<parents> suffix restricts that domain. Parent indices follow residue order in the complete supplied sequence: residues in floating blocks are counted left to right before the main glycan, and substituent blocks add no indices. A floating part may target another floating component or the main tree, but cannot target itself. Indices are remapped to canonical complete sequence order in the result. The suffix is a glyrepr extension to curly-brace IUPAC notation. A singleton candidate set is accepted as input but fully localizes the attachment, so {Neu5Ac(a2-3)|2}Gal(b1-4)GlcNAc(b1- canonicalizes to the ordinary structure Neu5Ac(a2-3)Gal(b1-4)GlcNAc(b1-.

Floating substituents use the same leading-brace and candidate-parent syntax. For example, {6S}<main> leaves the sulfated residue unrestricted across all residue nodes, {6S|1,2}<main> restricts it to complete-sequence nodes 1 and 2, and {?S}<main> also leaves the carbon position unknown. A singleton candidate is normalized into the selected residue's ordinary sub attribute.

Examples

library(igraph)
#> 
#> Attaching package: ‘igraph’
#> The following objects are masked from ‘package:stats’:
#> 
#>     decompose, spectrum
#> The following object is masked from ‘package:base’:
#> 
#>     union

# Convert a single igraph
graph <- make_graph(~ 1-+2)
V(graph)$mono <- c("GlcNAc", "GlcNAc")
V(graph)$sub <- ""
E(graph)$linkage <- "b1-4"
graph$anomer <- "a1"
as_glycan_structure(graph)
#> <glycan_structure[1]>
#> [1] GlcNAc(b1-4)GlcNAc(a1-
#> # Unique structures: 1

# Convert a list of igraphs
o_glycan_vec <- o_glycan_core_1()
o_glycan_graph <- get_structure_graphs(o_glycan_vec)
as_glycan_structure(list(graph, o_glycan_graph))
#> <glycan_structure[2]>
#> [1] GlcNAc(b1-4)GlcNAc(a1-
#> [2] Gal(b1-3)GalNAc(a1-
#> # Unique structures: 2

# Convert a character vector of IUPAC-condensed strings
as_glycan_structure(c("GlcNAc(b1-4)GlcNAc(b1-", "Man(a1-2)GlcNAc(b1-"))
#> <glycan_structure[2]>
#> [1] GlcNAc(b1-4)GlcNAc(b1-
#> [2] Man(a1-2)GlcNAc(b1-
#> # Unique structures: 2
as_glycan_structure(c("D-Fuc(a1-", "L-Gul(b1-", "D-Fucf(a1-"))
#> <glycan_structure[3]>
#> [1] D-Fuc(a1-
#> [2] L-Gul(b1-
#> [3] D-Fucf(a1-
#> # Unique structures: 3
as_glycan_structure("Gal(b1-4)GlcNAc-ol(a1-")
#> <glycan_structure[1]>
#> [1] Gal(b1-4)GlcNAc-ol(a1-
#> # Unique structures: 1

# Parse a floating residue with two candidate parents
floating_iupac <- paste0(
  "{Neu5Ac(a2-3)|2,5}",
  "Gal(b1-4)GlcNAc(b1-2)Man(a1-3)",
  "[Gal(b1-4)GlcNAc(b1-2)Man(a1-6)]",
  "Man(b1-4)GlcNAc(b1-4)GlcNAc(b1-"
)
as_glycan_structure(floating_iupac)
#> <glycan_structure[1]>
#> [1] {Neu5Ac(a2-3)|2,5}Gal(b1-4)GlcNAc(b1-2)Man(a1-3)[Gal(b1-4)GlcNAc(b1-2)Man(a1-6)]Man(b1-4)GlcNAc(b1-4)GlcNAc(b1-
#> # Unique structures: 1

# Preserve valid elements while replacing an invalid element with NA
as_glycan_structure(
  c(valid = "Glc(?1-", invalid = "not-a-structure"),
  on_failure = "na"
)
#> Warning: 1 structure failed validation and was replaced with `NA`.
#> ✖ Position 2 (`invalid`): Could not parse IUPAC-condensed string:
#>   "not-a-structure" ℹ Invalid characters or format in IUPAC-condensed string
#> <glycan_structure[2]>
#> [1] valid	Glc(?1-
#> [2] invalid	NA
#> # Unique structures: 1