Metadata-Version: 2.5
Name: glyco-gwstoolkit
Version: 0.1.0
Summary: Enumerate glycan tree isomers, fragment via GlycanBuilder2, generate MSP spectral libraries with SNFG visualization
Project-URL: Homepage, https://github.com/sosyphe/glyco-gwstoolkit
Project-URL: Repository, https://github.com/sosyphe/glyco-gwstoolkit
Project-URL: Issues, https://github.com/sosyphe/glyco-gwstoolkit/issues
Author-email: Yee <76564061+sosyphe@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bioinformatics,glycan,glycomics,mass-spectrometry,msp,snfg
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1
Requires-Dist: networkx>=3.0
Requires-Dist: pillow>=10.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# glyco-gwstoolkit

![Python](https://img.shields.io/badge/python-≥3.10-blue)
[![PyPI Version](https://img.shields.io/pypi/v/glyco-gwstoolkit)](https://pypi.org/project/glyco-gwstoolkit)
[![PyPI Downloads](https://static.pepy.tech/badge/glyco-gwstoolkit)](https://pepy.tech/project/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 ![GlycanBuilder2](https://github.com/glycoinfo/GlycanBuilder2) — 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

```bash
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:

```bash
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.

| Example | Meaning |
|---------|---------|
| `Glc:3,Gal:6` | 3 glucose + 6 galactose |
| `Man:3,GlcNAc:4,Fuc:2` | N-glycan core composition |
| `Gal:2,NeuAc:2` | Sialylated galactose |

### Options

**Ion modes and adducts:**

| Mode | Adducts | Precursor Types |
|------|---------|----------------|
| Positive (`pos`) | H, Na, K | [M+H]⁺, [M+Na]⁺, [M+K]⁺ |
| Negative (`neg`) | H only | [M-H]⁻ |

```bash
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

```mermaid
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"]
```

<p align="center"><img src="https://raw.githubusercontent.com/sosyphe/glyco-gwstoolkit/main/docs/images/snfg-example.png" alt="SNFG Example" width="400"></p>

### Run steps individually

```bash
# 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:

| Composition | Residues | Structures | Enum | Fragment |
|-------------|----------|-----------|------|----------|
| `Glc:2,Gal:3` | 5 | 63 | <0.01s | ~2s |
| `Glc:3,Gal:3` | 6 | 268 | 0.02s | ~6s |
| `Glc:3,Gal:6` | 9 | 14,684 | 1.4s | ~31min |
| `Man:5,GlcNAc:4,Fuc:1` | 10 | 464,364 | 63s | ~5h |

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](LICENSE)
