new_glycan_structure: Construct a Glycan Structure Vector from Trusted Data

In glyrepr: Representation for Glycan Compositions and Structures

Construct a Glycan Structure Vector from Trusted Data

Description

Assemble a glycan structure vector from IUPAC-condensed values and a graph lookup table without graph validation, canonicalization, IUPAC generation, vector-level compatibility checks, or graph deduplication.

Usage

new_glycan_structure(iupac = character(), graphs = list())

Arguments

iupac	A character vector of canonical IUPAC-condensed strings. Missing values are allowed, and names are preserved exactly.
graphs	A named list of valid, canonical igraph glycan graphs keyed by IUPAC-condensed strings.

Details

graphs must be a named list containing one graph for every distinct, non-missing value in iupac. Additional named graphs are allowed so that vctrs prototypes can retain their graph lookup tables. Graph names must be unique and non-missing. This function checks these inexpensive representation invariants but trusts that each graph matches its key.

Value

A glyrepr_structure vector.

Choosing a construction pipeline

Prefer as_glycan_structure() for ordinary construction from IUPAC strings or graphs. Parsers that already produce residue and edge arrays should use structure_from_arrays() to validate and canonicalize records through the shared compact backend, then build deduplicated graph storage.

For existing graph parsers, canonicalize_glycan_graphs() validates a batch and returns aligned canonical graphs, IUPAC keys, and per-element status. It preserves input names and arbitrary graph, vertex, and edge attributes. Equal structures retain separate graphs until the caller explicitly deduplicates them. This is useful when source attributes differ.

The individual low-level functions remain available when an intermediate graph is needed. validate_glycan_graph() validates one graph; canonicalize_glycan_graph() assumes a valid graph; graph_to_iupac() assumes a valid, canonical graph. validate_glycan_graph_vector() checks the graph-list container, not each graph's semantics. new_glycan_structure() trusts that graphs are valid and canonical and match their keys; it does not validate, canonicalize, or deduplicate them. Incorrect use can create vectors that fail in later operations.

Floating graph schemas

A floating structure is one weakly disconnected graph with exactly one main outward tree and one outward tree per floating part. Its floating_parts graph attribute is a list of entries with integer root, integer nodes, character linkage, and integer parents fields. nodes contains every vertex in that floating component. parents = integer() means all feasible nodes outside that component, including nodes in other floating components. Legacy input graphs may omit nodes; canonical output graphs always contain it. During canonicalization, a part with exactly one effective candidate parent is converted to an ordinary graph edge and its floating metadata is removed. Otherwise, the virtual attachment linkage is not a graph edge. See glycan_structure() for the complete contract.

A graph may also have a floating_substituents attribute. It is a list of entries with character substituent and integer parents fields. An empty parent vector means all feasible residue nodes in the complete structure. A singleton candidate is moved into the selected vertex's sub attribute during canonicalization. All parent indices refer to the complete graph's vertex positions, not positions within a component.

Name-preserving graph construction

Use the batch interface to obtain canonical graphs and keys together, then explicitly deduplicate graph storage when constructing a structure vector:

batch <- canonicalize_glycan_graphs(graphs)
keep <- batch$status == "ok" & !duplicated(batch$iupac)
unique_graphs <- batch$graphs[keep]
names(unique_graphs) <- unname(batch$iupac[keep])

new_glycan_structure(batch$iupac, unique_graphs)

Names and missing positions are preserved; use NULL for missing input graphs. With the default on_failure = "error", an invalid graph raises an error identifying its original position. Set on_failure = "na" to warn and retain successful entries, with invalid positions represented by missing keys and NULL graphs. The same assembly code works in both modes. Deduplication keeps the first graph for each key, including its source attributes. Keep batch$graphs instead when per-input provenance is needed. Use validate = FALSE only when every non-missing graph has already passed validate_glycan_graph().

See Also

Other low-level glycan structure functions: canonicalize_glycan_graph(), graph_to_iupac(), validate_glycan_graph(), validate_glycan_graph_vector()

glyrepr documentation built on Sept. 22, 2026, 5:09 p.m.