glyco-gwstoolkit 0.1.0__tar.gz

glyco_gwstoolkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test (full suite, including Java slow tests)
+        run: uv run pytest

glyco_gwstoolkit-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,75 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test (full suite, including Java slow tests)
+        run: uv run pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Verify tag matches package version
+        run: |
+          pyproject_version=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          init_version=$(grep -m1 '__version__' src/glyco_gwstoolkit/__init__.py | cut -d'"' -f2)
+          if [ "v${pyproject_version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match pyproject.toml version v${pyproject_version}"
+            exit 1
+          fi
+          if [ "${pyproject_version}" != "${init_version}" ]; then
+            echo "::error::pyproject.toml version ${pyproject_version} != __init__.py __version__ ${init_version}"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

glyco_gwstoolkit-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Docs build output
+docs/_build/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# AI
+.claude
+CLAUDE.md
+
+# NOTE: vendored Java artifacts (src/glyco_gwstoolkit/java_bridge/vendor/*.jar,
+# *.class) MUST be committed — do not add ignore rules for them.

glyco_gwstoolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 glyco-gwstoolkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

glyco_gwstoolkit-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+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)

glyco_gwstoolkit-0.1.0/README.md

@@ -0,0 +1,134 @@
+# 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)

glyco_gwstoolkit-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "glyco-gwstoolkit"
+version = "0.1.0"
+description = "Enumerate glycan tree isomers, fragment via GlycanBuilder2, generate MSP spectral libraries with SNFG visualization"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Yee", email = "76564061+sosyphe@users.noreply.github.com" }
+]
+keywords = ["glycan", "mass-spectrometry", "msp", "snfg", "glycomics", "bioinformatics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "typer>=0.9",
+    "rich>=13.0",
+    "networkx>=3.0",
+    "jinja2>=3.1",
+    "pillow>=10.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4",
+    "mypy>=1.8",
+]
+
+[project.scripts]
+gwstoolkit = "glyco_gwstoolkit.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/sosyphe/glyco-gwstoolkit"
+Repository = "https://github.com/sosyphe/glyco-gwstoolkit"
+Issues = "https://github.com/sosyphe/glyco-gwstoolkit/issues"
+
+[tool.hatch.build]
+artifacts = [
+    "**/*.class",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/glyco_gwstoolkit"]
+
+[tool.hatch.build.targets.sdist]
+artifacts = [
+    "**/*.class",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: marks tests that require Java (deselect with -m 'not slow')",
+    "integration: marks integration tests",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[[tool.mypy.overrides]]
+# networkx ships no type information and networkx-stubs is incomplete
+module = "networkx.*"
+ignore_missing_imports = true
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.8",
+]

glyco_gwstoolkit-0.1.0/src/glyco_gwstoolkit/__init__.py

@@ -0,0 +1,20 @@
+"""glyco-gwstoolkit: Enumerate glycan tree isomers, fragment via GlycanBuilder2,
+generate MSP spectral libraries with SNFG visualization."""
+
+__version__ = "0.1.0"
+
+# Public API
+from glyco_gwstoolkit.enumeration import enumerate_structures
+from glyco_gwstoolkit.models.composition import SugarComposition
+from glyco_gwstoolkit.models.structure import GlycanStructure, SugarCounts
+from glyco_gwstoolkit.models.sugar_types import SugarType, SugarTypeRegistry
+
+__all__ = [
+    "GlycanStructure",
+    "SugarComposition",
+    "SugarCounts",
+    "SugarType",
+    "SugarTypeRegistry",
+    "__version__",
+    "enumerate_structures",
+]

glyco_gwstoolkit-0.1.0/src/glyco_gwstoolkit/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m glyco_gwstoolkit`."""
+
+from glyco_gwstoolkit.cli.main import app
+
+app()