gcf-spectra-association-ranking
Summary
Compute ranked associations between Genomic Cluster Families (GCFs) and molecular spectra using the Metcalf scoring algorithm, producing a weighted LinkGraph artifact that represents putative biosynthetic-metabolomic links with quantified confidence scores.
When to use
When you have integrated genomic data (GCFs from AntiSMASH via BigScape clustering) and metabolomic data (spectra and molecular families from GNPS molecular networking) and need to identify and rank which secondary metabolites detected in spectra are likely produced by which biosynthetic gene clusters, quantifying the strength of each putative association.
When NOT to use
- Input genomic or metabolomic data has not been pre-processed through AntiSMASH, BigScape, and GNPS respectively—Metcalf scoring assumes upstream clustering and networking are complete.
- You require probabilistic uncertainty quantification or Bayesian credible intervals around link scores—MetcalfScoring produces point estimates only.
- Spectral or GCF data is incomplete, misaligned, or missing key metadata (e.g., molecular weights, fragmentation patterns, or cluster boundary annotations).
Inputs
- GCFs (Genomic Cluster Families) from AntiSMASH/BigScape clustering
- Molecular spectra from mass spectrometry
- Molecular families from GNPS molecular networking
- Loaded NPLinker Dataset object
Outputs
- LinkGraph object containing weighted directed edges between GCFs and spectral entities
- Link score annotations (numeric weights on edges)
- Ranked associations (implicit via edge scores)
How to apply
Load pre-prepared genomic and metabolomic datasets (GCFs, spectra, and molecular families) using NPLinker's DatasetLoader. Initialize a MetcalfScoring instance with the loaded entities. Execute the scoring computation via NPLinker.get_links(), which applies the Metcalf algorithm to compute pairwise links between GCFs and spectral entities. The algorithm returns a LinkGraph object—a directed weighted graph where each edge represents a GCF-to-spectrum association labeled with a numeric link score. Validate the LinkGraph by confirming that links are present and scores fall within expected ranges (typically [0, 1] or similar normalized interval). The ranking is implicit in the link scores; higher scores indicate stronger predicted associations.
Related tools
- nplinker (Core framework providing DatasetLoader, MetcalfScoring class, and LinkGraph data structure for computing and managing GCF-spectra associations) — https://github.com/NPLinker/nplinker
- AntiSMASH (Upstream tool for detecting and annotating biosynthetic gene clusters (input to BigScape clustering))
- BigScape (Clustering tool that groups AntiSMASH BGCs into GCFs, which serve as genomic entities for Metcalf scoring)
- GNPS (Metabolomic networking platform providing molecular families and spectra that are scored against GCFs) — https://gnps.ucsd.edu
- Python (Programming environment for executing NPLinker DatasetLoader and MetcalfScoring methods)
Examples
from nplinker import NPLinker; npl = NPLinker.load(config_file='config.yaml'); npl.load_data(); links = npl.get_links(scoring_method='metcalf'); print(links.edges())
Evaluation signals
- LinkGraph is non-empty: at least one GCF-to-spectrum link is present in the output.
- Link scores are numeric and within expected normalized range (e.g., [0.0, 1.0] or equivalent quantile).
- All GCF and spectrum identifiers in LinkGraph edges correspond to entities in the input Dataset.
- LinkGraph is a directed graph with GCFs and spectral entities as node sets and weighted edges representing associations.
- Rerunning the same computation with identical inputs produces identical link scores (deterministic output).
Limitations
- MetcalfScoring requires upstream AntiSMASH, BigScape, and GNPS preprocessing; garbage input data produces garbage output.
- Link scores are deterministic point estimates; no confidence intervals or uncertainty bounds are returned.
- The Metcalf algorithm's specificity and sensitivity depend on the quality and completeness of the input genomic and metabolomic datasets; sparse or noisy data may yield false positives or false negatives.
- No discussion section or methodological limitations are documented in the provided source material; algorithm rationale and failure modes are not explicitly described.
Evidence
- [other] The MetcalfScoring computation accepts GCFs and molecular families/spectra as inputs and computes links between them, returning a LinkGraph artifact that represents the scoring results.: "The MetcalfScoring computation accepts GCFs and molecular families/spectra as inputs and computes links between them, returning a LinkGraph artifact that represents the scoring results."
- [other] Load pre-prepared datasets containing GCFs (from AntiSMASH via BigScape clustering), spectra, and molecular families (from GNPS molecular networking) using NPLinker's DatasetLoader.: "Load pre-prepared datasets containing GCFs (from AntiSMASH via BigScape clustering), spectra, and molecular families (from GNPS molecular networking)"
- [other] Execute the scoring computation via the NPLinker.get_links() method, which applies the Metcalf scoring algorithm to compute pairwise links between GCFs and spectral entities.: "Execute the scoring computation via the NPLinker.get_links() method, which applies the Metcalf scoring algorithm to compute pairwise links between GCFs and spectral entities."
- [other] Return a LinkGraph object containing the computed links as a directed weighted graph with link scores and metadata.: "Return a LinkGraph object containing the computed links as a directed weighted graph with link scores and metadata."
- [other] Validate the LinkGraph by checking that links are present and scores are in expected range.: "Validate the LinkGraph by checking that links are present and scores are in expected range."
- [readme] NPLinker is a python framework for data mining microbial natural products by integrating genomics and metabolomics data.: "NPLinker is a python framework for data mining microbial natural products by integrating genomics and metabolomics data."
1---2name: gcf-spectra-association-ranking3description: Use when when you have integrated genomic data (GCFs from AntiSMASH via BigScape clustering) and metabolomic data (spectra and molecular families from GNPS molecular networking) and need to identify and rank which secondary metabolites detected in spectra are likely produced by which biosynthetic.4license: CC-BY-4.05---67# gcf-spectra-association-ranking89## Summary1011Compute ranked associations between Genomic Cluster Families (GCFs) and molecular spectra using the Metcalf scoring algorithm, producing a weighted LinkGraph artifact that represents putative biosynthetic-metabolomic links with quantified confidence scores.1213## When to use1415When you have integrated genomic data (GCFs from AntiSMASH via BigScape clustering) and metabolomic data (spectra and molecular families from GNPS molecular networking) and need to identify and rank which secondary metabolites detected in spectra are likely produced by which biosynthetic gene clusters, quantifying the strength of each putative association.1617## When NOT to use1819- Input genomic or metabolomic data has not been pre-processed through AntiSMASH, BigScape, and GNPS respectively—Metcalf scoring assumes upstream clustering and networking are complete.20- You require probabilistic uncertainty quantification or Bayesian credible intervals around link scores—MetcalfScoring produces point estimates only.21- Spectral or GCF data is incomplete, misaligned, or missing key metadata (e.g., molecular weights, fragmentation patterns, or cluster boundary annotations).2223## Inputs2425- GCFs (Genomic Cluster Families) from AntiSMASH/BigScape clustering26- Molecular spectra from mass spectrometry27- Molecular families from GNPS molecular networking28- Loaded NPLinker Dataset object2930## Outputs3132- LinkGraph object containing weighted directed edges between GCFs and spectral entities33- Link score annotations (numeric weights on edges)34- Ranked associations (implicit via edge scores)3536## How to apply3738Load pre-prepared genomic and metabolomic datasets (GCFs, spectra, and molecular families) using NPLinker's DatasetLoader. Initialize a MetcalfScoring instance with the loaded entities. Execute the scoring computation via NPLinker.get_links(), which applies the Metcalf algorithm to compute pairwise links between GCFs and spectral entities. The algorithm returns a LinkGraph object—a directed weighted graph where each edge represents a GCF-to-spectrum association labeled with a numeric link score. Validate the LinkGraph by confirming that links are present and scores fall within expected ranges (typically [0, 1] or similar normalized interval). The ranking is implicit in the link scores; higher scores indicate stronger predicted associations.3940## Related tools4142- **nplinker** (Core framework providing DatasetLoader, MetcalfScoring class, and LinkGraph data structure for computing and managing GCF-spectra associations) — https://github.com/NPLinker/nplinker43- **AntiSMASH** (Upstream tool for detecting and annotating biosynthetic gene clusters (input to BigScape clustering))44- **BigScape** (Clustering tool that groups AntiSMASH BGCs into GCFs, which serve as genomic entities for Metcalf scoring)45- **GNPS** (Metabolomic networking platform providing molecular families and spectra that are scored against GCFs) — https://gnps.ucsd.edu46- **Python** (Programming environment for executing NPLinker DatasetLoader and MetcalfScoring methods)4748## Examples4950```51from nplinker import NPLinker; npl = NPLinker.load(config_file='config.yaml'); npl.load_data(); links = npl.get_links(scoring_method='metcalf'); print(links.edges())52```5354## Evaluation signals5556- LinkGraph is non-empty: at least one GCF-to-spectrum link is present in the output.57- Link scores are numeric and within expected normalized range (e.g., [0.0, 1.0] or equivalent quantile).58- All GCF and spectrum identifiers in LinkGraph edges correspond to entities in the input Dataset.59- LinkGraph is a directed graph with GCFs and spectral entities as node sets and weighted edges representing associations.60- Rerunning the same computation with identical inputs produces identical link scores (deterministic output).6162## Limitations6364- MetcalfScoring requires upstream AntiSMASH, BigScape, and GNPS preprocessing; garbage input data produces garbage output.65- Link scores are deterministic point estimates; no confidence intervals or uncertainty bounds are returned.66- The Metcalf algorithm's specificity and sensitivity depend on the quality and completeness of the input genomic and metabolomic datasets; sparse or noisy data may yield false positives or false negatives.67- No discussion section or methodological limitations are documented in the provided source material; algorithm rationale and failure modes are not explicitly described.6869## Evidence7071- [other] The MetcalfScoring computation accepts GCFs and molecular families/spectra as inputs and computes links between them, returning a LinkGraph artifact that represents the scoring results.: "The MetcalfScoring computation accepts GCFs and molecular families/spectra as inputs and computes links between them, returning a LinkGraph artifact that represents the scoring results."72- [other] Load pre-prepared datasets containing GCFs (from AntiSMASH via BigScape clustering), spectra, and molecular families (from GNPS molecular networking) using NPLinker's DatasetLoader.: "Load pre-prepared datasets containing GCFs (from AntiSMASH via BigScape clustering), spectra, and molecular families (from GNPS molecular networking)"73- [other] Execute the scoring computation via the NPLinker.get_links() method, which applies the Metcalf scoring algorithm to compute pairwise links between GCFs and spectral entities.: "Execute the scoring computation via the NPLinker.get_links() method, which applies the Metcalf scoring algorithm to compute pairwise links between GCFs and spectral entities."74- [other] Return a LinkGraph object containing the computed links as a directed weighted graph with link scores and metadata.: "Return a LinkGraph object containing the computed links as a directed weighted graph with link scores and metadata."75- [other] Validate the LinkGraph by checking that links are present and scores are in expected range.: "Validate the LinkGraph by checking that links are present and scores are in expected range."76- [readme] NPLinker is a python framework for data mining microbial natural products by integrating genomics and metabolomics data.: "NPLinker is a python framework for data mining microbial natural products by integrating genomics and metabolomics data."
HolobiomicsLab 