MetaboliteSpectralMatching Class Reference

Metabolomics spectral-library search by hyperscore. More...

#include <OpenMS/ANALYSIS/ID/MetaboliteSpectralMatching.h>

Inheritance diagram for MetaboliteSpectralMatching:

Collaboration diagram for MetaboliteSpectralMatching:

Public Member Functions
	MetaboliteSpectralMatching ()
	Default constructor; installs the search parameters (see class docs)
	~MetaboliteSpectralMatching () override
	Default destructor.
void	run (PeakMap &msexp, PeakMap &spec_db, MzTab &mztab_out, std::string &out_spectra)
	Run the metabolomics spectral-library search and populate the MzTab output.
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)

Static Public Member Functions
static double	computeHyperScore (double fragment_mass_error, bool fragment_mass_tolerance_unit_ppm, const MSSpectrum &exp_spectrum, const MSSpectrum &db_spectrum, double mz_lower_bound=0.0)
	Compute the X!Tandem-style hyperscore for one experimental vs. DB spectrum pair.
static double	computeHyperScore (double fragment_mass_error, bool fragment_mass_tolerance_unit_ppm, const MSSpectrum &exp_spectrum, const MSSpectrum &db_spectrum, std::vector< PeptideHit::PeakAnnotation > &annotations, double mz_lower_bound=0.0)
	Same as the other overload, but also fills annotations with per-peak match metadata.
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.

Protected Member Functions
void	updateMembers_ () override
	This method is used to update extra member variables at the end of the setParameters() 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 double	computeHyperScore_ (double fragment_mass_error, bool fragment_mass_tolerance_unit_ppm, const MSSpectrum &exp_spectrum, const MSSpectrum &db_spectrum, std::vector< PeptideHit::PeakAnnotation > *annotations=0, double mz_lower_bound=0.0)
	Shared implementation behind the two public computeHyperScore() overloads; uses a pointer for annotations because mutable references cannot carry a temporary default value.

Private Member Functions
void	exportMzTab_ (const std::vector< SpectralMatch > &, MzTab &)
	Convert the accumulated SpectralMatch records into an MzTab table.

Private Attributes
double	precursor_mz_error_
	Precursor m/z tolerance (value); unit per mz_error_unit_.
double	fragment_mz_error_
	Fragment m/z tolerance (value); unit per mz_error_unit_.
std::string	mz_error_unit_
	"ppm" or "Da"
std::string	ion_mode_
	Cached value of parameter "ionization_mode"; "positive" or "negative"; pre-filters DB spectra by precursor-charge sign.
std::string	report_mode_
	Cached value of parameter "report_mode"; only "top3" or "best" are valid — controls whether the top 3 or only the single best match per spectrum is exported to MzTab.
bool	merge_spectra_
	If true, merge same-precursor MS2 spectra before searching.
double	ccs_error_percent_
	Cached value of parameter "ccs_error_percent"; allowed CCS error in percent for filtering candidates (0 = filtering disabled)

Additional Inherited Members
Public Types inherited from ProgressLogger
enum	LogType { CMD , GUI , NONE }
	Possible log types. More...
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_
Static Protected Attributes inherited from ProgressLogger
static int	recursion_depth_

Detailed Description

Metabolomics spectral-library search by hyperscore.

Matches the MS2 spectra in an experimental PeakMap against the MS2 spectra of a spectral library (the .cpp recognises GNPS- and MassBank-style metadata on the DB-side spectrum — see SpectralMatch::getPrimaryIdentifier for the actual lookup chain) and emits the matching results as an MzTab table.

Pipeline:

1. Sort the library by precursor m/z (using PrecursorMassComparator) for fast lookup.
2. Apply WindowMower noise reduction to each experimental MS2 spectrum.
3. For each experimental MS2 spectrum, select DB spectra whose precursor is within the configured precursor m/z tolerance and ion-mode filter (parameter "ionization_mode", values "positive" or "negative").
4. Score each candidate via computeHyperScore — the hyperscore formula popularised by X!Tandem, log(dot_product) + log(factorial(matched_ions)). Matches with fewer than three matched ions are scored 0.
5. Sort matches per spectrum by score (using the SpectralMatchScoreComparator instance SpectralMatchScoreGreater) and emit either the top three or only the single best match per spectrum according to parameter "report_mode" (only "top3" or "best" are valid values) to MzTab.

Optionally, candidates can additionally be filtered by collision cross section (CCS / ion mobility): when parameter "ccs_error_percent" is greater than 0, a candidate is discarded if the relative CCS error |observed - library| / library * 100 exceeds the configured percentage. The experimental CCS is taken (in this order) from a CCS-unit drift time, a 1/K0 (VSSC) drift time converted via IMTypes::oneOverK0ToCCS, or a numeric "CCS" meta value; the library CCS is taken from the DB-side spectrum the same way. If either side has no CCS, the candidate is kept (CCS does not penalise data lacking ion mobility). The observed/library CCS and the relative CCS error are always exported to MzTab when available.

Configuration is exposed through DefaultParamHandler — see the defaults installed by the constructor for the supported keys ("prec_mass_error_value", "frag_mass_error_value", "mass_error_unit", "ionization_mode", "report_mode", "merge_spectra", "ccs_error_percent").

Constructor & Destructor Documentation

MetaboliteSpectralMatching()

MetaboliteSpectralMatching

(

)

Default constructor; installs the search parameters (see class docs)

~MetaboliteSpectralMatching()

~MetaboliteSpectralMatching ( )

override

Default destructor.

Member Function Documentation

computeHyperScore() [1/2]

static double computeHyperScore ( double  fragment_mass_error, bool  fragment_mass_tolerance_unit_ppm, const MSSpectrum &  exp_spectrum, const MSSpectrum &  db_spectrum, double  mz_lower_bound = 0.0  )

static

Compute the X!Tandem-style hyperscore for one experimental vs. DB spectrum pair.

Formula: log(dot_product) + log(factorial(matched_ions)). The dot product sums (db_intensity * exp_intensity) over peak pairs where the experimental peak is within fragment_mass_error of a DB peak (ppm or Th per fragment_mass_tolerance_unit_ppm). Matches that find fewer than three matched ions return 0; matched-ion counts above boost::math::max_factorial saturate at the maximum factorial. Negative hyperscores are clamped to 0.

Parameters

[in]	fragment_mass_error	Fragment-ion tolerance (value).
[in]	fragment_mass_tolerance_unit_ppm	If true, fragment_mass_error is in ppm; otherwise Th.
[in]	exp_spectrum	Experimental MS2 spectrum (sorted by m/z).
[in]	db_spectrum	DB MS2 spectrum (sorted by m/z).
[in]	mz_lower_bound	Minimum m/z to consider; peaks below this are ignored. Default 0.0.

Returns

Hyperscore (>= 0; 0 if fewer than three matched peaks).

Referenced by NucleicAcidSearchEngine::main_().

computeHyperScore() [2/2]

static double computeHyperScore ( double  fragment_mass_error, bool  fragment_mass_tolerance_unit_ppm, const MSSpectrum &  exp_spectrum, const MSSpectrum &  db_spectrum, std::vector< PeptideHit::PeakAnnotation > &  annotations, double  mz_lower_bound = 0.0  )

static

Same as the other overload, but also fills annotations with per-peak match metadata.

Annotations are produced only when the DB spectrum carries a MSSpectrum::StringDataArray (annotation string) and a MSSpectrum::IntegerDataArray (charge) — otherwise this overload behaves like the no-annotation form.

Parameters

[in]	fragment_mass_error	Fragment-ion tolerance (value).
[in]	fragment_mass_tolerance_unit_ppm	If true, fragment_mass_error is in ppm; otherwise Th.
[in]	exp_spectrum	Experimental MS2 spectrum (sorted by m/z).
[in]	db_spectrum	DB MS2 spectrum (sorted by m/z).
[out]	annotations	Per-matched-peak annotations (annotation string, charge, m/z, intensity); appended to.
[in]	mz_lower_bound	Minimum m/z to consider; peaks below this are ignored.

Returns

Hyperscore (>= 0; 0 if fewer than three matched peaks).

computeHyperScore_()

static double computeHyperScore_ ( double  fragment_mass_error, bool  fragment_mass_tolerance_unit_ppm, const MSSpectrum &  exp_spectrum, const MSSpectrum &  db_spectrum, std::vector< PeptideHit::PeakAnnotation > *  annotations = 0, double  mz_lower_bound = 0.0  )

staticprotected

Shared implementation behind the two public computeHyperScore() overloads; uses a pointer for annotations because mutable references cannot carry a temporary default value.

exportMzTab_()

void exportMzTab_ ( const std::vector< SpectralMatch > &  , MzTab &    )

private

Convert the accumulated SpectralMatch records into an MzTab table.

run()

void run	(	PeakMap &	msexp,
		PeakMap &	spec_db,
		MzTab &	mztab_out,
		std::string &	out_spectra
	)

Run the metabolomics spectral-library search and populate the MzTab output.

Implements the pipeline described in the class brief: sort the DB by precursor m/z, noise-reduce each experimental MS2 via WindowMower, score candidate library spectra, keep the top-N per query, and export to MzTab.

Parameters

[in,out]	msexp	Experimental MS2 spectra. Modified in place by the noise-reduction step.
[in,out]	spec_db	Spectral library; will be sorted by precursor m/z.
[out]	mztab_out	MzTab result table populated with the top matches.
[in]	out_spectra	If non-empty, the (noise-reduced) experimental spectra are also written to this mzML path.

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

ccs_error_percent_

double ccs_error_percent_

private

Cached value of parameter "ccs_error_percent"; allowed CCS error in percent for filtering candidates (0 = filtering disabled)

fragment_mz_error_

double fragment_mz_error_

private

Fragment m/z tolerance (value); unit per mz_error_unit_.

ion_mode_

std::string ion_mode_

private

Cached value of parameter "ionization_mode"; "positive" or "negative"; pre-filters DB spectra by precursor-charge sign.

merge_spectra_

bool merge_spectra_

private

If true, merge same-precursor MS2 spectra before searching.

mz_error_unit_

std::string mz_error_unit_

private

"ppm" or "Da"

precursor_mz_error_

double precursor_mz_error_

private

Precursor m/z tolerance (value); unit per mz_error_unit_.

report_mode_

std::string report_mode_

private

Cached value of parameter "report_mode"; only "top3" or "best" are valid — controls whether the top 3 or only the single best match per spectrum is exported to MzTab.