Helper class for looking up spectra based on different attributes. More...

#include <OpenMS/METADATA/SpectrumLookup.h>

Inheritance diagram for SpectrumLookup:

Collaboration diagram for SpectrumLookup:

Public Member Functions
	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 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)

Public Attributes
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...

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

Protected Member Functions
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...

Protected Attributes
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...

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

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

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

Detailed Description

Helper class for looking up spectra based on different attributes.

This class provides functions for looking up spectra that are stored in a vector (e.g. MSExperiment::getSpectra()) by index, retention time, native ID, scan number (extracted from the native ID), or by a reference string containing any of the previous information ("spectrum reference").

Spectrum reference formats

Formats for spectrum references are defined by regular expressions, that must contain certain fields (named groups, i.e. "(?<GROUP>...)") referring to usable information. The following named groups are recognized and can be used to look up spectra:

INDEX0: spectrum index, i.e. position in the vector of spectra, counting from zero
INDEX1: spectrum index, i.e. position in the vector of spectra, counting from one
ID: spectrum native ID
SCAN: scan number (extracted from the native ID)
RT: retention time

: For example, if the format of a spectrum reference is "scan=123", where 123 is the scan number, the expression "scan=(?<SCAN>\\d+)" can be used to extract that number, allowing look-up of the corresponding spectrum.

: Reference formats are registered via addReferenceFormat(). Several possible formats can be added and will be tried in order by the function findByReference().

See also: SpectrumMetaDataLookup

Constructor & Destructor Documentation

◆ SpectrumLookup() [1/2]

SpectrumLookup ( )

Constructor.

◆ ~SpectrumLookup()

virtual ~SpectrumLookup ( )

virtual

Destructor.

◆ SpectrumLookup() [2/2]

SpectrumLookup ( const SpectrumLookup & )

private

Copy constructor (not implemented)

Member Function Documentation

◆ addEntry_()

void addEntry_	(	Size	index,
		double	rt,
		Int	scan_number,
		const String &	native_id
	)

protected

Add a look-up entry for a spectrum.

Parameters

index	Spectrum index (position in the vector)
rt	Retention time
scan_number	Scan number
native_id	Native ID

◆ addReferenceFormat()

void addReferenceFormat ( const String & regexp )

Register a possible format for a spectrum reference.

Parameters

regexp Regular expression defining the format

Exceptions

Exception::IllegalArgument if regexp does not contain any of the recognized named groups

The regular expression defining the reference format must contain one or more of the recognized named groups defined in SpectrumLookup::regexp_names_.

◆ empty()

bool empty ( ) const

Check if any spectra were set.

◆ extractScanNumber() [1/2]

static Int extractScanNumber	(	const String &	native_id,
		const boost::regex &	scan_regexp,
		bool	no_error = `false`
	)

static

Extract the scan number from the native ID of a spectrum.

Parameters

native_id	Spectrum native ID
scan_regexp	Regular expression to use (must contain the named group "?<SCAN>")
no_error	Suppress the exception on failure

Exceptions

Exception::ParseError if the scan number could not be extracted (unless no_error is set)

Returns: Scan number of the spectrum (or -1 on failure to extract)

◆ extractScanNumber() [2/2]

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

static

◆ findByIndex()

Size findByIndex	(	Size	index,
		bool	count_from_one = `false`
	)		const

Look up spectrum by index (position in the vector of spectra).

Parameters

index	Index to look up
count_from_one	Do indexes start counting at one (default: zero)?

Exceptions

Exception::ElementNotFound if no matching spectrum was found

Returns: Index of the spectrum that matched

◆ findByNativeID()

Size findByNativeID ( const String & native_id ) const

Look up spectrum by native ID.

Parameters

native_id Native ID to look up

Exceptions

Exception::ElementNotFound if no matching spectrum was found

Returns: Index of the spectrum that matched

◆ findByReference()

Size findByReference ( const String & spectrum_ref ) const

Look up spectrum by reference.

Parameters

spectrum_ref Spectrum reference to parse

Exceptions

Exception::ElementNotFound	if no matching spectrum was found
Exception::ParseError	if the reference could not be parsed (no reference format matched)

Returns: Index of the spectrum that matched

The regular expressions in SpectrumLookup::reference_formats are matched against the spectrum reference in order. The first one that matches is used to look up the spectrum.

◆ findByRegExpMatch_()

Size findByRegExpMatch_	(	const String &	spectrum_ref,
		const String &	regexp,
		const boost::smatch &	match
	)		const

protected

Look up spectrum by regular expression match.

Parameters

spectrum_ref	Spectrum reference that was parsed
regexp	Regular expression used for parsing
match	Regular expression match

Exceptions

Exception::ElementNotFound if no matching spectrum was found

Returns: Index of the spectrum that matched

◆ findByRT()

Size findByRT ( double rt ) const

Look up spectrum by retention time (RT).

Parameters

rt	Retention time to look up

Exceptions

Exception::ElementNotFound if no matching spectrum was found

Returns: Index of the spectrum that matched

There is a tolerance for matching of RT values defined by SpectrumLookup::rt_tolerance. The spectrum with the closest match within that tolerance is returned (if any).

◆ findByScanNumber()

Size findByScanNumber ( Size scan_number ) const

Look up spectrum by scan number (extracted from the native ID).

Parameters

scan_number Scan number to look up

Exceptions

Exception::ElementNotFound if no matching spectrum was found

Returns: Index of the spectrum that matched

◆ operator=()

SpectrumLookup& operator= ( const SpectrumLookup & )

private

Assignment operator (not implemented).

◆ readSpectra()

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

inline

Read and index spectra for later look-up.

Template Parameters

SpectrumContainer Spectrum container class, must support size and operator[]

Parameters

spectra	Container of spectra
scan_regexp	Regular expression for matching scan numbers in spectrum native IDs (must contain the named group "?<SCAN>")

Exceptions

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

Spectra are indexed by retention time, native ID and scan number. In all cases it is expected that the value for each spectrum will be unique. Setting scan_regexp to the empty string ("") disables extraction of scan numbers; look-ups by scan number will fail in that case.

References SpectrumSettings::getNativeID(), MSSpectrum::getRT(), and OPENMS_LOG_WARN.

◆ setScanRegExp_()

void setScanRegExp_ ( const String & scan_regexp )

protected

Set the regular expression for extracting scan numbers from spectrum native IDs.

Parameters

scan_regexp Regular expression to use (must contain the named group "?<SCAN>")

Member Data Documentation

◆ default_scan_regexp

const String& default_scan_regexp

static

Default regular expression for extracting scan numbers from spectrum native IDs.

◆ ids_

std::map<String, Size> ids_

protected

Mapping: native ID -> spectrum index.

◆ n_spectra_

Size n_spectra_

protected

Number of spectra.

◆ reference_formats

std::vector<boost::regex> reference_formats

Possible formats of spectrum references, defined as regular expressions.

◆ regexp_name_list_

std::vector<String> regexp_name_list_

protected

Named groups in vector format.

◆ regexp_names_

const String& regexp_names_

staticprotected

Named groups recognized in regular expression.

◆ rt_tolerance

double rt_tolerance

Tolerance for look-up by retention time.

◆ rts_

std::map<double, Size> rts_

protected

Mapping: RT -> spectrum index.

◆ scan_regexp_

boost::regex scan_regexp_

protected

Regular expression to extract scan numbers.

◆ scans_

std::map<Size, Size> scans_

protected

Mapping: scan number -> spectrum index.

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SpectrumLookup() [1/2]

◆ ~SpectrumLookup()

◆ SpectrumLookup() [2/2]

Member Function Documentation

◆ addEntry_()

◆ addReferenceFormat()

◆ empty()

◆ extractScanNumber() [1/2]

◆ extractScanNumber() [2/2]

◆ findByIndex()

◆ findByNativeID()

◆ findByReference()

◆ findByRegExpMatch_()

◆ findByRT()

◆ findByScanNumber()

◆ operator=()

◆ readSpectra()

◆ setScanRegExp_()

Member Data Documentation

◆ default_scan_regexp

◆ ids_

◆ n_spectra_

◆ reference_formats

◆ regexp_name_list_

◆ regexp_names_

◆ rt_tolerance

◆ rts_

◆ scan_regexp_

◆ scans_