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 (DoubleReal max_intensity=1.0, bool force_constraints=false)
	Constructor.
virtual	~FeatureDistance ()
	Destructor.
FeatureDistance &	operator= (const FeatureDistance &other)
	Assignment operator.
std::pair< bool, DoubleReal >	operator() (const BaseFeature &left, const BaseFeature &right)
	Evaluation operator - checks constraints and computes the distance between two features.
Static Public Attributes
static const DoubleReal	infinity
	Value to return if max. difference is exceeded or if charge states don't match.
Protected Member Functions
void	updateMembers_ ()
	Docu in base class.
DoubleReal	distance_ (DoubleReal diff, const DistanceParams_ &params) const
	Computes a distance component given absolute difference and parameters.
Protected Attributes
DistanceParams_	params_rt_
	Storage of parameters for the individual distance components.
DistanceParams_	params_mz_
DistanceParams_	params_intensity_
DoubleReal	total_weight_reciprocal_
	Reciprocal value of the total weight in the distance function.
DoubleReal	max_intensity_
	Maximum intensity of features (for normalization).
bool	ignore_charge_
	Compute a distance even if charge states don't match?
bool	force_constraints_
	Always return infinity if "max. difference" constraints are not met?

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.

${\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. If an absolute difference exceeds the specified maximum, the behavior depends on the value used for check_constraints in the constructor: If "false", the distance will be computed normally, but may become greater than 1; if "true", the fixed value infinity is returned.

$int_{max}$ is the maximum intensity that can occur for features compared by this distance function. It is not a parameter specified by the user, but depends on the data at hand and is thus set in the constructor (via parameter max_intensity).

$ w_X $ is the weight of distance component 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. (Note that the default weight for the intensity component is zero, i.e. intensity is not considered by default.)

$ p_X $ is the exponent for distance component X, specified by the parameter distance_X:exponent. Normalized differences are taken to this power. This makes it possible to compare values using linear, quadratic, etc. distance.

By default, two features are only compared if they have the same charge state (or charge state 0 for "undefined") - 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	Compare features normally even if their charge states are different
distance_RT:max_difference	float	100	min: 0	Maximum allowed difference in RT in seconds
distance_RT:exponent	float	1	min: 0	Normalized RT differences are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)
distance_RT:weight	float	1	min: 0	RT distances are weighted by this factor
distance_MZ:max_difference	float	0.3	min: 0	Maximum allowed difference in m/z (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 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	m/z distances are weighted by this factor
distance_intensity:exponent	float	1	min: 0	Differences in relative intensity are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)
distance_intensity:weight	float	0	min: 0	Distances based on relative intensity are weighted by this factor

Note:

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

Constructor & Destructor Documentation

FeatureDistance	(	DoubleReal	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?

virtual ~FeatureDistance ( ) [virtual]

Destructor.

Member Function Documentation

DoubleReal distance_	(	DoubleReal	diff,
		const DistanceParams_ &	params
	)			const `[inline, protected]`

Computes a distance component given absolute difference and parameters.

std::pair<bool, DoubleReal> 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).

FeatureDistance& operator= ( const FeatureDistance & other )

Assignment operator.

void updateMembers_ ( ) [protected, virtual]

Docu in base class.

Reimplemented from DefaultParamHandler.