USI Class Reference

Utility class for handling Universal Spectrum Identifiers (USI). More...

#include <OpenMS/METADATA/USI.h>

Public Types
enum class	IndexType { SCAN , INDEX , NATIVEID }
	Supported index types in USI. More...

Public Member Functions
Constructors and Destructor
	USI ()
	Default constructor (creates an empty/invalid USI)
	USI (const std::string &collection, const std::string &ms_run, IndexType index_type, const std::string &index, const std::string &interpretation="")
	Construct a USI from its components.
	USI (const std::string &usi_string)
	Construct a USI from its string representation.
	USI (const USI &)=default
	Copy constructor.
	USI (USI &&) noexcept=default
	Move constructor.
	~USI ()=default
	Destructor.
Assignment operators
USI &	operator= (const USI &)=default
	Copy assignment operator.
USI &	operator= (USI &&) noexcept=default
	Move assignment operator.
Comparison operators
bool	operator== (const USI &rhs) const
	Equality operator.
bool	operator!= (const USI &rhs) const
	Inequality operator.
bool	operator< (const USI &rhs) const
	Less-than operator (for sorting/containers)
Accessors
const std::string &	getCollection () const
	Returns the collection (dataset identifier or library name)
void	setCollection (const std::string &collection)
	Sets the collection (dataset identifier or library name)
const std::string &	getMSRun () const
	Returns the MS run file name.
void	setMSRun (const std::string &ms_run)
	Sets the MS run file name.
IndexType	getIndexType () const
	Returns the index type.
void	setIndexType (IndexType index_type)
	Sets the index type.
const std::string &	getIndex () const
	Returns the spectrum index as a string.
void	setIndex (const std::string &index)
	Sets the spectrum index.
const std::string &	getInterpretation () const
	Returns the interpretation (peptide sequence/charge)
void	setInterpretation (const std::string &interpretation)
	Sets the interpretation (peptide sequence/charge)
bool	hasInterpretation () const
	Returns true if an interpretation is present.
std::string conversion
std::string	toString () const
	Converts the USI to its string representation.
bool	fromString (const std::string &usi_string)
	Parse a USI string and populate this object.

Static Public Member Functions
Static utility methods
static USI	createFromScanNumber (const std::string &dataset_id, const std::string &filename, int scan_number, const std::string &interpretation="")
	Create a USI from spectrum metadata.
static USI	createFromNativeID (const std::string &dataset_id, const std::string &filename, const std::string &native_id)
	Create a USI from a native spectrum identifier.
static std::optional< int >	extractScanNumberFromNativeID (const std::string &native_id)
	Extract scan number from a native spectrum ID for USI generation.
static std::optional< std::pair< IndexType, std::string > >	nativeIdToUSIIndex (const std::string &native_id)
	Convert a native spectrum ID to USI index type and value per the PSI USI spec.
static std::string	indexTypeToString (IndexType index_type)
	Get the index type string representation.
static IndexType	indexTypeFromString (const std::string &type_string)
	Parse index type from string.
static std::string	extractBasename (const std::string &filepath)
	Extract basename from a file path (removes directory and extension).

CV term information
std::string	collection_
	Dataset identifier or library name.
std::string	ms_run_
	MS run file name.
IndexType	index_type_
	Type of spectrum index.
std::string	index_
	Spectrum index value.
std::string	interpretation_
	Optional peptide interpretation.
static const std::string	USI_PREFIX
	Prefix for all USIs.
static const std::string	CV_ACCESSION
	CV accession for USI.
static const std::string	CV_NAME
	CV name for USI.
static const std::string &	getCVAccession ()
	Returns the PSI-MS CV accession for USI (MS:1003063)
static const std::string &	getCVName ()
	Returns the PSI-MS CV name for USI.

Validity checking
bool	isValid () const
	Check if this USI is valid (has all required components).
static bool	isValidUSI (const std::string &usi_string)
	Check if a string is a valid USI format.
static std::optional< USI >	tryParse (const std::string &usi_string)
	Try to parse a USI string (non-throwing).

Detailed Description

Utility class for handling Universal Spectrum Identifiers (USI).

The Universal Spectrum Identifier (USI) is a standardized identifier format defined by the HUPO-PSI (Human Proteome Organization - Proteomics Standards Initiative) for uniquely referencing mass spectrometry spectra across public repositories. The USI format enables unambiguous identification of spectra in ProteomeXchange partner repositories (PRIDE, PeptideAtlas, MassIVE, jPOST, iProX) and spectral libraries.

USI Format

The general format of a USI is:

mzspec:<collection>:<ms_run>:<index_type>:<index>[:interpretation]

Where:

• collection: ProteomeXchange dataset identifier (e.g., PXD000561) or spectral library name
• ms_run: Name of the MS run file (e.g., sample1.mzML)
• index_type: Type of spectrum index, typically "scan" or "index"
• index: Numeric identifier of the spectrum
• interpretation: Optional peptide interpretation in ProForma format (sequence/charge)

Examples

• Basic spectrum reference: mzspec:PXD000561:Adult_Frontalcortex.mzML:scan:12345
• With peptide interpretation: mzspec:PXD000561:Adult_Frontalcortex.mzML:scan:12345:PEPTIDEK/2
• With modification: mzspec:PXD000561:sample.mzML:scan:1234:PEPT[Phospho]IDEK/2

PSI-MS CV Term

USI is defined in the PSI-MS ontology as MS:1003063 (universal spectrum identifier).

See also

SpectrumLookup, SpectrumSettings, PeptideIdentification

https://www.psidev.info/usi (USI specification)

Member Enumeration Documentation

IndexType

enum class IndexType

strong

Supported index types in USI.

Enumerator
SCAN	scan number (most common)
INDEX	zero-based spectrum index
NATIVEID	native spectrum identifier from the instrument

Constructor & Destructor Documentation

USI() [1/5]

USI

(

)

Default constructor (creates an empty/invalid USI)

USI() [2/5]

USI	(	const std::string &	collection,
		const std::string &	ms_run,
		IndexType	index_type,
		const std::string &	index,
		const std::string &	interpretation = ""
	)

Construct a USI from its components.

Parameters

collection	ProteomeXchange dataset identifier or spectral library name
ms_run	Name of the MS run file
index_type	Type of spectrum index (scan, index, or nativeId)
index	Numeric identifier of the spectrum
interpretation	Optional peptide interpretation (sequence/charge)

USI() [3/5]

USI ( const std::string &  usi_string )

explicit

Construct a USI from its string representation.

Parameters

usi_string

Complete USI string to parse

Exceptions

Exception::ParseError

if the USI string is malformed

USI() [4/5]

USI ( const USI &  )

default

Copy constructor.

USI() [5/5]

USI ( USI &&  )

defaultnoexcept

Move constructor.

~USI()

~USI ( )

default

Destructor.

Member Function Documentation

createFromNativeID()

static USI createFromNativeID ( const std::string &  dataset_id, const std::string &  filename, const std::string &  native_id  )

static

Create a USI from a native spectrum identifier.

Parameters

dataset_id	ProteomeXchange dataset identifier
filename	MS file name
native_id	Native spectrum identifier from the instrument

Returns

Constructed USI object

createFromScanNumber()

static USI createFromScanNumber ( const std::string &  dataset_id, const std::string &  filename, int  scan_number, const std::string &  interpretation = ""  )

static

Create a USI from spectrum metadata.

This is a convenience method for creating a USI from commonly available spectrum information.

Parameters

dataset_id	ProteomeXchange dataset identifier (e.g., "PXD000561")
filename	MS file name (e.g., "sample.mzML")
scan_number	Scan number
interpretation	Optional ProForma interpretation (e.g., "PEPTIDEK/2")

Returns

Constructed USI object

extractBasename()

static std::string extractBasename ( const std::string &  filepath )

static

Extract basename from a file path (removes directory and extension).

Converts full file paths to MS run root names for USI (PSI USI spec section 3.3.4: the msRun is "the root name of a .RAW file or .mzML file"). Example: "/path/to/sample.mzML" -> "sample" Example: "file:///C:/data/sample.raw" -> "sample"

Parameters

filepath

Full file path or URI

Returns

Root name without path or extension

extractScanNumberFromNativeID()

static std::optional< int > extractScanNumberFromNativeID ( const std::string &  native_id )

static

Extract scan number from a native spectrum ID for USI generation.

Only returns a scan number when the native ID format unambiguously identifies a scan number suitable for the USI scan: index type (PSI USI spec section 3.3.5):

• Thermo standard: controllerType=0 controllerNumber=1 scan=X → X
• Bare scan=X (Bruker/Agilent simple format) → X

Non-standard Thermo (controllerType != 0), Waters, Bruker TDF, SCIEX WIFF, and index-based native IDs return std::nullopt — callers should use nativeIdToUSIIndex() for the full USI-spec-compliant mapping.

Parameters

native_id

Native spectrum identifier

Returns

Scan number if this is a standard scan format, std::nullopt otherwise

fromString()

bool fromString

(

const std::string &

usi_string

)

Parse a USI string and populate this object.

Parameters

usi_string

USI string to parse

Returns

True if parsing succeeded, false otherwise

getCollection()

const std::string & getCollection

(

)

const

Returns the collection (dataset identifier or library name)

getCVAccession()

static const std::string & getCVAccession ( )

static

Returns the PSI-MS CV accession for USI (MS:1003063)

getCVName()

static const std::string & getCVName ( )

static

Returns the PSI-MS CV name for USI.

getIndex()

const std::string & getIndex

(

)

const

Returns the spectrum index as a string.

getIndexType()

IndexType getIndexType

(

)

const

Returns the index type.

getInterpretation()

const std::string & getInterpretation

(

)

const

Returns the interpretation (peptide sequence/charge)

getMSRun()

const std::string & getMSRun

(

)

const

Returns the MS run file name.

hasInterpretation()

bool hasInterpretation

(

)

const

Returns true if an interpretation is present.

indexTypeFromString()

static IndexType indexTypeFromString ( const std::string &  type_string )

static

Parse index type from string.

Parameters

type_string

std::string representation of index type

Returns

Index type enum value

Exceptions

Exception::InvalidValue

if the string is not a valid index type

indexTypeToString()

static std::string indexTypeToString ( IndexType  index_type )

static

Get the index type string representation.

Parameters

index_type

Index type enum value

Returns

std::string representation ("scan", "index", or "nativeId")

isValid()

bool isValid

(

)

const

Check if this USI is valid (has all required components).

A valid USI must have non-empty collection, ms_run, and index fields.

Returns

True if the USI is valid, false otherwise

isValidUSI()

static bool isValidUSI ( const std::string &  usi_string )

static

Check if a string is a valid USI format.

Validates that the string follows the USI specification format.

Parameters

usi_string

std::string to validate

Returns

True if the string is a valid USI, false otherwise

nativeIdToUSIIndex()

static std::optional< std::pair< IndexType, std::string > > nativeIdToUSIIndex ( const std::string &  native_id )

static

Convert a native spectrum ID to USI index type and value per the PSI USI spec.

Maps vendor native ID formats to the correct USI index representation:

• controllerType=0 controllerNumber=1 scan=X → (SCAN, "X")
• scan=X (bare, no other prefix) → (SCAN, "X")
• index=X → (INDEX, "X")
• controllerType=5 controllerNumber=1 scan=7 → (NATIVEID, "5,1,7")
• frame=120 scan=475 → (NATIVEID, "120,475")
• frame=120 scan=475 precursor=2 → (NATIVEID, "120,475,2") (OpenMS DDA extension)
• function=10 process=1 scan=345 → (NATIVEID, "10,1,345")
• sample=1 period=1 cycle=2740 experiment=10 → (NATIVEID, "1,1,2740,10")

Parameters

native_id

Native spectrum identifier

Returns

Pair of (IndexType, index string), or nullopt if native_id is empty

operator!=()

bool operator!=

(

const USI &

rhs

)

const

Inequality operator.

operator<()

bool operator<

(

const USI &

rhs

)

const

Less-than operator (for sorting/containers)

operator=() [1/2]

USI & operator= ( const USI &  )

default

Copy assignment operator.

operator=() [2/2]

USI & operator= ( USI &&  )

defaultnoexcept

Move assignment operator.

operator==()

bool operator==

(

const USI &

rhs

)

const

Equality operator.

setCollection()

void setCollection

(

const std::string &

collection

)

Sets the collection (dataset identifier or library name)

setIndex()

void setIndex

(

const std::string &

index

)

Sets the spectrum index.

setIndexType()

void setIndexType

(

IndexType

index_type

)

Sets the index type.

setInterpretation()

void setInterpretation

(

const std::string &

interpretation

)

Sets the interpretation (peptide sequence/charge)

setMSRun()

void setMSRun

(

const std::string &

ms_run

)

Sets the MS run file name.

toString()

std::string toString

(

)

const

Converts the USI to its string representation.

Returns

Complete USI string

tryParse()

static std::optional< USI > tryParse ( const std::string &  usi_string )

static

Try to parse a USI string (non-throwing).

This is the preferred method when you want to validate and use a USI in a single operation, avoiding double-parsing.

Parameters

usi_string

std::string to parse

Returns

Parsed USI if valid, std::nullopt otherwise

// Prefer this pattern:
if (auto usi = USI::tryParse(str)) {
  use(*usi);
}
// Over this (which parses twice):
if (USI::isValidUSI(str)) {
  USI usi(str);
  use(usi);
}

Member Data Documentation

collection_

std::string collection_

protected

Dataset identifier or library name.

CV_ACCESSION

const std::string CV_ACCESSION

staticprotected

CV accession for USI.

CV_NAME

const std::string CV_NAME

staticprotected

CV name for USI.

index_

std::string index_

protected

Spectrum index value.

index_type_

IndexType index_type_

protected

Type of spectrum index.

interpretation_

std::string interpretation_

protected

Optional peptide interpretation.

ms_run_

std::string ms_run_

protected

MS run file name.

USI_PREFIX

const std::string USI_PREFIX

staticprotected

Prefix for all USIs.