Strain spectrum mapping linkage

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"