Helper class for looking up spectrum meta data. More...

#include <OpenMS/METADATA/SpectrumMetaDataLookup.h>

Inheritance diagram for SpectrumMetaDataLookup:

Collaboration diagram for SpectrumMetaDataLookup:

Classes
struct	SpectrumMetaData
	Meta data of a spectrum. More...

Public Types
typedef unsigned char	MetaDataFlags
	Bit mask for which meta data to extract from a spectrum. More...

Public Member Functions
	SpectrumMetaDataLookup ()
	Constructor. More...

	~SpectrumMetaDataLookup () override
	Destructor. More...

template<typename SpectrumContainer >
void	readSpectra (const SpectrumContainer &spectra, const String &scan_regexp=default_scan_regexp, bool get_precursor_rt=false)
	Read spectra and store their meta data. More...

void	setSpectraDataRef (const String &spectra_data)
	set spectra_data from read SpectrumContainer origin (i.e. filename) More...

void	getSpectrumMetaData (Size index, SpectrumMetaData &meta) const
	Look up meta data of a spectrum. More...

void	getSpectrumMetaData (const String &spectrum_ref, SpectrumMetaData &meta, MetaDataFlags flags=MDF_ALL) const
	Extract meta data via a spectrum reference. More...

Public Member Functions inherited from SpectrumLookup
	SpectrumLookup ()
	Constructor. More...

virtual	~SpectrumLookup ()
	Destructor. More...

bool	empty () const
	Check if any spectra were set. More...

template<typename SpectrumContainer >
void	readSpectra (const SpectrumContainer &spectra, const String &scan_regexp=default_scan_regexp)
	Read and index spectra for later look-up. More...

Size	findByRT (double rt) const
	Look up spectrum by retention time (RT). More...

Size	findByNativeID (const String &native_id) const
	Look up spectrum by native ID. More...

Size	findByIndex (Size index, bool count_from_one=false) const
	Look up spectrum by index (position in the vector of spectra). More...

Size	findByScanNumber (Size scan_number) const
	Look up spectrum by scan number (extracted from the native ID). More...

Size	findByReference (const String &spectrum_ref) const
	Look up spectrum by reference. More...

void	addReferenceFormat (const String &regexp)
	Register a possible format for a spectrum reference. More...

Static Public Member Functions
static void	getSpectrumMetaData (const MSSpectrum &spectrum, SpectrumMetaData &meta, const boost::regex &scan_regexp=boost::regex(), const std::map< Size, double > &precursor_rts=(std::map< Size, double >()))
	Extract meta data from a spectrum. More...

static bool	addMissingRTsToPeptideIDs (std::vector< PeptideIdentification > &peptides, const String &filename, bool stop_on_error=false)
	Add missing retention time values to peptide identifications based on raw data. More...

static bool	addMissingSpectrumReferences (std::vector< PeptideIdentification > &peptides, const String &filename, bool stop_on_error=false, bool override_spectra_data=false, bool override_spectra_references=false, std::vector< ProteinIdentification > proteins=std::vector< ProteinIdentification >())
	Add missing "spectrum_reference"s to peptide identifications based on raw data. More...

Static Public Member Functions inherited from SpectrumLookup
static Int	extractScanNumber (const String &native_id, const boost::regex &scan_regexp, bool no_error=false)
	Extract the scan number from the native ID of a spectrum. More...

static Int	extractScanNumber (const String &native_id, const String &native_id_type_accession)

Static Public Attributes
static const MetaDataFlags	MDF_RT = 1

static const MetaDataFlags	MDF_PRECURSORRT = 2

static const MetaDataFlags	MDF_PRECURSORMZ = 4

static const MetaDataFlags	MDF_PRECURSORCHARGE = 8

static const MetaDataFlags	MDF_MSLEVEL = 16

static const MetaDataFlags	MDF_SCANNUMBER = 32

static const MetaDataFlags	MDF_NATIVEID = 64

static const MetaDataFlags	MDF_ALL = 127

Static Public Attributes inherited from SpectrumLookup
static const String &	default_scan_regexp
	Default regular expression for extracting scan numbers from spectrum native IDs. More...

Protected Attributes
std::vector< SpectrumMetaData >	metadata_
	Meta data for spectra. More...

String	spectra_data_ref

Protected Attributes inherited from SpectrumLookup
Size	n_spectra_
	Number of spectra. More...

boost::regex	scan_regexp_
	Regular expression to extract scan numbers. More...

std::vector< String >	regexp_name_list_
	Named groups in vector format. More...

std::map< double, Size >	rts_
	Mapping: RT -> spectrum index. More...

std::map< String, Size >	ids_
	Mapping: native ID -> spectrum index. More...

std::map< Size, Size >	scans_
	Mapping: scan number -> spectrum index. More...

Private Member Functions
	SpectrumMetaDataLookup (const SpectrumMetaDataLookup &)
	Copy constructor (not implemented) More...

SpectrumMetaDataLookup &	operator= (const SpectrumMetaDataLookup &)
	Assignment operator (not implemented) More...

Additional Inherited Members
Public Attributes inherited from SpectrumLookup
std::vector< boost::regex >	reference_formats
	Possible formats of spectrum references, defined as regular expressions. More...

double	rt_tolerance
	Tolerance for look-up by retention time. More...

Protected Member Functions inherited from SpectrumLookup
void	addEntry_ (Size index, double rt, Int scan_number, const String &native_id)
	Add a look-up entry for a spectrum. More...

Size	findByRegExpMatch_ (const String &spectrum_ref, const String &regexp, const boost::smatch &match) const
	Look up spectrum by regular expression match. More...

void	setScanRegExp_ (const String &scan_regexp)
	Set the regular expression for extracting scan numbers from spectrum native IDs. More...

Static Protected Attributes inherited from SpectrumLookup
static const String &	regexp_names_
	Named groups recognized in regular expression. More...

Detailed Description

Helper class for looking up spectrum meta data.

The class deals with meta data of spectra and provides functions for the extraction and look-up of this data.

A common use case for this functionality is importing peptide/protein identification results from search engine-specific file formats, where some meta information may have to be looked up in the raw data (primarily retention times). One example of this is in the function addMissingRTsToPeptideIDs().

Meta data of a spectra is stored in SpectrumMetaDataLookup::SpectrumMetaData structures. In order to control which meta data to extract/look-up, flags (SpectrumMetaDataLookup::MetaDataFlags) are used. Meta data can be extracted from spectra or from spectrum reference strings. The format of a spectrum reference is defined via a regular expression containing named groups (format "(?<GROUP>...)" for the different data items. The table below illustrates the different meta data types and how they are represented.

`SpectrumMetaData` member	`MetaDataFlags` flag	Reg. exp. group	Comment (*: undefined for MS1 spectra)
`rt`	`MDF_RT`	`RT`	Retention time of the spectrum
`precursor_rt`	`MDF_PRECURSORRT`	`PRECRT`	Retention time of the precursor spectrum*
`precursor_mz`	`MDF_PRECURSORMZ`	`MZ`	Mass-to-charge ratio of the precursor ion*
`precursor_charge`	`MDF_PRECURSORCHARGE`	`CHARGE`	Charge of the precursor ion*
`ms_level`	`MDF_MSLEVEL`	`LEVEL`	MS level (1 for survey scan, 2 for fragment scan, etc.)
`scan_number`	`MDF_SCANNUMBER`	`SCAN`	Scan number (extracted from the native ID)
`native_id`	`MDF_NATIVEID`	`ID`	Native ID of the spectrum
	`MDF_ALL`		Shortcut for "all flags set"
		`INDEX0`	Only for look-up: index (vector pos.) counting from 0
		`INDEX1`	Only for look-up: index (vector pos.) counting from 1

See also: OpenMS::SpectrumLookup

Member Typedef Documentation

◆ MetaDataFlags

typedef unsigned char MetaDataFlags

Bit mask for which meta data to extract from a spectrum.

Constructor & Destructor Documentation

◆ SpectrumMetaDataLookup() [1/2]

SpectrumMetaDataLookup ( )

inline

Constructor.

◆ ~SpectrumMetaDataLookup()

~SpectrumMetaDataLookup ( )

inlineoverride

Destructor.

◆ SpectrumMetaDataLookup() [2/2]

SpectrumMetaDataLookup ( const SpectrumMetaDataLookup & )

private

Copy constructor (not implemented)

Member Function Documentation

◆ addMissingRTsToPeptideIDs()

static bool addMissingRTsToPeptideIDs	(	std::vector< PeptideIdentification > &	peptides,
		const String &	filename,
		bool	stop_on_error = `false`
	)

static

Add missing retention time values to peptide identifications based on raw data.

Parameters

peptides	Peptide IDs with or without RT values
filename	Name of a raw data file (e.g. mzML) for looking up RTs
stop_on_error	Stop when an ID could not be matched to a spectrum (or keep going)?

Returns: True if all peptide IDs could be annotated successfully (including if all already had RT values), false otherwise.

Look-up works by matching the "spectrum_reference" (meta value) of a peptide ID to the native ID of a spectrum. Only peptide IDs without RT (where PeptideIdentification::getRT() returns "NaN") are looked up; the RT is set to that of the corresponding spectrum.

◆ addMissingSpectrumReferences()

static bool addMissingSpectrumReferences	(	std::vector< PeptideIdentification > &	peptides,
		const String &	filename,
		bool	stop_on_error = `false`,
		bool	override_spectra_data = `false`,
		bool	override_spectra_references = `false`,
		std::vector< ProteinIdentification >	proteins = `std::vector< ProteinIdentification >()`
	)

static

Add missing "spectrum_reference"s to peptide identifications based on raw data.

Parameters

peptides	Peptide IDs with or without spectrum_reference
filename	the name of the mz_file from which to draw spectrum_references
stop_on_error	Stop when an ID could not be matched to a spectrum (or keep going)?
override_spectra_data	if given ProteinIdentifications should be updated with new "spectra_data" values from SpectrumMetaDataLookup
override_spectra_references	if given PeptideIdentifications with existing spectrum_reference should be updated from SpectrumMetaDataLookup
proteins	Protein IDs corresponding to the Peptide IDs

Returns: True if all peptide IDs could be annotated successfully (including if all already had "spectrum_reference" values), false otherwise.

Look-up works by matching RT of a peptide identification with the given spectra. Matched spectra 'native ID' will be annotated to the identification. All spectrum_references are updated/added.

◆ getSpectrumMetaData() [1/3]

static void getSpectrumMetaData	(	const MSSpectrum &	spectrum,
		SpectrumMetaData &	meta,
		const boost::regex &	scan_regexp = `boost::regex()`,
		const std::map< Size, double > &	precursor_rts = `(std::map< Size, double >())`
	)

static

Extract meta data from a spectrum.

Parameters

spectrum	Spectrum input
meta	Meta data output
scan_regexp	Regular expression for extracting scan number from spectrum native ID
precursor_rts	RTs of potential precursor spectra of different MS levels

Scan number and precursor RT, respectively, are only extracted if scan_regexp/precursor_rts are not empty.

◆ getSpectrumMetaData() [2/3]

void getSpectrumMetaData	(	const String &	spectrum_ref,
		SpectrumMetaData &	meta,
		MetaDataFlags	flags = `MDF_ALL`
	)		const

Extract meta data via a spectrum reference.

Parameters

spectrum_ref	Spectrum reference to parse
metadata	Meta data output
flags	What meta data to extract

Exceptions

Exception::ElementNotFound if a spectrum look-up was necessary, but no matching spectrum was found

This function is a combination of getSpectrumMetaData() and SpectrumLookup::findByReference(). However, the spectrum is only looked up if necessary, i.e. if the required meta data - as defined by flags - cannot be extracted from the spectrum reference itself.

◆ getSpectrumMetaData() [3/3]

void getSpectrumMetaData	(	Size	index,
		SpectrumMetaData &	meta
	)		const

Look up meta data of a spectrum.

Parameters

index	Index of the spectrum
meta	Meta data output

◆ operator=()

SpectrumMetaDataLookup& operator= ( const SpectrumMetaDataLookup & )

private

Assignment operator (not implemented)

◆ readSpectra()

void readSpectra	(	const SpectrumContainer &	spectra,
		const String &	scan_regexp = `default_scan_regexp`,
		bool	get_precursor_rt = `false`
	)

inline

Read spectra and store their meta data.

Parameters

SpectrumContainer	Spectrum container class, must support `size` and `operator`[]
spectra	Container of spectra
scan_regexp	Regular expression for matching scan numbers in spectrum native IDs (must contain the named group "?<SCAN>")
get_precursor_rt	Assign precursor retention times? (This relies on all precursor spectra being present and in the right order.)

Exceptions

Exception::IllegalArgument if scan_regexp does not contain "?<SCAN>" (and is not empty)

References SpectrumMetaDataLookup::SpectrumMetaData::ms_level, SpectrumMetaDataLookup::SpectrumMetaData::native_id, SpectrumMetaDataLookup::SpectrumMetaData::rt, and SpectrumMetaDataLookup::SpectrumMetaData::scan_number.

◆ setSpectraDataRef()

void setSpectraDataRef ( const String & spectra_data )

inline

set spectra_data from read SpectrumContainer origin (i.e. filename)

Parameters

spectra_data the name (and path) of the origin of the read SpectrumContainer

Member Data Documentation

◆ MDF_ALL

const MetaDataFlags MDF_ALL = 127

static

◆ MDF_MSLEVEL

const MetaDataFlags MDF_MSLEVEL = 16

static

◆ MDF_NATIVEID

const MetaDataFlags MDF_NATIVEID = 64

static

◆ MDF_PRECURSORCHARGE

const MetaDataFlags MDF_PRECURSORCHARGE = 8

static

◆ MDF_PRECURSORMZ

const MetaDataFlags MDF_PRECURSORMZ = 4

static

◆ MDF_PRECURSORRT

const MetaDataFlags MDF_PRECURSORRT = 2

static

◆ MDF_RT

const MetaDataFlags MDF_RT = 1

static

Possible meta data to extract from a spectrum. Note that the static variables need to be put on separate lines due to a compiler bug in VS

◆ MDF_SCANNUMBER

const MetaDataFlags MDF_SCANNUMBER = 32

static

◆ metadata_

std::vector<SpectrumMetaData> metadata_

protected

Meta data for spectra.

◆ spectra_data_ref

String spectra_data_ref

protected

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Attributes

Private Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ MetaDataFlags

Constructor & Destructor Documentation

◆ SpectrumMetaDataLookup() [1/2]

◆ ~SpectrumMetaDataLookup()

◆ SpectrumMetaDataLookup() [2/2]

Member Function Documentation

◆ addMissingRTsToPeptideIDs()

◆ addMissingSpectrumReferences()

◆ getSpectrumMetaData() [1/3]

◆ getSpectrumMetaData() [2/3]

◆ getSpectrumMetaData() [3/3]

◆ operator=()

◆ readSpectra()

◆ setSpectraDataRef()

Member Data Documentation

◆ MDF_ALL

◆ MDF_MSLEVEL

◆ MDF_NATIVEID

◆ MDF_PRECURSORCHARGE

◆ MDF_PRECURSORMZ

◆ MDF_PRECURSORRT

◆ MDF_RT

◆ MDF_SCANNUMBER

◆ metadata_

◆ spectra_data_ref