How mobiusklein/glycresoft works
Project Type and Purpose
• GlycReSoft is an open-source, command-line tool for analyzing glycomics and glycoproteomics LC-MS/MS data.
• It is not a web or full-stack app but a monolithic CLI application/library with native (Cython/C) extensions for performance, data-processing pipelines, and reporting modules.
• Key features: building glycan/glycopeptide search spaces, preprocessing MS data, scoring and matching spectra, serializing and exporting results, and generating reports/plots.
File-Structure Analysis
• Top directories:
• src/glycresoft/cli — CLI entrypoints & command dispatch
• src/glycresoft/_c — Cython modules compiled to C for performance (core algorithms: chromatogram, scoring, structure)
• src/glycresoft/database & src/glycresoft/database/builder — Search-space and SQLite/disk-backed DB construction
• src/glycresoft/tandem,-scoring,-structure,-composition_* — Core processing logic: fragmentation modeling, scoring, network modeling
• src/glycresoft/serialize — ORM-style serialization of results to/from DB
• src/glycresoft/output & ‑plotting — Reporting layer: CSV, XML, HTML/templating and plotting utilities
• pyinstaller/ — Packaging scripts to bundle the tool as a standalone executable
• docs/ — Sphinx documentation, custom directives, tutorials, CLI reference
• Configuration/environment: pyproject.toml, setup.py, requirements.txt, external-requirements.txt
• Workflows: GitHub Actions YAML files automate tests, Docker builds, and Python publishing.
Key Components
a. CLI Layer
• glycresoft entrypoint
• Subcommands: analyze, build-hypothesis, mzml preprocess, export, config, tools
b. Core Pipeline Engine
• Task dispatcher (src/glycresoft/task.py)
• Workflow modules: tandem/workflow, scoring pipelines, elution-time grouping
c. Cython Performance Modules
• src/glycresoft/_c/... for computationally intensive routines (graph algorithms, scoring, structure loading)
d. Database Layer
• Builder classes → populate disk-backed/SQLite DB
• Query interfaces to search spaces (glycan, glycopeptide)
e. Serialization & Configuration
• config module reads/writes user settings
• serialize module bridges Python objects ↔ DB records
f. Reporting & Output
• CSV, XML, text exporters
• HTML templating + JS/CSS for interactive glycan/glycopeptide LC-MS reports
• Plotting utilities for charts and diagnostic figures
g. Packaging & Distribution
• PyInstaller hook scripts → standalone executables
• Dockerfile for containerized usage
h. External Inputs and Outputs
• mzML files, FASTA, mzID, JSON indexes → preprocessed data → analysis → result exports
Relationships and Data Flow
• User invokes CLI → CLI parser dispatches to a command module
• Command module invokes the Core Pipeline Engine
• Engine orchestrates:
1. Data ingestion (mzML, FASTA, prebuilt DB files)
2. Search-space building (glycan/glycopeptide DB builder modules)
3. Spectrum matching (tandem & scoring modules leveraging Cython extensions)
4. Elution/time grouping, recalibration
5. Hypothesis generation
6. Serialization of results to DB or in-memory objects
• Reporting layer pulls serialized results → writes CSV/XML/text or renders HTML + JS/CSS
• Plotting layer may be invoked to generate figures
• Config & logging operate throughout
Architectural Patterns & Design Principles
• Modular layering: CLI → Orchestration → Core logic → Data layer → Reporting
• Performance offload: Cython modules for hotspots
• Separation of concerns: Database builder separate from scoring, serialization separate from output
• Extensibility: plugin-style hooks in Cython, Sphinx extensions for docs
• Single executable packaging (PyInstaller) vs. library installation