A map alignment algorithm based on pose clustering. More...

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

Inheritance diagram for MapAlignmentAlgorithmPoseClustering:

Public Member Functions
	MapAlignmentAlgorithmPoseClustering ()
	Default constructor.

	~MapAlignmentAlgorithmPoseClustering () override
	Destructor.

void	align (const FeatureMap &map, TransformationDescription &trafo)

void	align (const PeakMap &map, TransformationDescription &trafo)

void	align (const ConsensusMap &map, TransformationDescription &trafo)

void	setReference (const FeatureMap &map)
	Sets the reference for the alignment: the 'max_num_peaks_considered' most intense features of `map`.

void	setReference (const PeakMap &map)
	Sets the reference for the alignment: 'max_num_peaks_considered' MS1 peaks of `map`, selected as set by 'peak_selection:method'.

Public Member Functions inherited from DefaultParamHandler
	DefaultParamHandler (const std::string &name)
	Constructor with name that is displayed in error messages.

	DefaultParamHandler (const DefaultParamHandler &rhs)
	Copy constructor.

virtual	~DefaultParamHandler ()
	Destructor.

DefaultParamHandler &	operator= (const DefaultParamHandler &rhs)
	Assignment operator.

virtual bool	operator== (const DefaultParamHandler &rhs) const
	Equality operator.

void	setParameters (const Param &param)
	Sets the parameters.

const Param &	getParameters () const
	Non-mutable access to the parameters.

const Param &	getDefaults () const
	Non-mutable access to the default parameters.

const std::string &	getName () const
	Non-mutable access to the name.

void	setName (const std::string &name)
	Mutable access to the name.

const std::vector< std::string > &	getSubsections () const
	Non-mutable access to the registered subsections.

Public Member Functions inherited from ProgressLogger
	ProgressLogger ()
	Constructor.

virtual	~ProgressLogger ()
	Destructor.

	ProgressLogger (const ProgressLogger &other)
	Copy constructor.

ProgressLogger &	operator= (const ProgressLogger &other)
	Assignment Operator.

void	setLogType (LogType type) const
	Sets the progress log that should be used. The default type is NONE!

LogType	getLogType () const
	Returns the type of progress log being used.

void	setLogger (ProgressLoggerImpl *logger)
	Sets the logger to be used for progress logging.

void	startProgress (SignedSize begin, SignedSize end, const std::string &label) const
	Initializes the progress display.

void	setProgress (SignedSize value) const
	Sets the current progress.

void	endProgress (UInt64 bytes_processed=0) const

void	nextProgress () const
	increment progress by 1 (according to range begin-end)

Protected Member Functions
void	updateMembers_ () override
	This method is used to update extra member variables at the end of the setParameters() method.

void	selectPeakLandmarks_ (UInt64 map_index, const PeakMap &map, ConsensusMap &output) const
	Selects the peaks of `map` to align, by selectPeaks_() or selectSpreadPeaks_() as set by 'peak_selection:method'.

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

Static Protected Member Functions
static void	selectPeaks_ (UInt64 map_index, const PeakMap &map, ConsensusMap &output, Size n)
	Copies the `n` most intense MS1 peaks of `map` into `output`, as consensus features of map `map_index`.

static void	selectSpreadPeaks_ (UInt64 map_index, const PeakMap &map, ConsensusMap &output, Size n, double rt_window, double mz_tolerance_ppm, Size max_charge, Size rt_bins, Size mz_bins)
	Copies up to `n` MS1 peaks of `map` into `output` that represent different analytes, spread over the RT and m/z range of `map`.

static void	selectFeatures_ (UInt64 map_index, const FeatureMap &map, ConsensusMap &output, Size n)
	Copies the `n` most intense features of `map` into `output`, as consensus features of map `map_index`.

Protected Attributes
PoseClusteringAffineSuperimposer	superimposer_

StablePairFinder	pairfinder_

ConsensusMap	reference_

Int	max_num_peaks_considered_

bool	spread_peaks_ = true
	'peak_selection:' parameters

double	spread_rt_window_ = 20.0

double	spread_mz_tolerance_ppm_ = 10.0

Size	spread_max_charge_ = 4

Size	spread_rt_bins_ = 10

Size	spread_mz_bins_ = 10

Protected Attributes inherited from DefaultParamHandler
Param	param_
	Container for current parameters.

Param	defaults_
	Container for default parameters. This member should be filled in the constructor of derived classes!

std::vector< std::string >	subsections_
	Container for registered subsections. This member should be filled in the constructor of derived classes!

std::string	error_name_
	Name that is displayed in error messages during the parameter checking.

bool	check_defaults_
	If this member is set to false no checking if parameters in done;.

bool	warn_empty_defaults_
	If this member is set to false no warning is emitted when defaults are empty;.

Protected Attributes inherited from ProgressLogger
LogType	type_

time_t	last_invoke_

ProgressLoggerImpl *	current_logger_

Private Member Functions
	MapAlignmentAlgorithmPoseClustering (const MapAlignmentAlgorithmPoseClustering &)
	Copy constructor intentionally not implemented -> private.

MapAlignmentAlgorithmPoseClustering &	operator= (const MapAlignmentAlgorithmPoseClustering &)
	Assignment operator intentionally not implemented -> private.

Additional Inherited Members
Public Types inherited from ProgressLogger
enum	LogType { CMD , GUI , NONE }
	Possible log types. More...

Static Public Member Functions inherited from DefaultParamHandler
static void	writeParametersToMetaValues (const Param &write_this, MetaInfoInterface &write_here, const std::string &key_prefix="")
	Writes all parameters to meta values.

Static Protected Attributes inherited from ProgressLogger
static std::atomic< int >	recursion_depth_

Detailed Description

A map alignment algorithm based on pose clustering.

Pose clustering analyzes pair distances to find the most probable transformation of retention times.

The algorithm uses up to 'max_num_peaks_considered' peaks/features per map: the most intense features of a feature map, or MS1 peaks of a peak map selected as set by 'peak_selection:method' (see below). This parameter influences the runtime and stability of the results. Bigger values prolong computation, smaller values might lead to no or unstable trafos. Set to -1 to use all features (might take very long for large maps).

For peak maps, 'peak_selection:method' 'spread' (the default) selects at most one peak per analyte (instead of many peaks of the elution profile and isotope pattern of a few intense analytes), spread over the RT and m/z range; see selectSpreadPeaks_(). 'intensity' selects the most intense peaks; see selectPeaks_().

For further details see:
Eva Lange et al.
A Geometric Approach for the Alignment of Liquid Chromatography-Mass Spectrometry Data
ISMB/ECCB 2007

Parameters of this class are:

Name	Type	Default	Restrictions	Description
max_num_peaks_considered	int	1000	min: -1	The maximal number of peaks/features to be considered per map. To use all, set to '-1'.
superimposer:mz_pair_max_distance	float	0.5	min: 0.0	Maximum of m/z deviation of corresponding elements in different maps. This condition applies to the pairs considered in hashing.
superimposer:rt_pair_distance_fraction	float	0.1	min: 0.0 max: 1.0	Within each of the two maps, the pairs considered for pose clustering must be separated by at least this fraction of the total elution time interval (i.e., max - min).
superimposer:num_used_points	int	2000	min: -1	Maximum number of elements considered in each map (selected by intensity). Use this to reduce the running time and to disregard weak signals during alignment. For using all points, set this to -1.
superimposer:scaling_bucket_size	float	5.0e-03	min: 0.0	The scaling of the retention time interval is being hashed into buckets of this size during pose clustering. A good choice for this would be a bit smaller than the error you would expect from repeated runs.
superimposer:shift_bucket_size	float	3.0	min: 0.0	The shift at the lower (respectively, higher) end of the retention time interval is being hashed into buckets of this size during pose clustering. A good choice for this would be about the time between consecutive MS scans.
superimposer:max_shift	float	1000.0	min: 0.0	Maximal shift which is considered during histogramming (in seconds). This applies for both directions.
superimposer:max_scaling	float	2.0	min: 1.0	Maximal scaling which is considered during histogramming. The minimal scaling is the reciprocal of this.
superimposer:dump_buckets	string			[DEBUG] If non-empty, base filename where hash table buckets will be dumped to. A serial number for each invocation will be appended automatically.
superimposer:dump_pairs	string			[DEBUG] If non-empty, base filename where the individual hashed pairs will be dumped to (large!). A serial number for each invocation will be appended automatically.
pairfinder:second_nearest_gap	float	2.0	min: 1.0	Only link features whose distance to the second nearest neighbors (for both sides) is larger by 'second_nearest_gap' than the distance between the matched pair itself.
pairfinder:use_identifications	string	false	true, false	Never link features that are annotated with different peptides (features without ID's always match; only the best hit per peptide identification is considered).
pairfinder: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
pairfinder:ignore_adduct	string	true	true, false	true [default]: pairing requires equal adducts (or at least one without adduct annotation); true: Pairing irrespective of adducts
pairfinder:distance_RT:max_difference	float	100.0	min: 0.0	Never pair features with a larger RT distance (in seconds).
pairfinder: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)
pairfinder:distance_RT:weight	float	1.0	min: 0.0	Final RT distances are weighted by this factor
pairfinder:distance_MZ:max_difference	float	0.3	min: 0.0	Never pair features with larger m/z distance (unit defined by 'unit')
pairfinder:distance_MZ:unit	string	Da	Da, ppm	Unit of the 'max_difference' parameter
pairfinder: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)
pairfinder:distance_MZ:weight	float	1.0	min: 0.0	Final m/z distances are weighted by this factor
pairfinder: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)
pairfinder:distance_intensity:weight	float	0.0	min: 0.0	Final intensity distances are weighted by this factor
pairfinder: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))
peak_selection:method	string	spread	spread, intensity	How the 'max_num_peaks_considered' MS1 peaks of a peak map (e.g. mzML input) are selected. 'spread': at most one peak per analyte (the most intense one of its elution profile and isotope pattern), spread over the RT and m/z range of the map. 'intensity': the most intense peaks (the selection of OpenMS 3.6 and earlier); one intense analyte contributes many peaks (its elution profile and isotope pattern). Feature maps always use their most intense features.
peak_selection:rt_window	float	20.0	min: 0.0	('spread' only) A peak within this RT distance (in seconds) of a selected peak at the same m/z, or at an isotope position of it, belongs to the same analyte and is not selected. Use about the width of a chromatographic peak.
peak_selection:mz_tolerance	float	10.0	min: 0.0	('spread' only) m/z tolerance (in ppm) for the same m/z and for isotope positions.
peak_selection:max_charge	int	4	min: 0	('spread' only) Isotope positions m/z +/- k * 1.0033548378 / z (k = 1..3) are suppressed for the charges z = 1..max_charge. 0 suppresses no isotopes.
peak_selection:rt_bins	int	10	min: 1 max: 1000	('spread' only) Number of RT bins over which the selected peaks are spread.
peak_selection:mz_bins	int	10	min: 1 max: 1000	('spread' only) Number of m/z bins over which the selected peaks are spread.

Note:

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

Constructor & Destructor Documentation

◆ MapAlignmentAlgorithmPoseClustering() [1/2]

MapAlignmentAlgorithmPoseClustering ( )

Default constructor.

◆ ~MapAlignmentAlgorithmPoseClustering()

~MapAlignmentAlgorithmPoseClustering ( )

override

Destructor.

◆ MapAlignmentAlgorithmPoseClustering() [2/2]

MapAlignmentAlgorithmPoseClustering ( const MapAlignmentAlgorithmPoseClustering & )

private

Copy constructor intentionally not implemented -> private.

Member Function Documentation

◆ align() [1/3]

void align	(	const ConsensusMap &	map,
		TransformationDescription &	trafo
	)

◆ align() [2/3]

void align	(	const FeatureMap &	map,
		TransformationDescription &	trafo
	)

◆ align() [3/3]

void align	(	const PeakMap &	map,
		TransformationDescription &	trafo
	)

◆ operator=()

MapAlignmentAlgorithmPoseClustering & operator= ( const MapAlignmentAlgorithmPoseClustering & )

private

Assignment operator intentionally not implemented -> private.

◆ selectFeatures_()

static void selectFeatures_	(	UInt64	map_index,
		const FeatureMap &	map,
		ConsensusMap &	output,
		Size	n
	)

staticprotected

Copies the n most intense features of map into output, as consensus features of map map_index.

Like MapConversion::convert(UInt64, const FeatureMap&, ConsensusMap&, Size), but selects the most intense features instead of the first ones (ties are broken by RT, then m/z, then position in map). The selected features keep their order in map. With n at or above the number of features (e.g. Size(-1)), the result equals that conversion.

Exceptions

Exception::InvalidValue if a feature has a NaN intensity or a non-finite RT or m/z

◆ selectPeakLandmarks_()

void selectPeakLandmarks_	(	UInt64	map_index,
		const PeakMap &	map,
		ConsensusMap &	output
	)		const

protected

Selects the peaks of map to align, by selectPeaks_() or selectSpreadPeaks_() as set by 'peak_selection:method'.

◆ selectPeaks_()

static void selectPeaks_	(	UInt64	map_index,
		const PeakMap &	map,
		ConsensusMap &	output,
		Size	n
	)

staticprotected

Copies the n most intense MS1 peaks of map into output, as consensus features of map map_index.

output is cleared first. Only the peaks of MS level 1 spectra are used; spectra of other MS levels and chromatograms do not contribute. The peaks are ordered by descending intensity; equal intensities are ordered by RT, then m/z. n is capped by the number of MS1 peaks, so Size(-1) keeps all of them. Only the selected peaks are held in memory besides map. The column header size for map_index is the number of peaks copied.

The consensus features only carry the positions and intensities the alignment needs: they have no unique ids, and the single handle of each stores the index of the peak in output.

Exceptions

Exception::InvalidValue if an MS1 peak has a NaN intensity or a non-finite m/z, or a non-empty MS1 spectrum has a non-finite RT

◆ selectSpreadPeaks_()

static void selectSpreadPeaks_	(	UInt64	map_index,
		const PeakMap &	map,
		ConsensusMap &	output,
		Size	n,
		double	rt_window,
		double	mz_tolerance_ppm,
		Size	max_charge,
		Size	rt_bins,
		Size	mz_bins
	)

staticprotected

Copies up to n MS1 peaks of map into output that represent different analytes, spread over the RT and m/z range of map.

Many peaks belong to the same analyte: the peaks of its elution profile (the same m/z in consecutive spectra) and of its isotope pattern. Taking the most intense peaks (selectPeaks_()) therefore picks a few intense analytes many times, which the superimposer and the pair finder cannot use. This selection keeps one peak per analyte and spreads the peaks over the map:

The MS1 peaks are binned into a grid of rt_bins x mz_bins cells over the RT and m/z range of the MS1 peaks. Each cell keeps only its most intense candidates, at first a multiple of its share of n, so that memory stays proportional to n. Steps 1 to 3 are repeated with more candidates for each cell whose candidates were cut off where that was too few: step 3 would take further peaks from the cell (e.g. because other cells are empty, or its candidates belong to only a few analytes), or a cut-off peak of the cell may belong to the analyte of a peak selected from another cell (e.g. an elution profile that crosses the cell border, with the apex cut off). The selection is thus practically the one with all MS1 peaks as candidates, at a fraction of the memory.
Going from the most intense candidate down, a candidate is accepted unless an accepted peak lies within rt_window (in seconds) of it at the same m/z, or at an isotope position m/z +/- k * 1.0033548378 / z (k = 1..3, z = 1..max_charge), within mz_tolerance_ppm. The accepted peaks are the apices of different analytes.
The accepted peaks are taken round-robin over the grid cells (the most intense of each cell first, then the second most intense of each cell, ...), until n peaks are selected.

Fewer than n peaks are selected if fewer analytes are found. The selected peaks are ordered by descending intensity (equal intensities by RT, then m/z), and output is otherwise set up as by selectPeaks_().

Exceptions

Exception::InvalidValue if an MS1 peak has a NaN intensity or a non-finite m/z, or a non-empty MS1 spectrum has a non-finite RT

◆ setReference() [1/2]

void setReference ( const FeatureMap & map )

Sets the reference for the alignment: the 'max_num_peaks_considered' most intense features of map.

◆ setReference() [2/2]

void setReference ( const PeakMap & map )

Sets the reference for the alignment: 'max_num_peaks_considered' MS1 peaks of map, selected as set by 'peak_selection:method'.

◆ updateMembers_()

void updateMembers_ ( )

overrideprotectedvirtual

This method is used to update extra member variables at the end of the setParameters() method.

Also call it at the end of the derived classes' copy constructor and assignment operator.

The default implementation is empty.

Reimplemented from DefaultParamHandler.

Member Data Documentation

◆ max_num_peaks_considered_

Int max_num_peaks_considered_

protected

◆ pairfinder_

StablePairFinder pairfinder_

protected

◆ reference_

ConsensusMap reference_

protected

◆ spread_max_charge_

Size spread_max_charge_ = 4

protected

◆ spread_mz_bins_

Size spread_mz_bins_ = 10

protected

◆ spread_mz_tolerance_ppm_

double spread_mz_tolerance_ppm_ = 10.0

protected

◆ spread_peaks_

bool spread_peaks_ = true

protected

'peak_selection:' parameters

◆ spread_rt_bins_

Size spread_rt_bins_ = 10

protected

◆ spread_rt_window_

double spread_rt_window_ = 20.0

protected

◆ superimposer_

PoseClusteringAffineSuperimposer superimposer_

protected

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MapAlignmentAlgorithmPoseClustering() [1/2]

◆ ~MapAlignmentAlgorithmPoseClustering()

◆ MapAlignmentAlgorithmPoseClustering() [2/2]

Member Function Documentation

◆ align() [1/3]

◆ align() [2/3]

◆ align() [3/3]

◆ operator=()

◆ selectFeatures_()

◆ selectPeakLandmarks_()

◆ selectPeaks_()

◆ selectSpreadPeaks_()

◆ setReference() [1/2]

◆ setReference() [2/2]

◆ updateMembers_()

Member Data Documentation

◆ max_num_peaks_considered_

◆ pairfinder_

◆ reference_

◆ spread_max_charge_

◆ spread_mz_bins_

◆ spread_mz_tolerance_ppm_

◆ spread_peaks_

◆ spread_rt_bins_

◆ spread_rt_window_

◆ superimposer_