Archive Extraction And File Mapping

archive-extraction-and-file-mapping

Summary

Decompose a GNPS molecular networking job archive into constituent metabolomics data files (spectra, molecular families, annotations, file mappings) and standardize their naming for downstream NPLinker processing. This skill bridges raw GNPS output archives to the normalized file structure required by integrated genomics–metabolomics analysis.

When to use

When you have downloaded a GNPS molecular networking job archive (from GNPS1 or GNPS2 workflows: METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING, classical_networking_workflow, or feature_based_molecular_networking_workflow) and need to extract and standardize its contents into spectra.mgf, molecular_families.tsv, annotations.tsv, and file_mappings files for NPLinker's load_data() workflow.

When NOT to use

• Input is not a GNPS molecular networking job archive (e.g., raw LC–MS files, pre-extracted file set, or output from a different networking platform).
• The GNPS archive is from an unsupported workflow type or version not recognized by the GNPSExtractor.
• The target gnps directory already contains partially extracted or corrupted files; extraction should be performed on a clean directory.

Inputs

• GNPS job archive file (compressed, e.g., .zip or .tar.gz)
• GNPS workflow type identifier (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1; classical_networking_workflow, feature_based_molecular_networking_workflow for GNPS2)
• Target gnps directory path (may be created if not present)

Outputs

• spectra.mgf file (mass spectrometry spectral data)
• molecular_families.tsv file (molecular networking clusters)
• annotations.tsv file (compound/feature annotations)
• file_mappings.tsv or file_mappings.csv file (sample–spectrum associations)
• gnps directory containing all four standardized files

How to apply

Initialize a GNPSExtractor with the local path to the downloaded archive and a target gnps directory. Call the extraction method, which decompresses the archive and identifies relevant data files based on the workflow type. The extractor then renames and relocates the extracted files to NPLinker's standard names: spectra.mgf (mass spectrometry data), molecular_families.tsv (networking clusters), annotations.tsv (compound annotations), and file_mappings.tsv or file_mappings.csv (sample-to-spectrum mappings). Verify all four required files are present in the gnps directory with correct naming and accessible format before proceeding to load_data(). This normalization ensures compatibility with subsequent genomics integration steps.

Related tools

• GNPSDownloader (Fetches the GNPS molecular networking job archive from GNPS servers and returns the local file path; prerequisite to extraction.) — https://github.com/NPLinker/nplinker
• GNPSExtractor (Core extraction tool that decompresses the archive, identifies files by GNPS workflow type, and renames them to NPLinker standard names.) — https://github.com/NPLinker/nplinker
• nplinker (Python framework that integrates the extraction step into the broader genomics–metabolomics data mining pipeline; exposes load_data() method to read standardized files.) — https://github.com/NPLinker/nplinker

Examples

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

Evaluation signals

• All four required files (spectra.mgf, molecular_families.tsv, annotations.tsv, file_mappings.tsv or .csv) are present in the gnps directory.
• File names exactly match NPLinker's standard naming scheme (no residual workflow-specific prefixes or extensions).
• spectra.mgf is a valid MGF format file containing MS/MS spectral records with m/z and intensity pairs.
• molecular_families.tsv and annotations.tsv contain tab-separated data with expected column headers (e.g., cluster_id, compound name, adduct).
• file_mappings contains all sample–spectrum associations without gaps; subsequent npl.load_data() executes without file-not-found errors.

Limitations

• Extraction success depends on the GNPS archive conforming to one of the supported workflow types; archives from custom or deprecated GNPS workflows may fail silently or produce incomplete extraction.
• The extractor requires sufficient disk space to decompress large archives; no streaming or incremental extraction is available.
• File naming standardization assumes GNPS workflows follow standard output conventions; manual post-extraction checks are recommended before downstream analysis to catch workflow-specific deviations.

Evidence

• [other] The workflow operates in two sequential steps: 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.: "GNPSDownloader fetches a GNPS molecular networking job archive and returns its file path; second, GNPSExtractor extracts the archive contents into a designated gnps directory"
• [other] Initialize a GNPSExtractor with the downloaded archive path and the target gnps directory path, then call the extraction method to decompress the archive and identify the relevant data files based on the 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).: "Initialize a GNPSExtractor with the downloaded archive path and the target gnps directory path, then call the extraction method to decompress the archive and identify the relevant data files based on"
• [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)"
• [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] NPLinker currently accepts data from both GNPS1 (https://gnps.ucsd.edu) and GNPS2 (https://gnps2.org) workflows: "NPLinker currently accepts data from both GNPS1 and GNPS2 workflows"