microbe-compound-identification
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Identify metabolites and trace their origins to specific microbial taxa using single-spectrum mass spectrometry searches against curated microbe-specific reference libraries. This skill enables taxonomically informed annotation of microbial metabolomics data by leveraging domain-specific mass spectral databases integrated with NCBI taxonomy lineage information.
When to use
You have collected MS/MS spectra from a microbial sample (pure culture, environmental isolate, or mixed community) and need to assign chemical identities to observed m/z features while simultaneously resolving which microbial taxa are likely producers of each metabolite. Use this skill when a single spectrum query against microbe-specific reference data is sufficient for your research question; if you have dozens of spectra to process simultaneously across multiple domains (microbe, plant, food, tissue), use batch search instead.
When NOT to use
- Input is already a curated feature table or annotated compound list — use this skill to perform initial spectrum-to-compound annotation, not to post-process existing identifications.
- You need simultaneous batch search across non-microbial domains (plants, tissues, food) — use jobs.py with batch search API instead of single-spectrum queries.
- Your spectra come from non-microbial sources or environmental samples where plant, tissue, or food contamination is the primary concern — use domain-specific MASSTs (plantMASST, tissueMASST, foodMASST) appropriate to your sample type.
Inputs
- Single MS/MS spectrum (in .mgf format or Universal Spectrum Identifier / USI)
- Search parameters: cosine similarity threshold, m/z tolerance, minimum peak match count
Outputs
- Ranked list of spectral matches from microbeMASST reference library (with cosine scores)
- Taxonomic lineage information for matched spectra (kingdom, phylum, class, order, family, genus, species, strain)
- GNPS library annotations (Level 2 MSI) for matched compounds
- Sample-level match counts and dataset distribution (via _matches.tsv, _library.tsv, _datasets.tsv)
- Interactive HTML and JSON tree visualizations of taxonomic assignment
How to apply
Deploy the microbeMASST standalone web application (hosted at https://masst.gnps2.org/microbemasst/) or clone and run the code from GNPS_MASST and robinschmid/microbe_masst repositories. Input a single MS/MS spectrum (in .mgf format or as a USI reference) and configure search parameters: minimum cosine similarity score (typical range 0.6–0.7), m/z tolerance (e.g., 0.1 Da for high-resolution instruments), and minimum number of matching peaks (typically 6–10 depending on spectral quality). The search queries the indexed microbeMASST reference library, which currently covers 8 kingdoms, 20 phyla, 48 classes, 124 orders, 278 families, 561 genera, 1379 species, and 542 strains. Review the returned matches ranked by cosine score; cross-reference library matches (enabling Level 2 MSI annotation) with sample-level counts to infer producer taxa. Optionally aggregate outputs using metadataMASST for visualization across multiple spectra.
Related tools
- GNPS_MASST (Hosts the standalone web application code and deployment infrastructure for microbeMASST and other domain-specific MASSTs) — https://github.com/mwang87/GNPS_MASST
- microbe_masst (Contains the microbeMASST-specific implementation, batch search job runner (jobs.py), taxonomic lineage data, and reference library curation logic) — https://github.com/robinschmid/microbe_masst
- metadataMASST (Aggregates and visualizes search outputs from single or batch microbeMASST queries for multi-spectrum analysis and cross-domain comparison) — https://masst.gnps2.org/metadatamasst/
- Fast Search API (Powers batch spectrum queries against indexed GNPS/MassIVE, Metabolomics Workbench, Metabolights, and NORMAN data for high-throughput microbe compound identification) — https://fasst.gnps2.org/fastsearch/
- MZmine (Upstream tool for preprocessing raw MS data and exporting .mgf spectra for input to microbeMASST queries) — https://github.com/mzmine/mzmine
Examples
# Query a single spectrum via USI or .mgf file using the microbeMASST web interface at https://masst.gnps2.org/microbemasst/, or programmatically via batch run: python code/jobs.py (after adding entries to jobs_list with cosine_threshold=0.7, mz_tolerance=0.1, and minimum_peaks=6)
Evaluation signals
- Returned matches have cosine similarity scores above your configured threshold and show clear peak alignment between query and reference spectra (inspect interactive HTML tree or JSON structure).
- Matched compounds are chemically consistent with known microbial natural products (e.g., secondary metabolites, antibiotics, pigments) and the taxonomic lineages returned are biologically plausible producers of those compounds.
- Library matches (when present) are ranked higher than non-library matches, enabling MSI Level 2 annotation confidence for your compound of interest.
- If the same metabolite is matched across multiple NCBI taxonomy IDs, inspect the strain/species coverage in the lineage files to confirm representation across the expected producer taxa.
- Re-running the same spectrum with relaxed search parameters (lower cosine threshold, higher m/z tolerance) should yield a superset of matches; if not, check API logs or re-run via batch jobs.py with skip_existing=False to detect transient failures.
Limitations
- microbeMASST reference library is limited to currently indexed and curated microbial spectra; novel or rare compounds may lack matches despite being biologically relevant.
- Single-spectrum queries do not provide quantitative abundance or co-occurrence information; use batch search with metadataMASST for multi-spectrum ecological context.
- Fast Search API can experience transient failures on first run; the README recommends running jobs.py multiple times (with skip_existing=True) to capture all possible matches.
- Taxonomic assignment is only as informative as the lineage metadata associated with reference spectra; spectra from uncultured or poorly annotated environmental samples will yield incomplete or ambiguous producer lineages.
- Search parameters (cosine threshold, m/z tolerance, peak match count) must be manually tuned based on instrument resolution and spectral quality; no automated parameter selection is provided.
Evidence
- [other] microbeMASST is implemented as a standalone web application that accepts individual mass spectra as input and performs searches against a microbe-specific reference database: "microbeMASST is implemented as a standalone web application that accepts individual mass spectra as input and performs searches against a microbe-specific reference database"
- [readme] The code for the different 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] microbeMASST currently covers 8 kingdoms, 20 phyla, 48 classes, 124 orders, 278 families, 561 genera, 1379 species, and 542 strains: "microbeMASST | 8 | 20 | 48 | 124 | 278 | 561 | 1379 | 542"
- [readme] Aggregated search outputs can be generated and visualized using metadataMASST: "Aggregated search outputs can be generated and visualized using metadataMASST"
- [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: "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] A _library.tsv file will be generated. This contains a list of spectra from the GNPS libraries found to match your spectrum of interest. This enables a Level 2 annotation according the Metabolomics Standards Initiative.: "A _library.tsv file will be generated. This contains a list of spectra from the GNPS libraries found to match your spectrum of interest. This enables a Level 2 annotation according the Metabolomics"
- [readme] Check and adjust the different parameters for the search, such as minimum cosine score, mz tolerance, and number of minimum matching peaks based on your research question.: "Check and adjust the different parameters for the search, such as minimum cosine score, mz tolerance, and number of minimum matching peaks based on your research question."
- [readme] Due to the Fast Search API some of the entries will fail. Nevertheless sequent re-runs should catch all the possible matches.: "Due to the Fast Search API some of the entries will fail. Nevertheless sequent re-runs should catch all the possible matches."
1---2name: microbe-compound-identification3description: Use when you have collected MS/MS spectra from a microbial sample (pure culture, environmental isolate, or mixed community) and need to assign chemical identities to observed m/z features while simultaneously resolving which microbial taxa are likely producers of each metabolite.4license: CC-BY-4.05---67# microbe-compound-identification89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Identify metabolites and trace their origins to specific microbial taxa using single-spectrum mass spectrometry searches against curated microbe-specific reference libraries. This skill enables taxonomically informed annotation of microbial metabolomics data by leveraging domain-specific mass spectral databases integrated with NCBI taxonomy lineage information.1314## When to use1516You have collected MS/MS spectra from a microbial sample (pure culture, environmental isolate, or mixed community) and need to assign chemical identities to observed m/z features while simultaneously resolving which microbial taxa are likely producers of each metabolite. Use this skill when a single spectrum query against microbe-specific reference data is sufficient for your research question; if you have dozens of spectra to process simultaneously across multiple domains (microbe, plant, food, tissue), use batch search instead.1718## When NOT to use1920- Input is already a curated feature table or annotated compound list — use this skill to perform initial spectrum-to-compound annotation, not to post-process existing identifications.21- You need simultaneous batch search across non-microbial domains (plants, tissues, food) — use jobs.py with batch search API instead of single-spectrum queries.22- Your spectra come from non-microbial sources or environmental samples where plant, tissue, or food contamination is the primary concern — use domain-specific MASSTs (plantMASST, tissueMASST, foodMASST) appropriate to your sample type.2324## Inputs2526- Single MS/MS spectrum (in .mgf format or Universal Spectrum Identifier / USI)27- Search parameters: cosine similarity threshold, m/z tolerance, minimum peak match count2829## Outputs3031- Ranked list of spectral matches from microbeMASST reference library (with cosine scores)32- Taxonomic lineage information for matched spectra (kingdom, phylum, class, order, family, genus, species, strain)33- GNPS library annotations (Level 2 MSI) for matched compounds34- Sample-level match counts and dataset distribution (via _matches.tsv, _library.tsv, _datasets.tsv)35- Interactive HTML and JSON tree visualizations of taxonomic assignment3637## How to apply3839Deploy the microbeMASST standalone web application (hosted at https://masst.gnps2.org/microbemasst/) or clone and run the code from GNPS_MASST and robinschmid/microbe_masst repositories. Input a single MS/MS spectrum (in .mgf format or as a USI reference) and configure search parameters: minimum cosine similarity score (typical range 0.6–0.7), m/z tolerance (e.g., 0.1 Da for high-resolution instruments), and minimum number of matching peaks (typically 6–10 depending on spectral quality). The search queries the indexed microbeMASST reference library, which currently covers 8 kingdoms, 20 phyla, 48 classes, 124 orders, 278 families, 561 genera, 1379 species, and 542 strains. Review the returned matches ranked by cosine score; cross-reference library matches (enabling Level 2 MSI annotation) with sample-level counts to infer producer taxa. Optionally aggregate outputs using metadataMASST for visualization across multiple spectra.4041## Related tools4243- **GNPS_MASST** (Hosts the standalone web application code and deployment infrastructure for microbeMASST and other domain-specific MASSTs) — https://github.com/mwang87/GNPS_MASST44- **microbe_masst** (Contains the microbeMASST-specific implementation, batch search job runner (jobs.py), taxonomic lineage data, and reference library curation logic) — https://github.com/robinschmid/microbe_masst45- **metadataMASST** (Aggregates and visualizes search outputs from single or batch microbeMASST queries for multi-spectrum analysis and cross-domain comparison) — https://masst.gnps2.org/metadatamasst/46- **Fast Search API** (Powers batch spectrum queries against indexed GNPS/MassIVE, Metabolomics Workbench, Metabolights, and NORMAN data for high-throughput microbe compound identification) — https://fasst.gnps2.org/fastsearch/47- **MZmine** (Upstream tool for preprocessing raw MS data and exporting .mgf spectra for input to microbeMASST queries) — https://github.com/mzmine/mzmine4849## Examples5051```52# Query a single spectrum via USI or .mgf file using the microbeMASST web interface at https://masst.gnps2.org/microbemasst/, or programmatically via batch run: python code/jobs.py (after adding entries to jobs_list with cosine_threshold=0.7, mz_tolerance=0.1, and minimum_peaks=6)53```5455## Evaluation signals5657- Returned matches have cosine similarity scores above your configured threshold and show clear peak alignment between query and reference spectra (inspect interactive HTML tree or JSON structure).58- Matched compounds are chemically consistent with known microbial natural products (e.g., secondary metabolites, antibiotics, pigments) and the taxonomic lineages returned are biologically plausible producers of those compounds.59- Library matches (when present) are ranked higher than non-library matches, enabling MSI Level 2 annotation confidence for your compound of interest.60- If the same metabolite is matched across multiple NCBI taxonomy IDs, inspect the strain/species coverage in the lineage files to confirm representation across the expected producer taxa.61- Re-running the same spectrum with relaxed search parameters (lower cosine threshold, higher m/z tolerance) should yield a superset of matches; if not, check API logs or re-run via batch jobs.py with skip_existing=False to detect transient failures.6263## Limitations6465- microbeMASST reference library is limited to currently indexed and curated microbial spectra; novel or rare compounds may lack matches despite being biologically relevant.66- Single-spectrum queries do not provide quantitative abundance or co-occurrence information; use batch search with metadataMASST for multi-spectrum ecological context.67- Fast Search API can experience transient failures on first run; the README recommends running jobs.py multiple times (with skip_existing=True) to capture all possible matches.68- Taxonomic assignment is only as informative as the lineage metadata associated with reference spectra; spectra from uncultured or poorly annotated environmental samples will yield incomplete or ambiguous producer lineages.69- Search parameters (cosine threshold, m/z tolerance, peak match count) must be manually tuned based on instrument resolution and spectral quality; no automated parameter selection is provided.7071## Evidence7273- [other] microbeMASST is implemented as a standalone web application that accepts individual mass spectra as input and performs searches against a microbe-specific reference database: "microbeMASST is implemented as a standalone web application that accepts individual mass spectra as input and performs searches against a microbe-specific reference database"74- [readme] The code for the different 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"75- [readme] microbeMASST currently covers 8 kingdoms, 20 phyla, 48 classes, 124 orders, 278 families, 561 genera, 1379 species, and 542 strains: "microbeMASST | 8 | 20 | 48 | 124 | 278 | 561 | 1379 | 542"76- [readme] Aggregated search outputs can be generated and visualized using metadataMASST: "Aggregated search outputs can be generated and visualized using metadataMASST"77- [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: "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,"78- [readme] A _library.tsv file will be generated. This contains a list of spectra from the GNPS libraries found to match your spectrum of interest. This enables a Level 2 annotation according the Metabolomics Standards Initiative.: "A _library.tsv file will be generated. This contains a list of spectra from the GNPS libraries found to match your spectrum of interest. This enables a Level 2 annotation according the Metabolomics"79- [readme] Check and adjust the different parameters for the search, such as minimum cosine score, mz tolerance, and number of minimum matching peaks based on your research question.: "Check and adjust the different parameters for the search, such as minimum cosine score, mz tolerance, and number of minimum matching peaks based on your research question."80- [readme] Due to the Fast Search API some of the entries will fail. Nevertheless sequent re-runs should catch all the possible matches.: "Due to the Fast Search API some of the entries will fail. Nevertheless sequent re-runs should catch all the possible matches."
HolobiomicsLab