Domain Context To Application Routing

---
name: domain-context-to-application-routing
description: Use when when a user submits one or more MS/MS spectra and has declared
  or implied a domain context (microbial, plant, tissue, microbiome, food, or metadata
  aggregation), and the search must be executed against the appropriate domain-curated
  spectral library.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3763
  edam_topics:
  - http://edamontology.org/topic_3520
  - http://edamontology.org/topic_0121
  tools:
  - microbeMASST
  - plantMASST
  - tissueMASST
  - microbiomeMASST
  - foodMASST
  - metadataMASST
  - GNPS_MASST
  - jobs.py
  - Fast Search API
  techniques:
  - MS-imaging
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1038/s41564-023-01575-9
  title: microbemasst
evidence_spans:
- microbeMASST, plantMASST, tissueMASST, microbiomeMASST, and foodMASST
- Aggregated search outputs can be generated and visualized using metadataMASST
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_microbemasst
    doi: 10.1038/s41564-023-01575-9
    title: microbemasst
  dedup_kept_from: coll_microbemasst
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1038/s41564-023-01575-9
  all_source_dois:
  - 10.1038/s41564-023-01575-9
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# domain-context-to-application-routing

## Summary

A conditional routing mechanism that maps user-submitted mass spectra to domain-specific MASST applications (microbeMASST, plantMASST, tissueMASST, microbiomeMASST, foodMASST, or metadataMASST) based on explicit domain-context metadata. This skill enables single-spectrum or batch searches to be dispatched to the correct standalone web application or search endpoint without manual user navigation.

## When to use

When a user submits one or more MS/MS spectra and has declared or implied a domain context (microbial, plant, tissue, microbiome, food, or metadata aggregation), and the search must be executed against the appropriate domain-curated spectral library. Apply this skill as the first dispatch step in a multi-domain MASST workflow to avoid cross-contamination of results or loss of domain-specific annotations.

## When NOT to use

- Domain context is unknown and cannot be inferred from sample metadata — use metadataMASST for aggregated results instead of forcing a single-domain route.
- The input spectrum file is already pre-filtered to a single domain — routing logic is redundant; proceed directly to batch search execution.
- The user intent is exploratory across all domains simultaneously — invoke the batch search (jobs.py) without intermediate single-domain routing to generate multi-domain outputs in one pass.

## Inputs

- MS/MS spectrum file (.mgf format, optionally generated by MZmine or GNPS molecular networking)
- Universal Spectrum Identifier (USI) list (.csv or .tsv format)
- Spectrum metadata containing domain-context field (string: 'microbial', 'plant', 'tissue', 'microbiome', 'food', or 'metadata')
- Search parameters (minimum cosine score, m/z tolerance, minimum matching peaks)

## Outputs

- Routed spectrum request dispatched to selected domain-specific MASST application endpoint
- Interactive HTML tree file (_domain.html, e.g., _microbe.html, _plant.html)
- JSON tree representation (_domain.json)
- _matches.tsv: all spectrum matches found in indexed GNPS/MassIVE, Metabolomics Workbench, Metabolights, and NORMAN datasets
- _library.tsv: GNPS library matches enabling Level 2 annotation (MSI standard)
- _datasets.tsv: count of unique samples per matched dataset
- _count_domain.tsv: match counts per domain-specific MASST

## How to apply

Extract the domain-context label from the user's spectrum metadata submission or explicit interface selection (e.g., dropdown menu or .tsv metadata column). Implement a conditional mapping that routes the spectrum metadata and search parameters to one of six standalone web application endpoints or backend modules (microbeMASST → https://masst.gnps2.org/microbemasst/, plantMASST → https://masst.gnps2.org/plantmasst/, etc.). Validate that the domain context string matches one of the six recognized domains; if ambiguous or absent, default to metadataMASST for aggregated output or reject with a user prompt. Pass through the spectrum's m/z tolerance, minimum cosine similarity score (the README notes typical adjustment of this parameter), and minimum matching peaks thresholds unchanged. Confirm correct routing by comparing the domain context token against the NCBI taxonomy scope and sample lineage coverage documented for each tool (e.g., microbeMASST covers 561 genera and 1379 species; plantMASST covers 1796 genera and 3712 species).

## Related tools

- **microbeMASST** (Domain-specific MASST for microbial metabolomics search; receives routed spectra with 'microbial' context label and searches against curated microbial spectral library (561 genera, 1379 species, 542 strains).) — https://masst.gnps2.org/microbemasst/
- **plantMASST** (Domain-specific MASST for plant metabolomics search; receives routed spectra with 'plant' context label and searches against curated plant library (1796 genera, 3712 species).) — https://masst.gnps2.org/plantmasst/
- **tissueMASST** (Domain-specific MASST for tissue/human metabolomics search; receives routed spectra with 'tissue' context label.) — https://masst.gnps2.org/tissuemasst/
- **microbiomeMASST** (Domain-specific MASST for microbiome metabolomics search; receives routed spectra with 'microbiome' context label.) — https://masst.gnps2.org/microbiomemasst/
- **foodMASST** (Domain-specific MASST for food metabolomics search; receives routed spectra with 'food' context label.) — https://masst.gnps2.org/foodmasst2/
- **metadataMASST** (Aggregated search and visualization tool for multi-domain outputs; receives routed spectra when domain context is ambiguous or 'metadata' label, or aggregates results from all domain-specific MASSTs.) — https://masst.gnps2.org/metadatamasst/
- **GNPS_MASST** (Source codebase containing conditional routing logic and backend implementation for all standalone web applications; used to configure and deploy domain-context-based dispatch rules.) — https://github.com/mwang87/GNPS_MASST
- **jobs.py** (Batch orchestration script that iterates over multiple spectra and executes routing + search for each; manages retry logic and aggregates domain-specific outputs across a full dataset.) — https://github.com/robinschmid/microbe_masst/blob/master/code/jobs.py
- **Fast Search API** (Underlying API service that executes the actual spectral search after routing; receives routed spectrum queries and searches indexed GNPS/MassIVE, Metabolomics Workbench, Metabolights, and NORMAN datasets.) — https://fasst.gnps2.org/fastsearch/

## Examples

```
python jobs.py  # After adding entries to the files list as ("input_directory/input_file", "output_directory/output_prefix") and setting domain-specific parameters (min_cosine_score, mz_tolerance, min_matching_peaks), then re-run until skip_existing=True produces no new output.
```

## Evaluation signals

- Routing table or conditional logic returns exactly one of {microbeMASST, plantMASST, tissueMASST, microbiomeMASST, foodMASST, metadataMASST} for each input spectrum.
- Routed spectrum invocation includes correct domain-specific endpoint URL and passes through search parameters (cosine score, m/z tolerance, minimum peaks) unchanged.
- Output HTML tree files end with the correct domain suffix (e.g., _microbe.html for microbial spectra, _plant.html for plant spectra).
- Taxonomy lineage coverage of returned matches matches the documented domain scope (e.g., matches for microbeMASST queries are restricted to 8 kingdoms, 20 phyla, 561 genera verified against lineages/ folder).
- Batch execution of jobs.py produces all six domain-specific count files (_count_domain.tsv variants) if aggregated mode is requested, confirming multi-domain routing occurred.

## Limitations

- Domain context must be explicitly provided by the user or parseable from spectrum metadata; no automatic inference from spectral features is performed, risking misrouting if metadata is absent or malformed.
- The six domain-specific libraries are curated independently and may have non-overlapping sample coverage; a spectrum matching in microbeMASST may not match in plantMASST even if the metabolite is present in both domains, depending on what samples have been indexed.
- Fast Search API failures on individual entries require re-running jobs.py multiple times (with skip_existing=True) to catch all possible matches, introducing operational overhead and potential incomplete results on first execution.
- Python 3.10 is required for jobs.py execution; compatibility with other Python versions is not documented and may cause import or API errors.
- metadataMASST aggregation outputs do not preserve domain-of-origin labels for individual matches, making it difficult to trace which domain-specific routing path a particular match came from in downstream analysis.

## Evidence

- [other] The repository contains code and data for six domain-specific MASSTs (microbeMASST, plantMASST, tissueMASST, microbiomeMASST, foodMASST, and metadataMASST) that operate as standalone web applications allowing users to search one spectrum at a time, with the underlying routing code available in the GNPS_MASST codebase.: "The repository contains code and data for six domain-specific MASSTs (microbeMASST, plantMASST, tissueMASST, microbiomeMASST, foodMASST, and metadataMASST) that operate as standalone web applications"
- [readme] standalone web applications, which allow users to search one spectrum at a time, can be found in GNPS_MASST: "The code for the different standalone web applications, which allow users to search one spectrum at a time, can be found in GNPS_MASST"
- [readme] Aggregated search outputs can be generated and visualized using metadataMASST: "Aggregated search outputs can be generated and visualized using metadataMASST"
- [other] Parse user-submitted spectrum metadata and extract the domain-context selection (e.g., microbial, plant, tissue, microbiome, food, or metadata aggregation). Implement conditional routing logic that maps domain context to the corresponding standalone web application endpoint or module.: "Parse user-submitted spectrum metadata and extract the domain-context selection (e.g., microbial, plant, tissue, microbiome, food, or metadata aggregation). Implement conditional routing logic that"
- [readme] Running jobs.py allows users to leverage the Fast Search API and execute a batch search of multiple MS/MS spectra against the current indexed data in GNPS/MassIVE, Metabolomics Workbench, Metabolights, and NORMAN and generate multiple outputs for all listed domainMASSTs simultaneously.: "Running jobs.py allows users to leverage the Fast Search API and execute a batch search of multiple MS/MS spectra against the current indexed data in GNPS/MassIVE, Metabolomics Workbench,"
- [readme] You can run either a single .mgf file generated via MZmine, from the molecular networking in GNPS workflow, or a list of USIs provided either via a .csv or .tsv file.: "You can run either a single .mgf file generated via MZmine, from the molecular networking in GNPS workflow, or a list of USIs provided either via a .csv or .tsv file."
- [readme] microbeMASST covers Kingdom 8, Phylum 20, Class 48, Order 124, Family 278, Genus 561, Species 1379, Strain 542; plantMASST covers Kingdom 1, Phylum 1, Class 11, Order 81, Family 319, Genus 1796, Species 3712: "microbeMASST | 8 | 20 | 48 | 124 | 278 | 561 | 1379 | 542; plantMASST | 1 | 1 | 11 | 81 | 319 | 1796 | 3712 | NA"
- [readme] Make sure to run jobs.py a couple of times, until no new output is generated by having the option: skip_existing=True. Due to the Fast Search API some of the entries will fail.: "Make sure to run jobs.py **_a couple of times_**, until no new output is generated by having the option: `skip_existing=True`. Due to the Fast Search API some of the entries will fail."
- [readme] Please make user to use Python 3.10: "Please make user to use **_Python 3.10_**"