Crate crabwurcs

Expand description

crabWURCS: a pure-Rust toolkit for glycan notation conversion, chemical-structure interop, and SNFG rendering.

This crate is a thin facade — it does no work itself, it just re-exports the workspace’s other crates under one name so a consumer can use crabwurcs::... instead of depending on each sub-crate individually. All real logic lives in:

core — the WURCS grammar and the shared core::ResidueGraph model
iupac — IUPAC condensed/extended notation
mol — MOL/SDF/SMILES chemical structure interop (MolWURCS equivalent)
pdb — glycan extraction from PDB/mmCIF structures
snfg — SNFG SVG rendering (seq2snfg equivalent)

Conversions are computed from the parsed residue graph. The facade also carries a table of the notations of 942 GlycoShape records (938 molecularly specified structures plus four notation-only edge cases); it is consulted only when asked, through convert_with_table, either as a fallback for inputs that cannot be converted or as a check of a computed structure. SMILES is written and read by the pure-Rust molecular backend.

The sections below — generated from the renderer’s own output — document every supported monosaccharide symbol, the SNFG rendering rules, and motif highlighting.

§Supported monosaccharides

crabWURCS renders the complete SNFG 2.0.4 symbol table. Every residue resolves to a shape + colour pair — together they encode the monosaccharide identity following the official Symbol Nomenclature for Glycans (the symbol alone is the label; residue abbreviations are optional).

The 87 entries below are the authoritative list returned by ResidueKind::ALL. Generic classes (marked generic) preserve unspecified stereochemistry: they keep their family colour but draw in white, match any member of their family in motif queries, and cannot be exported to GLYCAM (which would require assigning stereochemistry that is not present).

Each symbol image on this page is generated by render_symbol_svg from the same renderer that draws full glycan figures, so the legend can never drift from the library’s actual output.

§Hexoses — circle

Name	WURCS UniqueRES	Aliases	Generic
`Hex`	`axxxxh-1x_1-5`	Hexose	✓
`Glc`	`a2122h-1x_1-5`	Glucose
`Man`	`a1122h-1x_1-5`	Mannose
`Gal`	`a2112h-1x_1-5`	Galactose
`Gul`	`a2212h-1x_1-5`	Gulose
`Alt`	`a1222h-1x_1-5`	Altrose
`All`	`a1111h-1x_1-5`	Allose
`Tal`	`a1112h-1x_1-5`	Talose
`Ido`	`a2121h-1x_1-5`	Idose

§N-Acetylhexosamines — square

Name	WURCS UniqueRES	Aliases	Generic
`HexNAc`	`axxxxh-1x_1-5_2*NCC/3=O`	N-Acetylhexosamine	✓
`GlcNAc`	`a2122h-1x_1-5_2*NCC/3=O`	N-Acetylglucosamine
`ManNAc`	`a1122h-1x_1-5_2*NCC/3=O`	N-Acetylmannosamine
`GalNAc`	`a2112h-1x_1-5_2*NCC/3=O`	N-Acetylgalactosamine
`GulNAc`	`a2212h-1x_1-5_2*NCC/3=O`	N-Acetylgulosamine
`AltNAc`	`a1222h-1x_1-5_2*NCC/3=O`	N-Acetylaltrosamine
`AllNAc`	`a1111h-1x_1-5_2*NCC/3=O`	N-Acetylallosamine
`TalNAc`	`a1112h-1x_1-5_2*NCC/3=O`	N-Acetyltalosamine
`IdoNAc`	`a2121h-1x_1-5_2*NCC/3=O`	N-Acetylidosamine

§Hexosamines — notched square

A white square with a coloured corner triangle indicates an amino (non-acetylated) sugar.

Name	WURCS UniqueRES	Aliases	Generic
`HexN`	`axxxxh-1x_1-5_2*N`	Hexosamine	✓
`GlcN`	`a2122h-1x_1-5_2*N`	Glucosamine
`ManN`	`a1122h-1x_1-5_2*N`	Mannosamine
`GalN`	`a2112h-1x_1-5_2*N`	Galactosamine
`GulN`	`a2212h-1x_1-5_2*N`	Gulosamine
`AltN`	`a1222h-1x_1-5_2*N`	Altrosamine
`AllN`	`a1111h-1x_1-5_2*N`	Allosamine
`TalN`	`a1112h-1x_1-5_2*N`	Talosamine
`IdoN`	`a2121h-1x_1-5_2*N`	Idosamine

§Hexuronates — divided diamond

The coloured half of the diamond denotes a uronic acid. Most uronates colour the top half; IdoA is drawn with the bottom half coloured (brown), matching the official table.

Name	WURCS UniqueRES	Aliases	Generic
`HexA`	`axxxxA-1x_1-5`	Hexuronate, HexuronicAcid	✓
`GlcA`	`a2122A-1x_1-5`	GlucuronicAcid
`ManA`	`a1122A-1x_1-5`	MannuronicAcid
`GalA`	`a2112A-1x_1-5`	GalacturonicAcid
`GulA`	`a2212A-1x_1-5`	GuluronicAcid
`AltA`	`a1222A-1x_1-5`	AltruronicAcid
`AllA`	`a1111A-1x_1-5`	AlluronicAcid
`TalA`	`a1112A-1x_1-5`	TaluronicAcid
`IdoA`	`a2121A-1x_1-5`	IduronicAcid

§6-Deoxyhexoses — triangle

Name	WURCS UniqueRES	Aliases	Generic
`dHex`	`axxxxm-1x_1-5`	Deoxyhexose	✓
`Qui`	`a2122m-1x_1-5`	Quinovose
`Rha`	`a2211m-1x_1-5`	Rhamnose
`6dGul`	`a2212m-1x_1-5`	6-DeoxyGulose
`6dAlt`	`a2111m-1x_1-5`	6-DeoxyAltrose
`6dTal`	`a1112m-1x_1-5`	6-DeoxyTalose
`Fuc`	`a1221m-1x_1-5`	Fucose

§6-Deoxyhexosamines — divided triangle

Name	WURCS UniqueRES	Aliases	Generic
`dHexNAc`	`axxxxm-1x_1-5_2*NCC/3=O`	DeoxyhexNAc	✓
`QuiNAc`	`a2122m-1x_1-5_2*NCC/3=O`	N-Acetylquinovosamine
`RhaNAc`	`a2211m-1x_1-5_2*NCC/3=O`	N-Acetylrhamnosamine
`6dAltNAc`	`a2111m-1x_1-5_2*NCC/3=O`	N-Acetyl6-DeoxyAltrosamine
`6dTalNAc`	`a1112m-1x_1-5_2*NCC/3=O`	N-Acetyl6-DeoxyTalosamine
`FucNAc`	`a1221m-1x_1-5_2*NCC/3=O`	N-Acetylfucosamine

§2,6-Dideoxyhexoses — flat rectangle

Name	WURCS UniqueRES	Aliases	Generic
`ddHex`	`adxxxm-1x_1-5`	Di-deoxyhexose, Dideoxyhexose	✓
`Oli`	`ad122m-1x_1-5`	Olivose
`Tyv`	`a1d22m-1x_1-5`	Tyvelose
`Abe`	`a2d12m-1x_1-5`	Abequose
`Par`	`a2d22m-1x_1-5`	Paratose
`Dig`	`ad222m-1x_1-5`	Digitoxose
`Col`	`a1d21m-1x_1-5`	Colitose

§Pentoses — star

Name	WURCS UniqueRES	Aliases	Generic
`Pen`	`axxxh-1x_1-5`	Pentose	✓
`Ara`	`a211h-1x_1-5`	Arabinose
`Lyx`	`a112h-1x_1-5`	Lyxose
`Xyl`	`a212h-1x_1-5`	Xylose
`Rib`	`a222h-1x_1-5`	Ribose

§Nonulosonic acids (sialic acids) — diamond

Name	WURCS UniqueRES	Aliases	Generic
`NulO`	`Aadxxxxxh-2x_2-6`	3-deoxy-nonulosonicAcid, Nonulosonate	✓
`Kdn`	`Aad21122h-2x_2-6`	KDN
`Neu5Ac`	`Aad21122h-2x_2-6_5*NCC/3=O`	NeuAc, Neup5Ac
`Neu5Gc`	`Aad21122h-2x_2-6_5*NCCO/3=O`	NeuGc, Neup5Gc
`Neu`	`Aad21122h-2x_2-6_5*N`	NeuraminicAcid
`Sia`	(no UniqueRES — display class only)	SialicAcid	✓

§3,9-Dideoxy-nonulosonic acids — flat diamond

Name	WURCS UniqueRES	Aliases	Generic
`ddNulO`	`Aadxxxxxm-2x_2-6_5N_7N`	3,9-dideoxy-nonulosonicAcid	✓
`Pse`	`Aad22111m-2x_2-6_5N_7N`	PseudaminicAcid
`Leg`	`Aad21122m-2x_2-6_5N_7N`	LegionaminicAcid
`Aci`	`Aad21111m-2x_2-6_5N_7N`	AcinetaminicAcid
`4eLeg`	`Aad11122m-2x_2-6_5N_7N`	4-epi-Leg

§Unknown & bacterial — flat hexagon

Name	WURCS UniqueRES	Aliases	Generic
`Unknown`	(no UniqueRES — display class only)	UnknownSaccharide	✓
`Bac`	`a2122m-1x_1-5_2N_4N`	Bacillosamine
`LDmanHep`	`a11221h-1x_1-5`	L-glycero-D-manno-Heptose
`Kdo`	`Aad1122h-2x_2-6`	KDO
`Dha`	`Aad112A-2x_2-6`
`DDmanHep`	`a11222h-1x_1-5`	D-glycero-D-manno-Heptose
`MurNAc`	`a2122h-1x_1-5_2NCC/3=O_3OC^RCO/4=O/3C`
`MurNGc`	`a2122h-1x_1-5_2NCCO/3=O_3OC^RCO/4=O/3C`
`Mur`	`a2122h-1x_1-5_2N_3OC^RCO/4=O/3C`	MuramicAcid

§Assigned & ketoses — pentagon

The white Assigned pentagon stands in for any user-named residue whose chemistry is not in the registry; its in-shape label is the uppercased first letter of the assigned name. The remaining pentagons are ketoses.

Name	WURCS UniqueRES	Aliases	Generic
`Assigned`	(no UniqueRES — display class only)		✓
`Api`	`a15h-1x_1-4_3*CO`	Apiose
`Fru`	`ha122h-2x_2-6`	Fructose
`Tag`	`ha112h-2x_2-6`	Tagatose
`Sor`	`ha121h-2x_2-6`	Sorbose
`Psi`	`ha222h-2x_2-6`	Psicose

§Programmatic access

Resolve a residue’s symbol at runtime with classify_residue and render_symbol_svg:

use crabwurcs::{RenderOptions, render_symbol_svg, residue_from_kind, ResidueKind};

let residue = residue_from_kind(ResidueKind::Glc).unwrap();
let svg = render_symbol_svg(&residue, &RenderOptions::default()).unwrap();
assert!(svg.contains("fill=\"#0072BC\"")); // official SNFG blue

Residues that arrive from a parsed notation (not the registry) are classified automatically — render_svg calls the same classifier, so any WURCS or IUPAC input resolves to the correct symbol without an explicit ResidueKind.

§SNFG rendering

render_svg and friends turn a ResidueGraph into an SNFG (Symbol Nomenclature for Glycans) figure. The output follows SNFG 2.0.4: shape encodes the chemical class, colour encodes the stereochemical family, and the layout places the reducing end on the right with children extending to the left.

§Shapes

Each monosaccharide family maps to a distinct geometric primitive. The gallery below shows one representative per shape; see Supported monosaccharides for the full table.

Shape	Family	Example
Circle	Hexoses
Square	N-Acetylhexosamines
Notched square	Hexosamines (amino, non-acetylated)
Divided diamond (top)	Hexuronates
Divided diamond (bottom)	Iduronic acid
Triangle	6-Deoxyhexoses
Divided triangle	6-Deoxyhexosamines
Flat rectangle	2,6-Dideoxyhexoses
Star	Pentoses
Diamond	Nonulosonic acids (sialic acids)
Flat diamond	3,9-Dideoxy-nonulosonic acids
Flat hexagon	Unknown / bacterial / muramic acid family
Pentagon	Assigned & ketoses

§Colour palette

The official SNFG RGB palette. Generic classes (unspecified stereochemistry) draw in white while keeping their family shape.

Name	Hex	Swatch
White	`#FFFFFF`
Blue	`#0072BC`
Green	`#00A651`
Yellow	`#FFD400`
Orange	`#F47920`
Pink	`#F69EA1`
Purple	`#A54399`
Light blue	`#8FCCE9`
Brown	`#A17A4D`
Red	`#ED1C24`

Family → colour assignment follows the standard mapping: Glc blue, Gal yellow, Man green, Fuc red, sialic acids purple/light-blue, iduronic brown, and so on. Generic classes (e.g. Hex, HexNAc) keep the family shape but fill white.

§Layout

The renderer lays the glycan out as a rooted tree:

Root on the right. The reducing-end residue sits at the right edge of the canvas; every child extends one step (100 px) to the left.
Post-order vertical packing. A parent is centred vertically between its children; leaf residues are stacked at 100 px vertical spacing.
Branch order follows the acceptor position. Higher acceptor positions sit above lower ones — for example the N-glycan α1-6 arm is drawn above α1-3, and β1-4 above β1-2.
Terminal deoxy-sugar lanes. Terminal fucose and rhamnose residues are drawn vertically aligned with their parent. When a parent carries both a α1-3 and α1-6 fucose (or α1-2 and α1-4 rhamnose), they are split above and below the parent instead of overlapping; a single such branch and the core α6-fucose default to one side so no residue is overprinted.
Disconnected components (compositions, undefined antennae) are all laid out rather than silently dropped.

Linkage labels (α3, β4, etc.) are placed beside each bond, rotated to the bond angle. Repeat/cyclic and undefined bonds draw as dashed grey lines; an unknown position renders as ?.

§Composition layout

WURCS compositions (a multiset of residues with no linkage information) render as a single row of grouped symbols, each with a ×N count.

composition

§Render options

RenderOptions controls the figure:

Field	Default	Effect
`colour`	`true`	Fill shapes with the SNFG palette; `false` draws outlines only.
`show_labels`	`false`	Draw residue abbreviations inside shapes. Off by default — SNFG convention is that shape + colour is the label.
`show_linkages`	`true`	Draw anomeric and position labels on each bond.
`font_family`	`Arial, Helvetica, sans-serif`	Font stack for all text.
`scale`	`1.0`	Uniform scale of the whole figure.
`source_notation`	`None`	Records the exact input notation in the SVG metadata.

Assigned pentagons always show their first-letter label regardless of show_labels, because their identity is not recoverable from shape or colour.

§Output formats

SVG — render_svg / render_svg_with_options. Vector output, transparent background, embeds accessible <title>/<desc> and a <metadata> block carrying the canonical IUPAC condensed and WURCS notation.
PNG — render_png / render_png_with_options. Transparent RGBA raster at twice the SVG dimensions.

use crabwurcs::{render_svg_with_options, render_png, RenderOptions};

let graph = crabwurcs::iupac::parse_iupac_condensed("Gal(b1-4)GlcNAc").unwrap();

let svg = render_svg_with_options(&graph, &RenderOptions::default()).unwrap();
let png = render_png(&graph).unwrap(); // transparent 2× RGBA

§Embedded metadata

Every SVG carries an invisible <metadata> block (crabwurcs:notations) with:

the canonical IUPAC condensed form,
the canonical WURCS form, and
the original source notation and detected format (when available).

Each field is marked available="true|false" so a downstream tool knows when a canonical form could not be produced (for example an Assigned residue that cannot be represented in WURCS) without failing the render.

§Motif highlighting

render_svg_with_motifs de-emphasises every residue outside a motif of interest, so a specific substructure stands out against the rest of the glycan. This is the same GlycoDraw-compatible look used by the crabwurcs render --highlight-motif CLI flag.

§At a glance

Target: Neu5Ac(a2-3)Gal(b1-4)[Fuc(a1-3)]GlcNAc. Highlighted motif: Gal(b1-4)[Fuc(a1-3)]GlcNAc.

Without highlight	With motif highlighted

Matched residues and the motif-internal bonds keep their full SNFG colour; the non-matching Neu5Ac branch and its bond drop to the muted palette below.

§How matching works

Matching is structural and wildcard-aware, implemented by find_motif_matches. The motif is an ordinary ResidueGraph parsed from WURCS, IUPAC (condensed or extended), or GLYCAM.

Injective, directed, non-induced. Each motif node maps to one target node; extra branches and extra residue modifications on the target are allowed and do not block a match.
Unknown anomers and positions are wildcards. Fuc(a1-?)GlcNAc matches Fuc(a1-3)GlcNAc, Fuc(a1-4)GlcNAc, etc.
Generic classes match their whole family. A motif residue Hex matches Glc, Man, Gal, and every other hexose; HexNAc matches every N-acetylhexosamine; Sia matches Neu5Ac, Neu5Gc, Kdn, Neu. This follows ResidueKind::matches_family, so a single generic motif captures every stereochemical variant in its row of the SNFG table.
Union over motifs and occurrences. Every occurrence of every supplied motif is highlighted; passing several motifs builds up the union of their matches. An empty motif list is identical to a plain render.

Boundary edges — the bonds between a matched region and the rest of the target — are treated as outside the motif and dimmed with their target-side residue.

§The muted palette

Dimmed residues stay fully opaque (they must occlude the bonds drawn behind them) but drop to desaturated versions of the SNFG colours:

SNFG colour	Muted
Blue `#0072BC`	`#CDE7EF`
Green `#00A651`	`#CDE9DF`
Yellow `#FFD400`	`#FFF6DE`
Orange `#F47920`	`#FDE7E0`
Pink `#F69EA1`	`#FDF0F1`
Purple `#A54399`	`#F1E6ED`
Light blue `#8FCCE9`	`#EEF8FB`
Brown `#A17A4D`	`#F1E9E5`
Red `#ED1C24`	`#F7E0E0`

Bonds and text outside a match draw in light grey #D9D9D9.

§Usage

use crabwurcs::{render_svg_with_motifs, RenderOptions};

let target = crabwurcs::iupac::parse_iupac_condensed(
    "Neu5Ac(a2-3)Gal(b1-4)[Fuc(a1-3)]GlcNAc",
).unwrap();

// Wildcard linkage position — matches α3 or α4 fucose.
let motif = crabwurcs::iupac::parse_iupac_condensed("Gal(b1-4)[Fuc(a1-?)]GlcNAc").unwrap();

let svg = render_svg_with_motifs(&target, &[motif], &RenderOptions::default()).unwrap();

Repeat the call with several motifs to highlight a union of substructures. PNG output is available through render_png_with_motifs.

§Motif constraints

A motif must describe a connected, directed tree of known residues. The matcher returns MotifError otherwise:

Variant	Meaning
`Empty`	The motif graph has no residues.
`Composition`	Compositions cannot be used as motifs.
`Disconnected`	The motif is not a single connected graph.
`NotTree`	The motif is not a directed tree rooted at its reducing end.
`CycleOrRepeat`	The motif contains a cycle or a repeat-closing edge.
`UndefinedLinkage`	The motif contains an undefined (candidate-parent) linkage.
`UndefinedModification`	The motif contains an undefined (candidate-parent) modification.

Re-exports§

pub use crabwurcs_core as core;
pub use crabwurcs_iupac as iupac;
pub use crabwurcs_mol as mol;
pub use crabwurcs_pdb as pdb;
pub use crabwurcs_snfg as snfg;

Structs§

ExtractedGlycan
ExtractedGlycanWithProvenance: An extracted glycan together with the source residue identity for every graph node. The legacy ExtractedGlycan API remains available for callers that only need the graph.
HighlightSelection: Exact graph elements to keep vivid in a highlighted SNFG rendering. Indices are the stable petgraph node/edge indices exposed by the source ResidueGraph; elements not listed here are rendered with the muted SNFG palette.
MotifMatch
PdbReadOptions: Options for read_glycans_from_file and read_glycans_from_str.
PdbReading: The result of read_glycans_from_file / read_glycans_from_str.
PdbResidueReference: A graph-node provenance record retained from the source PDB/mmCIF file.
PdbWarning: Something about one residue that its name and its coordinates do not agree on, or that the coordinates cannot decide.
RenderOptions
ResidueGraph
ResidueReading: What the coordinates and the name say about one glycan residue.
SourceNotation
StereoCentre: One configuration read from a signed volume.

Enums§

ConversionError
CoreError
Format
MotifError
NamePolicy: What decides when a residue name and the coordinates disagree.
PdbWarningKind: The kind of a PdbWarning.
ResidueKind
SnfgError
TableConversionError
TableMode: How convert_with_table uses the bundled table of GlycoShape notations.

Functions§

classify_residue: Classify a WURCS residue as an official SNFG 2.0.4 residue.
convert: Convert input from one notation to another by parsing it into the residue graph and writing that graph. The bundled GlycoShape table is not consulted; see convert_with_table.
convert_with_table: convert, with the bundled GlycoShape table used as mode says.
detect_format: Guess the notation of input from its syntax.
extract_glycans_from_file: Extract glycans (coordinates decide; warnings are dropped). See read_glycans_from_file for the warnings and the policy.
extract_glycans_from_str: Extract glycans (coordinates decide; warnings are dropped). See read_glycans_from_str for the warnings and the policy.
extract_glycans_with_provenance_from_file: Extract glycans from a PDB/mmCIF file while retaining source residue identities for every graph node (coordinates decide; warnings are dropped). PDB files are read through pdb_records_used.
extract_glycans_with_provenance_from_str: Extract glycans from a PDB or mmCIF string while retaining source residue identities for every graph node (coordinates decide; warnings are dropped). PDB text is read through pdb_records_used.
find_motif_matches: Find every injective, directed, non-induced occurrence of motif in target.
normalize_wurcs
parse_notation
read_glycans_from_file: Read the glycans of a PDB/mmCIF file with their warnings and per-residue readings. Only the first model is read.
read_glycans_from_str: Read the glycans of PDB or mmCIF text with their warnings and per-residue readings. PDB text is read through pdb_records_used; of mmCIF, the first model is read.
render_png: Render an SNFG diagram as a transparent PNG at twice the SVG dimensions.
render_png_with_motifs: Render a motif-highlighted SNFG diagram as a transparent PNG at twice the SVG dimensions.
render_png_with_options: Render an SNFG diagram as a transparent PNG using the supplied SVG rendering options.
render_png_with_selection: Render an exact-selection SNFG diagram as a transparent PNG at twice the SVG dimensions.
render_svg
render_svg_with_motifs: Render an SNFG SVG while highlighting the union of every occurrence of every supplied motif.
render_svg_with_options
render_svg_with_selection: Render an SNFG SVG with exactly the supplied graph nodes and edges highlighted. This is intended for callers that have already resolved a specific occurrence and must not highlight every matching motif.
render_symbol_svg: Render a single SNFG symbol as a tightly-cropped, transparent-background SVG.
residue_from_kind
standardize_wurcs: Backward-compatible name for normalize_wurcs.
table_lookup: The notation in to of the bundled GlycoShape record that holds input in from (Format::Auto: in any column), without converting anything. WURCS answers are normalized.
write_iupac_condensed_canonical: Serialize a graph to canonical IUPAC condensed without reusing a preserved source string from parsing.
write_notation
write_wurcs_canonical: Serialize a graph to canonical WURCS without reusing a preserved source string from parsing.

Type Aliases§

ConversionResult
CoreResult
SnfgResult

Crate crabwurcs

Crate crabwurcs Copy item path

§Supported monosaccharides

§Hexoses — circle

§N-Acetylhexosamines — square

§Hexosamines — notched square

§Hexuronates — divided diamond

§6-Deoxyhexoses — triangle

§6-Deoxyhexosamines — divided triangle

§2,6-Dideoxyhexoses — flat rectangle

§Pentoses — star

§Nonulosonic acids (sialic acids) — diamond

§3,9-Dideoxy-nonulosonic acids — flat diamond

§Unknown & bacterial — flat hexagon

§Assigned & ketoses — pentagon

§Programmatic access

§SNFG rendering

§Shapes

§Colour palette

§Layout

§Composition layout

§Render options

§Output formats

§Embedded metadata

§Motif highlighting

§At a glance

§How matching works

§The muted palette

§Usage

§Motif constraints

Re-exports§

Structs§

Enums§

Functions§

Type Aliases§

Crate crabwurcs