Sample Spectrum Metadata Alignment

sample-spectrum-metadata-alignment

Summary

Retrieve and extract molecular networking job results from GNPS (versions 1 and 2) to obtain standardized spectral and metadata files required for downstream computational analysis of natural product spectra and their associated sample metadata.

When to use

You have a GNPS task ID from a completed molecular networking workflow (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING on GNPS1, or classical_networking_workflow / feature_based_molecular_networking_workflow on GNPS2) and need to access the resulting spectral data (spectra.mgf), molecular family annotations, file mappings, and metadata for integration with genomic data in NPLinker or similar multi-omics frameworks.

When NOT to use

• Your GNPS workflow has not yet completed or the task ID is invalid; wait for GNPS job completion before attempting download.
• You already have local copies of spectra.mgf, molecular_families.tsv, and file mappings; extraction is redundant if these files are already aligned to your working directory.
• You are using a non-standard or custom GNPS workflow variant not listed in the supported versions (METABOLOMICS-SNETS*, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1, or classical/feature_based for GNPS2); detection and file renaming may fail silently.

Inputs

• GNPS task ID (string)
• download directory path (string)
• GNPS workflow version (inferred from compressed archive contents)

Outputs

• spectra.mgf (standardized mass spectrometry spectral data file)
• molecular_families.tsv (molecular network cluster assignments)
• annotations.tsv (GNPS spectral library matches and metadata)
• file_mappings.tsv or .csv (mapping between spectral features and input samples)
• gnps directory (standardized output directory tree)

How to apply

Execute a two-step download-and-extract workflow: (1) Instantiate a GNPSDownloader with your GNPS task ID and target download directory, invoke download() to retrieve the compressed archive from GNPS servers, and capture the returned archive file path; (2) Instantiate a GNPSExtractor with the archive path and a target gnps directory, invoke extraction to automatically detect the GNPS workflow version (GNPS1 or GNPS2) and rename the resulting files according to the version-specific mapping (spectra.mgf, molecular_families.tsv, annotations.tsv, and file_mappings.tsv or .csv). This standardization enables consistent downstream access to molecular networking results across heterogeneous GNPS releases.

Related tools

• GNPSDownloader (Retrieves compressed GNPS workflow output archive from remote GNPS servers (GNPS1 or GNPS2) given a task ID and returns the local archive file path.) — https://github.com/NPLinker/nplinker
• GNPSExtractor (Unpacks and standardizes the contents of a GNPS output archive by detecting workflow version and renaming spectral, annotation, and mapping files to canonical names (spectra.mgf, molecular_families.tsv, etc.) for downstream use.) — https://github.com/NPLinker/nplinker
• GNPS (Remote spectral networking platform that generates molecular networking results (task output archives) consumed by this skill.) — https://gnps.ucsd.edu
• NPLinker (Python framework that orchestrates this download–extract workflow as a prerequisite to multi-omics data integration (genomics + metabolomics).) — https://github.com/NPLinker/nplinker
• Python (Runtime environment (≥3.11) for executing GNPSDownloader and GNPSExtractor class instantiation and method invocation.)

Examples

from nplinker.gnps import GNPSDownloader, GNPSExtractor
downloader = GNPSDownloader('task_id_12345', './downloads')
archive_path = downloader.download()
extractor = GNPSExtractor(archive_path, './gnps')
extractor.extract()

Evaluation signals

• Archive download succeeds and archive file path is returned and non-empty (file size > 0 bytes).
• Extraction completes without errors and the target gnps directory contains exactly four expected files: spectra.mgf (non-empty, valid MS/MS format), molecular_families.tsv, annotations.tsv, and either file_mappings.tsv or file_mappings.csv (all non-zero byte size).
• GNPS workflow version is correctly detected (log or return value indicates METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING, classical_networking_workflow, or feature_based_molecular_networking_workflow) and file renaming is applied accordingly.
• File format integrity: spectra.mgf conforms to MGF schema, TSV files are tab-delimited with consistent column structure, and no truncation or corruption is present.
• Downstream NPLinker module (npl.load_data()) successfully loads the extracted files without schema or path errors, confirming alignment with expected metadata structure.

Limitations

• Requires an active internet connection to GNPS1 (https://gnps.ucsd.edu) or GNPS2 (https://gnps2.org) servers; network outages or server maintenance will cause download failure.
• GNPS task ID must correspond to a completed workflow; incomplete or failed GNPS tasks will produce an invalid or corrupted archive that extraction may not detect or report clearly.
• Only supports four GNPS1 workflow variants (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING) and two GNPS2 variants; custom or future GNPS workflows not in this list will not be recognized and may extract to incorrect file names.
• File naming is fixed and cannot be customized; if downstream tools expect alternative names or directory structures, post-extraction renaming or symlinking is required.
• Storage requirements depend on GNPS dataset size; large spectral libraries (>10 GB archives) may consume significant disk space and transfer time.

Evidence

• [other] NPLinker uses a two-step process: Download GNPS data & get the path to the downloaded archive, then Extract GNPS data to gnps directory, enabling access to molecular networking results for subsequent computational analysis.: "NPLinker uses a two-step process: Download GNPS data & get the path to the downloaded archive, then Extract GNPS data to gnps directory"
• [other] Instantiate GNPSDownloader with a GNPS task ID and download directory path, then invoke the download() method to retrieve the compressed archive from GNPS servers and obtain the archive file path.: "Instantiate GNPSDownloader with a GNPS task ID and download directory path, then invoke the download() method to retrieve the compressed archive from GNPS servers"
• [other] Instantiate GNPSExtractor with the downloaded archive path and target gnps directory path, then invoke extraction to identify and rename the workflow-specific files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv or .csv) according to the mapping table for the detected GNPS workflow version: "invoke extraction to identify and rename the workflow-specific files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv or .csv)"
• [other] METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1; classical_networking_workflow or feature_based_molecular_networking_workflow for GNPS2: "for the detected GNPS workflow version (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1; classical_networking_workflow or"
• [other] currently accepts data from both GNPS1 (https://gnps.ucsd.edu) and GNPS2 (https://gnps2.org) workflows: "currently accepts data from both GNPS1 (https://gnps.ucsd.edu) and GNPS2 (https://gnps2.org) workflows"