USI-based spectrum retrieval and loading
Summary
Load mass spectrometry spectra from public proteomics and metabolomics repositories using Universal Spectrum Identifiers (USI), enabling direct programmatic access to published data without manual download. This skill bridges online data discovery and local analysis by parsing USI accessions and instantiating spectrum objects ready for downstream processing and visualization.
When to use
You have a USI accession (e.g., 'mzspec:MSV000082283:f07074:scan:5475' or 'mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555') pointing to a publicly deposited tandem mass spectrometry scan in a GNPS or ProteomeXchange repository, and you need to retrieve and instantiate that spectrum programmatically for annotation, processing, or visualization without downloading raw files locally.
When NOT to use
- Input is a local raw file (mzML, mzXML, mgf); use file-based loading methods instead (e.g., spectrum_utils.io.mgf_file() or pymzML).
- Network connectivity is unavailable or unreliable; pre-download spectra locally or use offline formats.
- The data is from a private or restricted-access repository not indexed by GNPS or ProteomeXchange; USI mechanism requires public metadata registration.
Inputs
- USI accession string (e.g., 'mzspec:MSV000082283:f07074:scan:5475')
- Network connectivity to public mass spectrometry data repositories (GNPS, MassIVE, ProteomeXchange)
Outputs
- MsmsSpectrum object with populated m/z array, intensity array, precursor m/z, precursor charge, and scan metadata
How to apply
Call the MsmsSpectrum.from_usi() method with the USI string as the sole argument; this queries the remote repository index (GNPS, MassIVE, or ProteomeXchange) via HTTP, retrieves the scan metadata and peak list, and returns a spectrum object with m/z and intensity arrays. The USI parsing is handled transparently by spectrum_utils, which maps the repository prefix (MSV, PXD) and scan identifier to the corresponding data service endpoint. Verify successful retrieval by inspecting the returned spectrum's precursor m/z, charge state, and peak count; empty or malformed spectra indicate network failure or invalid USI format. This approach is preferred when you need reproducibility (USI is a persistent identifier) and want to avoid storing large raw mzML or mzXML files locally.
Related tools
- spectrum_utils (Provides MsmsSpectrum.from_usi() method for USI-based retrieval and instantiation; handles USI parsing, repository endpoint mapping, and spectrum object construction) — https://github.com/bittremieuxlab/spectrum_utils
- GNPS public library (Public repository indexed by USI that hosts mass spectrometry spectra and library matches)
- ProteomeXchange (PXD datasets) (Repository system (MassIVE, PRIDE, jPOST) that provides persistent access to submitted proteomics datasets via USI identifiers)
Examples
from spectrum_utils.spectrum import MsmsSpectrum; spectrum = MsmsSpectrum.from_usi('mzspec:MSV000082283:f07074:scan:5475')
Evaluation signals
- Returned MsmsSpectrum object is not None and contains non-empty m/z and intensity arrays
- Precursor m/z, charge state, and scan identifier match the expected values from the USI accession metadata
- Peak count and intensity distribution are consistent with the original repository record (spot-check against online viewer if available)
- Subsequent processing steps (e.g., annotation, filtering) execute without errors on the retrieved spectrum
- HTTP request to the repository endpoint succeeds (200 status) and completes within a reasonable timeout (e.g., <10 seconds per spectrum)
Limitations
- Requires network connectivity; cannot be used offline or in restricted-network environments.
- Dependent on remote repository availability and uptime; spectra may become temporarily or permanently unavailable if the repository is down or the dataset is retracted.
- USI resolution relies on correct repository indexing; newly uploaded datasets may have a lag before USI resolution succeeds.
- Large-scale batch retrieval of many spectra via USI may be rate-limited by the remote service; consider caching or batching requests.
- No changelog found in the spectrum_utils repository, limiting ability to track breaking changes in USI parsing or API mappings.
Evidence
- [intro] Spectrum loading from online proteomics and metabolomics data resources using the Universal Spectrum Identifier (USI) mechanism.: "Spectrum loading from online proteomics and metabolomics data resources using the Universal Spectrum Identifier (USI) mechanism."
- [other] Example USI accession for a public spectrum: "usi = "mzspec:MSV000082283:f07074:scan:5475""
- [other] Method signature and usage: "Retrieve the spectrum from an online proteomics data resource using MsmsSpectrum.from_usi() with the provided USI accession."
- [other] Supported datasets from multiple repositories: "usi = "mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555""
1---2name: usi-spectrum-retrieval-and-loading-23description: Use when you have a USI accession (e.g., 'mzspec:MSV000082283:f07074:scan:5475' or 'mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555') pointing to a publicly deposited tandem mass spectrometry scan in a GNPS or ProteomeXchange repository, and you need to retrieve and instantiate.4license: CC-BY-4.05metadata:6 edam_operation: http://edamontology.org/operation_24097 edam_topics:8 - http://edamontology.org/topic_01219 - http://edamontology.org/topic_352010 tools:11 - spectrum_utils12 - Python13 - matplotlib14 - GNPS public library15 - ProteomeXchange (PXD datasets)16derived_from:17- doi: 10.1021/acs.analchem.9b0488418 title: spectrumutils19evidence_spans:20- spectrum_utils is a Python package for efficient mass spectrometry data processing and visualization.21- fragment ions can be annotated based on the [ProForma 2.0](https://www.psidev.info/proforma) specification22- spectrum_utils is a Python package23- spectrum = sus.MsmsSpectrum.from_usi(usi)24- import matplotlib.pyplot as plt25- fig, ax = plt.subplots(figsize=(12, 6))26claims: []27provenance:28 collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v129 assembled_by: scripts/collect_metabolomics_collection.py30 sources:31 - build: coll_spectrumutils32 doi: 10.1021/acs.analchem.9b0488433 title: spectrumutils34 dedup_kept_from: coll_spectrumutils35schema_version: 0.2.036---3738# USI-based spectrum retrieval and loading3940## Summary4142Load mass spectrometry spectra from public proteomics and metabolomics repositories using Universal Spectrum Identifiers (USI), enabling direct programmatic access to published data without manual download. This skill bridges online data discovery and local analysis by parsing USI accessions and instantiating spectrum objects ready for downstream processing and visualization.4344## When to use4546You have a USI accession (e.g., 'mzspec:MSV000082283:f07074:scan:5475' or 'mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555') pointing to a publicly deposited tandem mass spectrometry scan in a GNPS or ProteomeXchange repository, and you need to retrieve and instantiate that spectrum programmatically for annotation, processing, or visualization without downloading raw files locally.4748## When NOT to use4950- Input is a local raw file (mzML, mzXML, mgf); use file-based loading methods instead (e.g., spectrum_utils.io.mgf_file() or pymzML).51- Network connectivity is unavailable or unreliable; pre-download spectra locally or use offline formats.52- The data is from a private or restricted-access repository not indexed by GNPS or ProteomeXchange; USI mechanism requires public metadata registration.5354## Inputs5556- USI accession string (e.g., 'mzspec:MSV000082283:f07074:scan:5475')57- Network connectivity to public mass spectrometry data repositories (GNPS, MassIVE, ProteomeXchange)5859## Outputs6061- MsmsSpectrum object with populated m/z array, intensity array, precursor m/z, precursor charge, and scan metadata6263## How to apply6465Call the MsmsSpectrum.from_usi() method with the USI string as the sole argument; this queries the remote repository index (GNPS, MassIVE, or ProteomeXchange) via HTTP, retrieves the scan metadata and peak list, and returns a spectrum object with m/z and intensity arrays. The USI parsing is handled transparently by spectrum_utils, which maps the repository prefix (MSV, PXD) and scan identifier to the corresponding data service endpoint. Verify successful retrieval by inspecting the returned spectrum's precursor m/z, charge state, and peak count; empty or malformed spectra indicate network failure or invalid USI format. This approach is preferred when you need reproducibility (USI is a persistent identifier) and want to avoid storing large raw mzML or mzXML files locally.6667## Related tools6869- **spectrum_utils** (Provides MsmsSpectrum.from_usi() method for USI-based retrieval and instantiation; handles USI parsing, repository endpoint mapping, and spectrum object construction) — https://github.com/bittremieuxlab/spectrum_utils70- **GNPS public library** (Public repository indexed by USI that hosts mass spectrometry spectra and library matches)71- **ProteomeXchange (PXD datasets)** (Repository system (MassIVE, PRIDE, jPOST) that provides persistent access to submitted proteomics datasets via USI identifiers)7273## Examples7475```76from spectrum_utils.spectrum import MsmsSpectrum; spectrum = MsmsSpectrum.from_usi('mzspec:MSV000082283:f07074:scan:5475')77```7879## Evaluation signals8081- Returned MsmsSpectrum object is not None and contains non-empty m/z and intensity arrays82- Precursor m/z, charge state, and scan identifier match the expected values from the USI accession metadata83- Peak count and intensity distribution are consistent with the original repository record (spot-check against online viewer if available)84- Subsequent processing steps (e.g., annotation, filtering) execute without errors on the retrieved spectrum85- HTTP request to the repository endpoint succeeds (200 status) and completes within a reasonable timeout (e.g., <10 seconds per spectrum)8687## Limitations8889- Requires network connectivity; cannot be used offline or in restricted-network environments.90- Dependent on remote repository availability and uptime; spectra may become temporarily or permanently unavailable if the repository is down or the dataset is retracted.91- USI resolution relies on correct repository indexing; newly uploaded datasets may have a lag before USI resolution succeeds.92- Large-scale batch retrieval of many spectra via USI may be rate-limited by the remote service; consider caching or batching requests.93- No changelog found in the spectrum_utils repository, limiting ability to track breaking changes in USI parsing or API mappings.9495## Evidence9697- [intro] Spectrum loading from online proteomics and metabolomics data resources using the Universal Spectrum Identifier (USI) mechanism.: "Spectrum loading from online proteomics and metabolomics data resources using the Universal Spectrum Identifier (USI) mechanism."98- [other] Example USI accession for a public spectrum: "usi = "mzspec:MSV000082283:f07074:scan:5475""99- [other] Method signature and usage: "Retrieve the spectrum from an online proteomics data resource using MsmsSpectrum.from_usi() with the provided USI accession."100- [other] Supported datasets from multiple repositories: "usi = "mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555""
HolobiomicsLab 