| OpenMS 2.5.0

Public Member Functions | Static Public Member Functions | Protected Types | Private Types | Private Member Functions | Private Attributes | List of all members
QTClusterFinder Class Reference
Analysis » FeatureGrouping

A variant of QT clustering for the detection of feature groups. More...

`#include <OpenMS/ANALYSIS/MAPMATCHING/QTClusterFinder.h>`

Inheritance diagram for QTClusterFinder:

## Public Member Functions

| QTClusterFinder ()
| Constructor. More...
| ~QTClusterFinder () override
| Destructor. More...
void | run (const std::vector< ConsensusMap > &input_maps, ConsensusMap &result_map) override
| Runs the algorithm on consensus maps. More...
void | run (const std::vector< FeatureMap > &input_maps, ConsensusMap &result_map)
| Runs the algorithm on feature maps. More...
Public Member Functions inherited from BaseGroupFinder
| BaseGroupFinder ()
| Default constructor. More...
| ~BaseGroupFinder () override
| Destructor. 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...
Public Member Functions inherited from ProgressLogger
| ProgressLogger ()
| Constructor. More...
| ~ProgressLogger ()
| Destructor. More...
| ProgressLogger (const ProgressLogger &other)
| Copy constructor. More...
ProgressLogger & | operator= (const ProgressLogger &other)
| Assignment Operator. More...
void | setLogType (LogType type) const
| Sets the progress log that should be used. The default type is NONE! More...
LogType | getLogType () const
| Returns the type of progress log being used. More...
void | startProgress (SignedSize begin, SignedSize end, const String &label) const
| Initializes the progress display. More...
void | setProgress (SignedSize value) const
| Sets the current progress. More...
void | endProgress () const
| Ends the progress display. More...
void | nextProgress () const
| increment progress by 1 (according to range begin-end) More...

## Static Public Member Functions

static const String | getProductName ()
| Returns the name of the product. More...
static BaseGroupFinder * | create ()
| Returns an instance of this class. More...
Static Public Member Functions inherited from BaseGroupFinder
static void | registerChildren ()
| Register all derived classes here. More...

## Protected Types

enum | { RT = Peak2D::RT, MZ = Peak2D::MZ }

## Private Types

typedef OpenMSBoost::unordered_map< std::pair< OpenMS::GridFeature *, OpenMS::GridFeature * >, double > | PairDistances
| Distances between pairs of grid features. More...
typedef OpenMSBoost::unordered_map< OpenMS::GridFeature *, std::vector< QTCluster * > > | ElementMapping
| Map to store which grid features are next to which clusters. More...
typedef HashGrid< OpenMS::GridFeature * > | Grid

## Private Member Functions

double | getDistance_ (const OpenMS::GridFeature *left, const OpenMS::GridFeature *right)
| Calculates the distance between two grid features. More...
void | setParameters_ (double max_intensity, double max_mz)
| Sets algorithm parameters. More...
void | makeConsensusFeature_ (std::list< QTCluster > &clustering, ConsensusFeature &feature, ElementMapping &element_mapping, Grid &)
| Generates a consensus feature from the best cluster and updates the clustering. More...
void | computeClustering_ (Grid &grid, std::list< QTCluster > &clustering)
| Computes an initial QT clustering of the points in the hash grid. More...
template<typename MapType >
void | run_ (const std::vector< MapType > &input_maps, ConsensusMap &result_map)
| Runs the algorithm on feature maps or consensus maps. More...
template<typename MapType >
void | run_internal_ (const std::vector< MapType > &input_maps, ConsensusMap &result_map, bool do_progress)
| Runs the algorithm on feature maps or consensus maps (internal) More...
void | addClusterElements_ (int x, int y, const Grid &grid, QTCluster &cluster, const OpenMS::GridFeature *center_feature)
| Adds elements to the cluster based on the elements hashed in the grid. More...

## Private Attributes

Size | num_maps_
| Number of input maps. More...
bool | use_IDs_
| Consider peptide identifications for grouping? More...
double | max_diff_rt_
| Maximum RT difference. More...
double | max_diff_mz_
| Maximum m/z difference. More...
int | nr_partitions_
| Maximum m/z difference. More...
FeatureDistance | feature_distance_
| Feature distance functor. More...
std::set< OpenMS::GridFeature * > | already_used_
| Set of features already used. More...

## Additional Inherited Members

Public Types inherited from ProgressLogger
enum | LogType { CMD, GUI, NONE }
| Possible log types. More...
Protected Member Functions inherited from BaseGroupFinder
void | checkIds_ (const std::vector< ConsensusMap > &maps) const
| Checks if all file descriptions have disjoint map identifiers. More...
Protected Member Functions inherited from DefaultParamHandler
virtual void | updateMembers_ ()
| This method is used to update extra member variables at the end of the setParameters() method. More...
void | defaultsToParam_ ()
| Updates the parameters after the defaults have been set in the constructor. More...
Static Protected Member Functions inherited from ProgressLogger
static String | logTypeToFactoryName_ (LogType type)
| Return the name of the factory product used for this log type. 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...
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

A variant of QT clustering for the detection of feature groups.

The algorithm accumulates all features from all input maps, then applies a variant of QT clustering to find groups of corresponding features. In more detail, every feature from every input map is considered as a potential cluster center. For every center, its nearest neighbors from the other input maps are detected and added to the potential cluster. Iteratively, the cluster with the highest quality is extracted and the clustering is updated.

Properties affecting the grouping

To be included in a particular cluster, a feature has to fulfill the following conditions:

- differences in RT and m/z from the cluster center must be below user-defined thresholds (`distance_RT:max_difference` and `distance_MZ:max_difference`),

- the charge state must match that of the cluster center (unless `ignore_charge` is set),

- if `use_identifications` is set and both the feature and the cluster center are annotated with peptide identifications, the identifications have to match.

Every cluster contains at most one feature from each input map - namely the feature closest to the cluster center that meets the criteria and does not belong to a better cluster.

The notion of "closeness" for features is defined by the distance function implemented in FeatureDistance, the parameters of which can be set by the user.

The quality of a cluster is computed from the number of elements in it and their distances to the cluster center. For more details see QTCluster.

Optimization

This algorithm includes a number of optimizations to reduce run-time:

- two-dimensional hashing of features,
- a look-up table for feature distances,
- a variant of QT clustering that requires only one round of clustering.

See also
  FeatureGroupingAlgorithmQT

Parameters of this class are:

Name | Type | Default | Restrictions | Description
--- | --- | --- | --- | ---
use_identifications | string | false | true, false | Never link features that are annotated with different peptides (only the best hit per peptide identification is taken into account).
nr_partitions | int | 100 | min: 1 | How many partitions in m/z space should be used for the algorithm (more partitions means faster runtime and more memory efficient execution )
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.

## Member Typedef Documentation

## ◆ ElementMapping

typedef OpenMSBoost::unordered_map< OpenMS::GridFeature*, std::vector<QTCluster*> > ElementMapping

private

Map to store which grid features are next to which clusters.

## ◆ Grid

typedef HashGrid<OpenMS::GridFeature*> Grid

private

## ◆ PairDistances

typedef OpenMSBoost::unordered_map< std::pair<OpenMS::GridFeature*, OpenMS::GridFeature*>, double> PairDistances

private

Distances between pairs of grid features.

## Member Enumeration Documentation

## ◆ anonymous enum

anonymous enum

protected

Enumerator
RT |
MZ |

## Constructor & Destructor Documentation

## ◆ QTClusterFinder()

QTClusterFinder | ( |  | ) |

Constructor.

## ◆ ~QTClusterFinder()

~QTClusterFinder | ( |  | ) |

override

Destructor.

## Member Function Documentation

## ◆ addClusterElements_()

void addClusterElements_ | ( | int | x,
|  | int | y,
|  | const Grid & | grid,
|  | QTCluster & | cluster,
|  | const OpenMS::GridFeature * | center_feature
| ) |  |

private

Adds elements to the cluster based on the elements hashed in the grid.

## ◆ computeClustering_()

void computeClustering_ | ( | Grid & | grid,
|  | std::list< QTCluster > & | clustering
| ) |  |

private

Computes an initial QT clustering of the points in the hash grid.

## ◆ create()

static BaseGroupFinder* create | ( |  | ) |

inline static

Returns an instance of this class.

## ◆ getDistance_()

double getDistance_ | ( | const OpenMS::GridFeature * | left,
|  | const OpenMS::GridFeature * | right
| ) |  |

private

Calculates the distance between two grid features.

## ◆ getProductName()

static const String getProductName | ( |  | ) |

inline static

Returns the name of the product.

## ◆ makeConsensusFeature_()

void makeConsensusFeature_ | ( | std::list< QTCluster > & | clustering,
|  | ConsensusFeature & | feature,
|  | ElementMapping & | element_mapping,
|  | Grid & |
| ) |  |

private

Generates a consensus feature from the best cluster and updates the clustering.

## ◆ run() [1/2]

void run | ( | const std::vector< ConsensusMap > & | input_maps,
|  | ConsensusMap & | result_map
| ) |  |

override virtual

Runs the algorithm on consensus maps.

Precondition
  The data ranges of the input maps have to be up-to-date (use ConsensusMap::updateRanges).

Exceptions

  Exception::IllegalArgument | is thrown if the input data is not valid.

Implements BaseGroupFinder.

## ◆ run() [2/2]

void run | ( | const std::vector< FeatureMap > & | input_maps,
|  | ConsensusMap & | result_map
| ) |  |

Runs the algorithm on feature maps.

Precondition
  The data ranges of the input maps have to be up-to-date (use FeatureMap::updateRanges).

Exceptions

  Exception::IllegalArgument | is thrown if the input data is not valid.

## ◆ run_()

void run_ | ( | const std::vector< MapType > & | input_maps,
|  | ConsensusMap & | result_map
| ) |  |

private

Runs the algorithm on feature maps or consensus maps.

## ◆ run_internal_()

void run_internal_ | ( | const std::vector< MapType > & | input_maps,
|  | ConsensusMap & | result_map,
|  | bool | do_progress
| ) |  |

private

Runs the algorithm on feature maps or consensus maps (internal)

## ◆ setParameters_()

void setParameters_ | ( | double | max_intensity,
|  | double | max_mz
| ) |  |

private

Sets algorithm parameters.

## Member Data Documentation

## ◆ already_used_

std::set<OpenMS::GridFeature*> already_used_

private

Set of features already used.

## ◆ feature_distance_

FeatureDistance feature_distance_

private

Feature distance functor.

## ◆ max_diff_mz_

double max_diff_mz_

private

Maximum m/z difference.

## ◆ max_diff_rt_

double max_diff_rt_

private

Maximum RT difference.

## ◆ nr_partitions_

int nr_partitions_

private

Maximum m/z difference.

## ◆ num_maps_

Size num_maps_

private

Number of input maps.

## ◆ use_IDs_

bool use_IDs_

private

Consider peptide identifications for grouping?