Gnps Workflow Identifier Retrieval

---
name: gnps-workflow-identifier-retrieval
description: Use when when you have a GNPS molecular networking task ID and need to
  fetch the job archive, decompose it into standard metabolomics file formats (spectra.mgf,
  molecular_families.tsv, annotations.tsv, file_mappings), and prepare them for integration
  with genomics data.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3791
  edam_topics:
  - http://edamontology.org/topic_0625
  - http://edamontology.org/topic_3172
  tools:
  - nplinker
  - Python
  - GNPSDownloader
  - GNPSExtractor
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1186/s40168-022-01444-3
  title: NPClassScore
evidence_spans:
- It provides the tools [`GNPSDownloader`][nplinker.metabolomics.gnps.GNPSDownloader]
  and [`GNPSExtractor`][nplinker.metabolomics.gnps.GNPSExtractor]
- '[![github repo badge](https://img.shields.io/badge/github-nplinker-000.svg?color=blue)](https://github.com/NPLinker/nplinker)'
- Python version ≥3.11
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_npclassscore_cq
    doi: 10.1186/s40168-022-01444-3
    title: NPClassScore
  dedup_kept_from: coll_npclassscore_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1186/s40168-022-01444-3
  all_source_dois:
  - 10.1186/s40168-022-01444-3
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# gnps-workflow-identifier-retrieval

## Summary

Retrieve and validate GNPS molecular networking job archives by task ID, then extract and standardize constituent files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings) for downstream metabolomics data integration. This skill bridges GNPS data repositories (GNPS1 and GNPS2) into NPLinker's local processing pipeline.

## When to use

When you have a GNPS molecular networking task ID and need to fetch the job archive, decompose it into standard metabolomics file formats (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings), and prepare them for integration with genomics data. Specifically when the workflow type is one of METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING (GNPS1) or classical_networking_workflow, feature_based_molecular_networking_workflow (GNPS2).

## When NOT to use

- GNPS data has already been downloaded and extracted into standardized NPLinker file formats
- You do not have a valid GNPS task ID or the task corresponds to a non-metabolomics GNPS workflow
- The GNPS job was generated by a workflow type not supported by NPLinker (e.g., custom or third-party networking)

## Inputs

- GNPS task ID (string)
- local downloads directory path (string)
- target gnps output directory path (string)

## Outputs

- spectra.mgf (mass spectrometry spectral data)
- molecular_families.tsv (molecular networking cluster assignments)
- annotations.tsv (chemical annotations)
- file_mappings.tsv or file_mappings.csv (sample-to-spectrum mappings)

## How to apply

Initialize a GNPSDownloader with your GNPS task ID and a local downloads directory path, then call download() to fetch the job archive and retrieve its file path. Next, initialize a GNPSExtractor with the downloaded archive path and target gnps directory, then call the extraction method to decompress the archive and identify data files based on the detected GNPS workflow type (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1, or classical_networking_workflow, feature_based_molecular_networking_workflow for GNPS2). Rename and move extracted files to standardized NPLinker names in the gnps directory. Verify all four required files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv or file_mappings.csv) are present, accessible, and correctly named before proceeding to data loading.

## Related tools

- **GNPSDownloader** (Fetches GNPS molecular networking job archive from GNPS repository by task ID and returns local file path) — https://github.com/NPLinker/nplinker
- **GNPSExtractor** (Decompresses GNPS job archive and identifies constituent data files based on workflow type detection) — https://github.com/NPLinker/nplinker
- **nplinker** (Python framework that orchestrates GNPS data retrieval and integration with genomics data) — https://github.com/NPLinker/nplinker

## Examples

```
from nplinker.gnps import GNPSDownloader, GNPSExtractor; dl = GNPSDownloader('task_001', './downloads'); archive_path = dl.download(); ex = GNPSExtractor(archive_path, './gnps'); ex.extract()
```

## Evaluation signals

- All four required output files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv/.csv) exist in the target gnps directory with correct naming
- spectra.mgf contains valid MGF-format mass spectrometry data with m/z and intensity values
- molecular_families.tsv contains valid TSV entries mapping spectra to GCF (Gene Cluster Family) cluster IDs
- file_mappings.tsv/.csv correctly links sample/file names to spectrum identifiers
- No extraction errors or file corruption detected during decompression and format validation

## Limitations

- Only supports GNPS1 (https://gnps.ucsd.edu) and GNPS2 (https://gnps2.org) data; custom or forked GNPS instances may not be recognized
- Workflow type detection is workflow-name dependent; unsupported workflow types will cause extraction to fail
- Network connectivity required for GNPSDownloader to reach GNPS repository; offline or air-gapped systems cannot retrieve archives
- File naming and structure within GNPS archives may vary across workflow versions, potentially requiring updates to extraction logic

## Evidence

- [other] first, GNPSDownloader fetches a GNPS molecular networking job archive and returns its file path; second, GNPSExtractor extracts the archive contents into a designated `gnps` directory for subsequent data loading operations: "first, GNPSDownloader fetches a GNPS molecular networking job archive and returns its file path; second, GNPSExtractor extracts the archive contents into a designated `gnps` directory for subsequent"
- [other] METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1, or classical_networking_workflow, feature_based_molecular_networking_workflow for GNPS2: "METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1, or classical_networking_workflow, feature_based_molecular_networking_workflow for GNPS2"
- [other] Rename and move the extracted files to the standard NPLinker names (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv or file_mappings.csv) in the gnps directory: "Rename and move the extracted files to the standard NPLinker names (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv or file_mappings.csv) in the gnps directory"
- [other] Verify that all four required files are present and accessible in the gnps directory with correct naming and format: "Verify that all four required files are present and accessible in the gnps directory with correct naming and format"
- [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"