HolobiomicsLab 
strain-spectrum-mapping-linkage
Summary
Load and validate strain-to-spectrum file mappings from GNPS archive data to establish the linkage between microbial strains and their corresponding mass spectrometry records. This is a prerequisite step for integrating genomics and metabolomics data in natural product discovery workflows.
When to use
When you have downloaded and extracted a GNPS archive (from GNPS1 or GNPS2 workflows) and need to establish which spectral records (from spectra.mgf) were generated from which bacterial strains or samples. The file_mappings.tsv or file_mappings.csv file in the archive provides this critical linkage and must be loaded before computing strain-to-metabolite links.
When NOT to use
- GNPS data has not yet been downloaded and extracted to a directory
- The GNPS workflow version is unknown or not specified (cannot determine appropriate schema)
- file_mappings.tsv or file_mappings.csv is missing or corrupted in the archive
Inputs
- GNPS archive (downloaded and extracted)
- file_mappings.tsv or file_mappings.csv from GNPS output
- Previously loaded Spectrum objects (for cross-reference validation)
Outputs
- Strain-to-spectrum mapping records
- Validated file mapping structure with no missing required fields
How to apply
Initialize a GNPSFormat object from the extracted GNPS archive by calling gnps_format_from_archive() or gnps_format_from_file_mapping(), specifying the correct GNPS workflow version (METABOLOMICS-SNETS, METABOLOMICS-SNETS-V2, or FEATURE-BASED-MOLECULAR-NETWORKING for GNPS1; classical_networking_workflow or feature_based_molecular_networking_workflow for GNPS2). Then use GNPSFileMappingLoader with the file_mappings.tsv or file_mappings.csv file to produce strain-to-spectrum mapping records. Validate that all loaded records contain no missing required fields and that cross-references are consistent between the mapping records and the previously loaded Spectrum objects from spectra.mgf.
Related tools
- nplinker (Provides GNPSFileMappingLoader class and helper functions (gnps_format_from_archive, gnps_format_from_file_mapping) to load and validate strain-spectrum mappings from GNPS archives) — https://github.com/NPLinker/nplinker
- GNPS (Generates the file_mappings.tsv/csv output file that maps sample/strain identifiers to spectral records) — https://gnps.ucsd.edu, https://gnps2.org
- Python (Language in which nplinker and the GNPSFileMappingLoader are implemented (requires ≥3.11))
Examples
from nplinker import GNPSFormat, GNPSFileMappingLoader; gnps_fmt = GNPSFormat.gnps_format_from_archive('path/to/extracted/gnps', workflow_version='METABOLOMICS-SNETS-V2'); loader = GNPSFileMappingLoader(gnps_fmt); mappings = loader.load('path/to/file_mappings.tsv')
Evaluation signals
- All records loaded from file_mappings.tsv/csv have no missing required fields (strain identifier, spectrum identifier, or equivalent)
- Cross-references between mapping records and Spectrum objects are consistent (every mapped spectrum ID corresponds to a loaded Spectrum)
- No duplicate strain-spectrum pairs exist in the loaded mapping
- Validation step completes without errors or warnings when called on the loaded mapping records
- The number of loaded mapping records matches the expected number of strain-spectrum pairs in the GNPS archive
Limitations
- File format (TSV vs. CSV) must match the GNPS workflow version used; incorrect format selection will cause parsing failures
- Validation depends on prior successful loading of spectra.mgf via GNPSSpectrumLoader; incomplete or corrupted spectral data will cause cross-reference validation to fail
- The mapping file structure differs between GNPS1 and GNPS2 workflows; GNPSFormat object must be initialized with the correct workflow version to parse correctly
Evidence
- [other] Load file mappings using GNPSFileMappingLoader with file_mappings.tsv (or .csv) to produce strain-to-spectrum mapping records.: "Load file mappings using GNPSFileMappingLoader with file_mappings.tsv (or .csv) to produce strain-to-spectrum mapping records"
- [other] Initialize GNPSFormat object from an extracted or downloaded GNPS archive using gnps_format_from_archive() or gnps_format_from_file_mapping() helper functions, specifying the GNPS workflow version: "Initialize GNPSFormat object from an extracted or downloaded GNPS archive using gnps_format_from_archive() or gnps_format_from_file_mapping() helper functions, specifying the GNPS workflow version"
- [other] Validate all loaded records for completeness (no missing required fields, consistent cross-references between spectra and families and annotations).: "Validate all loaded records for completeness (no missing required fields, consistent cross-references between spectra and families and annotations)"
- [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"