| OpenMS 2.5.0

Classes | Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
FeatureDistance Class Reference
Analysis » FeatureGrouping

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:

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

, , and are the RT, m/z, and intensity values of the respective feature.

Constraints are: and . 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.

and 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.

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.

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.

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, 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.0 | min: 0.0 | Never pair features with a larger RT distance (in seconds).
distance_RT:exponent | float | 1.0 | min: 0.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.0 | min: 0.0 | Final RT distances are weighted by this factor
distance_MZ:max_difference | float | 0.3 | min: 0.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.0 | min: 0.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.0 | min: 0.0 | Final m/z distances are weighted by this factor
distance_intensity:exponent | float | 1.0 | min: 0.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.0 | min: 0.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

inline protected

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_ | ( |  | ) |

override protected virtual

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.