Generic description of a coordinate transformation. More...

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

Collaboration diagram for TransformationDescription:

Classes
struct	TransformationStatistics
	Summary statistics before/after applying the transformation. For deviations before/after transformation, the percentiles 100, 99, 95, 90, 75, 50, 25 are returned. More...

Public Types
typedef TransformationModel::DataPoint	DataPoint
	Coordinate pair. More...

typedef TransformationModel::DataPoints	DataPoints
	Vector of coordinate pairs. More...

Public Member Functions
	TransformationDescription ()
	Default constructor. More...

	TransformationDescription (const DataPoints &data)
	Constructor from data. More...

	~TransformationDescription ()
	Destructor. More...

	TransformationDescription (const TransformationDescription &rhs)
	Copy constructor. More...

TransformationDescription &	operator= (const TransformationDescription &rhs)
	Assignment operator. More...

void	fitModel (const String &model_type, const Param &params=Param())
	Fits a model to the data. More...

double	apply (double value) const
	Applies the transformation to `value`. More...

const String &	getModelType () const
	Gets the type of the fitted model. More...

void	setDataPoints (const DataPoints &data)
	Sets the data points. More...

void	setDataPoints (const std::vector< std::pair< double, double > > &data)
	Sets the data points (backwards-compatible overload) More...

const DataPoints &	getDataPoints () const
	Returns the data points. More...

const Param &	getModelParameters () const
	Non-mutable access to the model parameters. More...

void	invert ()
	Computes an (approximate) inverse of the transformation. More...

void	getDeviations (std::vector< double > &diffs, bool do_apply=false, bool do_sort=true) const
	Get the deviations between the data pairs. More...

TransformationStatistics	getStatistics () const
	Get summary statistics (ranges and errors before/after) More...

void	printSummary (std::ostream &os) const
	Print summary statistics for the transformation. More...

double	estimateWindow (double quantile=0.99, bool invert=true, bool full_window=true, double padding_factor=1.0) const
	Estimate a coordinate-transformation, residual-based extraction window. More...

Static Public Member Functions
static void	getModelTypes (StringList &result)
	Gets the possible types of models. More...

Protected Attributes
DataPoints	data_
	Data points. More...

String	model_type_
	Type of model. More...

TransformationModel *	model_
	Pointer to model. More...

Detailed Description

Generic description of a coordinate transformation.

This description primarily stores data points (coordinate pairs) from which a transformation model can be estimated. Applying the transformation to a coordinate (via apply) then means evaluating the model at that coordinate.

The following models are available:

none (TransformationModel): \( f(x) = x \) (identity)
identity: Same as none, but intended for reference files (used to indicate that no other model should be fit, because the identity is already optimal).
linear (TransformationModelLinear): \( f(x) = slope * x + intercept \)
interpolated (TransformationModelInterpolated): Interpolation between pairs, extrapolation using first and last pair. Supports different interpolation types.
b-spline (TransformationModelBSpline): Non-linear smoothing spline, with different options for extrapolation.
lowess (TransformationModelLowess): Non-linear smoothing via local regression, with different options for extrapolation.

Remarks: TransformationDescription stores data points, TransformationModel stores parameters. That way, data can be modeled using different models/parameters, and models can still keep a representation of the data in the format they need (if at all).

Member Typedef Documentation

◆ DataPoint

typedef TransformationModel::DataPoint DataPoint

Coordinate pair.

◆ DataPoints

typedef TransformationModel::DataPoints DataPoints

Vector of coordinate pairs.

Constructor & Destructor Documentation

◆ TransformationDescription() [1/3]

TransformationDescription ( )

Default constructor.

◆ TransformationDescription() [2/3]

TransformationDescription ( const DataPoints & data )

explicit

Constructor from data.

◆ ~TransformationDescription()

~TransformationDescription ( )

Destructor.

◆ TransformationDescription() [3/3]

TransformationDescription ( const TransformationDescription & rhs )

Copy constructor.

Member Function Documentation

◆ apply()

double apply ( double value ) const

Applies the transformation to value.

Returns the result of evaluating the fitted model at value. Returns value unchanged if no model was fitted.

◆ estimateWindow()

double estimateWindow	(	double	quantile = `0.99`,
		bool	invert = `true`,
		bool	full_window = `true`,
		double	padding_factor = `1.0`
	)		const

Estimate a coordinate-transformation, residual-based extraction window.

Given stored data points (x_i, y_i) and a fitted transform T relating them, this computes absolute residuals between experimental and theoretical coordinates and returns an extraction window derived from a chosen quantile.
Residual definition:

If invert == false: r_i = | T(x_i) - y_i | (in transformed y units)
If invert == true : r_i = | x_i - T^{-1}(y_i) | (in original x units)
The window is computed using an adaptive quantile that is robust to sparse outliers but permissive when tails are genuinely dense:
1) Let |r| be the absolute residuals. Compute the Tukey upper fence UF = Q3 + k*IQR (with k = 1.5).
2) Compute:
h_raw = quantile(|r|, q)
h_rob = quantile(winsorize(|r|, UF), q), where values above UF are capped at UF (lower cap is 0 for absolute residuals).
3) Let tail = fraction(|r| > UF). Blend h = (1 - w)*h_rob + w*h_raw with a weight w that increases linearly from 0 at tail <= 1% (favor robust) to 1 at tail >= 10% (favor raw). If UF is undefined (too few points or IQR <= 0), the method falls back to the raw quantile.
The chosen quantile q (e.g. 0.99) is interpreted as a half-width h such that approximately q*100% of residuals satisfy |r| <= h. If full_window is true, the function returns 2*h (full width), otherwise h (half-width). The padding_factor multiplies the final result.
Typical usage:
RT: set invert = true to obtain residuals in seconds (original x units).

IM: same pattern; units are the instrument’s native mobility units (e.g., 1/k0).

Parameters

quantile	Quantile of \|residual\| to use (0 < quantile ≤ 1), e.g. 0.99.
invert	If true, compute residuals in original x-units via T^{-1}; otherwise compute in transformed y-units via T.
full_window	If true, return full width (2·half-width); else return half-width.
padding_factor	A padding factor to add to the estimated window.

Returns: Estimated window (in the units implied by invert). If no data points are available, returns 0.0.

◆ fitModel()

void fitModel	(	const String &	model_type,
		const Param &	params = `Param()`
	)

Fits a model to the data.

◆ getDataPoints()

const DataPoints& getDataPoints ( ) const

Returns the data points.

◆ getDeviations()

void getDeviations	(	std::vector< double > &	diffs,
		bool	do_apply = `false`,
		bool	do_sort = `true`
	)		const

Get the deviations between the data pairs.

Parameters

diffs	Output
do_apply	Get deviations after applying the model?
do_sort	Sort `diffs` before returning?

◆ getModelParameters()

const Param& getModelParameters ( ) const

Non-mutable access to the model parameters.

◆ getModelType()

const String& getModelType ( ) const

Gets the type of the fitted model.

◆ getModelTypes()

static void getModelTypes ( StringList & result )

static

Gets the possible types of models.

◆ getStatistics()

TransformationStatistics getStatistics ( ) const

Get summary statistics (ranges and errors before/after)

◆ invert()

void invert ( )

Computes an (approximate) inverse of the transformation.

◆ operator=()

TransformationDescription& operator= ( const TransformationDescription & rhs )

Assignment operator.

◆ printSummary()

void printSummary ( std::ostream & os ) const

Print summary statistics for the transformation.

◆ setDataPoints() [1/2]

void setDataPoints ( const DataPoints & data )

Sets the data points.

Removes the model that was previously fitted to the data (if any).

◆ setDataPoints() [2/2]

void setDataPoints ( const std::vector< std::pair< double, double > > & data )

Sets the data points (backwards-compatible overload)

Removes the model that was previously fitted to the data (if any).

Member Data Documentation

◆ data_

DataPoints data_

protected

Data points.

◆ model_

TransformationModel* model_

protected

Pointer to model.

◆ model_type_

String model_type_

protected

Type of model.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ DataPoint

◆ DataPoints

Constructor & Destructor Documentation

◆ TransformationDescription() [1/3]

◆ TransformationDescription() [2/3]

◆ ~TransformationDescription()

◆ TransformationDescription() [3/3]

Member Function Documentation

◆ apply()

◆ estimateWindow()

◆ fitModel()

◆ getDataPoints()

◆ getDeviations()

◆ getModelParameters()

◆ getModelType()

◆ getModelTypes()

◆ getStatistics()

◆ invert()

◆ operator=()

◆ printSummary()

◆ setDataPoints() [1/2]

◆ setDataPoints() [2/2]

Member Data Documentation

◆ data_

◆ model_

◆ model_type_