OpenMS
MassTraceDetection Class Reference

A mass trace extraction method that gathers peaks similar in m/z and moving along retention time. More...

#include <OpenMS/FEATUREFINDER/MassTraceDetection.h>

Inheritance diagram for MassTraceDetection:
[legend]
Collaboration diagram for MassTraceDetection:
[legend]

Classes

struct  Apex
 
struct  PeakCandidate
 Encapsulates peak finding logic for both up and down directions. More...
 
struct  TraceExtensionState
 Encapsulates trace extension state. More...
 

Public Types

enum  TraceTerminationCriterion { OUTLIER , SAMPLE_RATE }
 Trace termination criteria enum for performance optimization. More...
 
- Public Types inherited from ProgressLogger
enum  LogType { CMD , GUI , NONE }
 Possible log types. More...
 

Public Member Functions

 MassTraceDetection ()
 Default constructor. More...
 
 ~MassTraceDetection () override
 Default destructor. More...
 
Main computation methods
void run (const PeakMap &, std::vector< MassTrace > &, const Size max_traces=0)
 Main method of MassTraceDetection. Extracts mass traces of a MSExperiment and gathers them into a vector container. More...
 
void run (PeakMap::ConstAreaIterator &begin, PeakMap::ConstAreaIterator &end, std::vector< MassTrace > &found_masstraces)
 Invokes the run method (see above) on merely a subregion of a MSExperiment map. More...
 
bool hasFwhmMz () const
 determine if meta array is available More...
 
bool hasFwhmIm () const
 
bool hasCentroidIm () const
 
- 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...
 
DefaultParamHandleroperator= (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 ParamgetParameters () const
 Non-mutable access to the parameters. More...
 
const ParamgetDefaults () const
 Non-mutable access to the default parameters. More...
 
const StringgetName () 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...
 
virtual ~ProgressLogger ()
 Destructor. More...
 
 ProgressLogger (const ProgressLogger &other)
 Copy constructor. More...
 
ProgressLoggeroperator= (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 setLogger (ProgressLoggerImpl *logger)
 Sets the logger to be used for progress logging. 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 (UInt64 bytes_processed=0) const
 
void nextProgress () const
 increment progress by 1 (according to range begin-end) More...
 

Private methods and members

bool has_fwhm_mz_ = false
 
bool has_fwhm_im_ = false
 
bool has_centroid_im_ = false
 
double mass_error_ppm_
 
double mass_error_da_
 
double noise_threshold_int_
 
double chrom_peak_snr_
 
double ion_mobility_tolerance_
 
MassTrace::MT_QUANTMETHOD quant_method_
 
TraceTerminationCriterion trace_termination_criterion_
 
Size trace_termination_outliers_
 
double min_sample_rate_
 
double min_trace_length_
 
double max_trace_length_
 
bool reestimate_mt_sd_
 
int fwhm_meta_idx_ = -1
 
int ion_mobility_idx_ = -1
 
int im_fwhm_idx_ = -1
 
void updateMembers_ () override
 This method is used to update extra member variables at the end of the setParameters() method. More...
 
static void updateIterativeWeightedMean_ (const double &added_value, const double &added_intensity, double &centroid_value, double &prev_counter, double &prev_denom)
 allows for the iterative computation of intensity weighted of a mass trace's centroid m/z or ion mobility More...
 
void run_ (const std::vector< Apex > &chrom_apices, const Size peak_count, const PeakMap &work_exp, const std::vector< Size > &spec_offsets, std::vector< MassTrace > &found_masstraces, const Size max_traces=0)
 The internal run method. More...
 
void getIMIndices_ (const PeakMap &spectra, int &fwhm_meta_idx, bool &has_fwhm_mz, int &im_idx, bool &has_centroid_im, int &im_fwhm_idx, bool &has_fwhm_im) const
 Internal helper to extract and validate metadata float array indices. More...
 
PeakCandidate findBestPeak_ (const MSSpectrum &spectrum, double centroid_mz, double ftl_sd, double centroid_im=-1.0) const
 Find the best matching peak in a spectrum considering m/z and optionally ion mobility. More...
 
bool isPeakAcceptable_ (const PeakCandidate &candidate, double centroid_mz, double ftl_sd, double centroid_im, Size spectrum_idx, const std::vector< Size > &spec_offsets, const boost::dynamic_bitset<> &peak_visited) const
 Check if peak candidate meets acceptance criteria. More...
 
void processPeak_ (const PeakCandidate &candidate, const MSSpectrum &spectrum, std::list< PeakType > &current_trace, std::vector< std::pair< Size, Size >> &gathered_idx, std::vector< double > &fwhms_mz, std::vector< double > &fwhms_im, double &centroid_mz, double &centroid_im, double &prev_counter, double &prev_denom, double &prev_counter_im, double &prev_denom_im, double &ftl_sd, double &intensity_so_far, Size spectrum_idx, bool is_upward_extension)
 Process a single peak during trace extension. More...
 
bool isTraceValid_ (const std::list< PeakType > &trace, Size total_scans_visited, Size consecutive_missed_down, Size consecutive_missed_up) const
 Check if a mass trace meets quality criteria. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from DefaultParamHandler
static void writeParametersToMetaValues (const Param &write_this, MetaInfoInterface &write_here, const String &key_prefix="")
 Writes all parameters to meta values. More...
 
- Protected Member Functions inherited from DefaultParamHandler
void defaultsToParam_ ()
 Updates the parameters after the defaults have been set in the constructor. 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< Stringsubsections_
 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_
 
ProgressLoggerImplcurrent_logger_
 
- Static Protected Attributes inherited from ProgressLogger
static int recursion_depth_
 

Detailed Description

A mass trace extraction method that gathers peaks similar in m/z and moving along retention time.

Peaks of a MSExperiment are sorted by their intensity and stored in a list of potential chromatographic apex positions. Only peaks that are above the noise threshold (user-defined) are analyzed and only peaks that are n times above this minimal threshold are considered as apices. This saves computational resources and decreases the noise in the resulting output.

Starting with these, mass traces are extended in- and decreasingly in retention time. During this extension phase, the centroid m/z is computed on-line as an intensity-weighted mean of peaks.

The extension phase ends when either the frequency of gathered peaks drops below a threshold (min_sample_rate, see MassTraceDetection parameters) or when the number of missed scans exceeds a threshold (trace_termination_outliers, see MassTraceDetection parameters).

Finally, only mass traces that pass a filter (a certain minimal and maximal length as well as having the minimal sample rate criterion fulfilled) get added to the result.

Parameters of this class are:

NameTypeDefaultRestrictionsDescription
mass_error_ppm float20.0  Allowed mass deviation (in ppm).
noise_threshold_int float10.0  Intensity threshold below which peaks are removed as noise.
chrom_peak_snr float3.0  Minimum intensity above noise_threshold_int (signal-to-noise) a peak should have to be considered an apex.
ion_mobility_tolerance float0.01  Allowed ion mobility deviation (in 1/k0).
reestimate_mt_sd stringtrue true, falseEnables dynamic re-estimation of m/z variance during mass trace collection stage.
quant_method stringarea area, median, max_heightMethod of quantification for mass traces. For LC data 'area' is recommended, 'median' for direct injection data. 'max_height' simply uses the most intense peak in the trace.
trace_termination_criterion stringoutlier outlier, sample_rateTermination criterion for the extension of mass traces. In 'outlier' mode, trace extension cancels if a predefined number of consecutive outliers are found (see trace_termination_outliers parameter). In 'sample_rate' mode, trace extension in both directions stops if ratio of found peaks versus visited spectra falls below the 'min_sample_rate' threshold.
trace_termination_outliers int5  Mass trace extension in one direction cancels if this number of consecutive spectra with no detectable peaks is reached.
min_sample_rate float0.5  Minimum fraction of scans along the mass trace that must contain a peak.
min_trace_length float5.0  Minimum expected length of a mass trace (in seconds).
max_trace_length float-1.0  Maximum expected length of a mass trace (in seconds). Set to a negative value to disable maximal length check during mass trace detection.

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

Member Enumeration Documentation

◆ TraceTerminationCriterion

Trace termination criteria enum for performance optimization.

Enumerator
OUTLIER 

Terminate when consecutive outliers exceed threshold.

SAMPLE_RATE 

Terminate when sample rate falls below threshold.

Constructor & Destructor Documentation

◆ MassTraceDetection()

Default constructor.

◆ ~MassTraceDetection()

~MassTraceDetection ( )
override

Default destructor.

Member Function Documentation

◆ findBestPeak_()

PeakCandidate findBestPeak_ ( const MSSpectrum spectrum,
double  centroid_mz,
double  ftl_sd,
double  centroid_im = -1.0 
) const
private

Find the best matching peak in a spectrum considering m/z and optionally ion mobility.

◆ getIMIndices_()

void getIMIndices_ ( const PeakMap spectra,
int &  fwhm_meta_idx,
bool &  has_fwhm_mz,
int &  im_idx,
bool &  has_centroid_im,
int &  im_fwhm_idx,
bool &  has_fwhm_im 
) const
private

Internal helper to extract and validate metadata float array indices.

◆ hasCentroidIm()

bool hasCentroidIm ( ) const
inline

◆ hasFwhmIm()

bool hasFwhmIm ( ) const
inline

◆ hasFwhmMz()

bool hasFwhmMz ( ) const
inline

determine if meta array is available

◆ isPeakAcceptable_()

bool isPeakAcceptable_ ( const PeakCandidate candidate,
double  centroid_mz,
double  ftl_sd,
double  centroid_im,
Size  spectrum_idx,
const std::vector< Size > &  spec_offsets,
const boost::dynamic_bitset<> &  peak_visited 
) const
private

Check if peak candidate meets acceptance criteria.

◆ isTraceValid_()

bool isTraceValid_ ( const std::list< PeakType > &  trace,
Size  total_scans_visited,
Size  consecutive_missed_down,
Size  consecutive_missed_up 
) const
private

Check if a mass trace meets quality criteria.

◆ processPeak_()

void processPeak_ ( const PeakCandidate candidate,
const MSSpectrum spectrum,
std::list< PeakType > &  current_trace,
std::vector< std::pair< Size, Size >> &  gathered_idx,
std::vector< double > &  fwhms_mz,
std::vector< double > &  fwhms_im,
double &  centroid_mz,
double &  centroid_im,
double &  prev_counter,
double &  prev_denom,
double &  prev_counter_im,
double &  prev_denom_im,
double &  ftl_sd,
double &  intensity_so_far,
Size  spectrum_idx,
bool  is_upward_extension 
)
private

Process a single peak during trace extension.

◆ run() [1/2]

void run ( const PeakMap ,
std::vector< MassTrace > &  ,
const Size  max_traces = 0 
)

Main method of MassTraceDetection. Extracts mass traces of a MSExperiment and gathers them into a vector container.

◆ run() [2/2]

void run ( PeakMap::ConstAreaIterator begin,
PeakMap::ConstAreaIterator end,
std::vector< MassTrace > &  found_masstraces 
)

Invokes the run method (see above) on merely a subregion of a MSExperiment map.

◆ run_()

void run_ ( const std::vector< Apex > &  chrom_apices,
const Size  peak_count,
const PeakMap work_exp,
const std::vector< Size > &  spec_offsets,
std::vector< MassTrace > &  found_masstraces,
const Size  max_traces = 0 
)
private

The internal run method.

◆ updateIterativeWeightedMean_()

static void updateIterativeWeightedMean_ ( const double &  added_value,
const double &  added_intensity,
double &  centroid_value,
double &  prev_counter,
double &  prev_denom 
)
staticprotected

allows for the iterative computation of intensity weighted of a mass trace's centroid m/z or ion mobility

◆ 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

◆ chrom_peak_snr_

double chrom_peak_snr_
private

◆ fwhm_meta_idx_

int fwhm_meta_idx_ = -1
mutableprivate

◆ has_centroid_im_

bool has_centroid_im_ = false
private

◆ has_fwhm_im_

bool has_fwhm_im_ = false
private

◆ has_fwhm_mz_

bool has_fwhm_mz_ = false
private

◆ im_fwhm_idx_

int im_fwhm_idx_ = -1
mutableprivate

◆ ion_mobility_idx_

int ion_mobility_idx_ = -1
mutableprivate

◆ ion_mobility_tolerance_

double ion_mobility_tolerance_
private

◆ mass_error_da_

double mass_error_da_
private

◆ mass_error_ppm_

double mass_error_ppm_
private

◆ max_trace_length_

double max_trace_length_
private

◆ min_sample_rate_

double min_sample_rate_
private

◆ min_trace_length_

double min_trace_length_
private

◆ noise_threshold_int_

double noise_threshold_int_
private

◆ quant_method_

MassTrace::MT_QUANTMETHOD quant_method_
private

◆ reestimate_mt_sd_

bool reestimate_mt_sd_
private

◆ trace_termination_criterion_

TraceTerminationCriterion trace_termination_criterion_
private

◆ trace_termination_outliers_

Size trace_termination_outliers_
private