# Usi String Parsing And Resolution

> Use when you have a USI string referencing a spectrum in an online public repository (PRIDE, MassIVE, etc.) and need to load its raw spectral data without downloading the entire dataset file.

- Skill: `holobiomicslab/usi-string-parsing-and-resolution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/usi-string-parsing-and-resolution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/usi-string-parsing-and-resolution/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/usi-string-parsing-and-resolution

---


# usi-string-parsing-and-resolution

## Summary

Parse and resolve Universal Spectrum Identifier (USI) strings to retrieve raw MS/MS spectrum data (m/z array, intensity array, precursor m/z, charge state, retention time) from online proteomics and metabolomics repositories (PRIDE, MassIVE). This skill bridges USI string syntax to live spectrum objects suitable for downstream processing and annotation.

## When to use

You have a USI string referencing a spectrum in an online public repository (PRIDE, MassIVE, etc.) and need to load its raw spectral data without downloading the entire dataset file. Common scenarios: comparing spectra across repositories, rapid spectrum retrieval for annotation workflows, or integrating live data into interactive analysis notebooks.

## When NOT to use

- USI string points to a private or access-restricted repository without valid authentication credentials.
- Spectrum data is already available locally in mzML or other standard file format; use local file parsing instead.
- Network connectivity is unavailable or the online repository endpoint is down.

## Inputs

- USI string (e.g., 'mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555')
- Internet connectivity to online proteomics repository

## Outputs

- MsmsSpectrum object with populated attributes: title, precursor_mz, charge, mz array, intensity array, retention_time

## How to apply

Parse the USI string to extract the repository accession (e.g., 'mzspec:PXD000561'), dataset/file identifier, and scan number using spectrum_utils' built-in USI resolver. Query the online proteomics resource's USI endpoint to retrieve the resolved spectrum data, including m/z array, intensity array, precursor m/z, charge state, and retention time. Instantiate an MsmsSpectrum object by passing these resolved attributes to the MsmsSpectrum constructor. Verify that all spectral attributes (title, precursor m/z, charge, arrays, retention time) are populated and accessible before proceeding to downstream processing chains such as noise removal, intensity scaling, or fragment annotation.

## Related tools

- **spectrum_utils** (Provides USI resolver, MsmsSpectrum class, and endpoint integration for parsing USI strings and loading spectra from online repositories.) — https://github.com/bittremieux/spectrum_utils
- **Python** (Programming language for executing USI parsing and spectrum object instantiation.)

## Examples

```
from spectrum_utils.spectrum import MsmsSpectrum; from spectrum_utils.resolvers import resolve_usi; usi = "mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555"; spectrum = resolve_usi(usi)
```

## Evaluation signals

- MsmsSpectrum object is successfully instantiated with non-null title, precursor_mz, charge, mz array, and intensity array.
- m/z and intensity arrays have matching length and contain only numeric values within physically plausible ranges (m/z > 0, intensity ≥ 0).
- Precursor m/z, charge state, and retention time are consistent with the USI repository metadata.
- Subsequent spectrum processing operations (e.g., set_mz_range, remove_precursor_peak, filter_intensity) execute without AttributeError or data validation failures.
- USI string parsing completes without network timeout or HTTP 404 errors from the repository endpoint.

## Limitations

- USI resolution depends on continuous availability and correct implementation of the online repository's USI endpoint; transient network or API changes may cause failures.
- Only supports repositories that implement the PSI-DEV USI standard; proprietary or non-standard repository formats are not supported.
- Large-scale batch USI resolution may be rate-limited by repository servers; no built-in batching or caching is mentioned in the article.
- Spectrum data retrieved via USI is read-only; local modifications to the MsmsSpectrum object do not persist back to the repository.

## Evidence

- [intro] spectrum_utils implements 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] Parse the USI string and extract repository/file/scan identifiers, then retrieve spectrum data via the USI endpoint, then construct an MsmsSpectrum object.: "Parse the USI string to extract repository accession, file/dataset identifier, and scan number using spectrum_utils' USI resolver. 2. Retrieve the raw spectrum data (m/z array, intensity array,"
- [other] Concrete USI examples from the article's workflow and datasets.: "usi = "mzspec:PXD000561:Adult_Frontalcortex_bRP_Elite_85_f09:scan:17555""
- [intro] spectrum_utils is a Python package for efficient mass spectrometry data processing and visualization.: "spectrum_utils is a Python package for efficient mass spectrometry data processing and visualization."
- [other] Return the populated MsmsSpectrum object with all spectral attributes accessible for subsequent processing chains.: "Return the populated MsmsSpectrum object with all spectral attributes accessible for subsequent processing chains."