HolobiomicsLab 
cross-view-similarity-scoring
Summary
Apply MultiView Projection (MVP) to compute cross-view similarity scores between a query spectrum and molecular candidate structures, enabling ranking of candidates by aggregated similarity. This skill is essential when you need to match an experimental mass spectrum against a library of putative molecular structures.
When to use
Use this skill when you have an experimental mass spectrum (query) and a set of molecular candidate structures, and you need to rank the candidates by how well their predicted spectral features match the query spectrum. Specifically applicable to MS/MS annotation tasks where spectral feature extraction and multi-view molecular descriptors are available.
When NOT to use
- Input spectra lack preprocessing or feature extraction (e.g., raw, unnormalized m/z–intensity pairs without binning or consensus spectral computation)
- Candidate structures are not available or only partial structural information exists
- Query spectrum is of insufficient quality or too sparse to extract reliable spectral features
Inputs
- Query mass spectrum (TSV or JSON format with m/z and intensity pairs)
- Candidate molecular structures (SMILES strings or molecular identifiers in JSON format)
- Spectral features extracted from query (binned spectra or formula-based subformula labels)
- Molecular descriptors for candidates (fingerprints, graph representations, or consensus spectra)
Outputs
- Ranked candidate list with aggregated cross-view similarity scores
- Structured output file (e.g., JSON or TSV) mapping candidates to scores in descending order
How to apply
Load the query spectrum and candidate molecular structures into memory. Extract or compute spectral features (e.g., binned spectra or formula-based spectral representations) from the query and molecular descriptors (views) from each candidate using preprocessing steps such as subformula assignment (if using formSpec) or binning (if using binnedSpec). Apply the MultiView Projection method to compute pairwise cross-view similarity scores between the query spectrum and each candidate by comparing their feature representations across views. Aggregate the similarity scores for each candidate and rank them in descending order. Export the ranked candidate list with their aggregated similarity scores to a structured output file.
Related tools
- MVP (MultiView Projection) (Core implementation for computing cross-view similarity scores and ranking molecular candidates against query spectra) — https://github.com/HassounLab/MVP
- PyTorch / PyTorch Geometric (Neural network and graph neural network backend for learning multi-view feature representations)
- RDKit (Molecular structure parsing and fingerprint/descriptor computation)
- DGL (Deep Graph Library) (Graph representation and message-passing for molecular candidate encoding)
- MassSpecGym (Source dataset for training and evaluation of ranking models) — https://github.com/pluskal-lab/MassSpecGym
Examples
python test.py --param_pth params_binnedSpec.yaml
Evaluation signals
- Ranked candidate list contains all input candidates with no duplicates and scores in descending order
- Similarity scores fall within the expected range (e.g., [0, 1] or normalized equivalents) for the chosen cross-view similarity metric
- Top-ranked candidate matches the ground-truth annotation (if available) or aligns with manual spectral interpretation
- Ranking is stable across repeated runs with the same inputs
- Output file is valid JSON/TSV with required fields (candidate_id, score, rank) and no missing or malformed entries
Limitations
- MVP requires preprocessed spectral features and molecular descriptors; raw spectra must first undergo binning or subformula assignment
- Performance depends on the quality of candidate structure set; missing or incorrect structures will not rank correctly
- Model trained on MassSpecGym may not generalize well to spectra from different ionization methods or mass analyzers outside the training distribution
- Computational cost scales with the number of candidates; large-scale rankings may require batching or model optimization
Evidence
- [readme] MVP can be used to rank a set of molecular candidates given a spectrum.: "MVP can be used to rank a set of molecular candidates given a spectrum."
- [other] Extract or compute spectral features and molecular descriptors (views) for both query and candidates.: "Extract or compute spectral features and molecular descriptors (views) for both query and candidates."
- [other] Apply MultiView Projection to compute cross-view similarity scores between the query spectrum and each candidate.: "Apply MultiView Projection to compute cross-view similarity scores between the query spectrum and each candidate."
- [readme] If using formSpec, compute subformula labels: "If using formSpec, compute subformula labels"
- [readme] Run our preprocess code to obatain fingerprints and consensus spectra files: "Run our preprocess code to obatain fingerprints and consensus spectra files"
- [other] Rank candidates by their aggregated similarity scores in descending order.: "Rank candidates by their aggregated similarity scores in descending order."