Method for the assembly of mass traces belonging to the same isotope pattern, i.e., that are compatible in retention times, mass-to-charge ratios, and isotope abundances. More...

#include <OpenMS/FEATUREFINDER/FeatureFindingMetabo.h>

Inheritance diagram for FeatureFindingMetabo:

[legend]

Collaboration diagram for FeatureFindingMetabo:

[legend]

Public Member Functions
	FeatureFindingMetabo ()
	Default constructor.

	~FeatureFindingMetabo () override
	Default destructor.

void	run (std::vector< MassTrace > &input_mtraces, FeatureMap &output_featmap, std::vector< std::vector< OpenMS::MSChromatogram > > &output_chromatograms)
	main method of FeatureFindingMetabo

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

	DefaultParamHandler (const DefaultParamHandler &rhs)
	Copy constructor.

virtual	~DefaultParamHandler ()
	Destructor.

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

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

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

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

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

const std::string &	getName () const
	Non-mutable access to the name.

void	setName (const std::string &name)
	Mutable access to the name.

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

Public Member Functions inherited from ProgressLogger
	ProgressLogger ()
	Constructor.

virtual	~ProgressLogger ()
	Destructor.

	ProgressLogger (const ProgressLogger &other)
	Copy constructor.

ProgressLogger &	operator= (const ProgressLogger &other)
	Assignment Operator.

void	setLogType (LogType type) const
	Sets the progress log that should be used. The default type is NONE!

LogType	getLogType () const
	Returns the type of progress log being used.

void	setLogger (ProgressLoggerImpl *logger)
	Sets the logger to be used for progress logging.

void	startProgress (SignedSize begin, SignedSize end, const std::string &label) const
	Initializes the progress display.

void	setProgress (SignedSize value) const
	Sets the current progress.

void	endProgress (UInt64 bytes_processed=0) const

void	nextProgress () const
	increment progress by 1 (according to range begin-end)

Protected Member Functions
void	updateMembers_ () override
	This method is used to update extra member variables at the end of the setParameters() method.

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

Private Member Functions
std::vector< const Element * >	elementsFromString_ (const std::string &elements_string) const
	parses a string of element symbols into a vector of Elements

Range	getTheoreticIsotopicMassWindow_ (const std::vector< Element const * > &alphabet, int peakOffset) const

double	computeCosineSim_ (const std::vector< double > &vec1, const std::vector< double > &vec2) const
	Computes the cosine similarity between two vectors.

int	isLegalIsotopePattern_ (const FeatureHypothesis &feat_hypo) const
	Compare intensities of feature hypothesis with model.

void	loadIsotopeModel_ (const std::string &)

double	scoreMZ_ (const MassTrace &mt1, const MassTrace &mt2, Size isotopic_position, Size charge, Range isotope_window) const
	Perform mass to charge scoring of two multiple mass traces.

double	scoreMZByExpectedMean_ (Size iso_pos, Size charge, const double diff_mz, double mt_variances) const
	score isotope m/z distance based on the expected m/z distances using C13-C12 or Kenar method

double	scoreMZByExpectedRange_ (Size charge, const double diff_mz, double mt_variances, Range isotope_window) const
	score isotope m/z distance based on an expected isotope window which was calculated from a set of expected elements

double	scoreRT_ (const MassTrace &mt1, const MassTrace &mt2) const
	Perform retention time scoring of two multiple mass traces.

double	computeAveragineSimScore_ (const std::vector< double > &intensities, const double &molecular_weight) const
	Perform intensity scoring using the averagine model (for peptides only)

void	findLocalFeatures_ (const std::vector< const MassTrace * > &candidates, double total_intensity, std::vector< FeatureHypothesis > &output_hypotheses) const
	Identify groupings of mass traces based on a set of reasonable candidates.

Private Attributes
std::unique_ptr< SimpleSVM >	isotope_filt_svm_
	SVM model (wraps LIBSVM) used to filter isotope patterns; loaded via loadIsotopeModel_()

std::vector< double >	svm_feat_centers_

std::vector< double >	svm_feat_scales_

double	local_rt_range_
	parameter stuff

double	local_im_range_

double	local_mz_range_

Size	charge_lower_bound_

Size	charge_upper_bound_

double	chrom_fwhm_

bool	report_summed_ints_

bool	enable_RT_filtering_

double	min_isotope_rt_overlap_

bool	isotope_rt_overlap_use_shorter_

std::string	isotope_filtering_model_

bool	use_smoothed_intensities_

bool	report_smoothed_intensities_

bool	use_mz_scoring_C13_

bool	use_mz_scoring_by_element_range_

bool	report_convex_hulls_

bool	report_chromatograms_

bool	remove_single_traces_

bool	has_im_data_ = false
	whether the input mass traces contain ion mobility data

std::vector< const Element * >	elements_

Additional Inherited Members
Public Types inherited from ProgressLogger
enum	LogType { CMD , GUI , NONE }
	Possible log types. More...

Static Public Member Functions inherited from DefaultParamHandler
static void	writeParametersToMetaValues (const Param &write_this, MetaInfoInterface &write_here, const std::string &key_prefix="")
	Writes all parameters to meta values.

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

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

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

std::string	error_name_
	Name that is displayed in error messages during the parameter checking.

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

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

Protected Attributes inherited from ProgressLogger
LogType	type_

time_t	last_invoke_

ProgressLoggerImpl *	current_logger_

Static Protected Attributes inherited from ProgressLogger
static int	recursion_depth_

Detailed Description

Method for the assembly of mass traces belonging to the same isotope pattern, i.e., that are compatible in retention times, mass-to-charge ratios, and isotope abundances.

In FeatureFindingMetabo, mass traces detected by the MassTraceDetection method and afterwards split into individual chromatographic peaks by the ElutionPeakDetection method are assembled to composite features if they are compatible with respect to RTs, m/z ratios, and isotopic intensities. To this end, feature hypotheses are formulated exhaustively based on the set of mass traces detected within a local RT and m/z region. These feature hypotheses are scored by their similarity to real metabolite isotope patterns. The score is derived from independent models for retention time shifts and m/z differences between isotopic mass traces. Hypotheses with correct or false isotopic abundances are distinguished by a SVM model. Mass traces that could not be assembled or low-intensity metabolites with only a monoisotopic mass trace to observe are left in the resulting FeatureMap as singletons with the undefined charge state of 0.

Reference: Kenar et al., doi: 10.1074/mcp.M113.031278

Parameters of this class are:

Name	Type	Default	Restrictions	Description
local_rt_range	float	10.0		RT range where to look for coeluting mass traces
local_im_range	float	0.02		IM range where to look for coeluting mass traces
local_mz_range	float	6.5		MZ range where to look for isotopic mass traces
charge_lower_bound	int	1		Lowest charge state to consider
charge_upper_bound	int	3		Highest charge state to consider
chrom_fwhm	float	5.0		Expected chromatographic peak width (in seconds).
report_summed_ints	string	false	false, true	Set to true for a feature intensity summed up over all traces rather than using monoisotopic trace intensity alone.
enable_RT_filtering	string	true	false, true	Require sufficient overlap in RT while assembling mass traces. Disable for direct injection data..
isotope_rt_overlap_reference	string	longer	longer, shorter	Reference trace the RT overlap is measured against when scoring two co-eluting mass traces (only used if 'enable_RT_filtering' is enabled): 'longer' measures the overlap against the longer trace (default, historic behavior); 'shorter' measures it against the shorter trace and additionally requires the apex of the longer trace to fall within the RT range of the shorter trace. Since low-intensity isotope traces are usually much shorter than the monoisotopic trace, 'shorter' better groups them (see issue @#4483).
min_isotope_rt_overlap	float	0.7	min: 0.0 max: 1.0	Minimum fraction of the reference trace (see 'isotope_rt_overlap_reference') in RT (within FWHM) that must overlap the other trace so the two are scored as isotopes. Only used if 'enable_RT_filtering' is enabled.
isotope_filtering_model	string	metabolites (5% RMS)	metabolites (2% RMS), metabolites (5% RMS), peptides, none	Remove/score candidate assemblies based on isotope intensities. SVM isotope models for metabolites were trained with either 2% or 5% RMS error. For peptides, an averagine cosine scoring is used. Select the appropriate noise model according to the quality of measurement or MS device.
mz_scoring_13C	string	false	false, true	Use the 13C isotope peak position (~1.003355 Da) as the expected shift in m/z for isotope mass traces (highly recommended for lipidomics!). Disable for general metabolites (as described in Kenar et al. 2014, MCP.).
use_smoothed_intensities	string	true	false, true	Use LOWESS intensities instead of raw intensities.
report_smoothed_intensities	string	true	false, true	Report smoothed intensities (only if use_smoothed_intensities is true).
report_convex_hulls	string	false	false, true	Augment each reported feature with the convex hull of the underlying mass traces (increases featureXML file size considerably).
report_chromatograms	string	false	false, true	Adds Chromatogram for each reported feature (Output in mzml).
remove_single_traces	string	false	false, true	Remove unassembled traces (single traces).
mz_scoring_by_elements	string	false	false, true	Use the m/z range of the assumed elements to detect isotope peaks. A expected m/z range is computed from the isotopes of the assumed elements. If enabled, this ignores 'mz_scoring_13C'
elements	string	CHNOPS		Elements assumes to be present in the sample (this influences isotope detection).

Note:

If a section name is documented, the documentation is displayed as tooltip.
Advanced parameter names are italic.

Constructor & Destructor Documentation

◆ FeatureFindingMetabo()

FeatureFindingMetabo ( )

Default constructor.

◆ ~FeatureFindingMetabo()

~FeatureFindingMetabo ( )

override

Default destructor.

Member Function Documentation

◆ computeAveragineSimScore_()

double computeAveragineSimScore_	(	const std::vector< double > &	intensities,
		const double &	molecular_weight
	)		const

private

Perform intensity scoring using the averagine model (for peptides only)

Compare the isotopic intensity distribution with the theoretical one expected for peptides, using the averagine model. Compute the cosine similarity between the two values.

Parameters

[in]	intensities	Intensity values
[in]	molecular_weight	Molecular weight

◆ computeCosineSim_()

double computeCosineSim_	(	const std::vector< double > &	vec1,
		const std::vector< double > &	vec2
	)		const

private

Computes the cosine similarity between two vectors.

The cosine similarity (or cosine distance) is the cosine of the angle between two vectors or the normalized dot product of two vectors.

Parameters

[in]	vec1	First vector
[in]	vec2	Second vector

◆ elementsFromString_()

std::vector< const Element * > elementsFromString_ ( const std::string & elements_string ) const

private

parses a string of element symbols into a vector of Elements

Parameters

[in] elements_string string of element symbols without whitespaces or commas. e.g. CHNOPSCl

Returns: vector of Elements

◆ findLocalFeatures_()

void findLocalFeatures_	(	const std::vector< const MassTrace * > &	candidates,
		double	total_intensity,
		std::vector< FeatureHypothesis > &	output_hypotheses
	)		const

private

Identify groupings of mass traces based on a set of reasonable candidates.

Takes a set of reasonable candidates for mass trace grouping and checks all combinations of charge and isotopic positions on the candidates. It is assumed that candidates[0] is the monoisotopic trace.

The resulting possible groupings are appended to output_hypotheses.

Parameters

[in]	candidates	Candidate mass traces
[in]	total_intensity	Total intensity
[out]	output_hypotheses	Output feature hypotheses

◆ getTheoreticIsotopicMassWindow_()

Range getTheoreticIsotopicMassWindow_	(	const std::vector< Element const * > &	alphabet,
		int	peakOffset
	)		const

private

Calculate the maximal and minimal mass defects of isotopes for a given set of elements.

Parameters

[in]	alphabet	chemical alphabet (elements which are expected to be present)
[in]	peakOffset	integer distance between isotope peak and monoisotopic peak (minimum: 1)

Returns: an interval which should contain the isotopic peak. This interval is relative to the monoisotopic peak.

◆ isLegalIsotopePattern_()

int isLegalIsotopePattern_ ( const FeatureHypothesis & feat_hypo ) const

private

Compare intensities of feature hypothesis with model.

Use a pre-trained SVM model to evaluate the intensity distribution of a given feature hypothesis. The model is trained on the monoisotopic and the first tree isotopic traces of each feature and uses the scaled ratios between the traces as input.

Reference: Kenar et al., doi: 10.1074/mcp.M113.031278

Parameters

[in] feat_hypo A feature hypotheses containing mass traces

Returns: 0 for 'no'; 1 for 'yes'; -1 if only a single mass trace exists

◆ loadIsotopeModel_()

void loadIsotopeModel_ ( const std::string & )

private

◆ run()

void run	(	std::vector< MassTrace > &	input_mtraces,
		FeatureMap &	output_featmap,
		std::vector< std::vector< OpenMS::MSChromatogram > > &	output_chromatograms
	)

main method of FeatureFindingMetabo

◆ scoreMZ_()

double scoreMZ_	(	const MassTrace &	mt1,
		const MassTrace &	mt2,
		Size	isotopic_position,
		Size	charge,
		Range	isotope_window
	)		const

private

Perform mass to charge scoring of two multiple mass traces.

Scores two mass traces based on the m/z and the hypothesis that one trace is an isotopic trace of the other one. The isotopic position (which trace it is) and the charge for the hypothesis are given as additional parameters. The scoring is described in Kenar et al., and is based on a random sample of 115 000 compounds drawn from a comprehensive set of 24 million putative sum formulas, of which the isotopic distribution was accurately calculated. Thus, a theoretical mu and sigma are calculated as:

mu = 1.000857 * j + 0.001091 u sigma = 0.0016633 j * 0.0004751

where j is the isotopic peak considered. A similarity score based on agreement with the model is then computed.

Reference: Kenar et al., doi: 10.1074/mcp.M113.031278

An alternative scoring was added which test if isotope m/z distances lie in an expected m/z window. This window is computed from a given set of elements.

Parameters

[in]	mt1	First mass trace
[in]	mt2	Second mass trace
[in]	isotopic_position	Isotopic position
[in]	charge	Charge
[in]	isotope_window	Isotope window

◆ scoreMZByExpectedMean_()

double scoreMZByExpectedMean_	(	Size	iso_pos,
		Size	charge,
		const double	diff_mz,
		double	mt_variances
	)		const

private

score isotope m/z distance based on the expected m/z distances using C13-C12 or Kenar method

Parameters

[in]	iso_pos	Isotopic position
[in]	charge	Charge
[in]	diff_mz	Mass-to-charge difference
[in]	mt_variances	Mass trace variances

Returns: Score value

◆ scoreMZByExpectedRange_()

double scoreMZByExpectedRange_	(	Size	charge,
		const double	diff_mz,
		double	mt_variances,
		Range	isotope_window
	)		const

private

score isotope m/z distance based on an expected isotope window which was calculated from a set of expected elements

Parameters

[in]	charge	Charge
[in]	diff_mz	Mass-to-charge difference
[in]	mt_variances	m/z variance between the two mass traces which are compared
[in]	isotope_window	Isotope window

Returns: Score value

◆ scoreRT_()

double scoreRT_	(	const MassTrace &	mt1,
		const MassTrace &	mt2
	)		const

private

Perform retention time scoring of two multiple mass traces.

Computes the similarity of the two peak shapes using cosine similarity (see computeCosineSim_) if some conditions are fulfilled. The RT overlap of the two peaks at FWHM must exceed the fraction given by the 'min_isotope_rt_overlap' parameter. By default ('isotope_rt_overlap_reference' = "longer") the overlap is measured against the longer trace with a threshold of 0.7 (i.e. 70 % overlap), as described in Kenar et al. When 'isotope_rt_overlap_reference' is set to "shorter", the overlap is measured against the shorter trace instead (better for low-intensity isotope traces that are much shorter than the monoisotopic trace) and, additionally, the apex (most intense peak) of the longer trace must fall within the RT range of the shorter trace.

Note: this only works for equally sampled mass traces, e.g. they need to come from the same map (not for SRM measurements for example).

Parameters

[in]	mt1	First mass trace
[in]	mt2	Second mass trace

◆ updateMembers_()

void updateMembers_ ( )

overrideprotectedvirtual

This method is used to update extra member variables at the end of the setParameters() method.

Also call it at the end of the derived classes' copy constructor and assignment operator.

The default implementation is empty.

Reimplemented from DefaultParamHandler.

Member Data Documentation

◆ charge_lower_bound_

Size charge_lower_bound_

private

◆ charge_upper_bound_

Size charge_upper_bound_

private

◆ chrom_fwhm_

double chrom_fwhm_

private

◆ elements_

std::vector<const Element*> elements_

private

◆ enable_RT_filtering_

bool enable_RT_filtering_

private

◆ has_im_data_

bool has_im_data_ = false

private

whether the input mass traces contain ion mobility data

◆ isotope_filt_svm_

std::unique_ptr<SimpleSVM> isotope_filt_svm_

private

SVM model (wraps LIBSVM) used to filter isotope patterns; loaded via loadIsotopeModel_()

◆ isotope_filtering_model_

std::string isotope_filtering_model_

private

◆ isotope_rt_overlap_use_shorter_

bool isotope_rt_overlap_use_shorter_

private

◆ local_im_range_

double local_im_range_

private

◆ local_mz_range_

double local_mz_range_

private

◆ local_rt_range_

double local_rt_range_

private

parameter stuff

◆ min_isotope_rt_overlap_

double min_isotope_rt_overlap_

private

◆ remove_single_traces_

bool remove_single_traces_

private

◆ report_chromatograms_

bool report_chromatograms_

private

◆ report_convex_hulls_

bool report_convex_hulls_

private

◆ report_smoothed_intensities_

bool report_smoothed_intensities_

private

◆ report_summed_ints_

bool report_summed_ints_

private

◆ svm_feat_centers_

std::vector<double> svm_feat_centers_

private

◆ svm_feat_scales_

std::vector<double> svm_feat_scales_

private

◆ use_mz_scoring_by_element_range_

bool use_mz_scoring_by_element_range_

private

◆ use_mz_scoring_C13_

bool use_mz_scoring_C13_

private

◆ use_smoothed_intensities_

bool use_smoothed_intensities_

private

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FeatureFindingMetabo()

◆ ~FeatureFindingMetabo()

Member Function Documentation

◆ computeAveragineSimScore_()

◆ computeCosineSim_()

◆ elementsFromString_()

◆ findLocalFeatures_()

◆ getTheoreticIsotopicMassWindow_()

◆ isLegalIsotopePattern_()

◆ loadIsotopeModel_()

◆ run()

◆ scoreMZ_()

◆ scoreMZByExpectedMean_()

◆ scoreMZByExpectedRange_()

◆ scoreRT_()

◆ updateMembers_()

Member Data Documentation

◆ charge_lower_bound_

◆ charge_upper_bound_

◆ chrom_fwhm_

◆ elements_

◆ enable_RT_filtering_

◆ has_im_data_

◆ isotope_filt_svm_

◆ isotope_filtering_model_

◆ isotope_rt_overlap_use_shorter_

◆ local_im_range_

◆ local_mz_range_

◆ local_rt_range_

◆ min_isotope_rt_overlap_

◆ remove_single_traces_

◆ report_chromatograms_

◆ report_convex_hulls_

◆ report_smoothed_intensities_

◆ report_summed_ints_

◆ svm_feat_centers_

◆ svm_feat_scales_

◆ use_mz_scoring_by_element_range_

◆ use_mz_scoring_C13_

◆ use_smoothed_intensities_