base class for filtering centroided and profile data for peak patterns
More...
#include <OpenMS/FEATUREFINDER/MultiplexFiltering.h>
|
| | MultiplexFiltering (const MSExperiment &exp_centroided, const std::vector< MultiplexIsotopicPeakPattern > &patterns, int isotopes_per_peptide_min, int isotopes_per_peptide_max, double intensity_cutoff, double rt_band, double mz_tolerance, bool mz_tolerance_unit, double peptide_similarity, double averagine_similarity, double averagine_similarity_scaling, std::string averagine_type="peptide") |
| | constructor
|
| |
| MSExperiment & | getCentroidedExperiment () |
| | returns the intensity-filtered, centroided spectral data
|
| |
| MSExperiment | getBlacklist () |
| | returns the blacklisted, centroided peaks
|
| |
| std::vector< std::vector< BlacklistOwner > > | getBlacklistOwners () const |
| | the owners of the blacklisted peaks, aligned with getBlacklist(): one list per spectrum, one entry per peak
|
| |
| std::vector< BlacklistOwner > | getBlacklistOwners (Size spectrum_index) const |
| | the owners of the blacklisted peaks of one spectrum, aligned with that spectrum of getBlacklist()
|
| |
| void | setDeuteriumLabels (const std::map< std::string, DeuteriumLabel > &labels) |
| | take the lower isotopologue of deuterium labels into account where a peak one isotope below a peptide is checked
|
| |
| | 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 double | deuteriumLowerFraction (unsigned deuterium, double enrichment, const IsotopeDistribution &isotopes) |
| | the peak one isotope below a deuterium-labelled peptide that its own label isotopologues produce, relative to its monoisotopic peak
|
| |
| static double | deuteriumAllowance (unsigned deuterium, double enrichment, const IsotopeDistribution &isotopes) |
| | the part of the peak one isotope below a deuterium-labelled peptide that the check for another envelope allows, relative to its monoisotopic peak
|
| |
|
| void | updateWhiteMSExperiment_ () |
| | construct an MS experiment from exp_centroided_ containing peaks which have not been previously blacklisted in blacklist_
|
| |
| int | checkForSignificantPeak_ (double mz, double mz_tolerance, MSExperiment::ConstIterator &it_rt, double intensity_first_peak, double fraction=0.3) const |
| | check for significant peak
|
| |
| double | deuteriumAllowance_ (const MultiplexIsotopicPeakPattern &pattern, size_t peptide, double mz) const |
| | deuteriumAllowance() for peptide peptide of pattern (monoisotopic m/z mz), with its deuterium labels (setDeuteriumLabels()); 0 without 2H
|
| |
| bool | filterPeakPositions_ (double mz, const MSExperiment::ConstIterator &it_rt_begin, const MSExperiment::ConstIterator &it_rt_band_begin, const MSExperiment::ConstIterator &it_rt_band_end, const MultiplexIsotopicPeakPattern &pattern, MultiplexFilteredPeak &peak, std::vector< BlacklistEntry > *blacklist_reads=nullptr) const |
| | check if there are enough peaks in the RT band to form the pattern
|
| |
| void | blacklistPeak_ (const MultiplexFilteredPeak &peak, unsigned pattern_idx, size_t peak_idx) |
| | blacklist this peak
|
| |
| void | applyBlacklistEntries_ (const std::vector< BlacklistEntry > &entries, unsigned pattern_idx, size_t peak_idx) |
| | write entries to blacklist_, with the filtered peak (pattern_idx, peak_idx) as their owner
|
| |
| void | blacklistEntries_ (const MultiplexFilteredPeak &peak, unsigned pattern_idx, std::vector< BlacklistEntry > &entries) const |
| | the entries of blacklist_ that blacklistPeak_() sets, with their new values, in the order it sets them
|
| |
| void | filterSpectrum_ (size_t idx_rt, unsigned pattern_idx, const PeakFilter &filter_peak, MultiplexFilteredMSExperiment &result) |
| | filter all peaks of one 'white' spectrum, add the ones that pass to result and blacklist them
|
| |
| bool | filterAveragineModel_ (const MultiplexIsotopicPeakPattern &pattern, const MultiplexFilteredPeak &peak) const |
| | check if the satellite peaks conform with the averagine model
|
| |
| const IsotopeDistribution & | averagineDistribution_ (double mass) const |
| | averagine isotope distribution (of the type averagine_type_, with isotopes_per_peptide_max_ isotopes) of a molecule of mass
|
| |
| bool | filterPeptideCorrelation_ (const MultiplexIsotopicPeakPattern &pattern, const MultiplexFilteredPeak &peak) const |
| | check if corresponding satellite peaks of different peptides show a good correlation
|
| |
base class for filtering centroided and profile data for peak patterns
The algorithm searches for patterns of multiple peptides in the data. The peptides appear as characteristic patterns of isotopic peaks in MS1 spectra. We first search the centroided data, and optionally in a second step the spline interpolated profile data. For each peak pattern the algorithm generates a filter result.
The algorithm differs slightly for centroided and profile input data. This base class comprises code common to both. The two child classes MultiplexFilteringCentroided and MultiplexFilteringProfile contain specific functions and the primary filter() method.
- See also
- MultiplexIsotopicPeakPattern
-
MultiplexFilteredMSExperiment
-
MultiplexFilteringCentroided
-
MultiplexFilteringProfile
◆ OpenMS::MultiplexFiltering::BlacklistEntry
| struct OpenMS::MultiplexFiltering::BlacklistEntry |
an entry of blacklist_ (spectrum index and peak index in exp_centroided_) and a value read from or written to it
| Class Members |
|
size_t |
mz_idx |
|
|
size_t |
rt_idx |
|
|
int |
value |
|
◆ OpenMS::MultiplexFiltering::BlacklistOwner
| struct OpenMS::MultiplexFiltering::BlacklistOwner |
who blacklisted a peak: the first and the last filtered peak that reserved it (the same if only one did)
| Class Members |
|
BlacklistWriter |
first |
the first filtered peak that reserved the peak |
|
BlacklistWriter |
last |
the last one, whose mass trace the blacklist holds |
◆ OpenMS::MultiplexFiltering::BlacklistOwnerRecord
| struct OpenMS::MultiplexFiltering::BlacklistOwnerRecord |
the owners of a peak of blacklist_ that more than one filtered peak reserved (indices in filtered_peaks_)
| Class Members |
|
int |
first |
the first filtered peak that reserved the peak |
|
int |
first_value |
the value first left in blacklist_ (read when another filtered peak reserved the peak for the first time) |
|
int |
last |
the last filtered peak that reserved the peak, whose value blacklist_ holds |
◆ OpenMS::MultiplexFiltering::BlacklistWriter
| struct OpenMS::MultiplexFiltering::BlacklistWriter |
a filtered peak that blacklisted a peak, and the mass trace of its pattern it reserved the peak for
| Class Members |
|
int |
mass_trace |
mass trace of the pattern the peak was reserved for (peptide * isotopes_per_peptide_max + isotope) |
|
unsigned |
pattern_idx |
index of the pattern, i.e. of its filter result in the list filter() returns |
|
unsigned |
peak_idx |
index of the filtered peak in the filter result of the pattern (MultiplexFilteredMSExperiment::getPeak()); it fits in an int, since the filtered peaks of all patterns together are limited to INT_MAX (see applyBlacklistEntries_())
|
◆ OpenMS::MultiplexFiltering::DeuteriumLabel
| struct OpenMS::MultiplexFiltering::DeuteriumLabel |
a deuterium label (setDeuteriumLabels()), or the deuterium labels of a peptide
| Class Members |
|
unsigned |
deuterium = 0 |
number of 2H atoms |
|
double |
enrichment = 1.0 |
their 2H atom fraction, in (0, 1] |
◆ PeakFilter
decides on one peak of a 'white' spectrum
Called with the peak index in the white spectrum and, if not null, the list to which every entry of blacklist_ read is to be appended (see filterPeakPositions_()). Returns the peak with its satellites if it passes all filters.
◆ White2Original
index mapping from a 'white' experiment to its original experiment
An MSExperiment contains a set of spectra each containing a number of peaks. In the course of the filtering, some peaks are blacklisted since they are identified to belong to a certain pattern i.e. peptide. An experiment in which blacklisted peaks are removed is called 'white'. White spectra contain fewer peaks than their corresponding primary spectra. Consequently, their indices are shifted. The type maps a peak index in a 'white' spectrum back to its original spectrum: element [s][i] is the index in spectrum s of the original experiment of peak i of white spectrum s.
◆ MultiplexFiltering()
| MultiplexFiltering |
( |
const MSExperiment & |
exp_centroided, |
|
|
const std::vector< MultiplexIsotopicPeakPattern > & |
patterns, |
|
|
int |
isotopes_per_peptide_min, |
|
|
int |
isotopes_per_peptide_max, |
|
|
double |
intensity_cutoff, |
|
|
double |
rt_band, |
|
|
double |
mz_tolerance, |
|
|
bool |
mz_tolerance_unit, |
|
|
double |
peptide_similarity, |
|
|
double |
averagine_similarity, |
|
|
double |
averagine_similarity_scaling, |
|
|
std::string |
averagine_type = "peptide" |
|
) |
| |
constructor
- Parameters
-
| [in] | exp_centroided | experimental data in centroid mode |
| [in] | patterns | patterns of isotopic peaks to be searched for |
| [in] | isotopes_per_peptide_min | minimum number of isotopic peaks in peptides |
| [in] | isotopes_per_peptide_max | maximum number of isotopic peaks in peptides |
| [in] | intensity_cutoff | intensity cutoff |
| [in] | rt_band | RT range used for filtering |
| [in] | mz_tolerance | error margin in m/z for matching expected patterns to experimental data |
| [in] | mz_tolerance_unit | unit for mz_tolerance, ppm (true), Da (false) |
| [in] | peptide_similarity | similarity score for two peptides in the same multiplet |
| [in] | averagine_similarity | similarity score for peptide isotope pattern and averagine model |
| [in] | averagine_similarity_scaling | scaling factor x for the averagine similarity parameter p when detecting peptide singlets. With p' = p + x(1-p). |
| [in] | averagine_type | Averagine model to use: 'peptide', 'RNA', 'DNA' |
◆ applyBlacklistEntries_()
| void applyBlacklistEntries_ |
( |
const std::vector< BlacklistEntry > & |
entries, |
|
|
unsigned |
pattern_idx, |
|
|
size_t |
peak_idx |
|
) |
| |
|
protected |
write entries to blacklist_, with the filtered peak (pattern_idx, peak_idx) as their owner
It becomes the last owner of each peak. As long as a single filtered peak has reserved a peak, blacklist_owner_ holds that owner. When a second filtered peak reserves it, the peak gets a record in blacklist_owner_records_ with the first owner, the value the first owner left in blacklist_, and the last owner. Later owners only replace the last owner of the record, so any owner in between is lost (see getBlacklistOwners()).
Owners and records are indexed by int, so the filtered peaks of all patterns together, and the peaks reserved by more than one of them, are limited to INT_MAX each.
- Exceptions
-
◆ averagineDistribution_()
averagine isotope distribution (of the type averagine_type_, with isotopes_per_peptide_max_ isotopes) of a molecule of mass
The returned reference is valid until the next call on the same thread. Peptide distributions are computed once per element composition of the averagine model.
- Exceptions
-
◆ blacklistEntries_()
the entries of blacklist_ that blacklistPeak_() sets, with their new values, in the order it sets them
They do not depend on the blacklist.
- Parameters
-
| [in] | peak | peak to be blacklisted |
| [in] | pattern_idx | index of the pattern in patterns_ |
| [out] | entries | the entries are appended to it |
◆ blacklistPeak_()
blacklist this peak
Each of the satellites is associated with a specific mass trace. We blacklist all peaks in these mass traces (even if they are not a satellite) extending them by a margin rt_band_.
- Parameters
-
| [in] | peak | peak to be blacklisted |
| [in] | pattern_idx | index of the pattern in patterns_ |
| [in] | peak_idx | index of peak in the filter result of the pattern, recorded as owner of the peaks |
◆ checkForSignificantPeak_()
| int checkForSignificantPeak_ |
( |
double |
mz, |
|
|
double |
mz_tolerance, |
|
|
MSExperiment::ConstIterator & |
it_rt, |
|
|
double |
intensity_first_peak, |
|
|
double |
fraction = 0.3 |
|
) |
| const |
|
protected |
check for significant peak
- Parameters
-
| [in] | mz | position where the peak is expected |
| [in] | mz_tolerance | m/z tolerance within the peak may lie |
| [in] | it_rt | pointer to the spectrum |
| [in] | intensity_first_peak | intensity to compare to |
| [in] | fraction | a peak is significant if its intensity exceeds this fraction of intensity_first_peak |
- Returns
- -1 (if there is no significant peak), or the index of the significant peak in the spectrum
it_rt points to (in filterPeakPositions_() a spectrum of exp_centroided_white_, see exp_centroided_mapping_)
◆ deuteriumAllowance()
| static double deuteriumAllowance |
( |
unsigned |
deuterium, |
|
|
double |
enrichment, |
|
|
const IsotopeDistribution & |
isotopes |
|
) |
| |
|
static |
the part of the peak one isotope below a deuterium-labelled peptide that the check for another envelope allows, relative to its monoisotopic peak
deuteriumLowerFraction(), but at most half the distance from 0.3 to I_0/I_1 of isotopes. If the peptide's peaks were really the isotopes of an envelope one isotope lower (its "monoisotopic" peak the M+1 of that envelope), the peak below would be about I_0/I_1 of it; with the cap, the bound 0.3 + allowance stays at least halfway between 30 % and that ratio, whatever the number of 2H atoms and the enrichment. 0 where I_0/I_1 is at most 0.3 (large peptides, for which the 30 % cannot tell either).
- Parameters
-
| [in] | deuterium | number of 2H atoms of the peptide's labels |
| [in] | enrichment | 2H atom fraction of the labels, in (0, 1] |
| [in] | isotopes | the peptide's isotope distribution without the labels' 2H (e.g. averagine) |
◆ deuteriumAllowance_()
◆ deuteriumLowerFraction()
| static double deuteriumLowerFraction |
( |
unsigned |
deuterium, |
|
|
double |
enrichment, |
|
|
const IsotopeDistribution & |
isotopes |
|
) |
| |
|
static |
the peak one isotope below a deuterium-labelled peptide that its own label isotopologues produce, relative to its monoisotopic peak
The molecules that lack j of the deuterium 2H atoms of the label (binomial in the 2H atom fraction enrichment, q_j = C(n, j) ((1 - p) / p)^j relative to the fully labelled ones) have the peptide's isotope distribution I shifted by -j * 1.0063 Da: their isotope j - 1 coincides with the peptide's M-1 within 0.0029 Da per 2H, their isotope j with its M+0. The result is sum_{j>=1} q_j I_{j-1} / sum_{j>=0} q_j I_j, about r / (1 + r I_1/I_0) for r = n (1 - p) / p.
- Parameters
-
| [in] | deuterium | number of 2H atoms of the peptide's labels |
| [in] | enrichment | 2H atom fraction of the labels, in (0, 1] |
| [in] | isotopes | the peptide's isotope distribution without the labels' 2H (e.g. averagine) |
- Returns
- 0 if
deuterium is 0, enrichment is not below 1 or isotopes has fewer than two isotopes
◆ filterAveragineModel_()
check if the satellite peaks conform with the averagine model
Check if the intensities of the satellite peaks correlate with the peak intensities of the averagine model. We check both Pearson and Spearman rank correlation.
- Parameters
-
| [in] | pattern | m/z pattern to search for |
| [in] | peak | peak with set of satellite peaks |
- Returns
- boolean if this filter was passed i.e. the correlation coefficient is greater than averagine_similarity_
◆ filterPeakPositions_()
check if there are enough peaks in the RT band to form the pattern
Checks if there are peaks at m/z positions corresponding to the pattern and that the primary peak position is not blacklisted.
- Parameters
-
| [in] | mz | m/z of the primary peak |
| [in] | it_rt_begin | RT iterator of the very first spectrum of exp_centroided_white_ (needed to determine indices; peak indices in its spectra are mapped to exp_centroided_ with exp_centroided_mapping_) |
| [in] | it_rt_band_begin | RT iterator of the first spectrum in the RT band (of exp_centroided_white_) |
| [in] | it_rt_band_end | RT iterator of the spectrum after the last spectrum in the RT band (of exp_centroided_white_) |
| [in] | pattern | m/z pattern to search for |
| [out] | peak | filter result output |
| [out] | blacklist_reads | if not null, every entry of blacklist_ read is appended to it, with the value read |
- Returns
- boolean if this filter was passed i.e. there are isotopes_per_peptide_min_ or more mass traces which form the pattern.
◆ filterPeptideCorrelation_()
check if corresponding satellite peaks of different peptides show a good correlation
Different peptides in the same multiplet have the same amino acid sequence and should therefore exhibit very similar isotope distributions. The filter checks if satellite peaks corresponding to different isotopes in different peptide features show a strong correlation. The filter is of course ignored for singlet feature detection.
- Parameters
-
| [in] | pattern | m/z pattern to search for |
| [in] | peak | peak with set of satellite peaks |
- Returns
- boolean if this filter was passed i.e. the correlation coefficient is greater than peptide_similarity_
◆ filterSpectrum_()
filter all peaks of one 'white' spectrum, add the ones that pass to result and blacklist them
Whether a peak passes depends on the blacklist, which every peak that passes extends. The result is that of filtering the peaks one after another in order of m/z (as a single thread does), whatever the number of threads: The peaks are filtered in parallel against the blacklist as it is when the spectrum is reached; every decision records the blacklist entries it read, and every peak that passes the entries it would blacklist. Then the peaks are accepted in order of m/z. A decision stands unless a peak accepted before it in this spectrum has changed one of the entries it read; then the peak is filtered again against the current blacklist. With one thread, the peaks are simply filtered in order of m/z.
- Parameters
-
| [in] | idx_rt | index of the spectrum in exp_centroided_white_ |
| [in] | pattern_idx | index of the pattern in patterns_ |
| [in] | filter_peak | decides on one peak of the spectrum |
| [out] | result | filter result the peaks that pass are added to |
◆ getBlacklist()
returns the blacklisted, centroided peaks
One spectrum per spectrum of the centroided experiment, with the blacklisted peaks in order of m/z. Call it before swapping the centroided experiment out (getCentroidedExperiment()).
◆ getBlacklistOwners() [1/2]
| std::vector< std::vector< BlacklistOwner > > getBlacklistOwners |
( |
| ) |
const |
the owners of the blacklisted peaks, aligned with getBlacklist(): one list per spectrum, one entry per peak
A pattern reserves the peaks of its mass traces over their RT range extended by the RT band, also peaks that another filtered peak reserved before, so a peak can be reserved several times. The owners are recorded when a peak passes, in the order in which peaks pass, so they do not depend on the number of threads.
Only the first and the last writer of a peak are kept. A filtered peak that reserved it in between is lost: if its multiplet is reported and the clusters of the first and the last writer are dropped, the peak counts as reserved by no reported feature (FeatureFinderMultiplexAlgorithm::getBlacklist()). That takes at least three writers of one peak, which in practice requires an RT band > 0 (rt_band_, FeatureFinderMultiplex's algorithm:rt_band).
This copy holds the owners of all blacklisted peaks at once; getBlacklistOwners(Size) returns those of one spectrum.
◆ getBlacklistOwners() [2/2]
the owners of the blacklisted peaks of one spectrum, aligned with that spectrum of getBlacklist()
The same entries as getBlacklistOwners()[spectrum_index], without a copy of the owners of the other spectra.
- Parameters
-
| [in] | spectrum_index | index of the spectrum in the centroided experiment (and in getBlacklist()) |
- Exceptions
-
◆ getCentroidedExperiment()
returns the intensity-filtered, centroided spectral data
◆ setDeuteriumLabels()
| void setDeuteriumLabels |
( |
const std::map< std::string, DeuteriumLabel > & |
labels | ) |
|
take the lower isotopologue of deuterium labels into account where a peak one isotope below a peptide is checked
A label with n deuterium (2H) atoms of atom fraction p < 1 leaves molecules that lack one 2H. Their monoisotopic peak lies 1.0063/z below the peptide's, 0.0029/z from its M-1, so within the m/z tolerance in which the filter looks for a significant peak one isotope below the peptide (which would make the peptide's peaks the isotopes of another envelope). For one Lys4 at p = 0.96 it is about 15 % of the monoisotopic peak, for two about 28 % (at 2 kDa), against the 30 % above which such a peak is significant. With this setting, a peak there is significant only above 30 % plus that expected part, capped so that a pattern one isotope too high is still rejected (deuteriumAllowance(), with the averagine distribution at the peptide's mass). Peptides whose labels have no 2H keep 30 %.
The labels of a peptide add up their 2H atoms (e.g. 8 for {Lys4, Lys4}, or for Dimethyl4 at the N-terminus and one K); if they differ in enrichment, the lowest one is used.
Call it after the construction, before filter().
- Parameters
-
- Exceptions
-
◆ updateWhiteMSExperiment_()
| void updateWhiteMSExperiment_ |
( |
| ) |
|
|
protected |
construct an MS experiment from exp_centroided_ containing peaks which have not been previously blacklisted in blacklist_
In addition, construct an index mapping of 'white' peak positions to their position in the corresponding, original spectrum.
◆ averagine_similarity_
| double averagine_similarity_ |
|
protected |
◆ averagine_similarity_scaling_
| double averagine_similarity_scaling_ |
|
protected |
averagine similarity scaling
◆ averagine_type_
| std::string averagine_type_ |
|
protected |
◆ blacklist_
| std::vector<std::vector<int> > blacklist_ |
|
protected |
auxiliary structs for blacklisting
◆ blacklist_owner_
| std::vector<std::vector<int> > blacklist_owner_ |
|
protected |
for every peak of blacklist_, who reserved it
-1: nobody (the peak is white); >= 0: the only filtered peak that reserved it so far (index in filtered_peaks_); <= -2: more than one filtered peak reserved it, and -2 - value is the index of its record in blacklist_owner_records_.
◆ blacklist_owner_records_
the first and the last owner of every peak reserved by more than one filtered peak (see blacklist_owner_)
◆ blacklist_reads_
for each peak of the spectrum being filtered, the entries of blacklist_ its decision read (see filterSpectrum_())
Kept from spectrum to spectrum, so that the lists keep their memory.
◆ blacklist_writes_
for each peak of the spectrum being filtered that passes, the entries of blacklist_ it sets (see filterSpectrum_())
◆ deuterium_
◆ exp_centroided_
centroided experimental data
◆ exp_centroided_mapping_
mapping of peak indices from a 'white' experiment exp_centroided_white_ to its original experiment exp_centroided_
◆ exp_centroided_white_
"white" centroided experimental data
subset of all peaks of exp_centroided_ which are not blacklisted in blacklist_
◆ filtered_peaks_
| std::vector<std::pair<unsigned, unsigned> > filtered_peaks_ |
|
protected |
every filtered peak that passed, in the order they passed: index of its pattern and its index in the pattern's filter result
◆ intensity_cutoff_
◆ isotopes_per_peptide_max_
| size_t isotopes_per_peptide_max_ |
|
protected |
maximum number of isotopic peaks per peptide
◆ isotopes_per_peptide_min_
| size_t isotopes_per_peptide_min_ |
|
protected |
minimum number of isotopic peaks per peptide
◆ mz_tolerance_
◆ mz_tolerance_unit_in_ppm_
| bool mz_tolerance_unit_in_ppm_ |
|
protected |
unit for m/z shift tolerance (ppm - true, Da - false)
◆ passed_
the decision of filterSpectrum_() on each peak of the spectrum (reused, as blacklist_reads_)
◆ patterns_
◆ peptide_similarity_
| double peptide_similarity_ |
|
protected |
◆ rt_band_
RT range used for filtering.