motif-similarity-ranking-interpretation
Summary
Interpret ranked MassQL-MotifDB similarity scores to assign functional meaning to discovered Mass2Motifs by evaluating match quality, ranking structure, and fragmentation pattern consistency. This skill bridges unsupervised motif discovery with reference-guided annotation by translating raw database hits into actionable substructure assignments.
When to use
After executing MassQL queries against a MotifDB reference database and retrieving ranked motif matches, when you need to determine which database entries represent true structural correspondence versus spurious matches, and to decide whether a motif's top-ranking hit is sufficiently similar to support confident annotation.
When NOT to use
- Input motif set has not yet been queried against MotifDB — apply MassQL query construction first.
- Match scores are unavailable or ranking structure is not preserved in the database output.
- Discovery goal is purely exploratory motif identification without reference-guided validation — skip to direct LDA interpretation.
Inputs
- inferred motifset in JSON format (output from MS2LDA LDA modeling step)
- ranked MotifDB match records per motif (motif ID, name, composition, match score)
- original Mass2Motif fragment and neutral-loss patterns
- spectral dataset metadata (compound identities, occurrence frequencies)
Outputs
- interpreted motif-to-database annotation assignments
- ranked similarity scores with confidence assessments
- per-motif annotation metadata (matched motif ID, name, score, structural rationale)
- annotation report documenting ranking confidence and pattern alignment
How to apply
Load the JSON output containing ranked MotifDB matches per Mass2Motif, sorting by the provided similarity or match score (higher scores indicate greater correspondence). Examine the top-ranked entry's composition and neutral-loss patterns against the original discovered motif's fragment and neutral-loss patterns extracted from the LDA inference step; assess whether the ranked hit's mass composition aligns with the motif's observed fragments and whether neutral-loss patterns co-occur consistently. Use the ranking order as a confidence signal: a match ranked first with substantially higher score than second-ranked alternatives suggests greater specificity. Cross-reference the match against the motif's occurrence frequency across the spectral dataset and the compounds in which it appears; if a high-scoring database hit occurs in structurally diverse compounds, evaluate whether the match represents a general fragmentation pattern or a specific substructure. Document the per-motif ranking structure preserved in the JSON to enable downstream filtering or threshold-based annotation decisions.
Related tools
- MassQL (query engine for constructing and executing database searches using fragment and neutral-loss patterns)
- MotifDB (searchable reference database containing ranked motif entries, composition, and match scores for comparison) — https://zenodo.org/records/15688609
- MS2LDA (generates the inferred motifset and provides LDA-learned Mass2Motif patterns as input to similarity ranking) — https://github.com/vdhooftcompmet/MS2LDA
- Spec2Vec (optionally supports automated annotation guidance (MAG) for motif interpretation)
Evaluation signals
- Top-ranked MotifDB entry's mass composition and neutral-loss patterns show >80% correspondence with the original discovered motif's fragment set.
- Ranking order is monotonic or near-monotonic (scores decrease or plateau from rank 1 to N), indicating valid score ordering without artifacts.
- Per-motif JSON output preserves ranking structure with ≥2 ranked candidates per motif, enabling comparative scoring.
- Annotated motif occurs consistently across a chemically coherent compound subset (e.g., alkaloids, lipids) rather than random scatter, validating structural relevance.
- Match score spread (top score − second-place score) exceeds a domain-specific threshold (e.g., >20% relative difference), suggesting confidence in the top hit.
Limitations
- MotifDB reference database completeness and curation directly affect match quality; sparse or outdated database entries may fail to retrieve true structural assignments.
- Ranking scores depend on MassQL query specificity; overly broad or overly narrow queries may rank spurious or missed matches.
- Neutral-loss patterns alone may not uniquely identify substructures, especially for compounds sharing common fragmentation routes; multi-evidence integration (MS/MS intensity, retention time, spectral context) is often required for high-confidence annotation.
- Top-ranked matches may reflect frequent mass motifs in the reference database rather than structurally unique substructures, potentially biasing annotation toward common fragmentations.
Evidence
- [other] For each motif, construct a MassQL query using its fragment and neutral-loss patterns to search the MotifDB reference database.: "For each motif, construct a MassQL query using its fragment and neutral-loss patterns to search the MotifDB reference database."
- [other] Execute the MassQL search against MotifDB via the MassQL4MotifDB integration module, retrieving ranked matches sorted by similarity or match score.: "Execute the MassQL search against MotifDB via the MassQL4MotifDB integration module, retrieving ranked matches sorted by similarity or match score."
- [other] Serialize query results and MotifDB match records (motif ID, name, composition, score) to a JSON output file preserving the per-motif ranking structure.: "Serialize query results and MotifDB match records (motif ID, name, composition, score) to a JSON output file preserving the per-motif ranking structure."
- [methods] MS2LDA integrates with a MassQL-searchable MotifDB to enable comparison of discovered motifs against known database entries, supporting automated motif annotation and result retrieval.: "MS2LDA integrates with a MassQL-searchable MotifDB to enable comparison of discovered motifs against known database entries, supporting automated motif annotation and result retrieval."
- [readme] identifying recurring substructures (motifs) across spectral datasets without relying on prior compound identification: "identifying recurring substructures (motifs) across spectral datasets without relying on prior compound identification"
1---2name: motif-similarity-ranking-interpretation3description: Use when after executing MassQL queries against a MotifDB reference database and retrieving ranked motif matches, when you need to determine which database entries represent true structural correspondence versus spurious matches, and to decide whether a motif's top-ranking hit is sufficiently.4license: CC-BY-4.05---67# motif-similarity-ranking-interpretation89## Summary1011Interpret ranked MassQL-MotifDB similarity scores to assign functional meaning to discovered Mass2Motifs by evaluating match quality, ranking structure, and fragmentation pattern consistency. This skill bridges unsupervised motif discovery with reference-guided annotation by translating raw database hits into actionable substructure assignments.1213## When to use1415After executing MassQL queries against a MotifDB reference database and retrieving ranked motif matches, when you need to determine which database entries represent true structural correspondence versus spurious matches, and to decide whether a motif's top-ranking hit is sufficiently similar to support confident annotation.1617## When NOT to use1819- Input motif set has not yet been queried against MotifDB — apply MassQL query construction first.20- Match scores are unavailable or ranking structure is not preserved in the database output.21- Discovery goal is purely exploratory motif identification without reference-guided validation — skip to direct LDA interpretation.2223## Inputs2425- inferred motifset in JSON format (output from MS2LDA LDA modeling step)26- ranked MotifDB match records per motif (motif ID, name, composition, match score)27- original Mass2Motif fragment and neutral-loss patterns28- spectral dataset metadata (compound identities, occurrence frequencies)2930## Outputs3132- interpreted motif-to-database annotation assignments33- ranked similarity scores with confidence assessments34- per-motif annotation metadata (matched motif ID, name, score, structural rationale)35- annotation report documenting ranking confidence and pattern alignment3637## How to apply3839Load the JSON output containing ranked MotifDB matches per Mass2Motif, sorting by the provided similarity or match score (higher scores indicate greater correspondence). Examine the top-ranked entry's composition and neutral-loss patterns against the original discovered motif's fragment and neutral-loss patterns extracted from the LDA inference step; assess whether the ranked hit's mass composition aligns with the motif's observed fragments and whether neutral-loss patterns co-occur consistently. Use the ranking order as a confidence signal: a match ranked first with substantially higher score than second-ranked alternatives suggests greater specificity. Cross-reference the match against the motif's occurrence frequency across the spectral dataset and the compounds in which it appears; if a high-scoring database hit occurs in structurally diverse compounds, evaluate whether the match represents a general fragmentation pattern or a specific substructure. Document the per-motif ranking structure preserved in the JSON to enable downstream filtering or threshold-based annotation decisions.4041## Related tools4243- **MassQL** (query engine for constructing and executing database searches using fragment and neutral-loss patterns)44- **MotifDB** (searchable reference database containing ranked motif entries, composition, and match scores for comparison) — https://zenodo.org/records/1568860945- **MS2LDA** (generates the inferred motifset and provides LDA-learned Mass2Motif patterns as input to similarity ranking) — https://github.com/vdhooftcompmet/MS2LDA46- **Spec2Vec** (optionally supports automated annotation guidance (MAG) for motif interpretation)4748## Evaluation signals4950- Top-ranked MotifDB entry's mass composition and neutral-loss patterns show >80% correspondence with the original discovered motif's fragment set.51- Ranking order is monotonic or near-monotonic (scores decrease or plateau from rank 1 to N), indicating valid score ordering without artifacts.52- Per-motif JSON output preserves ranking structure with ≥2 ranked candidates per motif, enabling comparative scoring.53- Annotated motif occurs consistently across a chemically coherent compound subset (e.g., alkaloids, lipids) rather than random scatter, validating structural relevance.54- Match score spread (top score − second-place score) exceeds a domain-specific threshold (e.g., >20% relative difference), suggesting confidence in the top hit.5556## Limitations5758- MotifDB reference database completeness and curation directly affect match quality; sparse or outdated database entries may fail to retrieve true structural assignments.59- Ranking scores depend on MassQL query specificity; overly broad or overly narrow queries may rank spurious or missed matches.60- Neutral-loss patterns alone may not uniquely identify substructures, especially for compounds sharing common fragmentation routes; multi-evidence integration (MS/MS intensity, retention time, spectral context) is often required for high-confidence annotation.61- Top-ranked matches may reflect frequent mass motifs in the reference database rather than structurally unique substructures, potentially biasing annotation toward common fragmentations.6263## Evidence6465- [other] For each motif, construct a MassQL query using its fragment and neutral-loss patterns to search the MotifDB reference database.: "For each motif, construct a MassQL query using its fragment and neutral-loss patterns to search the MotifDB reference database."66- [other] Execute the MassQL search against MotifDB via the MassQL4MotifDB integration module, retrieving ranked matches sorted by similarity or match score.: "Execute the MassQL search against MotifDB via the MassQL4MotifDB integration module, retrieving ranked matches sorted by similarity or match score."67- [other] Serialize query results and MotifDB match records (motif ID, name, composition, score) to a JSON output file preserving the per-motif ranking structure.: "Serialize query results and MotifDB match records (motif ID, name, composition, score) to a JSON output file preserving the per-motif ranking structure."68- [methods] MS2LDA integrates with a MassQL-searchable MotifDB to enable comparison of discovered motifs against known database entries, supporting automated motif annotation and result retrieval.: "MS2LDA integrates with a MassQL-searchable MotifDB to enable comparison of discovered motifs against known database entries, supporting automated motif annotation and result retrieval."69- [readme] identifying recurring substructures (motifs) across spectral datasets without relying on prior compound identification: "identifying recurring substructures (motifs) across spectral datasets without relying on prior compound identification"
HolobiomicsLab