# Gnps Workflow Identification

> Use when 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.

- Skill: `holobiomicslab/gnps-workflow-identification` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/gnps-workflow-identification`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/gnps-workflow-identification/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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"