OpenMS  2.8.0
Classes | Public Member Functions | Protected Member Functions | Private Attributes | List of all members
TargetedSpectraExtractor Class Reference

This class filters, annotates, picks, and scores spectra (e.g., taken from a DDA experiment) based on a target list. More...

#include <OpenMS/ANALYSIS/OPENSWATH/TargetedSpectraExtractor.h>

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

Classes

class  BinnedSpectrumComparator
 
class  Comparator
 
struct  Match
 

Public Member Functions

 TargetedSpectraExtractor ()
 
 ~TargetedSpectraExtractor () override=default
 
void getDefaultParameters (Param &params) const
 
void annotateSpectra (const std::vector< MSSpectrum > &spectra, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &annotated_spectra, FeatureMap &features, bool compute_features=true) const
 Filters and annotates those spectra that could potentially match the transitions of the target list. More...
 
void annotateSpectra (const std::vector< MSSpectrum > &spectra, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &annotated_spectra) const
 Filters and annotates those spectra that could potentially match the transitions of the target list. More...
 
void annotateSpectra (const std::vector< MSSpectrum > &spectra, const FeatureMap &ms1_features, FeatureMap &ms2_features, std::vector< MSSpectrum > &annotated_spectra) const
 Annotates the MS2 spectra with the likely MS1 feature that it was derived from. More...
 
void searchSpectrum (OpenMS::FeatureMap &feat_map, OpenMS::FeatureMap &feat_map_output) const
 Search accurate masses and add identification (peptide hits) as features/sub-features. More...
 
void pickSpectrum (const MSSpectrum &spectrum, MSSpectrum &picked_spectrum) const
 Picks a spectrum's peaks and saves them in picked_spectrum. More...
 
void scoreSpectra (const std::vector< MSSpectrum > &annotated_spectra, const std::vector< MSSpectrum > &picked_spectra, FeatureMap &features, std::vector< MSSpectrum > &scored_spectra, bool compute_features=true) const
 Assigns a score to the spectra given an input and saves them in scored_spectra. More...
 
void scoreSpectra (const std::vector< MSSpectrum > &annotated_spectra, const std::vector< MSSpectrum > &picked_spectra, std::vector< MSSpectrum > &scored_spectra) const
 Assigns a score to the spectra given an input and saves them in scored_spectra. More...
 
void selectSpectra (const std::vector< MSSpectrum > &scored_spectra, const FeatureMap &features, std::vector< MSSpectrum > &selected_spectra, FeatureMap &selected_features, bool compute_features=true) const
 The method selects the highest scoring spectrum for each possible annotation (i.e., transition name) More...
 
void selectSpectra (const std::vector< MSSpectrum > &scored_spectra, std::vector< MSSpectrum > &selected_spectra) const
 The method selects the highest scoring spectrum for each possible annotation (i.e., transition name) More...
 
void extractSpectra (const MSExperiment &experiment, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &extracted_spectra, FeatureMap &extracted_features, bool compute_features=true) const
 Combines the functionalities given by all the other methods implemented in this class. More...
 
void extractSpectra (const MSExperiment &experiment, const TargetedExperiment &targeted_exp, std::vector< MSSpectrum > &extracted_spectra) const
 Combines the functionalities given by all the other methods implemented in this class. More...
 
void matchSpectrum (const MSSpectrum &input_spectrum, const Comparator &cmp, std::vector< Match > &matches) const
 Searches the spectral library for the top scoring candidates that match the input spectrum. More...
 
void targetedMatching (const std::vector< MSSpectrum > &spectra, const Comparator &cmp, FeatureMap &features)
 Compares a list of spectra against a spectral library and updates the related features. More...
 
void untargetedMatching (const std::vector< MSSpectrum > &spectra, const Comparator &cmp, FeatureMap &features)
 Compares a list of spectra against a spectral library and creates a `FeatureMap` with the relevant information. More...
 
void storeSpectraTraML (const String &filename, const OpenMS::FeatureMap &ms1_features, const OpenMS::FeatureMap &ms2_features) const
 store MS1 and the associated MS2 features More...
 
void storeSpectraMSP (const String &filename, MSExperiment &experiment) const
 store spectra in MSP format More...
 
void mergeFeatures (const OpenMS::FeatureMap &fmap_input, OpenMS::FeatureMap &fmap_output) const
 organize into a map by combining features and subordinates with the same `identifier` More...
 
- 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...
 
virtual 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...
 

Protected Member Functions

void updateMembers_ () override
 Overridden function from DefaultParamHandler to keep members up to date, when a parameter is changed. More...
 
void deisotopeMS2Spectra_ (MSExperiment &experiment) const
 Deisotope MS2 spectra. More...
 
void removeMS2SpectraPeaks_ (MSExperiment &experiment) const
 Remove peaks form MS2 which are at a higher mz than the precursor + 10 ppm. More...
 
void organizeMapWithSameIdentifier (const OpenMS::FeatureMap &fmap_input, std::map< std::string, std::vector< OpenMS::Feature >> &fmapmap) const
 organize into a map by combining features and subordinates with the same `identifier` More...
 
- Protected Member Functions inherited from DefaultParamHandler
void defaultsToParam_ ()
 Updates the parameters after the defaults have been set in the constructor. More...
 

Private Attributes

bool mz_unit_is_Da_
 
double rt_window_
 
double mz_tolerance_
 
double peak_height_min_
 
double peak_height_max_
 
double fwhm_threshold_
 
double tic_weight_
 
double fwhm_weight_
 
double snr_weight_
 
double min_select_score_
 
bool use_gauss_
 
Size top_matches_to_report_
 
double min_match_score_
 Minimum score for a match to be considered valid in `matchSpectrum()`. More...
 
double min_fragment_mz_
 
double max_fragment_mz_
 
double relative_allowable_product_mass_
 
bool deisotoping_use_deisotoper_
 
double deisotoping_fragment_tolerance_
 
std::string deisotoping_fragment_unit_
 
int deisotoping_min_charge_
 
int deisotoping_max_charge_
 
int deisotoping_min_isopeaks_
 
int deisotoping_max_isopeaks_
 
bool deisotoping_keep_only_deisotoped_
 
bool deisotoping_annotate_charge_
 
double max_precursor_mass_threashold_
 

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

Detailed Description

This class filters, annotates, picks, and scores spectra (e.g., taken from a DDA experiment) based on a target list.

The input experiment is expected to be a standard .mzML file. The input target list is expected to be a standard TraML formatted .csv file.

The class deals with filtering and annotating only those spectra that reflect the characteristics described by the target list. The filtering is done based on the transition_name, PrecursorMz and RetentionTime. The spectra are smoothed and peaks are picked for each spectrum. The spectra are then scored based on total TIC, FWHM and SNR. One spectrum is chosen for each of those transitions for which at least one valid spectrum was found and matched.

The user can decide to use only extractSpectra(), otherwise run the methods in the following order: annotateSpectra() pickSpectrum() (called once for each annotated spectrum) scoreSpectra() selectSpectra()

Constructor & Destructor Documentation

◆ TargetedSpectraExtractor()

◆ ~TargetedSpectraExtractor()

~TargetedSpectraExtractor ( )
overridedefault

Member Function Documentation

◆ annotateSpectra() [1/3]

void annotateSpectra ( const std::vector< MSSpectrum > &  spectra,
const FeatureMap ms1_features,
FeatureMap ms2_features,
std::vector< MSSpectrum > &  annotated_spectra 
) const

Annotates the MS2 spectra with the likely MS1 feature that it was derived from.

Annotating based on MS1 feature results from AccurateMassSearch. In this case, the input will be e.g., const FeatureMap& ms1_features and the RTs and names (i.e., PeptideRef), defined in the FeatureMap.

Parameters
[in]spectraThe spectra to filter
[in]ms1_featuresThe MS1 features
[out]ms2_featuresThe MS2 features
[out]annotated_spectraThe resulting annotated spectra

◆ annotateSpectra() [2/3]

void annotateSpectra ( const std::vector< MSSpectrum > &  spectra,
const TargetedExperiment targeted_exp,
std::vector< MSSpectrum > &  annotated_spectra 
) const

Filters and annotates those spectra that could potentially match the transitions of the target list.

The spectra taken into account are those that fall within the precursor RT window and MZ tolerance set by the user through the parameters "rt_window" and "mz_tolerance". Default values are provided for both parameters.

Warning
The picked spectrum could be empty, meaning no peaks were found.
Parameters
[in]spectraThe spectra to filter
[in]targeted_expThe target list
[out]annotated_spectraThe spectra annotated with the related transition's name

◆ annotateSpectra() [3/3]

void annotateSpectra ( const std::vector< MSSpectrum > &  spectra,
const TargetedExperiment targeted_exp,
std::vector< MSSpectrum > &  annotated_spectra,
FeatureMap features,
bool  compute_features = true 
) const

Filters and annotates those spectra that could potentially match the transitions of the target list.

The spectra taken into account are those that fall within the precursor RT window and MZ tolerance set by the user through the parameters "rt_window" and "mz_tolerance". Default values are provided for both parameters.

Warning
The picked spectrum could be empty, meaning no peaks were found.
Parameters
[in]spectraThe spectra to filter
[in]targeted_expThe target list
[out]annotated_spectraThe spectra annotated with the related transition's name
[out]featuresA FeatureMap which will contain informations about the name, precursor RT and precursor MZ of the matched transition
[in]compute_featuresIf false, `features` will be ignored

◆ deisotopeMS2Spectra_()

void deisotopeMS2Spectra_ ( MSExperiment experiment) const
protected

Deisotope MS2 spectra.

◆ extractSpectra() [1/2]

void extractSpectra ( const MSExperiment experiment,
const TargetedExperiment targeted_exp,
std::vector< MSSpectrum > &  extracted_spectra 
) const

Combines the functionalities given by all the other methods implemented in this class.

The method expects an experiment and a target list in input, and constructs the extracted spectra. For each transition of the target list, the method tries to find its best spectrum match.

Parameters
[in]experimentThe input experiment
[in]targeted_expThe target list
[out]extracted_spectraThe spectra related to the transitions

◆ extractSpectra() [2/2]

void extractSpectra ( const MSExperiment experiment,
const TargetedExperiment targeted_exp,
std::vector< MSSpectrum > &  extracted_spectra,
FeatureMap extracted_features,
bool  compute_features = true 
) const

Combines the functionalities given by all the other methods implemented in this class.

The method expects an experiment and a target list in input, and constructs the extracted spectra and features. For each transition of the target list, the method tries to find its best spectrum match. A FeatureMap is also filled with informations about the extracted spectra.

Parameters
[in]experimentThe input experiment
[in]targeted_expThe target list
[out]extracted_spectraThe spectra related to the transitions
[out]extracted_featuresThe features related to the output spectra
[in]compute_featuresIf false, `extracted_features` will be ignored

◆ getDefaultParameters()

void getDefaultParameters ( Param params) const

◆ matchSpectrum()

void matchSpectrum ( const MSSpectrum input_spectrum,
const Comparator cmp,
std::vector< Match > &  matches 
) const

Searches the spectral library for the top scoring candidates that match the input spectrum.

Parameters
[in]input_spectrumThe input spectrum for which a match is desired
[in]cmpThe comparator object containing the library and the logic for matching
[out]matchesA vector of `Match`es, containing the matched spectra and their scores

◆ mergeFeatures()

void mergeFeatures ( const OpenMS::FeatureMap fmap_input,
OpenMS::FeatureMap fmap_output 
) const

organize into a map by combining features and subordinates with the same `identifier`

Parameters
[in]fmap_inputinput features map
[in]fmap_outputoutput features map

◆ organizeMapWithSameIdentifier()

void organizeMapWithSameIdentifier ( const OpenMS::FeatureMap fmap_input,
std::map< std::string, std::vector< OpenMS::Feature >> &  fmapmap 
) const
protected

organize into a map by combining features and subordinates with the same `identifier`

◆ pickSpectrum()

void pickSpectrum ( const MSSpectrum spectrum,
MSSpectrum picked_spectrum 
) const

Picks a spectrum's peaks and saves them in picked_spectrum.

The spectrum is first smoothed with a Gaussian filter (default) or using the Savitzky-Golay method. The parameter "use_gauss" handles this choice. The peak picking is executed with PeakPickerHiRes. Custom parameters provided with the prefix "GaussFilter:", "SavitzkyGolayFilter:" and "PeakPickerHiRes:" are taken into account. Peaks are then filtered by their heights and FWHM values. It is possible to set the peaks' limits through the parameters: "peak_height_min", "peak_height_max" and "fwhm_threshold".

Exceptions
Exception::IllegalArgumentIf `spectrum` is not sorted by position (mz).
Parameters
[in]spectrumThe input spectrum
[out]picked_spectrumA spectrum containing only the picked peaks

◆ removeMS2SpectraPeaks_()

void removeMS2SpectraPeaks_ ( MSExperiment experiment) const
protected

Remove peaks form MS2 which are at a higher mz than the precursor + 10 ppm.

◆ scoreSpectra() [1/2]

void scoreSpectra ( const std::vector< MSSpectrum > &  annotated_spectra,
const std::vector< MSSpectrum > &  picked_spectra,
FeatureMap features,
std::vector< MSSpectrum > &  scored_spectra,
bool  compute_features = true 
) const

Assigns a score to the spectra given an input and saves them in scored_spectra.

Also add the informations to the FeatureMap first constructed in annotateSpectra(). The scores are based on total TIC, SNR and FWHM. It is possible to assign a weight to these parameters using: "tic_weight", "fwhm_weight" and "snr_weight". For each spectrum, the TIC and the SNR are computed on the entire spectrum. The FWHMs are computed only on picked peaks. Both SNR and FWHM are averaged values. The informations are added as FloatDataArray in scored_spectra and as MetaValue in features.

Exceptions
Exception::InvalidSizeIf `features` and `annotated_spectra` sizes don't match.
Parameters
[in]annotated_spectraThe annotated spectra to score (for TIC and SNR)
[in]picked_spectraThe picked peaks found on each of the annotated spectra (for FWHM)
[in,out]featuresThe score informations are also added to this FeatureMap. Picked peaks' FWHMs are saved in features' subordinates.
[out]scored_spectraThe scored spectra. Basically a copy of annotated_spectra with the added score informations
[in]compute_featuresIf false, `features` will be ignored

◆ scoreSpectra() [2/2]

void scoreSpectra ( const std::vector< MSSpectrum > &  annotated_spectra,
const std::vector< MSSpectrum > &  picked_spectra,
std::vector< MSSpectrum > &  scored_spectra 
) const

Assigns a score to the spectra given an input and saves them in scored_spectra.

Also add the informations to the FeatureMap first constructed in annotateSpectra(). The scores are based on total TIC, SNR and FWHM. It is possible to assign a weight to these parameters using: "tic_weight", "fwhm_weight" and "snr_weight". For each spectrum, the TIC and the SNR are computed on the entire spectrum. The FWHMs are computed only on picked peaks. Both SNR and FWHM are averaged values.

Parameters
[in]annotated_spectraThe annotated spectra to score (for TIC and SNR)
[in]picked_spectraThe picked peaks found on each of the annotated spectra (for FWHM)
[out]scored_spectraThe scored spectra. Basically a copy of annotated_spectra with the added score informations

◆ searchSpectrum()

void searchSpectrum ( OpenMS::FeatureMap feat_map,
OpenMS::FeatureMap feat_map_output 
) const

Search accurate masses and add identification (peptide hits) as features/sub-features.

Parameters
[in]feat_mapThe feature map to search in
[in]feat_map_outputThe output feature map, with peptide identifaction as sub features

◆ selectSpectra() [1/2]

void selectSpectra ( const std::vector< MSSpectrum > &  scored_spectra,
const FeatureMap features,
std::vector< MSSpectrum > &  selected_spectra,
FeatureMap selected_features,
bool  compute_features = true 
) const

The method selects the highest scoring spectrum for each possible annotation (i.e., transition name)

Exceptions
Exception::InvalidSizeIf `scored_spectra` and `features` sizes don't match.
Parameters
[in]scored_spectraInput annotated and scored spectra
[in]featuresInput features
[out]selected_spectraOutput selected spectra
[out]selected_featuresOutput selected features
[in]compute_featuresIf false, `selected_features` will be ignored

◆ selectSpectra() [2/2]

void selectSpectra ( const std::vector< MSSpectrum > &  scored_spectra,
std::vector< MSSpectrum > &  selected_spectra 
) const

The method selects the highest scoring spectrum for each possible annotation (i.e., transition name)

Parameters
[in]scored_spectraInput annotated and scored spectra
[out]selected_spectraOutput selected spectra

◆ storeSpectraMSP()

void storeSpectraMSP ( const String filename,
MSExperiment experiment 
) const

store spectra in MSP format

Parameters
[in]filenamethe filename of the file to write
[in]experimentthe experiment to store

◆ storeSpectraTraML()

void storeSpectraTraML ( const String filename,
const OpenMS::FeatureMap ms1_features,
const OpenMS::FeatureMap ms2_features 
) const

store MS1 and the associated MS2 features

Parameters
[in]filenamethe filename of the file to write
[in]ms1_featuresthe MS1 features
[in]ms2_featuresthe MS2 features

◆ targetedMatching()

void targetedMatching ( const std::vector< MSSpectrum > &  spectra,
const Comparator cmp,
FeatureMap features 
)

Compares a list of spectra against a spectral library and updates the related features.

The metavalues added to each `Feature` within the `FeatureMap` are:

  • spectral_library_name The name of the match's spectrum found in the library
  • spectral_library_score The match score [0-1]
  • spectral_library_comments The comments for the match's spectrum

If a match for a given input spectrum is not found, the metavalues will be assigned a default value:

  • spectral_library_name and spectral_library_comments: an empty string
  • spectral_library_score: a value of 0.0
Note
The input `spectra` (and related `features`) are assumed to be the result of `extractSpectra()`, meaning they went (at least) through the process of peak picking.
Parameters
[in]spectraThe input spectra
[in]cmpThe `Comparator` object containing the spectral library
[in/out]features The `FeatureMap` to be updated with matching info

◆ untargetedMatching()

void untargetedMatching ( const std::vector< MSSpectrum > &  spectra,
const Comparator cmp,
FeatureMap features 
)

Compares a list of spectra against a spectral library and creates a `FeatureMap` with the relevant information.

The metavalues added to each `Feature` within the `FeatureMap` are:

  • spectral_library_name The name of the match's spectrum found in the library
  • spectral_library_score The match score [0-1]
  • spectral_library_comments The comments for the match's spectrum

If a match for a given input spectrum is not found, the metavalues will be assigned a default value:

  • spectral_library_name and spectral_library_comments: an empty string
  • spectral_library_score: a value of 0.0
Note
The input `spectra` (and related `features`) are assumed to be unprocessed, therefore undergoing a process of peak picking during execution of this method.
Parameters
[in]spectraThe input spectra
[in]cmpThe `Comparator` object containing the spectral library
[out]featuresThe `FeatureMap` to be filled with matching info

◆ updateMembers_()

void updateMembers_ ( )
overrideprotectedvirtual

Overridden function from DefaultParamHandler to keep members up to date, when a parameter is changed.

Reimplemented from DefaultParamHandler.

Member Data Documentation

◆ deisotoping_annotate_charge_

bool deisotoping_annotate_charge_
private

◆ deisotoping_fragment_tolerance_

double deisotoping_fragment_tolerance_
private

◆ deisotoping_fragment_unit_

std::string deisotoping_fragment_unit_
private

◆ deisotoping_keep_only_deisotoped_

bool deisotoping_keep_only_deisotoped_
private

◆ deisotoping_max_charge_

int deisotoping_max_charge_
private

◆ deisotoping_max_isopeaks_

int deisotoping_max_isopeaks_
private

◆ deisotoping_min_charge_

int deisotoping_min_charge_
private

◆ deisotoping_min_isopeaks_

int deisotoping_min_isopeaks_
private

◆ deisotoping_use_deisotoper_

bool deisotoping_use_deisotoper_
private

◆ fwhm_threshold_

double fwhm_threshold_
private

Used in pickSpectrum(), a peak's FWHM needs to be >= fwhm_threshold_ for it to be picked.

◆ fwhm_weight_

double fwhm_weight_
private

FWHM's weight when computing a spectrum's score

◆ max_fragment_mz_

double max_fragment_mz_
private

◆ max_precursor_mass_threashold_

double max_precursor_mass_threashold_
private

◆ min_fragment_mz_

double min_fragment_mz_
private

◆ min_match_score_

double min_match_score_
private

Minimum score for a match to be considered valid in `matchSpectrum()`.

◆ min_select_score_

double min_select_score_
private

Used in selectSpectra(), after the spectra have been assigned a score. Remained transitions will have at least one spectrum assigned. Each spectrum needs to have a score >= min_select_score_ to be valid, otherwise it gets filtered out.

◆ mz_tolerance_

double mz_tolerance_
private

Precursor MZ tolerance used during the annotation phase. For each transition in the target list, annotateSpectra() looks for the first spectrum whose precursor MZ is close enough (+-mz_tolerance_) to the transition's MZ. Also the spectrum's precursor RT is checked against the transition RT.

◆ mz_unit_is_Da_

bool mz_unit_is_Da_
private

Unit to use for mz_tolerance_ and fwhm_threshold_: true for Da, false for ppm.

◆ peak_height_max_

double peak_height_max_
private

Used in pickSpectrum(), a peak's intensity needs to be <= peak_height_max_ for it to be picked.

◆ peak_height_min_

double peak_height_min_
private

Used in pickSpectrum(), a peak's intensity needs to be >= peak_height_min_ for it to be picked.

◆ relative_allowable_product_mass_

double relative_allowable_product_mass_
private

◆ rt_window_

double rt_window_
private

Precursor Retention Time window used during the annotation phase. For each transition in the target list, annotateSpectra() looks for the first spectrum whose RT time falls within the RT Window, whose left and right limits are computed at each analyzed spectrum. Also the spectrum's precursor MZ is checked against the transition MZ.

◆ snr_weight_

double snr_weight_
private

SNR's weight when computing a spectrum's score

◆ tic_weight_

double tic_weight_
private

Total TIC's weight when computing a spectrum's score

◆ top_matches_to_report_

Size top_matches_to_report_
private

The number of matches to output from `matchSpectrum()`. These will be the matches of highest scores, sorted in descending order.

◆ use_gauss_

bool use_gauss_
private

Used in pickSpectrum(), it selects which filtering method is used during the smoothing phase. By default the Gauss filter is selected. Set to false for the Savitzky-Golay method.