# Spectral Data Standardization

> Use when you have completed a GNPS1 (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING) or GNPS2 (classical_networking_workflow, feature_based_molecular_networking_workflow) molecular networking job and need to access its output files in a standardized format for.

- Skill: `holobiomicslab/spectral-data-standardization` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/spectral-data-standardization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/spectral-data-standardization/raw
- Safety review: PASS (external: skill-scanner WARNING, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/spectral-data-standardization

---


# spectral-data-standardization

## Summary

Retrieve and extract molecular networking job results from GNPS workflows to obtain standardized spectral data files (spectra.mgf, molecular_families.tsv, annotations.tsv) needed for downstream natural products mining. This skill bridges GNPS output heterogeneity across workflow versions by identifying and renaming files according to detected workflow type.

## When to use

You have completed a GNPS1 (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING) or GNPS2 (classical_networking_workflow, feature_based_molecular_networking_workflow) molecular networking job and need to access its output files in a standardized format for integration with downstream tools like NPLinker. You possess a GNPS task ID and need a reproducible way to download and extract the compressed results archive.

## When NOT to use

- Your GNPS job has not yet completed or returned an error state; wait for job completion and check the GNPS interface before attempting download.
- You already possess locally extracted and properly named GNPS output files in your working directory; skip directly to data loading and link computation.
- You are working with metabolomics data from a non-GNPS source (e.g., raw LC-MS/MS spectra, vendor software outputs, or alternative networking platforms); this skill is GNPS-specific.

## Inputs

- GNPS task ID (string identifier for a completed GNPS job)
- download directory path (filesystem path for archive storage)
- target gnps directory path (filesystem location for extracted files)

## Outputs

- spectra.mgf (standardized mass spectrometry data file)
- molecular_families.tsv (standardized molecular networking results)
- annotations.tsv (standardized spectral annotations)
- file_mappings.tsv or file_mappings.csv (standardized file mapping table)

## How to apply

First, instantiate a GNPSDownloader with your GNPS task ID and a target download directory path, then invoke its download() method to retrieve the compressed archive from GNPS servers and capture the returned archive file path. Second, instantiate a GNPSExtractor with the downloaded archive path and a target gnps directory path, then invoke extraction which automatically detects the GNPS workflow version from the archive structure and renames the workflow-specific output files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv or .csv) according to an internal mapping table. This two-step process eliminates manual file hunting and version-specific renaming logic, ensuring consistent input for molecular networking analysis.

## Related tools

- **nplinker** (Python framework providing GNPSDownloader and GNPSExtractor classes for automated GNPS data retrieval and standardization) — https://github.com/NPLinker/nplinker
- **GNPS** (Global Natural Products Social molecular networking platform generating the job results being downloaded and extracted) — https://gnps.ucsd.edu

## Examples

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

## Evaluation signals

- Archive file path returned by download() method points to a valid .zip file that is readable and not truncated (file size > 1 MB typical for networking results).
- Extraction completes without error and produces all four expected standardized output files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv/.csv) in the target gnps directory.
- Output file headers and row counts match expectations for the detected GNPS workflow version (e.g., spectra.mgf contains valid MS/MS scan blocks, molecular_families.tsv contains cluster ID and member columns).
- Downstream tools (e.g., npl.load_data()) successfully ingest the extracted files without file-not-found or schema mismatch errors.
- Workflow version detected by GNPSExtractor matches the known workflow used to generate the GNPS job (verifiable via GNPS web interface or job metadata).

## Limitations

- GNPSExtractor supports only GNPS1 (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING) and GNPS2 (classical_networking_workflow, feature_based_molecular_networking_workflow) workflow outputs; other GNPS workflow types are not handled.
- Download success depends on network connectivity and GNPS server availability; transient network failures will cause the download() method to fail.
- File extraction is version-sensitive: if GNPS introduces new workflow types or renames output files without updating the internal GNPSExtractor mapping table, extraction will fail or produce incorrectly named outputs.

## 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 (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1; classical_networking_workflow or feature_based_molecular_networking_workflow for GNPS2).: "Instantiate GNPSExtractor with the downloaded archive path and target gnps directory path, then invoke extraction to identify and rename the workflow-specific files"
- [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"
- [other] NPLinker requires GNPS molecular networking data as input: "NPLinker requires GNPS molecular networking data as input"