TransformationDescription Class Reference

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.
typedef TransformationModel::DataPoints	DataPoints
	Vector of coordinate pairs.

Public Member Functions
	TransformationDescription ()
	Default constructor.
	TransformationDescription (const DataPoints &data)
	Constructor from data.
	~TransformationDescription ()
	Destructor.
	TransformationDescription (const TransformationDescription &rhs)
	Copy constructor.
TransformationDescription &	operator= (const TransformationDescription &rhs)
	Assignment operator.
void	fitModel (const String &model_type, const Param &params=Param())
	Fits a model to the data.
double	apply (double value) const
	Applies the transformation to value.
const String &	getModelType () const
	Gets the type of the fitted model.
void	setDataPoints (const DataPoints &data)
	Sets the data points.
void	setDataPoints (const std::vector< std::pair< double, double > > &data)
	Sets the data points (backwards-compatible overload)
const DataPoints &	getDataPoints () const
	Returns the data points.
const Param &	getModelParameters () const
	Non-mutable access to the model parameters.
void	invert ()
	Computes an (approximate) inverse of the transformation.
void	getDeviations (std::vector< double > &diffs, bool do_apply=false, bool do_sort=true) const
	Get the deviations between the data pairs.
TransformationStatistics	getStatistics () const
	Get summary statistics (ranges and errors before/after)
void	printSummary (std::ostream &os) const
	Print summary statistics for the transformation.
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.

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

Protected Attributes
DataPoints	data_
	Data points.
String	model_type_
	Type of model.
TransformationModel *	model_
	Pointer to model.

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

  [in]	quantile	Quantile of |residual| to use (0 < quantile ≤ 1), e.g. 0.99.
  [in]	invert	If true, compute residuals in original x-units via T^{-1}; otherwise compute in transformed y-units via T.
  [in]	full_window	If true, return full width (2·half-width); else return half-width.
  [in]	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

[out]	diffs	Output
[in]	do_apply	Get deviations after applying the model?
[in]	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.