This class filters, annotates, picks, and scores spectra (e.g., taken from a DDA experiment) based on a target list. More...

#include <OpenMS/ANALYSIS/OPENSWATH/TargetedSpectraExtractor.h>

Inheritance diagram for TargetedSpectraExtractor:

[legend]

Collaboration diagram for TargetedSpectraExtractor:

[legend]

Classes
class	BinnedSpectrumComparator

class	Comparator

struct	Match

Public Member Functions
	TargetedSpectraExtractor ()

	~TargetedSpectraExtractor () override=default

void	getDefaultParameters (Param &params) const

void	annotateSpectra (const std::vector< MSSpectrum > &spectra, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &annotated_spectra, FeatureMap &features, bool compute_features=true) const
	Filters and annotates those spectra that could potentially match the transitions of the target list. More...

void	annotateSpectra (const std::vector< MSSpectrum > &spectra, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &annotated_spectra) const
	Filters and annotates those spectra that could potentially match the transitions of the target list. More...

void	pickSpectrum (const MSSpectrum &spectrum, MSSpectrum &picked_spectrum) const
	Picks a spectrum's peaks and saves them in picked_spectrum. More...

void	scoreSpectra (const std::vector< MSSpectrum > &annotated_spectra, const std::vector< MSSpectrum > &picked_spectra, FeatureMap &features, std::vector< MSSpectrum > &scored_spectra, bool compute_features=true) const
	Assigns a score to the spectra given an input and saves them in scored_spectra. More...

void	scoreSpectra (const std::vector< MSSpectrum > &annotated_spectra, const std::vector< MSSpectrum > &picked_spectra, std::vector< MSSpectrum > &scored_spectra) const
	Assigns a score to the spectra given an input and saves them in scored_spectra. More...

void	selectSpectra (const std::vector< MSSpectrum > &scored_spectra, const FeatureMap &features, std::vector< MSSpectrum > &selected_spectra, FeatureMap &selected_features, bool compute_features=true) const
	The method selects the highest scoring spectrum for each possible annotation (i.e., transition name) More...

void	selectSpectra (const std::vector< MSSpectrum > &scored_spectra, std::vector< MSSpectrum > &selected_spectra) const
	The method selects the highest scoring spectrum for each possible annotation (i.e., transition name) More...

void	extractSpectra (const MSExperiment &experiment, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &extracted_spectra, FeatureMap &extracted_features, bool compute_features=true) const
	Combines the functionalities given by all the other methods implemented in this class. More...

void	extractSpectra (const MSExperiment &experiment, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &extracted_spectra) const
	Combines the functionalities given by all the other methods implemented in this class. More...

void	matchSpectrum (const MSSpectrum &input_spectrum, const Comparator &cmp, std::vector< Match > &matches)
	Searches the spectral library for the top scoring candidates that match the input spectrum. More...

void	targetedMatching (const std::vector< MSSpectrum > &spectra, const Comparator &cmp, FeatureMap &features)
	Compares a list of spectra against a spectral library and updates the related features. More...

void	untargetedMatching (const std::vector< MSSpectrum > &spectra, const Comparator &cmp, FeatureMap &features)
	Compares a list of spectra against a spectral library and creates a `FeatureMap` with the relevant information. More...

Public Member Functions inherited from DefaultParamHandler
	DefaultParamHandler (const String &name)
	Constructor with name that is displayed in error messages. More...

	DefaultParamHandler (const DefaultParamHandler &rhs)
	Copy constructor. More...

virtual	~DefaultParamHandler ()
	Destructor. More...

virtual DefaultParamHandler &	operator= (const DefaultParamHandler &rhs)
	Assignment operator. More...

virtual bool	operator== (const DefaultParamHandler &rhs) const
	Equality operator. More...

void	setParameters (const Param &param)
	Sets the parameters. More...

const Param &	getParameters () const
	Non-mutable access to the parameters. More...

const Param &	getDefaults () const
	Non-mutable access to the default parameters. More...

const String &	getName () const
	Non-mutable access to the name. More...

void	setName (const String &name)
	Mutable access to the name. More...

const std::vector< String > &	getSubsections () const
	Non-mutable access to the registered subsections. More...

Protected Member Functions
void	updateMembers_ () override
	Overridden function from DefaultParamHandler to keep members up to date, when a parameter is changed. More...

Protected Member Functions inherited from DefaultParamHandler
void	defaultsToParam_ ()
	Updates the parameters after the defaults have been set in the constructor. More...

Private Attributes
bool	mz_unit_is_Da_

double	rt_window_

double	mz_tolerance_

double	peak_height_min_

double	peak_height_max_

double	fwhm_threshold_

double	tic_weight_

double	fwhm_weight_

double	snr_weight_

double	min_select_score_

bool	use_gauss_

Size	top_matches_to_report_

double	min_match_score_
	Minimum score for a match to be considered valid in `matchSpectrum()`. More...

Additional Inherited Members
Static Public Member Functions inherited from DefaultParamHandler
static void	writeParametersToMetaValues (const Param &write_this, MetaInfoInterface &write_here, const String &prefix="")
	Writes all parameters to meta values. More...

Protected Attributes inherited from DefaultParamHandler
Param	param_
	Container for current parameters. More...

Param	defaults_
	Container for default parameters. This member should be filled in the constructor of derived classes! More...

std::vector< String >	subsections_
	Container for registered subsections. This member should be filled in the constructor of derived classes! More...

String	error_name_
	Name that is displayed in error messages during the parameter checking. More...

bool	check_defaults_
	If this member is set to false no checking if parameters in done;. More...

bool	warn_empty_defaults_
	If this member is set to false no warning is emitted when defaults are empty;. More...

Detailed Description

This class filters, annotates, picks, and scores spectra (e.g., taken from a DDA experiment) based on a target list.

The input experiment is expected to be a standard .mzML file. The input target list is expected to be a standard TraML formatted .csv file.

The class deals with filtering and annotating only those spectra that reflect the characteristics described by the target list. The filtering is done based on the transition_name, PrecursorMz and RetentionTime. The spectra are smoothed and peaks are picked for each spectrum. The spectra are then scored based on total TIC, FWHM and SNR. One spectrum is chosen for each of those transitions for which at least one valid spectrum was found and matched.

The user can decide to use only extractSpectra(), otherwise run the methods in the following order: annotateSpectra() pickSpectrum() (called once for each annotated spectrum) scoreSpectra() selectSpectra()

Constructor & Destructor Documentation

◆ TargetedSpectraExtractor()

TargetedSpectraExtractor ( )

◆ ~TargetedSpectraExtractor()

~TargetedSpectraExtractor ( )

overridedefault

Member Function Documentation

◆ annotateSpectra() [1/2]

void annotateSpectra	(	const std::vector< MSSpectrum > &	spectra,
		const TargetedExperiment &	targeted_exp,
		std::vector< MSSpectrum > &	annotated_spectra
	)		const

Filters and annotates those spectra that could potentially match the transitions of the target list.

The spectra taken into account are those that fall within the precursor RT window and MZ tolerance set by the user through the parameters "rt_window" and "mz_tolerance". Default values are provided for both parameters.

Warning: The picked spectrum could be empty, meaning no peaks were found.

Parameters

[in]	spectra	The spectra to filter
[in]	targeted_exp	The target list
[out]	annotated_spectra	The spectra annotated with the related transition's name

◆ annotateSpectra() [2/2]

void annotateSpectra	(	const std::vector< MSSpectrum > &	spectra,
		const TargetedExperiment &	targeted_exp,
		std::vector< MSSpectrum > &	annotated_spectra,
		FeatureMap &	features,
		bool	compute_features = `true`
	)		const

Filters and annotates those spectra that could potentially match the transitions of the target list.

The spectra taken into account are those that fall within the precursor RT window and MZ tolerance set by the user through the parameters "rt_window" and "mz_tolerance". Default values are provided for both parameters.

Warning: The picked spectrum could be empty, meaning no peaks were found.

Parameters

[in]	spectra	The spectra to filter
[in]	targeted_exp	The target list
[out]	annotated_spectra	The spectra annotated with the related transition's name
[out]	features	A FeatureMap which will contain informations about the name, precursor RT and precursor MZ of the matched transition
[in]	compute_features	If false, `features` will be ignored

◆ extractSpectra() [1/2]

void extractSpectra	(	const MSExperiment &	experiment,
		const TargetedExperiment &	targeted_exp,
		std::vector< MSSpectrum > &	extracted_spectra
	)		const

Combines the functionalities given by all the other methods implemented in this class.

The method expects an experiment and a target list in input, and constructs the extracted spectra. For each transition of the target list, the method tries to find its best spectrum match.

Parameters

[in]	experiment	The input experiment
[in]	targeted_exp	The target list
[out]	extracted_spectra	The spectra related to the transitions

◆ extractSpectra() [2/2]

void extractSpectra	(	const MSExperiment &	experiment,
		const TargetedExperiment &	targeted_exp,
		std::vector< MSSpectrum > &	extracted_spectra,
		FeatureMap &	extracted_features,
		bool	compute_features = `true`
	)		const

Combines the functionalities given by all the other methods implemented in this class.

The method expects an experiment and a target list in input, and constructs the extracted spectra and features. For each transition of the target list, the method tries to find its best spectrum match. A FeatureMap is also filled with informations about the extracted spectra.

Parameters

[in]	experiment	The input experiment
[in]	targeted_exp	The target list
[out]	extracted_spectra	The spectra related to the transitions
[out]	extracted_features	The features related to the output spectra
[in]	compute_features	If false, `extracted_features` will be ignored

◆ getDefaultParameters()

void getDefaultParameters ( Param & params ) const

◆ matchSpectrum()

void matchSpectrum	(	const MSSpectrum &	input_spectrum,
		const Comparator &	cmp,
		std::vector< Match > &	matches
	)

Searches the spectral library for the top scoring candidates that match the input spectrum.

Parameters

[in]	input_spectrum	The input spectrum for which a match is desired
[in]	cmp	The comparator object containing the library and the logic for matching
[out]	matches	A vector of `Match`es, containing the matched spectra and their scores

◆ pickSpectrum()

void pickSpectrum	(	const MSSpectrum &	spectrum,
		MSSpectrum &	picked_spectrum
	)		const

Picks a spectrum's peaks and saves them in picked_spectrum.

The spectrum is first smoothed with a Gaussian filter (default) or using the Savitzky-Golay method. The parameter "use_gauss" handles this choice. The peak picking is executed with PeakPickerHiRes. Custom parameters provided with the prefix "GaussFilter:", "SavitzkyGolayFilter:" and "PeakPickerHiRes:" are taken into account. Peaks are then filtered by their heights and FWHM values. It is possible to set the peaks' limits through the parameters: "peak_height_min", "peak_height_max" and "fwhm_threshold".

Exceptions

Exception::IllegalArgument If `spectrum` is not sorted by position (mz).

Parameters

[in]	spectrum	The input spectrum
[out]	picked_spectrum	A spectrum containing only the picked peaks

◆ scoreSpectra() [1/2]

void scoreSpectra	(	const std::vector< MSSpectrum > &	annotated_spectra,
		const std::vector< MSSpectrum > &	picked_spectra,
		FeatureMap &	features,
		std::vector< MSSpectrum > &	scored_spectra,
		bool	compute_features = `true`
	)		const

Assigns a score to the spectra given an input and saves them in scored_spectra.

Also add the informations to the FeatureMap first constructed in annotateSpectra(). The scores are based on total TIC, SNR and FWHM. It is possible to assign a weight to these parameters using: "tic_weight", "fwhm_weight" and "snr_weight". For each spectrum, the TIC and the SNR are computed on the entire spectrum. The FWHMs are computed only on picked peaks. Both SNR and FWHM are averaged values. The informations are added as FloatDataArray in scored_spectra and as MetaValue in features.

Exceptions

Exception::InvalidSize If `features` and `annotated_spectra` sizes don't match.

Parameters

[in]	annotated_spectra	The annotated spectra to score (for TIC and SNR)
[in]	picked_spectra	The picked peaks found on each of the annotated spectra (for FWHM)
[in,out]	features	The score informations are also added to this FeatureMap. Picked peaks' FWHMs are saved in features' subordinates.
[out]	scored_spectra	The scored spectra. Basically a copy of annotated_spectra with the added score informations
[in]	compute_features	If false, `features` will be ignored

◆ scoreSpectra() [2/2]

void scoreSpectra	(	const std::vector< MSSpectrum > &	annotated_spectra,
		const std::vector< MSSpectrum > &	picked_spectra,
		std::vector< MSSpectrum > &	scored_spectra
	)		const

Assigns a score to the spectra given an input and saves them in scored_spectra.

Also add the informations to the FeatureMap first constructed in annotateSpectra(). The scores are based on total TIC, SNR and FWHM. It is possible to assign a weight to these parameters using: "tic_weight", "fwhm_weight" and "snr_weight". For each spectrum, the TIC and the SNR are computed on the entire spectrum. The FWHMs are computed only on picked peaks. Both SNR and FWHM are averaged values.

Parameters

[in]	annotated_spectra	The annotated spectra to score (for TIC and SNR)
[in]	picked_spectra	The picked peaks found on each of the annotated spectra (for FWHM)
[out]	scored_spectra	The scored spectra. Basically a copy of annotated_spectra with the added score informations

◆ selectSpectra() [1/2]

void selectSpectra	(	const std::vector< MSSpectrum > &	scored_spectra,
		const FeatureMap &	features,
		std::vector< MSSpectrum > &	selected_spectra,
		FeatureMap &	selected_features,
		bool	compute_features = `true`
	)		const

The method selects the highest scoring spectrum for each possible annotation (i.e., transition name)

Exceptions

Exception::InvalidSize If `scored_spectra` and `features` sizes don't match.

Parameters

[in]	scored_spectra	Input annotated and scored spectra
[in]	features	Input features
[out]	selected_spectra	Output selected spectra
[out]	selected_features	Output selected features
[in]	compute_features	If false, `selected_features` will be ignored

◆ selectSpectra() [2/2]

void selectSpectra	(	const std::vector< MSSpectrum > &	scored_spectra,
		std::vector< MSSpectrum > &	selected_spectra
	)		const

The method selects the highest scoring spectrum for each possible annotation (i.e., transition name)

Parameters

[in]	scored_spectra	Input annotated and scored spectra
[out]	selected_spectra	Output selected spectra

◆ targetedMatching()

void targetedMatching	(	const std::vector< MSSpectrum > &	spectra,
		const Comparator &	cmp,
		FeatureMap &	features
	)

Compares a list of spectra against a spectral library and updates the related features.

The metavalues added to each `Feature` within the `FeatureMap` are:

spectral_library_name The name of the match's spectrum found in the library
spectral_library_score The match score [0-1]
spectral_library_comments The comments for the match's spectrum

If a match for a given input spectrum is not found, the metavalues will be assigned a default value:

spectral_library_name and spectral_library_comments: an empty string
spectral_library_score: a value of 0.0

Note: The input `spectra` (and related `features`) are assumed to be the result of `extractSpectra()`, meaning they went (at least) through the process of peak picking.

Parameters

[in]	spectra	The input spectra
[in]	cmp	The `Comparator` object containing the spectral library
	[in/out]	features The `FeatureMap` to be updated with matching info

◆ untargetedMatching()

void untargetedMatching	(	const std::vector< MSSpectrum > &	spectra,
		const Comparator &	cmp,
		FeatureMap &	features
	)

Compares a list of spectra against a spectral library and creates a `FeatureMap` with the relevant information.

The metavalues added to each `Feature` within the `FeatureMap` are:

spectral_library_name The name of the match's spectrum found in the library
spectral_library_score The match score [0-1]
spectral_library_comments The comments for the match's spectrum

If a match for a given input spectrum is not found, the metavalues will be assigned a default value:

spectral_library_name and spectral_library_comments: an empty string
spectral_library_score: a value of 0.0

Note: The input `spectra` (and related `features`) are assumed to be unprocessed, therefore undergoing a process of peak picking during execution of this method.

Parameters

[in]	spectra	The input spectra
[in]	cmp	The `Comparator` object containing the spectral library
[out]	features	The `FeatureMap` to be filled with matching info

◆ updateMembers_()

void updateMembers_ ( )

overrideprotectedvirtual

Overridden function from DefaultParamHandler to keep members up to date, when a parameter is changed.

Reimplemented from DefaultParamHandler.

Member Data Documentation

◆ fwhm_threshold_

double fwhm_threshold_

private

Used in pickSpectrum(), a peak's FWHM needs to be >= fwhm_threshold_ for it to be picked.

◆ fwhm_weight_

double fwhm_weight_

private

FWHM's weight when computing a spectrum's score

◆ min_match_score_

double min_match_score_

private

Minimum score for a match to be considered valid in `matchSpectrum()`.

◆ min_select_score_

double min_select_score_

private

Used in selectSpectra(), after the spectra have been assigned a score. Remained transitions will have at least one spectrum assigned. Each spectrum needs to have a score >= min_select_score_ to be valid, otherwise it gets filtered out.

◆ mz_tolerance_

double mz_tolerance_

private

Precursor MZ tolerance used during the annotation phase. For each transition in the target list, annotateSpectra() looks for the first spectrum whose precursor MZ is close enough (+-mz_tolerance_) to the transition's MZ. Also the spectrum's precursor RT is checked against the transition RT.

◆ mz_unit_is_Da_

bool mz_unit_is_Da_

private

Unit to use for mz_tolerance_ and fwhm_threshold_: true for Da, false for ppm.

◆ peak_height_max_

double peak_height_max_

private

Used in pickSpectrum(), a peak's intensity needs to be <= peak_height_max_ for it to be picked.

◆ peak_height_min_

double peak_height_min_

private

Used in pickSpectrum(), a peak's intensity needs to be >= peak_height_min_ for it to be picked.

◆ rt_window_

double rt_window_

private

Precursor Retention Time window used during the annotation phase. For each transition in the target list, annotateSpectra() looks for the first spectrum whose RT time falls within the RT Window, whose left and right limits are computed at each analyzed spectrum. Also the spectrum's precursor MZ is checked against the transition MZ.

◆ snr_weight_

double snr_weight_

private

SNR's weight when computing a spectrum's score

◆ tic_weight_

double tic_weight_

private

Total TIC's weight when computing a spectrum's score

◆ top_matches_to_report_

Size top_matches_to_report_

private

The number of matches to output from `matchSpectrum()`. These will be the matches of highest scores, sorted in descending order.

◆ use_gauss_

bool use_gauss_

private

Used in pickSpectrum(), it selects which filtering method is used during the smoothing phase. By default the Gauss filter is selected. Set to false for the Savitzky-Golay method.

Classes

Public Member Functions

Protected Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TargetedSpectraExtractor()

◆ ~TargetedSpectraExtractor()

Member Function Documentation

◆ annotateSpectra() [1/2]

◆ annotateSpectra() [2/2]

◆ extractSpectra() [1/2]

◆ extractSpectra() [2/2]

◆ getDefaultParameters()

◆ matchSpectrum()

◆ pickSpectrum()

◆ scoreSpectra() [1/2]

◆ scoreSpectra() [2/2]

◆ selectSpectra() [1/2]

◆ selectSpectra() [2/2]

◆ targetedMatching()

◆ untargetedMatching()

◆ updateMembers_()

Member Data Documentation

◆ fwhm_threshold_

◆ fwhm_weight_

◆ min_match_score_

◆ min_select_score_

◆ mz_tolerance_

◆ mz_unit_is_Da_

◆ peak_height_max_

◆ peak_height_min_

◆ rt_window_

◆ snr_weight_

◆ tic_weight_

◆ top_matches_to_report_

◆ use_gauss_