Gnps workflow identification

GNPS Workflow Identification

Summary

Identify and map GNPS workflow versions (GNPS1 vs. GNPS2, classical vs. feature-based networking) to correctly parse and rename molecular networking output files for downstream analysis in NPLinker.

When to use

You have downloaded a GNPS molecular networking job archive and need to extract its contents (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings) but do not know which GNPS workflow version produced it, preventing correct file naming and downstream computational analysis.

When NOT to use

• GNPS data has already been extracted and files renamed to standard names (spectra.mgf, molecular_families.tsv, etc.).
• You are working with non-GNPS molecular networking data (e.g., custom mass spectrometry networking output) that does not follow GNPS archive conventions.
• The GNPS job failed or the archive is corrupted and does not contain expected workflow output files.

Inputs

• GNPS compressed archive (downloaded from GNPS1 or GNPS2 server)
• GNPS task ID or job result URL
• Target extraction directory path

Outputs

• Standardized spectra.mgf file (renamed from workflow-specific source)
• Standardized molecular_families.tsv file
• Standardized annotations.tsv file
• Standardized file_mappings.tsv or .csv file
• Extracted gnps directory with workflow-normalized file hierarchy

How to apply

Examine the structure and filenames within the downloaded GNPS archive to detect which workflow variant generated it. NPLinker uses a workflow-version-specific mapping table: GNPS1 workflows (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING) and GNPS2 workflows (classical_networking_workflow, feature_based_molecular_networking_workflow) each produce distinctly named intermediate files. Once identified, instantiate the appropriate GNPSExtractor with the archive path and target gnps directory, then invoke extraction to rename workflow-specific files according to the detected version's mapping table. This ensures that renamed outputs (e.g., spectra.mgf, molecular_families.tsv) conform to NPLinker's standardized input interface for subsequent link computation.

Related tools

• NPLinker (Provides GNPSExtractor class and workflow-detection logic to map GNPS archive structure to standardized output file names) — https://github.com/NPLinker/nplinker
• Python (Runtime environment for instantiating GNPSExtractor and executing workflow identification and file extraction)
• GNPS (Source platform that produces the molecular networking archives with version-specific file naming conventions) — https://gnps.ucsd.edu; https://gnps2.org

Examples

from nplinker.genomics import GNPSExtractor; extractor = GNPSExtractor('/path/to/gnps_archive.zip', '/path/to/gnps'); extractor.extract()

Evaluation signals

• Extracted directory contains all four expected standardized files: spectra.mgf, molecular_families.tsv, annotations.tsv, and file_mappings.tsv (or .csv).
• File contents are non-empty and conform to expected schemas (e.g., spectra.mgf is valid MGF format, molecular_families.tsv is a valid tab-delimited table).
• Workflow version detected matches the actual GNPS platform and workflow type used to generate the job (e.g., METABOLOMICS-SNETS-V2 for GNPS1 feature-based networking).
• Renamed files are accessible to downstream NPLinker modules (e.g., load_data() succeeds without file-not-found errors).
• File mapping table correctly reconciles original workflow-specific filenames to standardized output names without data loss or truncation.

Limitations

• NPLinker currently supports only GNPS1 (gnps.ucsd.edu) and GNPS2 (gnps2.org) platforms; other GNPS instances or custom networking tools are not supported.
• Workflow detection relies on archive structure conventions; non-standard or manually edited GNPS archives may fail to identify correctly.
• The mapping table is static and may require updates if GNPS adds new workflow types or changes internal file naming schemes.
• File extraction assumes Unix-compatible file paths; Windows path handling or special characters in filenames may introduce platform-specific issues.

Evidence

• [other] Extract GNPS data to gnps directory, enabling access to molecular networking results for subsequent computational analysis.: "Extract GNPS data to gnps directory, enabling access to molecular networking results for subsequent computational analysis."
• [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 (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1; classical_networking_workflow or feature_based_molecular_networking_workflow for GNPS2).: "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"
• [other] NPLinker requires GNPS molecular networking data as input.: "NPLinker requires GNPS molecular networking data as input"
• [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"