A functor class for the calculation of distances between features or consensus features. More...

#include <OpenMS/ANALYSIS/MAPMATCHING/FeatureDistance.h>

Inheritance diagram for FeatureDistance:

Classes
struct	DistanceParams_
	Structure for storing distance parameters. More...

Public Member Functions
	FeatureDistance (double max_intensity=1.0, bool force_constraints=false)
	Constructor. More...

	~FeatureDistance () override
	Destructor. More...

FeatureDistance &	operator= (const FeatureDistance &other)
	Assignment operator. More...

std::pair< bool, double >	operator() (const BaseFeature &left, const BaseFeature &right)
	Evaluation operator - checks constraints and computes the distance between two features. 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...

Static Public Attributes
static const double	infinity
	Value to return if max. difference is exceeded or if charge states don't match. More...

Protected Member Functions
void	updateMembers_ () override
	Docu in base class. More...

double	distance_ (double diff, const DistanceParams_ &params) const
	Computes a distance component given absolute difference and parameters. More...

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

Protected Attributes
DistanceParams_	params_rt_
	Storage of parameters for the individual distance components. More...

DistanceParams_	params_mz_

DistanceParams_	params_intensity_

double	total_weight_reciprocal_
	Reciprocal value of the total weight in the distance function. More...

double	max_intensity_
	Maximum intensity of features (for normalization) More...

bool	ignore_charge_
	Compute a distance even if charge states don't match? More...

bool	ignore_adduct_
	Compute a distance even if adducts don't match? More...

bool	force_constraints_
	Always return infinity if "max. difference" constraints are not met? More...

bool	log_transform_
	Log-transform intensities when computing intensity distance? 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

A functor class for the calculation of distances between features or consensus features.

It implements a customizable distance function of the following form:

$w_{RT} \cdot \left( \frac{\left| RT_1 - RT_2 \right|}{\Delta RT_{max}} \right)^{p_{RT}} + w_{MZ} \cdot \left( \frac{\left| MZ_1 - MZ_2 \right|}{\Delta MZ_{max}} \right)^{p_{MZ}} + w_{int} \cdot \left( \frac{\left| int_1 - int_2 \right|}{int_{max}} \right)^{p_{int}}$

This function returns a normalized distance between zero and one (unless constraints are violated, see below).

$ RT_i $ , $ MZ_i $ , and $ int_i $ are the RT, m/z, and intensity values of the respective feature.

Constraints are: ${\Delta RT_{max}}, {\Delta MZ_{max}}$ and $int_{max}$ . If an absolute difference exceeds the specified maximum, the behavior depends on the value used for check_constraints in the constructor: If "false" (i.e., no constraints), the distance in that dimension may become greater than 1; if "true", infinity is returned as overall distance.

${\Delta RT_{max}}$ and ${\Delta MZ_{max}}$ are the maximum allowed differences in RT and m/z, respectively. They are specified by the parameters distance_RT:max_difference and distance_MZ:max_difference, and are used for normalization, i.e., the observed RT or m/z differences of the feature pair are scaled relative to this value.

$int_{max}$ is the intensity which yields a normalized intensity of 1. This parameter is not settable via user params, but is set in the constructor (via parameter max_intensity), since it depends on the data at hand.

$ p_X $ is the exponent for the distance in dimension X, specified by the parameter distance_X:exponent. Normalized differences (between (0, 1) unless unconstrained) are taken to this power. This makes it possible to compare values using linear, quadratic, etc. distance.

$ w_X $ is the weight of final distance in dimension X, specified by the parameter distance_X:weight. The weights can be used to increase or decrease the contribution of RT, m/z, or intensity in the distance function. (The default weight for the intensity dimension is zero, i.e. intensity is not considered by default. However, $int_{max}$ is still a constraint and should be set sensibly in the c'tor.)

By default, two features are paired only if they have the same charge state (or at least one unknown charge '0') - otherwise, infinity is returned. This behavior can be changed by the ignore_charge parameter.

Note: Peptide identifications annotated to features are not taken into account here, because they are stored in a format that is not suitable for rapid comparison.

Parameters of this class are:

Name	Type	Default	Restrictions	Description
ignore_charge	string	false	true, false	false [default]: pairing requires equal charge state (or at least one unknown charge '0'); true: Pairing irrespective of charge state
ignore_adduct	string	true	true, false	true [default]: pairing requires equal adducts (or at least one without adduct annotation); true: Pairing irrespective of adducts
distance_RT:max_difference	float	100	min: 0	Never pair features with a larger RT distance (in seconds).
distance_RT:exponent	float	1	min: 0	Normalized RT differences ([0-1], relative to 'max_difference') are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)
distance_RT:weight	float	1	min: 0	Final RT distances are weighted by this factor
distance_MZ:max_difference	float	0.3	min: 0	Never pair features with larger m/z distance (unit defined by 'unit')
distance_MZ:unit	string	Da	Da, ppm	Unit of the 'max_difference' parameter
distance_MZ:exponent	float	2	min: 0	Normalized ([0-1], relative to 'max_difference') m/z differences are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)
distance_MZ:weight	float	1	min: 0	Final m/z distances are weighted by this factor
distance_intensity:exponent	float	1	min: 0	Differences in relative intensity ([0-1]) are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)
distance_intensity:weight	float	0	min: 0	Final intensity distances are weighted by this factor
distance_intensity:log_transform	string	disabled	enabled, disabled	Log-transform intensities? If disabled, d = \|int_f2 - int_f1\| / int_max. If enabled, d = \|log(int_f2 + 1) - log(int_f1 + 1)\| / log(int_max + 1))

Note:

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

Constructor & Destructor Documentation

◆ FeatureDistance()

FeatureDistance	(	double	max_intensity = `1.0`,
		bool	force_constraints = `false`
	)

Constructor.

Parameters

max_intensity	Maximum intensity of features (for normalization)
force_constraints	Check "max. difference" constraints given in the parameters and return infinity if violated?

◆ ~FeatureDistance()

~FeatureDistance ( )

override

Destructor.

Member Function Documentation

◆ distance_()

double distance_	(	double	diff,
		const DistanceParams_ &	params
	)		const

inlineprotected

Computes a distance component given absolute difference and parameters.

◆ operator()()

std::pair<bool, double> operator()	(	const BaseFeature &	left,
		const BaseFeature &	right
	)

Evaluation operator - checks constraints and computes the distance between two features.

Returns: In the first element, whether constraints were satisfied; in the second element, the distance (infinity if constraints were violated and force_constraints_ is true).

◆ operator=()

FeatureDistance& operator= ( const FeatureDistance & other )

Assignment operator.

◆ updateMembers_()

void updateMembers_ ( )

overrideprotectedvirtual

Docu in base class.

Reimplemented from DefaultParamHandler.

Member Data Documentation

◆ force_constraints_

bool force_constraints_

protected

Always return infinity if "max. difference" constraints are not met?

◆ ignore_adduct_

bool ignore_adduct_

protected

Compute a distance even if adducts don't match?

◆ ignore_charge_

bool ignore_charge_

protected

Compute a distance even if charge states don't match?

◆ infinity

const double infinity

static

Value to return if max. difference is exceeded or if charge states don't match.

◆ log_transform_

bool log_transform_

protected

Log-transform intensities when computing intensity distance?

◆ max_intensity_

double max_intensity_

protected

Maximum intensity of features (for normalization)

◆ params_intensity_

DistanceParams_ params_intensity_

protected

◆ params_mz_

DistanceParams_ params_mz_

protected

◆ params_rt_

DistanceParams_ params_rt_

protected

Storage of parameters for the individual distance components.

◆ total_weight_reciprocal_

double total_weight_reciprocal_

protected

Reciprocal value of the total weight in the distance function.

Classes

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FeatureDistance()

◆ ~FeatureDistance()

Member Function Documentation

◆ distance_()

◆ operator()()

◆ operator=()

◆ updateMembers_()

Member Data Documentation

◆ force_constraints_

◆ ignore_adduct_

◆ ignore_charge_

◆ infinity

◆ log_transform_

◆ max_intensity_

◆ params_intensity_

◆ params_mz_

◆ params_rt_

◆ total_weight_reciprocal_