| OpenMS 2.5.0

Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Protected Attributes | Static Protected Attributes | Private Member Functions | List of all members
SpectrumLookup Class Reference

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

`#include <OpenMS/METADATA/SpectrumLookup.h>`

Inheritance 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_

static protected

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.