Abstract base class for fitting an RT-shape model to one or more mass traces. More...

#include <OpenMS/FEATUREFINDER/TraceFitter.h>

Inheritance diagram for TraceFitter:

Collaboration diagram for TraceFitter:

Classes
class	GenericFunctor
	Generic LM functor with a raw-pointer interface, used to keep Eigen out of the public API. More...

struct	ModelData
	Helper bundle passed to functors so they can read both the traces and the weighting flag. More...

Public Member Functions
	TraceFitter ()
	Default constructor; registers the `"max_iteration"` and `"weighted"` defaults on DefaultParamHandler.

	TraceFitter (const TraceFitter &source)
	Copy constructor.

TraceFitter &	operator= (const TraceFitter &source)
	Assignment operator.

	~TraceFitter () override
	Destructor.

virtual void	fit (FeatureFinderAlgorithmPickedHelperStructs::MassTraces &traces)=0
	Run the LM fit on `traces`.

virtual double	getLowerRTBound () const =0
	Lower RT bound of the fitted RT model.

virtual double	getUpperRTBound () const =0
	Upper RT bound of the fitted RT model.

virtual double	getHeight () const =0
	Height of the fitted RT model at its centre.

virtual double	getCenter () const =0
	Centre of the fitted RT model.

virtual double	getFWHM () const =0
	Full width at half maximum of the fitted RT model.

virtual double	getValue (double rt) const =0
	Evaluate the fitted model at retention time `rt`.

double	computeTheoretical (const FeatureFinderAlgorithmPickedHelperStructs::MassTrace &trace, Size k) const
	Evaluate the fitted model at the RT of the `k-th` peak of `trace`, scaled by the trace's theoretical intensity.

virtual bool	checkMinimalRTSpan (const std::pair< double, double > &rt_bounds, const double min_rt_span)=0
	Whether the fitted RT model covers at least `min_rt_span` of the extended search area.

virtual bool	checkMaximalRTSpan (const double max_rt_span)=0
	Whether the fitted RT model stays within `max_rt_span` of the extended search area.

virtual double	getArea ()=0
	Area under the fitted RT model.

virtual std::string	getGnuplotFormula (const FeatureFinderAlgorithmPickedHelperStructs::MassTrace &trace, const char function_name, const double baseline, const double rt_shift)=0
	Gnuplot expression of the fitted model for `trace`.

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.

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

virtual void	getOptimizedParameters_ (const std::vector< double > &s)=0
	Subclass hook: copy the optimised parameter vector back into the subclass's model fields.

void	optimize_ (std::vector< double > &x_init, GenericFunctor &functor)
	Run Levenberg-Marquardt on `functor` starting from `x_init`.

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

Protected Attributes
SignedSize	max_iterations_
	Maximum number of LM iterations; refreshed from `"max_iteration"` in updateMembers_.

bool	weighted_
	Whether mass traces are weighted by theoretical intensity during fitting; refreshed from `"weighted"` in updateMembers_.

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

Additional Inherited Members
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.

Detailed Description

Abstract base class for fitting an RT-shape model to one or more mass traces.

Provides the shared parameter handling and a Levenberg-Marquardt driver (optimize_) for subclasses that supply a concrete RT profile (Gaussian, EGH, ...). Subclasses implement fit, the geometric query methods (getLowerRTBound, getUpperRTBound, getHeight, getCenter, getFWHM, getValue, getArea), the validation hooks (checkMinimalRTSpan, checkMaximalRTSpan), the plot helper getGnuplotFormula, and getOptimizedParameters_.

Parameters

"max_iteration" (singular): maximum number of LM iterations (default 500).
"weighted" ("true"/"false"): whether mass traces are weighted by their theoretical intensity during fitting (default "false"). The flag is exposed as weighted_ for use by subclasses.

Class Documentation

◆ OpenMS::TraceFitter::ModelData

struct OpenMS::TraceFitter::ModelData

Helper bundle passed to functors so they can read both the traces and the weighting flag.

Collaboration diagram for TraceFitter::ModelData:

[legend]

Class Members
MassTraces *	traces_ptr	Mass traces being fitted.
bool	weighted	Mirror of weighted_ at fit time.

Constructor & Destructor Documentation

◆ TraceFitter() [1/2]

TraceFitter ( )

Default constructor; registers the "max_iteration" and "weighted" defaults on DefaultParamHandler.

◆ TraceFitter() [2/2]

TraceFitter ( const TraceFitter & source )

Copy constructor.

◆ ~TraceFitter()

~TraceFitter ( )

override

Destructor.

Member Function Documentation

◆ checkMaximalRTSpan()

virtual bool checkMaximalRTSpan ( const double max_rt_span )

pure virtual

Whether the fitted RT model stays within max_rt_span of the extended search area.

Parameters

[in] max_rt_span Maximum allowed RT span of the fitted model relative to the extended search area, as a fraction.

Returns: true when the model does not exceed max_rt_span of the search area.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ checkMinimalRTSpan()

virtual bool checkMinimalRTSpan	(	const std::pair< double, double > &	rt_bounds,
		const double	min_rt_span
	)

pure virtual

Whether the fitted RT model covers at least min_rt_span of the extended search area.

Parameters

[in]	rt_bounds	RT boundaries of the extended search area (lower, upper).
[in]	min_rt_span	Minimum RT span the fitted model must cover relative to `rt_bounds`, as a fraction.

Returns: true when the model spans at least min_rt_span of the search area.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ computeTheoretical()

double computeTheoretical	(	const FeatureFinderAlgorithmPickedHelperStructs::MassTrace &	trace,
		Size	k
	)		const

Evaluate the fitted model at the RT of the k-th peak of trace, scaled by the trace's theoretical intensity.

Parameters

[in]	trace	Mass trace; only the RT of its `k-th` peak is read.
[in]	k	Index of the peak in `trace.peaks`.

Returns: trace.theoretical_int * getValue(trace.peaks[k].first).

◆ fit()

virtual void fit ( FeatureFinderAlgorithmPickedHelperStructs::MassTraces & traces )

pure virtual

Run the LM fit on traces.

Subclasses fill the model parameters and (typically) call optimize_ on a problem-specific functor.

Parameters

[in,out] traces Mass traces to fit; subclasses may set additional bookkeeping on traces.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getArea()

virtual double getArea ( )

pure virtual

Area under the fitted RT model.

Returns: Integrated intensity of the fitted model.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getCenter()

virtual double getCenter ( ) const

pure virtual

Centre of the fitted RT model.

Returns: Centre retention time of the fitted model.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getFWHM()

virtual double getFWHM ( ) const

pure virtual

Full width at half maximum of the fitted RT model.

Returns: FWHM in retention-time units.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getGnuplotFormula()

virtual std::string getGnuplotFormula	(	const FeatureFinderAlgorithmPickedHelperStructs::MassTrace &	trace,
		const char	function_name,
		const double	baseline,
		const double	rt_shift
	)

pure virtual

Gnuplot expression of the fitted model for trace.

Parameters

[in]	trace	Mass trace whose theoretical intensity scales the expression.
[in]	function_name	Name of the function in the resulting expression (e.g. `'f'` for `"f(x)"`).
[in]	baseline	Intensity of the plotted baseline.
[in]	rt_shift	RT offset added to the expression so several traces can be plotted side by side (typically `0` for the first trace and incremented for subsequent traces).

Returns: Gnuplot expression as a String.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getHeight()

virtual double getHeight ( ) const

pure virtual

Height of the fitted RT model at its centre.

Returns: Model intensity at the centre RT.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getLowerRTBound()

virtual double getLowerRTBound ( ) const

pure virtual

Lower RT bound of the fitted RT model.

Returns: Lower RT bound (retention-time units).

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getOptimizedParameters_()

virtual void getOptimizedParameters_ ( const std::vector< double > & s )

protectedpure virtual

Subclass hook: copy the optimised parameter vector back into the subclass's model fields.

Called by optimize_ after the LM solver has converged.

Parameters

[in] s Optimised parameter vector (size matches the functor's inputs).

Implemented in GaussTraceFitter, and EGHTraceFitter.

◆ getUpperRTBound()

virtual double getUpperRTBound ( ) const

pure virtual

Upper RT bound of the fitted RT model.

Returns: Upper RT bound (retention-time units).

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ getValue()

virtual double getValue ( double rt ) const

pure virtual

Evaluate the fitted model at retention time rt.

Parameters

[in] rt Retention time at which to evaluate the model.

Returns: Model intensity at rt.

Implemented in EGHTraceFitter, and GaussTraceFitter.

◆ operator=()

TraceFitter & operator= ( const TraceFitter & source )

Assignment operator.

◆ optimize_()

void optimize_	(	std::vector< double > &	x_init,
		GenericFunctor &	functor
	)

protected

Run Levenberg-Marquardt on functor starting from x_init.

On return, x_init holds the optimised parameter vector and getOptimizedParameters_ has been called. The LM iteration limit is taken from the "max_iteration" parameter.

Parameters

[in,out]	x_init	Initial parameter vector; replaced with the optimised vector on success.
[in,out]	functor	LM functor providing residuals and the Jacobian.

Exceptions

Exception::UnableToFit when the number of residuals reported by functor is smaller than its number of free parameters, or when the LM solver reports a non-recoverable state (NotStarted / Running / ImproperInputParameters).

◆ 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_iterations_

SignedSize max_iterations_

protected

Maximum number of LM iterations; refreshed from "max_iteration" in updateMembers_.

◆ weighted_

bool weighted_

protected

Whether mass traces are weighted by theoretical intensity during fitting; refreshed from "weighted" in updateMembers_.

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Class Documentation

◆ OpenMS::TraceFitter::ModelData

Constructor & Destructor Documentation

◆ TraceFitter() [1/2]

◆ TraceFitter() [2/2]

◆ ~TraceFitter()

Member Function Documentation

◆ checkMaximalRTSpan()

◆ checkMinimalRTSpan()

◆ computeTheoretical()

◆ fit()

◆ getArea()

◆ getCenter()

◆ getFWHM()

◆ getGnuplotFormula()

◆ getHeight()

◆ getLowerRTBound()

◆ getOptimizedParameters_()

◆ getUpperRTBound()

◆ getValue()

◆ operator=()

◆ optimize_()

◆ updateMembers_()

Member Data Documentation

◆ max_iterations_

◆ weighted_