glyco-gwstoolkit

A Python toolkit for enumerating glycan tree topologies from sugar compositions and generating GWS/MSP libraries with SNFG visualization.

Features

• Combinatorial enumeration of all unique glycan tree topologies for arbitrary sugar compositions
• GlycoWorkbench-exact fragmentation via embedded — multi-charge, multi-adduct, pos/neg modes
• SNFG rendering + interactive HTML reports with Plotly charts and sortable tables
• One-command pipeline with checkpointing, resume, and multi-worker parallelism

Installation

Prerequisites: Python ≥ 3.10, Java JDK ≥ 11

git clone https://github.com/sosyphe/glyco-gwstoolkit.git
cd glyco-gwstoolkit
uv sync
gwstoolkit check    # verify Python + Java dependencies

Quick Start

One command — enumerate, fragment, render, and report:

gwstoolkit pipeline \
    --composition "Glc:2,Gal:2" \
    --output-dir output/ \
    --workers 4

Output:

• data/structures.json — 18 unique glycan tree isomers
• library.msp — theoretical fragmentation spectra (MSP format)
• images/ — SNFG diagrams for each unique topology
• report.html — interactive report with Plotly charts

Input: Sugar Composition

Composition is specified as Sugar:Count pairs, comma-separated.

Options

Ion modes and adducts:

gwstoolkit pipeline -c "Glc:2,Gal:2" --mode pos,neg --adducts H,Na
# → [M+H]⁺, [M+Na]⁺, [M-H]⁻  (Na auto-skipped in neg mode)

Fragmentation presets: GWB_default · CID_low · CID_high · HCD · BY_only

Pipeline

flowchart LR
    A["Glc:2,Gal:2"] --> B["① Enumerate"]
    B --> C["② Fragment"]
    C --> D["③ Render"]
    D --> E["④ Report"]

    B -.-> F["structures.json"]
    C -.-> G["library.msp"]
    D -.-> H["images/*.png"]
    E -.-> I["report.html"]

Run steps individually

# 1. Enumerate all unique structures
gwstoolkit enumerate -c "Glc:3,Gal:6" -o structures.json

# 2. Fragment → MSP library
gwstoolkit fragment -i structures.json -o library.msp \
    --preset GWB_default --charges 1,2,3,4 --adducts H,Na,K

# 3. Render SNFG diagrams
gwstoolkit render -i structures.json --output-dir images/

# 4. Generate HTML report
gwstoolkit report -i output/ -o report.html

Tip: fragment and render also accept GWS strings directly — use --gws "..." for a single structure or --gws-file gws_list.txt for batch input (one GWS per line).

Performance

Structure counts grow exponentially with residue count — plan compositions carefully:

Use --workers N for parallel acceleration.

Limitations

Current enumeration is purely combinatorial — no biochemical constraints:

• No anomeric configuration (α/β) — tree connectivity only, no stereochemistry
• No linkage position (1→3, 1→4, 1→6) — branching structure only
• No ring form (pyranose/furanose) distinction
• No biochemical rule filtering — biologically unlikely structures are included

Output is a superset of biologically plausible structures. Filter based on domain knowledge.

License

MIT