mwang87/massquerylanguage

Purpose and Entry Points

MassQL is a Python reference implementation of a mass-spectrometry query DSL: it parses MassQL statements and evaluates them against MS1/MS2 spectral data. Primary entry points are the Python API, notably massql/msql_engine.py, and the installed massql CLI implemented by massql/msql_cmd.py. Package exposure begins at massql/__init__.py.

Language Definition and Parsing

The language contract is defined by the EBNF grammar in massql/msql.ebnf. massql/msql_parser.py converts query text into an intermediate structured representation; this is the boundary between user-provided DSL syntax and execution logic. Parsed forms are also supported as JSON-oriented output, consistent with the documented parse API.

Query Translation and Execution

massql/msql_engine.py orchestrates query processing: accept query text plus an input filename or supplied MS1/MS2 data frames, parse the query, dispatch filtering, and return result data. massql/msql_translator.py translates parsed query structures into executable query/filter semantics. The central control flow is:

query string → parser → translated/interpreted clauses → engine evaluation → tabular results.

Spectral Data Boundary

massql/msql_fileloading.py is the ingestion boundary for mass-spectrometry files and produces separate MS1 and MS2 data frames. The engine can alternatively receive preloaded frames, separating file-format concerns from query evaluation. Representative fixture formats include tests/test_data/top_down.mgf and tests/test_data/top_down.txt; CLI examples document mzML input.

Filter Evaluation

massql/msql_engine_filters.py contains the domain-specific predicate layer used during evaluation. It applies MassQL constraints over precursor/product masses, neutral loss, tolerance, intensity, retention time, scan metadata, polarity, charge, and mobility. This layer is the key semantic boundary between generic data-frame operations and mass-spectrometry-aware matching.

Extraction and Visualization Outputs

massql/msql_extract.py supports extracting query-relevant spectral information from results/data. massql/msql_visualizer.py produces MS1/MS2 query visualizations, supporting the documented visualization endpoints. These are downstream consumers of parsed queries and loaded/evaluated spectral data rather than primary execution entry points.

Runtime, Packaging, and Integration

The implementation runs on Python (README states Python 3.9 is tested), with dependencies declared in requirements.txt and packaging in setup.py. GitHub Actions publish and validate the package through .github/workflows/publish.yml and test workflows. The README describes Nextflow/ProteoSAFe and hosted web API integration, but the tree contains only Nextflow runtime/cache artifacts under workflow/.nextflow; no workflow source or web-server implementation is present here.