OpenMS  2.7.0
Classes | Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
FeatureDistance Class Reference

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

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

Inheritance diagram for FeatureDistance:
[legend]
Collaboration diagram for FeatureDistance:
[legend]

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...
 
FeatureDistanceoperator= (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 DefaultParamHandleroperator= (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 ParamgetParameters () const
 Non-mutable access to the parameters. More...
 
const ParamgetDefaults () const
 Non-mutable access to the default parameters. More...
 
const StringgetName () 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< Stringsubsections_
 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...
 

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

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:

NameTypeDefaultRestrictionsDescription
ignore_charge stringfalse true, falsefalse [default]: pairing requires equal charge state (or at least one unknown charge '0'); true: Pairing irrespective of charge state
ignore_adduct stringtrue true, falsetrue [default]: pairing requires equal adducts (or at least one without adduct annotation); true: Pairing irrespective of adducts
distance_RT:max_difference float100.0 min: 0.0Never pair features with a larger RT distance (in seconds).
distance_RT:exponent float1.0 min: 0.0Normalized 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 float1.0 min: 0.0Final RT distances are weighted by this factor
distance_MZ:max_difference float0.3 min: 0.0Never pair features with larger m/z distance (unit defined by 'unit')
distance_MZ:unit stringDa Da, ppmUnit of the 'max_difference' parameter
distance_MZ:exponent float2.0 min: 0.0Normalized ([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 float1.0 min: 0.0Final m/z distances are weighted by this factor
distance_intensity:exponent float1.0 min: 0.0Differences 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 float0.0 min: 0.0Final intensity distances are weighted by this factor
distance_intensity:log_transform stringdisabled enabled, disabledLog-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:

Constructor & Destructor Documentation

◆ FeatureDistance()

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

Constructor.

Parameters
max_intensityMaximum intensity of features (for normalization)
force_constraintsCheck "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.